> ## 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.

# Nymble Commerce Carts API — Shopping Cart & Checkout Docs

> REST API reference for Nymble Commerce shopping cart endpoints — create carts, add and remove items, update shipping and PO numbers, and complete checkout.

The Carts API manages persistent shopping carts for B2B ordering. Carts survive across sessions and can be updated freely — add items, adjust quantities, change shipping details, and set a PO number — until you call the checkout endpoint. After checkout, the cart becomes immutable and an order is created.

All endpoints require a valid Bearer token. The `OrganizationId` is read automatically from your JWT claims.

***

## Create a cart

Create a new shopping cart for a customer. Nymble Commerce also adds the first item to the cart in this call, so you supply the initial SKU and quantity alongside the `CustomerNumber`.

```http theme={null}
POST https://api.achievemomentum.com/api/carts/{customerNumber}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number to create the cart for.
</ParamField>

### Body parameters

<ParamField body="customerNumber" type="string" required>
  The customer account number (must match the path parameter).
</ParamField>

<ParamField body="sku" type="string" required>
  SKU of the first product to add to the cart.
</ParamField>

<ParamField body="quantity" type="integer" required>
  Quantity of the first product to add.
</ParamField>

<ParamField body="orderType" type="string" required>
  The type of order this cart represents, e.g. `Standard`, `Quote`.
</ParamField>

### Response

Returns the newly created [cart object](#the-cart-object) including the first line item.

<Note>
  If an active cart already exists for this customer, the API returns a `400` error. Nymble Commerce enforces one active cart per customer. Retrieve the existing cart using [Get carts for a customer](#get-carts-for-a-customer) and add items to it instead.
</Note>

### Example

```bash theme={null}
curl -X POST "https://api.achievemomentum.com/api/carts/ACME-001" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "ACME-001",
    "sku": "WIDGET-BLU-L",
    "quantity": 10,
    "orderType": "Standard"
  }'
```

```json theme={null}
{
  "shoppingCartId": "cart_8f3a2c1d",
  "customerNumber": "ACME-001",
  "organizationId": "org_4e9b7f22",
  "companyName": "Acme Industrial Supply",
  "status": "PENDING",
  "pricingTier": "Wholesale",
  "currencyCode": "USD",
  "orderType": "Standard",
  "items": [
    {
      "itemId": "item_001",
      "sku": "WIDGET-BLU-L",
      "name": "Blue Widget — Large",
      "quantity": 10,
      "unitPrice": 18.50,
      "lineTotal": 185.00
    }
  ],
  "subtotal": 185.00,
  "createdAt": "2024-06-01T10:00:00Z",
  "updatedAt": "2024-06-01T10:00:00Z"
}
```

***

## Get a cart by ID

Retrieve a specific cart by its ID, including all line items and computed totals.

```http theme={null}
GET https://api.achievemomentum.com/api/carts/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the cart to retrieve.
</ParamField>

### Response

Returns a single [cart object](#the-cart-object).

### Example

```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/carts/cart_8f3a2c1d" \
  -H "Authorization: Bearer {token}"
```

***

## Get carts for a customer

Retrieve all active carts belonging to a specific customer.

```http theme={null}
GET https://api.achievemomentum.com/api/carts/customer/{customerNumber}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number to look up carts for.
</ParamField>

### Response

Returns an array of [cart objects](#the-cart-object) for the customer.

### Example

```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/carts/customer/ACME-001" \
  -H "Authorization: Bearer {token}"
```

***

## List all carts

Retrieve a paginated list of all carts in your organization. This is an admin-only endpoint useful for monitoring order activity across all customers.

```http theme={null}
GET https://api.achievemomentum.com/api/carts
```

### Query parameters

<ParamField query="pageNumber" default="1" type="integer">
  The page of results to return.
</ParamField>

<ParamField query="pageSize" default="25" type="integer">
  Number of carts per page.
</ParamField>

<ParamField query="sortOn" default="CompanyName" type="string">
  Field to sort on. Common values: `CompanyName`, `CustomerNumber`, `Status`.
</ParamField>

<ParamField query="sortDirection" default="asc" type="string">
  Sort direction. Accepts `asc` or `desc`.
</ParamField>

<ParamField query="filters" type="array">
  Optional filter objects. Can filter on `CustomerNumber`, `CompanyName`, or `Status`. Supported operators: `startswith`, `contains`, `notcontains`, `endswith`, `equals`, `notequals`.
</ParamField>

### Response

Returns a paginated result containing an array of [cart objects](#the-cart-object).

### Example

```bash theme={null}
curl -X GET "https://api.achievemomentum.com/api/carts?pageNumber=1&pageSize=25" \
  -H "Authorization: Bearer {token}"
```

***

## Update a cart

Update metadata on an existing cart, such as the order type or special instructions.

```http theme={null}
PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number.
</ParamField>

<ParamField path="shoppingCartId" type="string" required>
  The cart ID to update.
</ParamField>

### Body parameters

<ParamField body="cart" type="object" required>
  The updated cart object. Include only the fields you want to change.
</ParamField>

### Example

```bash theme={null}
curl -X PUT "https://api.achievemomentum.com/api/carts/ACME-001/cart_8f3a2c1d" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "cart": {
      "orderType": "Quote",
      "specialInstructions": "Ship to dock B. Call before delivery."
    }
  }'
```

***

## Add an item to a cart

Add a product to an existing cart by SKU. If the SKU is already in the cart, Nymble Commerce increases that line item's quantity rather than adding a duplicate line.

```http theme={null}
POST https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/items
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number.
</ParamField>

<ParamField path="shoppingCartId" type="string" required>
  The cart to add the item to.
</ParamField>

### Body parameters

<ParamField body="sku" type="string" required>
  The SKU of the product to add.
</ParamField>

<ParamField body="quantity" type="integer" required>
  The number of units to add.
</ParamField>

<ParamField body="customerNumber" type="string" required>
  The customer account number (must match the path parameter).
</ParamField>

### Response

Returns the updated [cart object](#the-cart-object) with the new item included.

### Example

```bash theme={null}
curl -X POST "https://api.achievemomentum.com/api/carts/ACME-001/cart_8f3a2c1d/items" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "ACME-001",
    "sku": "WIDGET-RED-M",
    "quantity": 5
  }'
