Purchasing API

our purchasing api is designed to store any purchases these can purchases not ready yet such as a cart, quote or a purchase which has yet to be confirmed and finally allows easy updates to an order once placed please note purchases created here will not be pushed to your e commerce platform (e g shopify) these purchases will show in the "my account" section for your b2b users if you wish to have the orders in your e commerce platform, you will need to use the api provided by the platform to create the order, e g shopify orders api https //shopify dev/docs/api/admin rest/2024 04/resources/order to create the order in order to have the orders sync through to sparklayer, they need a few properties applied this may be different depending on your e commerce platform for example, in shopify you will need to ensure the order has the b2b tag the sparklayer order import metafield for more details on this (for shopify), please refer to our documentation on importing orders here https //docs sparklayer io/shopify metafields#6jvt technical details any creates/updates to an order are saved via the put endpoint /api/v1/purchases/{lookupby}/{identifier} this can be a new purchase, or update an existing purchase if the lookupby and identifier are not found, a new purchase is created typically, if an order was created from sparklayer, it is important you use the spark cart id which was used to create the order on the platform, this will ensure the cart is replaced with the order below highlights the top level purchase identifiers lookup identifier description sparklayer passed to the ecommerce platform when a customer completes the checkout if a sparklayer order, this must be brought through to move the order from order unconfirmed to order type otherwise leave blank platform the internal ecommerce platform id internal the merchant id from a erp/oms visible the id which will be shown to the customer note that this endpoint replaces the previous data for a purchase, so when making updates, ensure you include the full purchase and not just updated fields this is to prevent any weird or stale states and lowers complexity of integration of orders to the platform also note all calculated fields are calculated by the api and should not be set in the request body purchases can be one of a few types, "quote", "cart", "awaiting approval", "order" and "order unconfirmed" typically, you will be using "order" purchase type description cart not used yet quote not used yet awaiting approval an purchase awaiting confirmation by another member of the customer typically used by our company user functionality order unconfirmed an order completed within sparklayer but not confirmed yet, either pending on the ecommerce platform or sync tooling has not completed yet order a finalised order saved within the ecommerce platform or from the merchants order source of truth such as erp/oms a purchase is mostly made up of packages, these packages store the line items, shipping methods, addresses and various ids when first creating an order, the orders line items should be placed in a "processing" package these items can then be moved to the relevant packages through a order lifecycle, such as "shipment", "refund" or "cancelled" you can use multiple of each, for say partial shipments the state of an order as reflected in the frontend is calculated by package dates, created at, shipped at etc when an order is missing required values, or they are invalid, the api will return a 400 with the appropriate error to identify the value