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.
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.