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