Orders API Reference for Nymble Commerce

The Orders API manages B2B orders from creation through fulfillment. Orders can originate from cart checkout or be created directly via the API for imports and assisted ordering. Every order belongs to a single tenant organization, identified automatically from your bearer token.

For cart-based ordering, use POST /api/carts/{cartId}/checkout instead of creating orders directly. Use the Orders API when you need to import historical orders, build assisted-ordering tools, or create orders programmatically without a cart session.

The order object

Every endpoint that returns order data uses the same order object shape.

string

Unique identifier for the order (GUID).

string

The tenant organization this order belongs to.

string

Human-readable order number generated by Nymble Commerce (e.g. ORD-00412). Supply your own on bulk import to preserve existing numbers — re-importing the same number updates the record rather than creating a duplicate.

string (ISO 8601)

The date and time the order was placed. Defaults to the time of creation when omitted.

string

Current status of the order (e.g. Pending, Processing, Shipped, Complete, Cancelled).

string

Describes how the order was placed (e.g. Direct, Web, EDI).

string

Customer’s purchase order number.

string

The pricing tier applied to this order (e.g. Wholesale, Retail).

string

ISO 4217 currency code (e.g. USD, CAD).

string

Payment terms (e.g. Net30, Net60, COD).

string

Sales channel the order came through (e.g. Web, Phone, EDI).

string

Your system’s identifier for this order. Used to make bulk imports idempotent — re-submitting the same externalId updates the existing order.

string

Free-text notes attached to the order.

string

If this order originated from a cart checkout, the ID of that cart.

object

The customer on this order.

Show customer fields

object

Billing address with fields: address1, address2, city, stateProvince, zipPostalCode, country.

object

Shipping address with the same fields as billingAddress.

object

The primary sales rep responsible for this order.

Show salesRep fields

object

The sales rep who took the order (if different from the primary rep). Same fields as primarySalesRep.

array

Line items on the order.

Show item fields

object

Shipping information for the order.

Show shippingDetails fields

Endpoints

Create an order

Creates a single order. Use this endpoint for assisted ordering or programmatic order creation. To import multiple historical orders in one call, use the bulk endpoint.

Request body

object

required

The customer placing the order.

Show customer fields

string

required

The customer’s account number in your system.

string

required

Customer’s company name.

string

Primary company email address.

string

Primary company phone number.

string

Company fax number.

object

Billing address. Fields: address1, address2, city, stateProvince, zipPostalCode, country.

object

Shipping address. Same fields as billingAddress.

string

required

How the order was placed (e.g. Direct, Web, EDI).

string

required

Customer’s purchase order number.

string

required

Pricing tier to apply (e.g. Wholesale, Retail). Must match a tier configured in your organization.

string

required

ISO 4217 currency code (e.g. USD).

object

required

The primary sales rep for this order.

Show salesRep fields

array

required

The line items on the order. Must contain at least one item.

Show item fields

object

required

The user creating the order.

Show user fields

object

Shipping method and cost for the order.

Show shippingDetails fields

object

The rep who took the order, if different from primarySalesRep. Same fields as primarySalesRep.

string

Payment terms (e.g. Net30, Net60, COD).

string

Free-text notes for this order.

string

Initial status to set on the order. Defaults to Pending when omitted.

string

Sales channel (e.g. Web, Phone, EDI).

string

Your system’s identifier for this order. Makes the creation idempotent — submitting the same externalId again updates the existing order instead of creating a new one.

number

Tax amount to apply to the order.

string

If this order was generated from a cart, the cart’s ID. Set automatically when using the checkout endpoint.

Example request

curl -X POST https://api.achievemomentum.com/api/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "customerNumber": "CUST-1042",
      "companyName": "Brightfield Supply Co.",
      "companyEmail": "[email protected]",
      "companyPhone": "555-400-1200",
      "billingAddress": {
        "address1": "300 Commerce Blvd",
        "city": "Portland",
        "stateProvince": "OR",
        "zipPostalCode": "97201",
        "country": "US"
      },
      "shippingAddress": {
        "address1": "300 Commerce Blvd",
        "city": "Portland",
        "stateProvince": "OR",
        "zipPostalCode": "97201",
        "country": "US"
      }
    },
    "orderType": "Direct",
    "poNumber": "PO-88412",
    "priceTier": "Wholesale",
    "currencyCode": "USD",
    "primarySalesRep": {
      "repNumber": "REP-007",
      "firstName": "Jordan",
      "lastName": "Avery",
      "email": "[email protected]"
    },
    "items": [
      {
        "sku": "WDG-BLU-L",
        "productName": "Widget Blue Large",
        "quantity": 24,
        "price": 12.50
      },
      {
        "sku": "WDG-RED-M",
        "productName": "Widget Red Medium",
        "quantity": 12,
        "price": 11.00
      }
    ],
    "user": {
      "userId": "usr_abc123",
      "userType": "SalesRep"
    },
    "shippingDetails": {
      "method": "FedEx Ground",
      "total": 18.50
    },
    "terms": "Net30",
    "channel": "Phone",
    "externalId": "ERP-ORDER-99821",
    "tax": 28.80,
    "notes": "Customer requested delivery before end of month."
  }'

