Place a B2B Order with the Nymble Commerce API

This guide walks you through creating a complete order in Nymble Commerce, from building the request to receiving the confirmed order number and confirmation ID.

Two approaches to placing an order

Nymble Commerce gives you two ways to place a B2B order:

Approach	Best for
Cart-based checkout	Customer-facing storefronts where buyers browse and build their order interactively
Direct order creation	ERP integrations, assisted ordering by sales reps, and bulk historical imports

Both approaches produce the same result: a confirmed order with an assigned order number.

Approach 1: Cart-based checkout

Use the cart flow when you need a stateful, multi-step ordering experience — for example, a storefront where a customer adds items over time before submitting.

Create a cart

Send a POST request to /api/carts/{customerNumber} to initialize a new cart for a customer. The customerNumber goes in the URL path; the OrganizationId is read automatically from your JWT claims.

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

Add items

Add additional products to the cart using 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
}

Adding an item whose SKU already exists in the cart increases that line item’s quantity rather than creating a duplicate line.

Set shipping details

Attach a shipping address and method to 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"
  }
}

Set a PO number

Attach your 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"
}

Complete checkout

Submit the cart for processing. Nymble Commerce converts the cart into 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"
}

After checkout, use the orderNumber to retrieve the full order via GET /api/orders/{orderNumber}.

Approach 2: Direct order creation

Use direct order creation when you already have all the order details in hand — for example, when importing from an ERP system or when a sales rep is placing an order on a customer’s behalf.

Submit the order

Send a single POST request to /api/orders with the complete order payload.

POST https://api.achievemomentum.com/api/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer": {
    "customerNumber": "CUST-1042",
    "companyName": "Acme Industrial Supply",
    "email": "[email protected]",
    "phone": "512-555-0100"
  },
  "orderType": "Standard",
  "poNumber": "PO-2024-88412",
  "priceTier": "Wholesale",
  "currencyCode": "USD",
  "terms": "Net 30",
  "primarySalesRep": {
    "repNumber": "REP-019",
    "name": "Jordan Lee"
  },
  "items": [
    {
      "sku": "WIDGET-BLU-L",
      "productName": "Blue Widget - Large",
      "quantity": 10,
      "price": 24.99
    },
    {
      "sku": "WIDGET-RED-M",
      "productName": "Red Widget - Medium",
      "quantity": 5,
      "price": 22.50
    }
  ],
  "shippingDetails": {
    "method": "UPS_GROUND",
    "total": 12.50
  },
  "notes": "Leave at loading dock B.",
  "externalId": "ERP-ORD-9921"
}

Confirm the order

A successful response returns the assigned order number and a confirmation ID.

{
  "id": "ord_c4d9e1f8",
  "orderNumber": "ORD-2024-004822"
}

Order line items

Each entry in the items array represents one line on the order:

Field	Type	Required	Description
`sku`	string	Yes	The product’s stock-keeping unit
`productName`	string	Yes	Display name for the line item
`quantity`	integer	Yes	Number of units ordered (minimum 1)
`price`	decimal	Yes	Price per unit for this line
`imageName`	string	No	Filename of the product image
`externalId`	string	No	Your external reference for this line

The price field on each line item is the unit price at the time of the order. Nymble Commerce does not automatically look up prices — always supply price explicitly on each line. Set priceTier on the order to record which pricing tier applied.

Bulk order import

To import historical orders in volume, use the bulk endpoint:

POST https://api.achievemomentum.com/api/orders/bulk
Authorization: Bearer {token}
Content-Type: application/json

{
  "orders": [
    { "externalId": "ERP-ORD-1001", "customer": { ... }, "items": [ ... ] },
    { "externalId": "ERP-ORD-1002", "customer": { ... }, "items": [ ... ] }
  ]
}

Always include externalId — set it to your ERP order number or any unique identifier from your source system. Nymble Commerce uses this field for idempotency: if you re-import an order with the same externalId, Nymble Commerce updates the existing order rather than creating a duplicate. This makes bulk imports safe to re-run after failures.

​Two approaches to placing an order

​Approach 1: Cart-based checkout

​Approach 2: Direct order creation

​Order line items

​Bulk order import

Two approaches to placing an order

Approach 1: Cart-based checkout

Approach 2: Direct order creation

Order line items

Bulk order import