```

<Note>
  Adding an item whose SKU is already in the cart increases the existing line item's quantity. It does not create a second line for the same SKU.
</Note>

***

## Update an item in a cart

Change the quantity of an existing line item in the cart. The SKU is specified as a path parameter.

```http theme={null}
PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/items/{sku}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number.
</ParamField>

<ParamField path="shoppingCartId" type="string" required>
  The cart containing the item.
</ParamField>

<ParamField path="sku" type="string" required>
  The SKU of the line item to update.
</ParamField>

### Body parameters

<ParamField body="quantity" type="integer" required>
  The new quantity for this line item. Set to `0` to remove the item from the cart.
</ParamField>

<ParamField body="customerNumber" type="string" required>
  The customer account number.
</ParamField>

### Response

Returns the updated [cart object](#the-cart-object).

### Example

```bash theme={null}
curl -X PUT "https://api.achievemomentum.com/api/carts/ACME-001/cart_8f3a2c1d/items/WIDGET-RED-M" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "ACME-001",
    "quantity": 12
  }'
```

***

## Remove an item from a cart

Delete a line item from the cart by SKU.

```http theme={null}
DELETE https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/items/{sku}
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number.
</ParamField>

<ParamField path="shoppingCartId" type="string" required>
  The cart to remove the item from.
</ParamField>

<ParamField path="sku" type="string" required>
  The SKU of the line item to remove.
</ParamField>

### Response

Returns the updated [cart object](#the-cart-object) without the removed item.

### Example

```bash theme={null}
curl -X DELETE "https://api.achievemomentum.com/api/carts/ACME-001/cart_8f3a2c1d/items/WIDGET-RED-M" \
  -H "Authorization: Bearer {token}"
```

***

## Set shipping details

Attach or replace the shipping address for a cart.

```http theme={null}
PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/shipping
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number.
</ParamField>

<ParamField path="shoppingCartId" type="string" required>
  The cart to update shipping on.
</ParamField>

### Body parameters

<ParamField body="shippingAddress" type="object" required>
  The shipping address to apply to this cart.

  <Expandable title="shippingAddress fields" />
</ParamField>

<ParamField body="customerNumber" type="string" required>
  The customer account number.
</ParamField>

### Example

```bash theme={null}
curl -X PUT "https://api.achievemomentum.com/api/carts/ACME-001/cart_8f3a2c1d/shipping" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "ACME-001",
    "shippingAddress": {
      "line1": "500 Commerce Drive",
      "line2": "Dock B",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US",
      "phone": "555-800-1000",
      "addressType": "Shipping",
      "isPrimary": true
    }
  }'
```

***

## Set a PO number

Attach a customer purchase order number to the cart. This value is passed through to the order and invoice.

```http theme={null}
PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/po-number
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number.
</ParamField>

<ParamField path="shoppingCartId" type="string" required>
  The cart to apply the PO number to.
</ParamField>

### Body parameters

<ParamField body="poNumber" type="string" required>
  The purchase order number from the customer, e.g. `PO-2024-88412`.
</ParamField>

<ParamField body="customerNumber" type="string" required>
  The customer account number.
</ParamField>

### Example

```bash theme={null}
curl -X PUT "https://api.achievemomentum.com/api/carts/ACME-001/cart_8f3a2c1d/po-number" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "ACME-001",
    "poNumber": "PO-2024-88412"
  }'
