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

customerNumber

string

required

The customer account number to create the cart for.

Body parameters

customerNumber

string

required

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

sku

string

required

SKU of the first product to add to the cart.

quantity

integer

required

Quantity of the first product to add.

orderType

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

customerNumber

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

pageNumber

integer

default:"1"

The page of results to return.

pageSize

integer

default:"25"

Number of carts per page.

sortOn

string

default:"CompanyName"

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

sortDirection

string

default:"asc"

Sort direction. Accepts asc or desc.

filters

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

customerNumber

string

required

The customer account number.

shoppingCartId

string

required

The cart ID to update.

Body parameters

cart

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

customerNumber

string

required

The customer account number.

shoppingCartId

string

required

The cart to add the item to.

Body parameters

sku

string

required

The SKU of the product to add.

quantity

integer

required

The number of units to add.

customerNumber

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

customerNumber

string

required

The customer account number.

shoppingCartId

string

required

The cart containing the item.

sku

string

required

The SKU of the line item to update.

Body parameters

quantity

integer

required

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

customerNumber

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

customerNumber

string

required

The customer account number.

shoppingCartId

string

required

The cart to remove the item from.

sku

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

customerNumber

string

required

The customer account number.

shoppingCartId

string

required

The cart to update shipping on.

Body parameters

shippingAddress

object

required

The shipping address to apply to this cart.

Show shippingAddress fields

customerNumber

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

customerNumber

string

required

The customer account number.

shoppingCartId

string

required

The cart to apply the PO number to.

Body parameters

poNumber

string

required

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

customerNumber

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

customerNumber

string

required

The customer account number.

shoppingCartId

string

required

The cart ID to check out.

Body parameters

customerNumber

string

required

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

channel

string

required

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

paymentProfileId

string

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

payment

object

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

Show payment fields

payment.billingAddress

object

Billing address for the payment.

Show billingAddress fields

payment.creditCard

object

Credit card details.

Show creditCard fields

Response

orderNumber

string

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

confirmationId

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

shoppingCartId

string

Nymble Commerce’s unique identifier for this cart.

organizationId

string

The organization this cart belongs to.

customerNumber

string

The customer account number.

companyName

string

The customer’s company name.

status

string

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

orderType

string

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

pricingTier

string

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

currencyCode

string

ISO 4217 currency code for this cart.

poNumber

string

The customer purchase order number, if set.

specialInstructions

string

Any special delivery or handling instructions.

items

array

Array of line item objects.

Show items[]

subtotal

number

Sum of all line totals before shipping and taxes.

shippingAddress

object

The shipping address set on this cart.

billingAddress

object

The billing address set on this cart.

createdAt

string

ISO 8601 timestamp of when the cart was created.

updatedAt

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