{
    "componentChunkName": "component---src-templates-article-page-template-js",
    "path": "/references/stock/",
    "result": {"data":{"markdownRemark":{"frontmatter":{"title":"Listing stock management","slug":"stock","updated":"2021-09-13T00:00:00.000Z","category":"references","ingress":"Reference documentation for listing stock management.","skills":null},"htmlAst":{"type":"root","children":[{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The listing stock management features of Flex allow providers to define\nthe quantity of available stock for purchase. There are three key\nconcepts related to stock management:"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"stock"}]},{"type":"text","value":" represents the quantity of available units, associated with\na listing. The units can be anything that makes sense for a given\nlisting or marketplace concept, as long as the quantity is integer\nnumber. For instance - the number of physical items kept in inventory;\na number of virtual items; number of available batches, when a listing\nis sold in batches rather than as individual items, etc."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"A "},{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"stock adjustment"}]},{"type":"text","value":" is a record of change in the quantity of stock\nfor a listing. A positive adjustment represents an increase in\navailable stock, while a negative adjustment represents a decrease.\nFor instance, providers add stock by recording a positive stock\nadjustment, while sales that happen through are transaction are\nrecorded as negative adjustments. Stock adjustments are immutable."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"A "},{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"stock reservation"}]},{"type":"text","value":" represents a reservation or purchase of\nparticular quantity of stock through a transaction."}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Providers and operators can manage stock for listings through the\nMarketplace API and the Integration API. Stock adjustments can be\ncreated either\n"},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/marketplace.html#create-stock-adjustment","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"directly"}]},{"type":"text","value":",\nor through a\n"},{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/marketplace.html#compare-and-set-total-stock","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"\"compare and set\" operation that sets the total available stock"}]},{"type":"text","value":"\nconsistently, given an expected current total stock quantity for a\nlisting."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"All stock reservations are created through transactions, governed by\nyour "},{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/concepts/transaction-process/"},"children":[{"type":"text","value":"transaction process"}]},{"type":"text","value":". An\nappropriately constructed transaction process ensures that reservations\ncan only be placed for available quantities of stock."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"stock-reservation-states","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#stock-reservation-states","ariaLabel":"stock reservation states permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Stock reservation states"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"A stock reservation can be in one of several possible states: "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"pending"}]},{"type":"text","value":",\n"},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"proposed"}]},{"type":"text","value":", "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"accepted"}]},{"type":"text","value":", "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"cancelled"}]},{"type":"text","value":" or "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"declined"}]},{"type":"text","value":". Just as with\n"},{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/availability/#booking-states"},"children":[{"type":"text","value":"bookings"}]},{"type":"text","value":", stock reservations\nchange state only through a corresponding transaction transition, using\none of the\n"},{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/transaction-process-actions/#stock-reservations"},"children":[{"type":"text","value":"stock reservation actions"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"All stock reservations in "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"pending"}]},{"type":"text","value":" or "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"accepted"}]},{"type":"text","value":" states count as\nreservation against the listing's available stock. On the other hand,\nstock reservations in the "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"proposed"}]},{"type":"text","value":", "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"cancelled"}]},{"type":"text","value":" or "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"declined"}]},{"type":"text","value":" states\ndo not affect the current available stock."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"It is important to note that the stock reservation's effect on stock is\nexplicitly recorded as individual stock adjustments as the reservation\nprogresses through its states. For example, if a proposed reservation is\naccepted, a new stock adjustment with negative sign (decrease of stock)\nis recorded. Similarly, if an "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"accepted"}]},{"type":"text","value":" stock reservation changes state\nto "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"cancelled"}]},{"type":"text","value":", a positive stock adjustment (increase of stock) is\nrecorded. On the other hand, a new stock adjustment is not recorded when\nthe change of states does not require one, as is the case for change\nfrom "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"pending"}]},{"type":"text","value":" to "},{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":"accepted"}]},{"type":"text","value":" state. All this ensures that the set of\nstock adjustments for a particular listing represents an accurate and\ndetailed view of how the listing's available stock has changed over\ntime."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"The figure below illustrates the possible stock reservation states,\ntransitions between the states and the corresponding actions that you\ncan use in your transaction process."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-wrapper"],"style":"position: relative; display: block; margin-left: auto; margin-right: auto; max-width: 635px; "},"children":[{"type":"text","value":"\n      "},{"type":"element","tagName":"a","properties":{"className":["gatsby-resp-image-link"],"href":"/docs/legacy/static/142638ab49fc8246f373397398195565/ed8d4/stock-reservation-states.png","style":"display: block","target":"_blank","rel":["noopener"]},"children":[{"type":"text","value":"\n    "},{"type":"element","tagName":"span","properties":{"className":["gatsby-resp-image-background-image"],"style":"padding-bottom: 98.74213836477988%; position: relative; bottom: 0; left: 0; background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAACXBIWXMAAAsTAAALEwEAmpwYAAADgUlEQVQ4y42Ua2scVRjH9ysIgi/8LPod+sZ3IoivhNJi1RcVRAlVwUiUtmil9YYlRbTSSzTR1Nja1EBtbGuNSchuZmd2du73OTOzl+Qn58zuJilBfPHnec7Z2f95rv9GnJfsR5QVEz8RlTqHWaH8RJR4SYGfyG+KybfSjv3GYWTSmm6AYfs0dYuWYamz5YV0Q4GTlORFb/Lg/yL04oxUVARJjhelWH6EZto0Oy6a5WM6vrqTUe//f+OwlCXyqs/y6iMuz9/k8sItfvrtriLW7Ii2E+H4EU6QqAclJhE+XgeJIBWU/R1Of/EtR9/8gBNTH3HqzJd4YYLmxLS6AR3bUyUxbI/tjo0bpSTjlCWJPKSiVCkkeUFWVGzpJisPN/n94Sb/NHUyUWJFAjuqfx83zglT3DA9GKETC3Q/xwiEgvSTYpe4hP4QdnchyivMqFRNycoesago+0MVUFpUiN6gjlBG1fZEPRJpgRsLUjHg3NINXrn0FSe/u8j0/HXWth0ebZloHQfDrPHjryt8M/cLs9cWuf3HXzTCVBCmOZqb1cVNBUGaszuE5z6Z5oljz/PUiRd55t2TBJaL17FxZM06DrZu8fbMeV49dVrV+tPZKzRsP0K3XDYNF92qCy0fSfKKu1tbzK3e44fVe9zZ2CCUk1DUqSYju94yeLDe4sF6k6ZhjVLOS3RfEO0bHzWHsSCPC4SsWTK6Gw20JEyKiv4ODHZhCJSDnb2maN7eLIWZoKqGnLu5yNGLFzg++znT81cxLQ/dsNA7trKyhld+vs3s1UW+/n6BpZU/a0IZoVyplpuieRmalxJmOxw5+z5PHn+Bp197iWffewOv6+KaDo7p4JoujmEz9eEFXn/nDMfemuH8pWt7c5iJSjVi0Icwk53v8bfRYXljneWNDe6326M09xCrWbVYa+qsbbXRum4dYSZ66H7IzOIcny0v4cUpfpyp+15/h6o3pCgHB7ZpjKzsI6qBQlb0aEhpEmWfTdPiyKkpXv74LJrpKIWRXZeNCNRoiUMI6+zCtIYSh2ikdbYfs3BjhVt37itfjpOULCdMJloo7XjdHtfOMQ6Ig5KqWO5lgukEIw2M6HqhEgHD8kY66alvDyOdEAZpobal5WYYTsi2YanUpQaO/abepd111Z0swX8SypXzTA+v42DZPq2OPallja6yUqr0rqtKsF+px4T/Ai2RvrRRmtg2AAAAAElFTkSuQmCC'); background-size: cover; display: block;"},"children":[]},{"type":"text","value":"\n  "},{"type":"element","tagName":"picture","properties":{},"children":[{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/142638ab49fc8246f373397398195565/82e29/stock-reservation-states.webp 159w","/docs/legacy/static/142638ab49fc8246f373397398195565/ef33f/stock-reservation-states.webp 318w","/docs/legacy/static/142638ab49fc8246f373397398195565/f1837/stock-reservation-states.webp 635w","/docs/legacy/static/142638ab49fc8246f373397398195565/29549/stock-reservation-states.webp 953w","/docs/legacy/static/142638ab49fc8246f373397398195565/c5420/stock-reservation-states.webp 1270w","/docs/legacy/static/142638ab49fc8246f373397398195565/beaa0/stock-reservation-states.webp 2206w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/webp"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"source","properties":{"srcSet":["/docs/legacy/static/142638ab49fc8246f373397398195565/8b9b5/stock-reservation-states.png 159w","/docs/legacy/static/142638ab49fc8246f373397398195565/fa108/stock-reservation-states.png 318w","/docs/legacy/static/142638ab49fc8246f373397398195565/53fb6/stock-reservation-states.png 635w","/docs/legacy/static/142638ab49fc8246f373397398195565/5a426/stock-reservation-states.png 953w","/docs/legacy/static/142638ab49fc8246f373397398195565/91155/stock-reservation-states.png 1270w","/docs/legacy/static/142638ab49fc8246f373397398195565/ed8d4/stock-reservation-states.png 2206w"],"sizes":"(max-width: 635px) 100vw, 635px","type":"image/png"},"children":[]},{"type":"text","value":"\n          "},{"type":"element","tagName":"img","properties":{"className":["gatsby-resp-image-image"],"src":"/docs/legacy/static/142638ab49fc8246f373397398195565/53fb6/stock-reservation-states.png","alt":"Stock reservation states","title":"Stock reservation states","loading":"lazy","decoding":"async","style":"width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0;"},"children":[]},{"type":"text","value":"\n        "}]},{"type":"text","value":"\n  "}]},{"type":"text","value":"\n    "}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"negative-stock-quantity","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#negative-stock-quantity","ariaLabel":"negative stock quantity permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Negative stock quantity"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"p","properties":{},"children":[{"type":"text","value":"Generally, the total available stock of a listing cannot be a negative\nnumber. However, in some rare cases, it is possible that the total stock\nbecomes negative. This should be considered an error case and is an\nindication that at least some\n"},{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/concepts/transaction-process/"},"children":[{"type":"text","value":"transaction transition"}]},{"type":"text","value":" failed to\nexecute properly. Such a transaction transition would include some of\nthe actions that "},{"type":"element","tagName":"em","properties":{},"children":[{"type":"text","value":"release"}]},{"type":"text","value":" some reserved stock (such as\n"},{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/transaction-process-actions/#actiondecline-stock-reservation"},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":":action/decline-stock-reservation"}]}]},{"type":"text","value":"\nor\n"},{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/transaction-process-actions/#actioncancel-stock-reservation"},"children":[{"type":"element","tagName":"code","properties":{},"children":[{"type":"text","value":":action/cancel-stock-reservation"}]}]},{"type":"text","value":"),\nwhich would typically be present in a transition representing a\ncancellation or a refund. As a mitigation, "},{"type":"element","tagName":"strong","properties":{},"children":[{"type":"text","value":"it is recommended to always\nplace actions that release a stock reservation last in the sequence of\nactions of a transition"}]},{"type":"text","value":"."}]},{"type":"text","value":"\n"},{"type":"element","tagName":"h2","properties":{"id":"further-reading","style":"position:relative;"},"children":[{"type":"element","tagName":"a","properties":{"href":"#further-reading","ariaLabel":"further reading permalink","className":["anchor","before"]},"children":[{"type":"element","tagName":"svg","properties":{"ariaHidden":"true","focusable":"false","height":"16","version":"1.1","viewBox":"0 0 16 16","width":"16"},"children":[{"type":"element","tagName":"path","properties":{"fillRule":"evenodd","d":"M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"},"children":[]}]}]},{"type":"text","value":"Further reading"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Marketplace API reference\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/marketplace.html#stock","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"stock"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/marketplace.html#stock-adjustments","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"stockAdjustments"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/marketplace.html#stock-reservations","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"stockReservations"}]}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"Integration API reference\n"},{"type":"element","tagName":"ul","properties":{},"children":[{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/integration.html#stock","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"stock"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/integration.html#stock-adjustments","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"stockAdjustments"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://www.sharetribe.com/api-reference/integration.html#stock-reservations","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"stockReservations"}]}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/references/transaction-process-actions/#stock-reservations"},"children":[{"type":"text","value":"Transaction process actions for stock reservations"}]}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"element","tagName":"a","properties":{"href":"https://github.com/sharetribe/example-processes#flex-product-default-process","target":"_blank","rel":["noopener","noreferrer"]},"children":[{"type":"text","value":"Example transaction process definition"}]},{"type":"text","value":"\nfor selling products using stock"}]},{"type":"text","value":"\n"},{"type":"element","tagName":"li","properties":{},"children":[{"type":"text","value":"The "},{"type":"element","tagName":"a","properties":{"href":"/docs/legacy/ftw/ftw-product/"},"children":[{"type":"text","value":"FTW product"}]},{"type":"text","value":" is an example implementation of\nstock management."}]},{"type":"text","value":"\n"}]}],"data":{"quirksMode":false}},"headings":[{"value":"Stock reservation states","depth":2},{"value":"Negative stock quantity","depth":2},{"value":"Further reading","depth":2}]}},"pageContext":{"slug":"stock","category":"references"}},
    "staticQueryHashes": ["3794076007","439097193","717698143"]}