Purchasing API

our purchasing api is designed to store any purchases these can be 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", "awaiting approval", "order" and "order unconfirmed" typically, you will be using "order" purchase type description quote a purchase in the state of quote with a quote status 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 purchase transactions to record transactions against a purchase such as payments, refunds etc you can use the purchase transactions put endpoint the transactions are used to calculate the payment status of the given purchase note if using this api it's important to not also send the same information to your e commerce platform as that could lead to the same transaction being recorded twice every transaction requires the sparkid of the purchase in the purchase spark id property that you want to record it against multiple transactions can be logged against a single purchase, but each transaction must have a unique combination of purchase spark id and platform id which is a reference to the id used by the 3rd party system to identify this specific transaction the total should be positive for a payment and negative for a refund a currency code is also required purchase transactions can be created in one of two states governed by the apply to balance boolean when set to false the record is created for informational purposes only it will not be used in the status calculation it will be available to be returned from the get endpoint, but no further processing of the record will take place this is useful for recording pending or failed transactions etc which may be useful for debugging setting to true will make this transaction part of the status calculation for the purchase and also trigger two additional processes firstly a new item will be added to the purchasehistory for the associated purchase which will be shown to the customer in the ui secondly, the value in the total property will be used to adjust the outstanding balance of the customer associated with the purchase updating a purchasetransaction that was previously set true to false will delete the purchasehistory item it created and revert the change to the customer's balance and payment status the full transaction property is a json string that can be used to store a full representation of the transaction as held by the 3rd party system be aware that this will be stored as given and no redaction will take place, so it's vital to ensure that sensitive data such as full credit card numbers etc are removed or obfuscated before sending to sparklayer