Nymble Commerce Carts API — Shopping Cart & Checkout Docs

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.

POST https://api.achievemomentum.com/api/carts/{customerNumber}

Path parameters

string

required

The customer account number to create the cart for.

Body parameters

string

required

The customer account number (must match the path parameter).

string

required

SKU of the first product to add to the cart.

integer

required

Quantity of the first product to add.

string

required

The type of order this cart represents, e.g. Standard, Quote.

Response

Returns the newly created cart object including the first line item.

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 and add items to it instead.

Example

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"
  }'

{
  "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.

GET https://api.achievemomentum.com/api/carts/{id}

Path parameters

string

required

The unique identifier of the cart to retrieve.

Response

Returns a single cart object.

Example

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.

GET https://api.achievemomentum.com/api/carts/customer/{customerNumber}

Path parameters

string

required

The customer account number to look up carts for.

Response

Returns an array of cart objects for the customer.

Example

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.

GET https://api.achievemomentum.com/api/carts

Query parameters

integer

default:"1"

The page of results to return.

integer

default:"25"

Number of carts per page.

string

default:"CompanyName"

Field to sort on. Common values: CompanyName, CustomerNumber, Status.

string

default:"asc"

Sort direction. Accepts asc or desc.

array

Optional filter objects. Can filter on CustomerNumber, CompanyName, or Status. Supported operators: startswith, contains, notcontains, endswith, equals, notequals.

Response

Returns a paginated result containing an array of cart objects.

Example

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.

PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}

Path parameters

string

required

The customer account number.

string

required

The cart ID to update.

Body parameters

object

required

The updated cart object. Include only the fields you want to change.

Example

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.

POST https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/items

Path parameters

string

required

The customer account number.

string

required

The cart to add the item to.

Body parameters

string

required

The SKU of the product to add.

integer

required

The number of units to add.

string

required

The customer account number (must match the path parameter).

Response

Returns the updated cart object with the new item included.

Example

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
  }'

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.

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.

PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/items/{sku}

Path parameters

string

required

The customer account number.

string

required

The cart containing the item.

string

required

The SKU of the line item to update.

Body parameters

integer

required

The new quantity for this line item. Set to 0 to remove the item from the cart.

string

required

The customer account number.

Response

Returns the updated cart object.

Example

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.

DELETE https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/items/{sku}

Path parameters

string

required

The customer account number.

string

required

The cart to remove the item from.

string

required

The SKU of the line item to remove.

Response

Returns the updated cart object without the removed item.

Example

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.

PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/shipping

Path parameters

string

required

The customer account number.

string

required

The cart to update shipping on.

Body parameters

object

required

The shipping address to apply to this cart.

Show shippingAddress fields

string

required

The customer account number.

Example

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.

PUT https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/po-number

Path parameters

string

required

The customer account number.

string

required

The cart to apply the PO number to.

Body parameters

string

required

The purchase order number from the customer, e.g. PO-2024-88412.

string

required

The customer account number.

Example

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.

POST https://api.achievemomentum.com/api/carts/{customerNumber}/{shoppingCartId}/complete-checkout

Path parameters

string

required

The customer account number.

string

required

The cart ID to check out.

Body parameters

string

required

The customer account number (must match the path parameter).

string

required

The sales channel for this order, e.g. Web, Storefront, EDI.

string

The ID of a saved payment profile to charge for this order.

object

Payment details for this order. Required if paymentProfileId is not provided.

Show payment fields

object

Billing address for the payment.

Show billingAddress fields

object

Credit card details.

Show creditCard fields

Response

string

The assigned order number for the completed order, e.g. MOM-00001.

string

A unique confirmation identifier for this checkout. Use this to reference the order when contacting support.

Example

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"
      }
    }
  }'

{
  "orderNumber": "MOM-00482",
  "confirmationId": "conf_a3f91bc2"
}

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.

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.

The cart object

string

Nymble Commerce’s unique identifier for this cart.

string

The organization this cart belongs to.

string

The customer account number.

string

The customer’s company name.

string

Current cart status. PENDING while the cart is open; CLOSED after checkout.

string

The type of order this cart represents, e.g. Standard, Quote.

string

The price tier applied to this cart, inherited from the customer’s account.

string

ISO 4217 currency code for this cart.

string

The customer purchase order number, if set.

string

Any special delivery or handling instructions.

array

Array of line item objects.

Show items[]

number

Sum of all line totals before shipping and taxes.

object

The shipping address set on this cart.

object

The billing address set on this cart.

string

ISO 8601 timestamp of when the cart was created.

string

ISO 8601 timestamp of the most recent update.

​Create a cart

​Path parameters

​Body parameters

​Response

​Example

​Get a cart by ID

​Path parameters

​Response

​Example

​Get carts for a customer

​Path parameters

​Response

​Example

​List all carts

​Query parameters

​Response

​Example

​Update a cart

​Path parameters

​Body parameters

​Example

​Add an item to a cart

​Path parameters

​Body parameters

​Response

​Example

​Update an item in a cart

​Path parameters

​Body parameters

​Response

​Example

​Remove an item from a cart

​Path parameters

​Response

​Example

​Set shipping details

​Path parameters

​Body parameters

​Example

​Set a PO number

​Path parameters

​Body parameters

​Example

​Complete checkout

​Path parameters

​Body parameters

​Response

​Example

​The cart object

Create a cart

Path parameters

Body parameters

Response

Example

Get a cart by ID

Path parameters

Response

Example

Get carts for a customer

Path parameters

Response

Example

List all carts

Query parameters

Response

Example

Update a cart

Path parameters

Body parameters

Example

Add an item to a cart

Path parameters

Body parameters

Response

Example

Update an item in a cart

Path parameters

Body parameters

Response

Example

Remove an item from a cart

Path parameters

Response

Example

Set shipping details

Path parameters

Body parameters

Example

Set a PO number

Path parameters

Body parameters

Example

Complete checkout

Path parameters

Body parameters

Response

Example

The cart object