Build and Manage Shopping Carts in Nymble Commerce

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.

Get Started

Core Concepts

Guides

Help

Build and Manage Shopping Carts in Nymble Commerce

Cart lifecycle

Creating a cart

Adding items

Updating items

Retrieving a cart

Shipping and PO number

Completing checkout

​Cart lifecycle

​Creating a cart

​Adding items

​Updating items

​Retrieving a cart

​Shipping and PO number

​Completing checkout

Cart lifecycle

Creating a cart

Adding items

Updating items

Retrieving a cart

Shipping and PO number

Completing checkout