> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and Manage Shopping Carts in Nymble Commerce

> Learn how to create, update, and check out shopping carts in Nymble Commerce, including adding and removing items and setting shipping preferences.

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:

```text theme={null}
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.

```http theme={null}
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**

```json theme={null}
{
  "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"
}
```

<Warning>
  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.
</Warning>

***

## Adding items

Append products to an existing cart with `POST /api/carts/{customerNumber}/{shoppingCartId}/items`.

```http theme={null}
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
}
```

<Note>
  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.
</Note>

***

## Updating items

Change the quantity on an existing line item using `PUT /api/carts/{customerNumber}/{shoppingCartId}/items/{sku}`:

```http theme={null}
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}`:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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`:

```http theme={null}
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`:

```http theme={null}
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.

```http theme={null}
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**

```json theme={null}
{
  "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.