Skip to main content
Nymble Commerce’s cart API lets you build persistent shopping carts that can be retrieved, updated, and converted to orders at checkout. Carts survive across sessions — a customer can start a cart on one device and complete it on another.

​
Cart lifecycle

A cart moves through the following states: 
Created → Items Added → Configured (shipping + PO) → Checked Out
                                                           ↓
                                                     Order created
                                                     Cart marked Complete
Once a cart is checked out it is marked Complete and can no longer be modified. Any subsequent changes must go through the resulting order.

​
Creating a cart

Send a POST request to /api/carts/{customerNumber}. The customer number goes in the URL path; the organizationId is injected automatically from your JWT. 
POST https://api.achievemomentum.com/api/carts/CUST-1042
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNumber": "CUST-1042",
  "sku": "WIDGET-BLU-L",
  "quantity": 1,
  "orderType": "Standard"
}
Response 
{
  "shoppingCartId": "cart_8f3a2c1d",
  "customerNumber": "CUST-1042",
  "organizationId": "org_4e9b7f22",
  "orderType": "Standard",
  "status": "PENDING",
  "items": [
    {
      "sku": "WIDGET-BLU-L",
      "quantity": 1
    }
  ],
  "createdAt": "2024-06-01T10:00:00Z"
}
Nymble Commerce allows only one active cart per customer at a time. Always call GET /api/carts/customer/{customerNumber} to check for an existing active cart before creating a new one — creating duplicate active carts can lead to confusing checkout experiences.

​
Adding items

Append products to an existing cart with POST /api/carts/{customerNumber}/{shoppingCartId}/items. 
POST https://api.achievemomentum.com/api/carts/CUST-1042/cart_8f3a2c1d/items
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNumber": "CUST-1042",
  "shoppingCartId": "cart_8f3a2c1d",
  "sku": "WIDGET-RED-M",
  "quantity": 3
}
If the SKU you add already exists as a line item in the cart, Nymble Commerce increases the existing line’s quantity by the amount you specify rather than creating a second line for the same product.

​
Updating items

Change the quantity on an existing line item using PUT /api/carts/{customerNumber}/{shoppingCartId}/items/{sku}: 
PUT https://api.achievemomentum.com/api/carts/CUST-1042/cart_8f3a2c1d/items/WIDGET-RED-M
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNumber": "CUST-1042",
  "shoppingCartId": "cart_8f3a2c1d",
  "sku": "WIDGET-RED-M",
  "quantity": 5
}
Remove a line item entirely using DELETE /api/carts/{customerNumber}/{shoppingCartId}/items/{sku}: 
DELETE https://api.achievemomentum.com/api/carts/CUST-1042/cart_8f3a2c1d/items/WIDGET-RED-M
Authorization: Bearer {token}
A 204 No Content response confirms the item has been removed.

​
Retrieving a cart

Fetch a single cart by its ID: 
GET https://api.achievemomentum.com/api/carts/cart_8f3a2c1d
Authorization: Bearer {token}
To find all carts for a specific customer, use the customer carts endpoint: 
GET https://api.achievemomentum.com/api/carts/customer/CUST-1042
Authorization: Bearer {token}
To list all carts across your organization (admin access required), use the list endpoint: 
GET https://api.achievemomentum.com/api/carts?pageNumber=1&pageSize=50
Authorization: Bearer {token}

​
Shipping and PO number

Set the delivery address on the cart with PUT /api/carts/{customerNumber}/{shoppingCartId}/shipping: 
PUT https://api.achievemomentum.com/api/carts/CUST-1042/cart_8f3a2c1d/shipping
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNumber": "CUST-1042",
  "shoppingCartId": "cart_8f3a2c1d",
  "shippingAddress": {
    "address1": "500 Commerce Drive",
    "address2": "Suite 200",
    "city": "Austin",
    "stateProvince": "TX",
    "postalCode": "78701",
    "country": "US"
  }
}
Attach the customer’s purchase order number with PUT /api/carts/{customerNumber}/{shoppingCartId}/po-number: 
PUT https://api.achievemomentum.com/api/carts/CUST-1042/cart_8f3a2c1d/po-number
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNumber": "CUST-1042",
  "shoppingCartId": "cart_8f3a2c1d",
  "poNumber": "PO-2024-88412"
}

​
Completing checkout

When the cart is ready, submit it for processing with POST /api/carts/{customerNumber}/{shoppingCartId}/complete-checkout. Nymble Commerce creates an order in a single atomic operation. 
POST https://api.achievemomentum.com/api/carts/CUST-1042/cart_8f3a2c1d/complete-checkout
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerNumber": "CUST-1042",
  "shoppingCartId": "cart_8f3a2c1d",
  "channel": "Web",
  "payment": {
    "billingAddress": {
      "address1": "123 Billing St",
      "city": "New York",
      "stateProvince": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "creditCard": {
      "cardNumber": "4111111111111111",
      "cardholderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": 2028,
      "cvv": "123"
    }
  }
}
Response 
{
  "orderNumber": "ORD-2024-004821",
  "confirmationId": "conf_a3f91bc2"
}
Use orderNumber to look up the full order details via GET /api/orders/{orderNumber}. After a successful checkout, the cart status is set to Complete. Any further PUT or POST requests against that cart return an error.