Ordering API

the ordering api allows you to create and manage sparklayer shopping carts on behalf of customers and convert those carts into orders while our api specification provides full endpoint and schema details, this guide focuses on the typical cart / order lifecycle and integration patterns note the api is not intended for working with active customer carts which have been created through a merchants store only carts which have been created via the api 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