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

# Orders API Reference for Nymble Commerce

> REST API reference for Nymble Commerce order management — create, retrieve, search, and update B2B orders, including bulk import and shipping updates.

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.

<Note>
  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.
</Note>

***

## The order object

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

<ResponseField name="id" type="string">
  Unique identifier for the order (GUID).
</ResponseField>

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

<ResponseField name="orderNumber" type="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.
</ResponseField>

<ResponseField name="orderDate" type="string (ISO 8601)">
  The date and time the order was placed. Defaults to the time of creation when omitted.
</ResponseField>

<ResponseField name="orderStatus" type="string">
  Current status of the order (e.g. `Pending`, `Processing`, `Shipped`, `Complete`, `Cancelled`).
</ResponseField>

<ResponseField name="orderType" type="string">
  Describes how the order was placed (e.g. `Direct`, `Web`, `EDI`).
</ResponseField>

<ResponseField name="poNumber" type="string">
  Customer's purchase order number.
</ResponseField>

<ResponseField name="priceTier" type="string">
  The pricing tier applied to this order (e.g. `Wholesale`, `Retail`).
</ResponseField>

<ResponseField name="currencyCode" type="string">
  ISO 4217 currency code (e.g. `USD`, `CAD`).
</ResponseField>

<ResponseField name="terms" type="string">
  Payment terms (e.g. `Net30`, `Net60`, `COD`).
</ResponseField>

<ResponseField name="channel" type="string">
  Sales channel the order came through (e.g. `Web`, `Phone`, `EDI`).
</ResponseField>

<ResponseField name="externalId" type="string">
  Your system's identifier for this order. Used to make bulk imports idempotent — re-submitting the same `externalId` updates the existing order.
</ResponseField>

<ResponseField name="notes" type="string">
  Free-text notes attached to the order.
</ResponseField>

<ResponseField name="originationCartId" type="string">
  If this order originated from a cart checkout, the ID of that cart.
</ResponseField>

<ResponseField name="customer" type="object">
  The customer on this order.

  <Expandable title="customer fields">
    <ResponseField name="billingAddress" type="object">
      Billing address with fields: `address1`, `address2`, `city`, `stateProvince`, `zipPostalCode`, `country`.
    </ResponseField>

    <ResponseField name="shippingAddress" type="object">
      Shipping address with the same fields as `billingAddress`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="primarySalesRep" type="object">
  The primary sales rep responsible for this order.

  <Expandable title="salesRep fields" />
</ResponseField>

<ResponseField name="takenBySalesRep" type="object">
  The sales rep who took the order (if different from the primary rep). Same fields as `primarySalesRep`.
</ResponseField>

<ResponseField name="items" type="array">
  Line items on the order.

  <Expandable title="item fields" />
</ResponseField>

<ResponseField name="shippingDetails" type="object">
  Shipping information for the order.

  <Expandable title="shippingDetails fields" />
</ResponseField>

***

## 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](#create-orders-in-bulk).

#### Request body

<ParamField body="customer" type="object" required>
  The customer placing the order.

  <Expandable title="customer fields">
    <ParamField body="customerNumber" type="string" required>
      The customer's account number in your system.
    </ParamField>

    <ParamField body="companyName" type="string" required>
      Customer's company name.
    </ParamField>

    <ParamField body="companyEmail" type="string">
      Primary company email address.
    </ParamField>

    <ParamField body="companyPhone" type="string">
      Primary company phone number.
    </ParamField>

    <ParamField body="companyFax" type="string">
      Company fax number.
    </ParamField>

    <ParamField body="billingAddress" type="object">
      Billing address. Fields: `address1`, `address2`, `city`, `stateProvince`, `zipPostalCode`, `country`.
    </ParamField>

    <ParamField body="shippingAddress" type="object">
      Shipping address. Same fields as `billingAddress`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="orderType" type="string" required>
  How the order was placed (e.g. `Direct`, `Web`, `EDI`).
</ParamField>

<ParamField body="poNumber" type="string" required>
  Customer's purchase order number.
</ParamField>

<ParamField body="priceTier" type="string" required>
  Pricing tier to apply (e.g. `Wholesale`, `Retail`). Must match a tier configured in your organization.
</ParamField>

<ParamField body="currencyCode" type="string" required>
  ISO 4217 currency code (e.g. `USD`).
</ParamField>

<ParamField body="primarySalesRep" type="object" required>
  The primary sales rep for this order.

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

<ParamField body="items" type="array" required>
  The line items on the order. Must contain at least one item.

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

<ParamField body="user" type="object" required>
  The user creating the order.

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

<ParamField body="shippingDetails" type="object">
  Shipping method and cost for the order.

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

<ParamField body="takenBySalesRep" type="object">
  The rep who took the order, if different from `primarySalesRep`. Same fields as `primarySalesRep`.
</ParamField>

<ParamField body="terms" type="string">
  Payment terms (e.g. `Net30`, `Net60`, `COD`).