Response

Returns 201 Created with the new order’s ID and order number.

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orderNumber": "ORD-00412"
  },
  "links": [
    {
      "rel": "self",
      "href": "/api/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

Create orders in bulk

Creates multiple orders in a single request. Designed for importing historical orders from an ERP or legacy system. Each order in the array follows the same shape as the single-order request body, with the addition of an optional orderNumber field.

Use externalId on each order to make the import idempotent. Re-submitting the same payload will update existing orders rather than create duplicates.

Request body

array

required

An array of order objects. Each object accepts the same fields as the single POST /api/orders request, plus:

Show additional bulk-only fields

string

Supply your existing order number to preserve it on import. Re-importing the same number updates the existing record.

string (ISO 8601)

Historical order date. Defaults to the time of import when omitted.

boolean

Set to false to soft-delete the matching order on import. Defaults to true.

Example request

curl -X POST https://api.achievemomentum.com/api/orders/bulk \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "orderNumber": "ORD-2023-001",
        "orderDate": "2023-06-15T09:30:00Z",
        "externalId": "ERP-10001",
        "customer": {
          "customerNumber": "CUST-0055",
          "companyName": "Apex Distributors"
        },
        "orderType": "EDI",
        "poNumber": "PO-55001",
        "priceTier": "Wholesale",
        "currencyCode": "USD",
        "primarySalesRep": { "repNumber": "REP-003" },
        "items": [
          { "sku": "PART-A1", "productName": "Part A1", "quantity": 100, "price": 4.25 }
        ],
        "user": { "userType": "Admin" },
        "orderStatus": "Complete",
        "terms": "Net60"
      },
      {
        "orderNumber": "ORD-2023-002",
        "orderDate": "2023-07-02T14:00:00Z",
        "externalId": "ERP-10002",
        "customer": {
          "customerNumber": "CUST-0082",
          "companyName": "Cornerstone Goods"
        },
        "orderType": "Direct",
        "poNumber": "PO-82001",
        "priceTier": "Wholesale",
        "currencyCode": "USD",
        "primarySalesRep": { "repNumber": "REP-007" },
        "items": [
          { "sku": "PART-B3", "productName": "Part B3", "quantity": 50, "price": 9.99 }
        ],
        "user": { "userType": "Admin" }
      }
    ]
  }'

Response

Returns 201 Created with an array of results, one per submitted order.

[
  {
    "data": { "id": "ord-uuid-001", "orderNumber": "ORD-2023-001" },
    "links": [{ "rel": "self", "href": "/api/orders/ord-uuid-001" }]
  },
  {
    "data": { "id": "ord-uuid-002", "orderNumber": "ORD-2023-002" },
    "links": [{ "rel": "self", "href": "/api/orders/ord-uuid-002" }]
  }
]

Get an order

Retrieves a single order by its ID. Returns the full order object.

Path parameters

string

required

The unique identifier (GUID) of the order.

Example request

curl https://api.achievemomentum.com/api/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organizationId": "org_xyz",
  "orderNumber": "ORD-00412",
  "orderDate": "2024-03-15T10:22:00Z",
  "orderStatus": "Processing",
  "orderType": "Direct",
  "poNumber": "PO-88412",
  "priceTier": "Wholesale",
  "currencyCode": "USD",
  "terms": "Net30",
  "channel": "Phone",
  "externalId": "ERP-ORDER-99821",
  "notes": "Customer requested delivery before end of month.",
  "customer": {
    "customerNumber": "CUST-1042",
    "companyName": "Brightfield Supply Co.",
    "companyEmail": "[email protected]",
    "companyPhone": "555-400-1200",
    "billingAddress": {
      "address1": "300 Commerce Blvd",
      "city": "Portland",
      "stateProvince": "OR",
      "zipPostalCode": "97201",
      "country": "US"
    }
  },
  "primarySalesRep": {
    "repNumber": "REP-007",
    "firstName": "Jordan",
    "lastName": "Avery",
    "fullName": "Jordan Avery",
    "email": "[email protected]"
  },
  "items": [
    {
      "sku": "WDG-BLU-L",
      "productName": "Widget Blue Large",
      "quantity": 24,
      "price": 12.50,
      "priceFormatted": "$12.50",
      "subTotal": 300.00,
      "subTotalFormatted": "$300.00",
      "discountAmount": 0,
      "minimumOrderQuantity": 1,
      "quantityIncrement": 1
    }
  ],
  "shippingDetails": {
    "method": "FedEx Ground",
    "total": 18.50,
    "totalFormatted": "$18.50"
  },
  "tax": 28.80,
  "taxFormatted": "$28.80",
  "subtotal": 432.00,
  "subtotalFormatted": "$432.00",
  "orderTotal": 479.30,
  "orderTotalFormatted": "$479.30",
  "discountAmount": 0,
  "active": true,
  "createdAt": "2024-03-15T10:22:00Z",
  "updatedAt": "2024-03-15T10:22:00Z"
}

