Ordering API

the ordering api allows you to create and manage sparklayer shopping carts on behalf of customers and convert those carts into orders it also provides an endpoint for fetching customer specific pricing, which can be used for validation or user feedback before creating a cart while our api specification provides full endpoint and schema details, this guide focuses on customer specific pricing lookups, the typical cart / order lifecycle, and integration patterns customer specific pricing lookup this endpoint can be used before creating a cart to check pricing and price breaks for validation or user feedback it calculates real time pricing for one or more skus in the context of a specific customer it returns per line item unit prices, line totals, and quantity price breaks, accounting for the customer's assigned price lists and any customer level discount percentage price calculation sparklayer looks up the customer's assigned price lists and uses those to calculate accurate pricing for each requested product this includes quantity price breaks — the price adjusts based on how many units are being ordered variant aggregation — if your store is configured to apply price breaks across variants, quantities across sizes or colours of the same product are combined when determining the price tier for example, ordering 5× size m and 5× size l could unlock the 10 unit price break for both customer discounts — any discount assigned to the customer is applied on top of the list price each product in the response includes the unit price, line total, and a full breakdown of available quantity price breaks all prices are returned as net values potential issues partial pricing failure — if any product cannot be priced, affected line items will include an error with null pricing data, while successfully priced items are still returned alongside them invalid request — returned if the request is malformed, the customer does not exist, or the customer has no price lists configured orders overview all orders begin as a shopping cart associated with a customer by using the same cart handling as the sparklayer cart, the platform can apply the same pricing, validation, ordering rules, and checkout logic that customers would experience when placing an order themselves a typical order lifecycle could follow these steps create a cart update the cart contents with line items calculate totals and available shipping / payment options complete the cart and create the order 1\ create an empty cart start by creating a new cart for the customer you wish to create an order for a cart is initially empty and acts as a container for all order information, including line items, quantities, shipping details, and payment method selection the response includes a unique cart identifier which should be used for all subsequent cart operations 2\ update the cart once a cart has been created, you can populate it with the information required for the order common updates include setting the line items & quantities setting shipping methods for drop shipping scenarios, you may wish to use a temporary shipping address when the delivery destination should not be permanently stored against the customer account validation each cart update returns the latest cart state, including any validation errors generated by sparklayer according to your configured business rules validation errors may indicate issues such as minimum or maximum order quantity restrictions product availability constraints customer specific purchasing restrictions the response also includes item level update results, allowing you to determine how each requested line item was processed and whether any adjustments or validation errors occurred the update cart and calculate cart operations always return a successful response, even when validation errors are present any validation errors are included in the response for your application to handle the complete cart operation behaves differently if validation errors exist, the operation fails and the cart cannot be completed if your implementation needs to allow specific validation errors, you can use the documented ignore validation errors property to specify which validation errors should be ignored during cart completion 3\ calculate the cart before completing an order, you should calculate the cart this step allows sparklayer to calculate order totals with the connected platform apply pricing determine shipping costs & available shipping methods determine available payment methods validate the current cart state the identifiers provided for these options can be used when selecting shipping and payment methods during the ordering process 4\ complete the cart once the cart has been validated and all required selections have been made, the cart can be completed completing a cart converts it into a sparklayer order and submits it to the connected ecommerce platform for processing after completion, the cart can no longer be modified and should be treated as a completed purchase recommended workflow for most integrations, we recommend the following sequence create a cart add products and order details review any validation messages calculate the cart select shipping and payment methods calculate the cart & confirm totals complete the cart