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

# Place a B2B Order with the Nymble Commerce API

> Step-by-step guide to creating and submitting B2B orders in Nymble Commerce, covering line items, shipping details, PO numbers, and direct ERP imports.

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.

<Steps>
  <Step title="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.

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

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

  <Step title="Add items">
    Add additional products to the cart using `POST /api/carts/{customerNumber}/{shoppingCartId}/items`.

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

    <Note>
      Adding an item whose SKU already exists in the cart increases that line item's quantity rather than creating a duplicate line.
    </Note>
  </Step>

  <Step title="Set shipping details">
    Attach a shipping address and method to the cart with `PUT /api/carts/{customerNumber}/{shoppingCartId}/shipping`.

    ```http theme={null}
    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"
      }
    }
    ```
  </Step>

  <Step title="Set a PO number">
    Attach your customer's purchase order number with `PUT /api/carts/{customerNumber}/{shoppingCartId}/po-number`.

    ```http theme={null}
    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"
    }
    ```
  </Step>

  <Step title="Complete checkout">
    Submit the cart for processing. Nymble Commerce converts the cart into an order in a single atomic operation.

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

    ```json theme={null}
    {
      "orderNumber": "ORD-2024-004821",
      "confirmationId": "conf_a3f91bc2"
    }
    ```

    After checkout, use the `orderNumber` to retrieve the full order via `GET /api/orders/{orderNumber}`.
  </Step>
</Steps>

***

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

<Steps>
  <Step title="Submit the order">
    Send a single `POST` request to `/api/orders` with the complete order payload.

    ```http theme={null}
    POST https://api.achievemomentum.com/api/orders
    Authorization: Bearer {token}
    Content-Type: application/json

    {
      "customer": {
        "customerNumber": "CUST-1042",
        "companyName": "Acme Industrial Supply",
        "email": "purchasing@acmeindustrial.com",
        "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"
    }
    ```
  </Step>

  <Step title="Confirm the order">
    A successful response returns the assigned order number and a confirmation ID.

    ```json theme={null}
    {
      "id": "ord_c4d9e1f8",
      "orderNumber": "ORD-2024-004822"
    }
    ```
  </Step>
</Steps>

***

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

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

***

## Bulk order import

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

```http theme={null}
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": [ ... ] }
  ]
}
```

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