</ParamField>

<ParamField body="notes" type="string">
  Free-text notes for this order.
</ParamField>

<ParamField body="orderStatus" type="string">
  Initial status to set on the order. Defaults to `Pending` when omitted.
</ParamField>

<ParamField body="channel" type="string">
  Sales channel (e.g. `Web`, `Phone`, `EDI`).
</ParamField>

<ParamField body="externalId" type="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.
</ParamField>

<ParamField body="tax" type="number">
  Tax amount to apply to the order.
</ParamField>

<ParamField body="originationCartId" type="string">
  If this order was generated from a cart, the cart's ID. Set automatically when using the checkout endpoint.
</ParamField>

#### Example request

```bash theme={null}
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": "orders@brightfieldsupply.com",
      "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": "javery@yourdomain.com"
    },
    "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.

```json theme={null}
{
  "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.

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

#### Request body

<ParamField body="orders" type="array" required>
  An array of order objects. Each object accepts the same fields as the single `POST /api/orders` request, plus:

  <Expandable title="additional bulk-only fields">
    <ParamField body="orderNumber" type="string">
      Supply your existing order number to preserve it on import. Re-importing the same number updates the existing record.
    </ParamField>

    <ParamField body="orderDate" type="string (ISO 8601)">
      Historical order date. Defaults to the time of import when omitted.
    </ParamField>

    <ParamField body="active" type="boolean">
      Set to `false` to soft-delete the matching order on import. Defaults to `true`.
    </ParamField>
  </Expandable>
</ParamField>

#### Example request

```bash theme={null}
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.

```json theme={null}
[
  {
    "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](#the-order-object).

#### Path parameters

<ParamField path="orderId" type="string" required>
  The unique identifier (GUID) of the order.
</ParamField>

#### Example request

```bash theme={null}
curl https://api.achievemomentum.com/api/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"
```

#### Example response

```json theme={null}
{
  "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": "orders@brightfieldsupply.com",
    "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": "javery@yourdomain.com"
  },
  "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

<ParamField query="pageNumber" type="integer">
  Page number to return. Defaults to `1`.
</ParamField>

<ParamField query="pageSize" type="integer">
  Number of results per page. Defaults to `25`.
</ParamField>

<ParamField query="sortOn" type="string">
  Field to sort results by. Defaults to `createdAt`.
</ParamField>

<ParamField query="sortDirection" type="string">
  Sort direction: `asc` or `desc`. Defaults to `asc`.
</ParamField>

<ParamField query="filters" type="array">
  An array of filter objects to narrow results. Each filter has:

  <Expandable title="filter fields">
    <ParamField query="field" type="string" required>
      The field name to filter on (e.g. `customerNumber`, `orderStatus`, `orderDate`, `poNumber`).
    </ParamField>

    <ParamField query="operator" type="string" required>
      Comparison operator. Accepted values: `startsWith`, `contains`, `notContains`, `endsWith`, `equals`, `notEquals`, `gt`, `gte`, `lt`, `lte`.
    </ParamField>

    <ParamField query="value" type="string" required>
      The value to compare against.
    </ParamField>
  </Expandable>
</ParamField>

#### Example request

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

#### Response

```json theme={null}
{
  "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

<ParamField path="orderId" type="string" required>
  The unique identifier of the order to update.
</ParamField>

#### Request body

<ParamField body="method" type="string" required>
  Shipping method name (e.g. `FedEx Ground`, `UPS 2nd Day Air`).
</ParamField>

<ParamField body="total" type="number" required>
  Shipping cost.
</ParamField>

<ParamField body="shippingAddress" type="object">
  Updated shipping address. Fields: `address1`, `address2`, `city`, `stateProvince`, `zipPostalCode`, `country`.
</ParamField>

#### Example request

```bash theme={null}
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

<ParamField path="orderId" type="string" required>
  The unique identifier of the order to update.
</ParamField>

#### Request body

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

<ParamField body="companyName" type="string" required>
  Customer's company name.
</ParamField>

<ParamField body="companyEmail" type="string">
  Primary company email address.
</ParamField>

<ParamField body="companyPhone" type="string">
  Primary company phone number.
</ParamField>

<ParamField body="companyFax" type="string">
  Company fax number.
</ParamField>

<ParamField body="billingAddress" type="object">
  Updated billing address. Fields: `address1`, `address2`, `city`, `stateProvince`, `zipPostalCode`, `country`.
</ParamField>

#### Example request

```bash theme={null}
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": "ap@brightfieldsupply.com",
    "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

<ParamField path="orderId" type="string" required>
  The unique identifier of the order.
</ParamField>

#### Request body

<ParamField body="emailAddresses" type="array" required>
  One or more email addresses to send the confirmation to.
</ParamField>

#### Example request

```bash theme={null}
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": [
      "orders@brightfieldsupply.com",
      "mgr@brightfieldsupply.com"
    ]
  }'
```

#### Response

Returns `200 OK` on success.