```

***

## Complete checkout

Submit the cart for processing. Nymble Commerce validates the cart, creates an order, and returns an order number and confirmation ID. After a successful checkout the cart status is set to `CLOSED` and can no longer be modified.

```http theme={null}
POST https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/complete-checkout
```

### Path parameters

<ParamField path="customerNumber" type="string" required>
  The customer account number.
</ParamField>

<ParamField path="shoppingCartId" type="string" required>
  The cart ID to check out.
</ParamField>

### Body parameters

<ParamField body="customerNumber" type="string" required>
  The customer account number (must match the path parameter).
</ParamField>

<ParamField body="channel" type="string" required>
  The sales channel for this order, e.g. `Web`, `Storefront`, `EDI`.
</ParamField>

<ParamField body="paymentProfileId" type="string">
  The ID of a saved payment profile to charge for this order.
</ParamField>

<ParamField body="payment" type="object">
  Payment details for this order. Required if `paymentProfileId` is not provided.

  <Expandable title="payment fields">
    <ParamField body="payment.billingAddress" type="object">
      Billing address for the payment.

      <Expandable title="billingAddress fields" />
    </ParamField>

    <ParamField body="payment.creditCard" type="object">
      Credit card details.

      <Expandable title="creditCard fields" />
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="orderNumber" type="string">
  The assigned order number for the completed order, e.g. `MOM-00001`.
</ResponseField>

<ResponseField name="confirmationId" type="string">
  A unique confirmation identifier for this checkout. Use this to reference the order when contacting support.
</ResponseField>

### Example

```bash theme={null}
curl -X POST "https://api.achievemomentum.com/api/carts/ACME-001/cart_8f3a2c1d/complete-checkout" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "ACME-001",
    "channel": "Web",
    "payment": {
      "billingAddress": {
        "address1": "500 Commerce Drive",
        "address2": "Suite 200",
        "city": "Austin",
        "stateProvince": "TX",
        "zipPostalCode": "78701",
        "country": "US"
      },
      "creditCard": {
        "cardNumber": "4111111111111111",
        "cardholderName": "Jane Smith",
        "expiryMonth": "10",
        "expiryYear": 2028,
        "cvv": "123"
      }
    }
  }'
```

```json theme={null}
{
  "orderNumber": "MOM-00482",
  "confirmationId": "conf_a3f91bc2"
}
```

<Warning>
  After a successful checkout, the cart is closed and immutable. Any subsequent attempts to add items or update the cart will return an error. Use the `orderNumber` to retrieve the full order details and the associated invoice from the [Orders API](/api-reference/orders).
</Warning>

<Tip>
  Store both the `orderNumber` and `confirmationId` in your system immediately after checkout. The `orderNumber` is used to look up the order and invoice; the `confirmationId` is the reference to provide customers and for support queries.
</Tip>

***

## The cart object

<ResponseField name="shoppingCartId" type="string">
  Nymble Commerce's unique identifier for this cart.
</ResponseField>

<ResponseField name="organizationId" type="string">
  The organization this cart belongs to.
</ResponseField>

<ResponseField name="customerNumber" type="string">
  The customer account number.
</ResponseField>

<ResponseField name="companyName" type="string">
  The customer's company name.
</ResponseField>

<ResponseField name="status" type="string">
  Current cart status. `PENDING` while the cart is open; `CLOSED` after checkout.
</ResponseField>

<ResponseField name="orderType" type="string">
  The type of order this cart represents, e.g. `Standard`, `Quote`.
</ResponseField>

<ResponseField name="pricingTier" type="string">
  The price tier applied to this cart, inherited from the customer's account.
</ResponseField>

<ResponseField name="currencyCode" type="string">
  ISO 4217 currency code for this cart.
</ResponseField>

<ResponseField name="poNumber" type="string">
  The customer purchase order number, if set.
</ResponseField>

<ResponseField name="specialInstructions" type="string">
  Any special delivery or handling instructions.
</ResponseField>

<ResponseField name="items" type="array">
  Array of line item objects.

  <Expandable title="items[]" />
</ResponseField>

<ResponseField name="subtotal" type="number">
  Sum of all line totals before shipping and taxes.
</ResponseField>

<ResponseField name="shippingAddress" type="object">
  The shipping address set on this cart.
</ResponseField>

<ResponseField name="billingAddress" type="object">
  The billing address set on this cart.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the cart was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the most recent update.
</ResponseField>