Ordering API

The Ordering API lets you create SparkLayer carts on behalf of your customers and complete them as orders on your connected eCommerce platform — for example to place orders from an external system or for drop shipping. Carts use the same pricing, validation, ordering rules and checkout logic as the SparkLayer cart your customers use, except that upfront payment methods aren't available for carts created through the API.

The API reference below gives full endpoint and schema details. This guide covers checking customer-specific pricing, the cart and order lifecycle, and how validation works.

Customer-specific pricing lookup

The Get customer-specific pricing endpoint is part of the Core API. Use it 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 can't be priced, the response status is 207: affected line items include an error with null pricing data, and successfully priced items are returned alongside them.
• Invalid request — a 400 is returned if the request is malformed, the customer doesn't exist, or the customer has no price lists configured.

Order lifecycle

Every order starts as a cart for a customer, and goes through four steps:

1. Create a cart for the customer.
2. Update the cart with line items and order details, and review any validation errors.
3. Calculate the cart to get totals and the available shipping and payment methods. Calculate again with your chosen shipping rate to confirm the totals.
4. Complete the cart with the shipping rate and payment method to place the order.

1. Create an empty cart

Create a cart for the customer you're placing the order for. Identify the customer with customer_id and customer_lookup_by: sparklayer (the customer's SparkLayer ID), platform (the ID from your eCommerce platform) or email.

A new cart is empty. It holds all the order information, including line items, quantities and the shipping address. The response includes a cart_id: use it for every later request about the cart.

2. Update the cart

Update the cart with the information the order needs:

• Line items and their quantities
• The shipping address (shipping_address_id), or a temporary_shipping_address
• The customer reference, PO number, requested shipping date and custom fields

Each update replaces the cart's line items, so always send the full list with the final quantity of each item. Omitting line_items, or sending an empty array, empties the cart.

For drop shipping, use a temporary shipping address when the delivery address shouldn't be stored against the customer's account.

Validation

Each cart update returns the latest cart state, including any validation errors generated by your business rules in SparkLayer, such as:

• Minimum or maximum order quantity restrictions
• Product availability constraints
• Customer-specific purchasing restrictions

The response also has a result for each line item, so you can see how each requested item was processed and whether it was adjusted or has a validation error.

The Update a cart and Calculate a cart operations don't fail because of validation errors: the errors are included in the response for your application to handle. Calculating does return a 422 if the cart is empty or the shipping rate you chose isn't available — see Cart errors.

The Complete a cart operation behaves differently. If validation errors exist, it returns a 422 and the cart isn't completed. To allow specific validation errors, list them in the ignore_validation_errors property.

3. Calculate the cart

Calculate the cart before completing it. SparkLayer:

• Calculates the order totals and tax with the connected platform
• Applies pricing
• Returns the available shipping methods and their costs
• Returns the allowed payment methods
• Validates the current cart state

To choose a shipping method, pass its shipping_rate_handle. If you leave it out, SparkLayer uses the first available shipping rate. Calculate again after changing the shipping rate or the cart, so the totals you show are up to date.

4. Complete the cart

Complete the cart once it's valid and you've chosen how to ship and pay. Send:

• shipping_rate_handle: a shipping rate returned when you calculated the cart
• payment_method: paymentByInvoice or paymentOnAccount
• ignore_validation_errors: the validation errors to allow (an empty list allows none, "*" allows all)

Completing a cart turns it into a SparkLayer order and submits it to the connected eCommerce platform.

The response includes the new purchase_id. The cart is deleted once it's completed, so later requests with its ID return 404.

Endpoints

Next steps

• Authentication: get an access token for your requests.
• Errors: the cart error codes and what they mean.
• Purchasing API: the orders and quotes customers see in My Account.