Search orders

Returns a paginated list of orders. Use query parameters to filter, sort, and paginate results. Each order in the response is paired with the invoice numbers of any invoices generated against it.

Query parameters

integer

Page number to return. Defaults to 1.

integer

Number of results per page. Defaults to 25.

string

Field to sort results by. Defaults to createdAt.

string

Sort direction: asc or desc. Defaults to asc.

array

An array of filter objects to narrow results. Each filter has:

Show filter fields

string

required

The field name to filter on (e.g. customerNumber, orderStatus, orderDate, poNumber).

string

required

Comparison operator. Accepted values: startsWith, contains, notContains, endsWith, equals, notEquals, gt, gte, lt, lte.

string

required

The value to compare against.

Example request

curl "https://api.achievemomentum.com/api/orders?pageNumber=1&pageSize=20&sortOn=orderDate&sortDirection=desc" \
  -H "Authorization: Bearer <token>"

Response

{
  "items": [ /* array of order objects, each with associated invoiceNumbers */ ],
  "totalCount": 47,
  "pageNumber": 1,
  "pageSize": 20,
  "totalPages": 3
}

Update shipping details

Updates the shipping method, cost, and/or address on an existing order. Use this after order creation to attach or revise shipping information.

Path parameters

string

required

The unique identifier of the order to update.

Request body

string

required

Shipping method name (e.g. FedEx Ground, UPS 2nd Day Air).

number

required

Shipping cost.

object

Updated shipping address. Fields: address1, address2, city, stateProvince, zipPostalCode, country.

Example request

curl -X PUT https://api.achievemomentum.com/api/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/shipping \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "UPS Next Day Air",
    "total": 42.00,
    "shippingAddress": {
      "address1": "1200 Industrial Pkwy",
      "city": "Salem",
      "stateProvince": "OR",
      "zipPostalCode": "97301",
      "country": "US"
    }
  }'

Response

Returns 200 OK with the updated order object.

Update customer details

Updates the customer information attached to an order. Use this to correct customer data or reassign an order to a different account.

Path parameters

string

required

The unique identifier of the order to update.

Request body

string

required

The customer’s account number.

string

required

Customer’s company name.

string

Primary company email address.

string

Primary company phone number.

string

Company fax number.

object

Updated billing address. Fields: address1, address2, city, stateProvince, zipPostalCode, country.

Example request

curl -X PUT https://api.achievemomentum.com/api/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/customer \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerNumber": "CUST-1042",
    "companyName": "Brightfield Supply Co. (Updated)",
    "companyEmail": "[email protected]",
    "companyPhone": "555-400-1201",
    "billingAddress": {
      "address1": "301 Commerce Blvd",
      "city": "Portland",
      "stateProvince": "OR",
      "zipPostalCode": "97201",
      "country": "US"
    }
  }'

Response

Returns 200 OK with the updated order object.

Send order confirmation email

Sends an order confirmation email to one or more recipients. The email uses your organization’s configured template and branding.

Path parameters

string

required

The unique identifier of the order.

Request body

array

required

One or more email addresses to send the confirmation to.

Example request

curl -X POST https://api.achievemomentum.com/api/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890/email \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddresses": [
      "[email protected]",
      "[email protected]"
    ]
  }'

Response

Returns 200 OK on success.

Overview

Auth & Users

Catalog

Commerce

Analytics & Tools

Orders API Reference for Nymble Commerce

The order object

Endpoints

Create an order

Request body

Example request

Response

Create orders in bulk

Request body

Example request

Response

Get an order

Path parameters

Example request

Example response

Search orders

Query parameters

Example request

Response

Update shipping details

Path parameters

Request body

Example request

Response

Update customer details

Path parameters

Request body

Example request

Response

Send order confirmation email

Path parameters

Request body

Example request

Response

​The order object

​Endpoints

​Create an order

​Request body

​Example request

​Response

​Create orders in bulk

​Request body

​Example request

​Response

​Get an order

​Path parameters

​Example request

​Example response

​Search orders

​Query parameters

​Example request

​Response

​Update shipping details

​Path parameters

​Request body

​Example request

​Response

​Update customer details

​Path parameters

​Request body

​Example request

​Response

​Send order confirmation email

​Path parameters

​Request body

​Example request

​Response

The order object

Endpoints

Create an order

Request body

Example request

Response

Create orders in bulk

Request body

Example request

Response

Get an order

Path parameters

Example request

Example response

Search orders

Query parameters

Example request

Response

Update shipping details

Path parameters

Request body

Example request

Response

Update customer details

Path parameters

Request body

Example request

Response

Send order confirmation email

Path parameters

Request body

Example request

Response