For cart-based ordering, use
POST /api/carts/{cartId}/checkout instead of creating orders directly. Use the Orders API when you need to import historical orders, build assisted-ordering tools, or create orders programmatically without a cart session.The order object
Every endpoint that returns order data uses the same order object shape.Unique identifier for the order (GUID).
The tenant organization this order belongs to.
Human-readable order number generated by Nymble Commerce (e.g.
ORD-00412). Supply your own on bulk import to preserve existing numbers — re-importing the same number updates the record rather than creating a duplicate.The date and time the order was placed. Defaults to the time of creation when omitted.
Current status of the order (e.g.
Pending, Processing, Shipped, Complete, Cancelled).Describes how the order was placed (e.g.
Direct, Web, EDI).Customer’s purchase order number.
The pricing tier applied to this order (e.g.
Wholesale, Retail).ISO 4217 currency code (e.g.
USD, CAD).Payment terms (e.g.
Net30, Net60, COD).Sales channel the order came through (e.g.
Web, Phone, EDI).Your system’s identifier for this order. Used to make bulk imports idempotent — re-submitting the same
externalId updates the existing order.Free-text notes attached to the order.
If this order originated from a cart checkout, the ID of that cart.
The customer on this order.
The primary sales rep responsible for this order.
The sales rep who took the order (if different from the primary rep). Same fields as
primarySalesRep.Line items on the order.
Shipping information for the order.
Endpoints
Create an order
Creates a single order. Use this endpoint for assisted ordering or programmatic order creation. To import multiple historical orders in one call, use the bulk endpoint.Request body
The customer placing the order.
How the order was placed (e.g.
Direct, Web, EDI).Customer’s purchase order number.
Pricing tier to apply (e.g.
Wholesale, Retail). Must match a tier configured in your organization.ISO 4217 currency code (e.g.
USD).The primary sales rep for this order.
The line items on the order. Must contain at least one item.
The user creating the order.
Shipping method and cost for the order.
The rep who took the order, if different from
primarySalesRep. Same fields as primarySalesRep.Payment terms (e.g.
Net30, Net60, COD).Free-text notes for this order.
Initial status to set on the order. Defaults to
Pending when omitted.Sales channel (e.g.
Web, Phone, EDI).Your system’s identifier for this order. Makes the creation idempotent — submitting the same
externalId again updates the existing order instead of creating a new one.Tax amount to apply to the order.
If this order was generated from a cart, the cart’s ID. Set automatically when using the checkout endpoint.
Example request
Response
Returns201 Created with the new order’s ID and order number.
Create orders in bulk
Creates multiple orders in a single request. Designed for importing historical orders from an ERP or legacy system. Each order in the array follows the same shape as the single-order request body, with the addition of an optionalorderNumber field.
Request body
An array of order objects. Each object accepts the same fields as the single
POST /api/orders request, plus:Example request
Response
Returns201 Created with an array of results, one per submitted order.
Get an order
Retrieves a single order by its ID. Returns the full order object.Path parameters
The unique identifier (GUID) of the order.
Example request
Example response
Search orders
Returns a paginated list of orders. Use query parameters to filter, sort, and paginate results. Each order in the response is paired with the invoice numbers of any invoices generated against it.Query parameters
Page number to return. Defaults to
1.Number of results per page. Defaults to
25.Field to sort results by. Defaults to
createdAt.Sort direction:
asc or desc. Defaults to asc.An array of filter objects to narrow results. Each filter has:
Example request
Response
Update shipping details
Updates the shipping method, cost, and/or address on an existing order. Use this after order creation to attach or revise shipping information.Path parameters
The unique identifier of the order to update.
Request body
Shipping method name (e.g.
FedEx Ground, UPS 2nd Day Air).Shipping cost.
Updated shipping address. Fields:
address1, address2, city, stateProvince, zipPostalCode, country.Example request
Response
Returns200 OK with the updated order object.
Update customer details
Updates the customer information attached to an order. Use this to correct customer data or reassign an order to a different account.Path parameters
The unique identifier of the order to update.
Request body
The customer’s account number.
Customer’s company name.
Primary company email address.
Primary company phone number.
Company fax number.
Updated billing address. Fields:
address1, address2, city, stateProvince, zipPostalCode, country.Example request
Response
Returns200 OK with the updated order object.
Send order confirmation email
Sends an order confirmation email to one or more recipients. The email uses your organization’s configured template and branding.Path parameters
The unique identifier of the order.
Request body
One or more email addresses to send the confirmation to.
Example request
Response
Returns200 OK on success.