---
search:
  tags:
    - Orders
    - POST
seo:
  description: >-
    Creates one ordinary order with the requested service.… Reference for the
    POST /v1/organizations/{orgId}/orders endpoint in the Stashtab Vault
    Warehouse API.
sidebar:
  label: Create an order for the warehouse to ship
  badge: POST
title: Create an order for the warehouse to ship
type: openapi-operation
---
Creates one ordinary order with the requested service. It starts On hold for a later explicit release unless hold is false; set hold to false to release it to the warehouse as awaiting shipment at once. A retry with the same submission key must repeat the same hold value, and a changed value conflicts. A retry more than five minutes after the original creation never sends a new release and reports the order's current state. Vault never buys a shipping label: the warehouse buys it after packing, and its tracking then appears in order.current.tracking on later reads. placement.state is released, on_hold, or release_unconfirmed when the order was created but its release could not be verified. A deliveryConfirmation request must match the priced shippingQuote selection. Omit the top-level value to carry the selection unchanged. Changed confirmation conflicts with the original intent. For the priced flow, preview the recipient and physical source, call createShippingQuote with those same products, quantities and recipient, choose a quote, and pass its exact selection as shippingQuote and its fulfillmentSource unchanged. An item may set declaredUnitValue.amount in USD independently of unitPrice; omitting it uses the verified product declaration. The top-level customs object remains only a compatibility fallback for older callers. Create rechecks eligibility, packing, pricing and service identity before sending; changed estimates require a new quote and explicit selection. Quotes are estimates, not price locks or label purchases. A quote prices one parcel at the order's total weight. The ordinary Vault web form requires this priced choice. Existing unquoted HTTP/MCP clients remain compatible: a named service requires preview's requestedService.selected and requestedService.review as requestedShippingService and requestedShippingServiceReview; omitting both requested-service fields retains their legacy warehouse-choice behavior. New submissions require a current fulfillmentSource. Confirmed legacy submissions replay their original receipt; unknown outcomes are never resent. The original 47-column CSV profile uses externalIdentity with source original_47_column_csv and the original Order # as reference (1–100 characters after trimming outer whitespace). It derives orderKey when omitted and recognizes equivalent initial content across CSV, API, MCP and replacement credentials. A changed recipient, item, declared customs value, quantity or requested service conflicts and requires a deliberate permitted held-order edit. An API or MCP create that names a CSV reference and sets hold to false is released at once; only held orders can be corrected.

`POST /v1/organizations/{orgId}/orders`

**Request body** (`application/json`, required)

- `deliveryConfirmation` (string)
- `customs` (object)
- `customerLabel` (string | null)
- `lines` (object[], required)
- `orderKey` (string)
- `orderNumber` (string)
- `recipient` (object, required)
- `storeLinkId` (string)
- `storeRef` (string)
- `visibleOrderNumber` (string)
- `shippingQuote` (object)
- `requestedShippingService` (string)
- `requestedShippingServiceReview` (string)
- `fulfillmentSource` (object)
- `externalIdentity` (object)
- `hold` (boolean)
- `submissionKey` (string, required)

Request body example:

```json
{
  "customerLabel": "Warehouse demo",
  "lines": [
    {
      "declaredUnitValue": {
        "amount": "1.25"
      },
      "name": "Demo card sleeve",
      "productId": "product_order_demo",
      "quantity": 2,
      "sku": "ORDER-DEMO-SLEEVE",
      "unitPrice": "1.25"
    }
  ],
  "orderKey": "create-order-demo-1",
  "orderNumber": "ORDER-DEMO-1",
  "recipient": {
    "city": "Toronto",
    "country": "CA",
    "email": "taylor@example.test",
    "name": "Taylor Example",
    "phone": "4165550100",
    "postalCode": "M5V 2T6",
    "state": "ON",
    "street1": "1 Example Street"
  },
  "storeRef": "store_example",
  "shippingQuote": {
    "deliveryConfirmation": "none",
    "insurance": {
      "kind": "native",
      "packages": [
        {
          "amount": "45.00",
          "currency": "USD"
        }
      ],
      "provider": "carrier"
    },
    "review": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "requestedShippingService": "Example Ground",
    "requestedShippingServiceReview": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  },
  "fulfillmentSource": {
    "configurationRevision": "2",
    "sourceSignature": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "physicalOriginEquivalenceRef": "physical_demo",
    "v1WarehouseId": 401
  },
  "hold": false,
  "submissionKey": "create-order-demo-1"
}
```

**Responses**

- `200` — Success
- `default` — Error

Response example, 200:

```json
{
  "data": {
    "effects": [
      "order_created",
      "order_associated",
      "order_released"
    ],
    "operationId": "operation_create_order_demo",
    "outcome": "confirmed",
    "order": {
      "customerLabel": "Warehouse demo",
      "id": "order_create_demo",
      "kind": "ordinary",
      "receipt": {
        "operationId": "operation_create_order_demo",
        "recordedAt": "2026-10-02T00:00:00.000Z"
      },
      "visibleOrderNumber": "ORDER-DEMO-1",
      "current": {
        "insurance": {
          "insured": true,
          "insuredValue": {
            "amount": "45.00",
            "currency": "USD"
          },
          "label": null,
          "provider": "carrier"
        },
        "orderDate": "2026-10-02",
        "providerOrderNumber": "demo-provider-create-order",
        "recipientName": "Taylor Example",
        "status": "ready",
        "tracking": [],
        "customerNotes": null,
        "holdUntilDate": null,
        "items": [
          {
            "name": "Demo card sleeve",
            "productId": null,
            "quantity": 2,
            "sku": "ORDER-DEMO-SLEEVE",
            "unitPrice": "1.25"
          }
        ],
        "recipient": {
          "city": "Toronto",
          "company": null,
          "country": "CA",
          "email": "taylor@example.test",
          "name": "Taylor Example",
          "phone": "4165550100",
          "postalCode": "M5V 2T6",
          "state": "ON",
          "street1": "1 Example Street",
          "street2": null
        },
        "revision": "demo-create-revision-1",
        "requestedShippingService": "Example Ground"
      },
      "sourceOrderId": null
    },
    "placement": {
      "state": "released"
    }
  },
  "meta": {
    "requestId": "example-createOrder"
  }
}
```
