Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview

Create an order for the warehouse to ship

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
Authorization
AuthorizationBasic auth · headerrequired

Registered confidential integration credentials. Keep the secret server-side.

or
CookieAPI key · headerrequired

Console-managed Vault session cookie; secure cookie naming may vary by environment.

or
AuthorizationBearer token (Vault organization API key) · headerrequired

Organization-owned credential with immutable mode and Read-only or Read/write permissions. Only explicitly declared ordinary customer operations accept it. Test business access refuses until shared Test composition is available; no staff, team, key-management or protocol authority is granted.

Path parameters
orgIdstringrequired
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
Request body
requiredapplication/json
deliveryConfirmationstring
Allowed:nonedeliverysignatureadult_signaturedirect_signature
customsobject
Show properties
countryOfOriginstringrequired
matches ^[A-Z]{2}$
declaredValueobjectrequired
Show properties
amountstringrequired
matches ^(0|[1-9]\d{0,8})(\.\d{1,4})?$
descriptionstringrequired
min length 1 · max length 200
tariffCodestringrequired
matches ^(?=(?:\D*\d){4,10}\D*$)\d+(?:\.\d+)*$
customerLabelstring | null
Show properties
Any of:
string
string
null
null
linesobject[]required
min items 1 · max items 100
Show properties
Array of object
declaredUnitValueobject
Show properties
amountstringrequired
matches ^(0|[1-9]\d{0,8})(\.\d{1,4})?$
namestringrequired
min length 1 · max length 200
productIdstring
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
quantityintegerrequired
min 1 · max 100000
skustring
min length 1 · max length 200
unitPricestringrequired
matches ^(0|[1-9]\d{0,8})(\.\d{1,4})?$
orderKeystring
min length 1 · max length 128
orderNumberstring
min length 1 · max length 100
recipientobjectrequired
Show properties
addressLine1string | null
Show properties
Any of:
string
string
null
null
addressLine2string | null
Show properties
Any of:
string
string
null
null
addressLine3string | null
Show properties
Any of:
string
string
null
null
citystring | null
Show properties
Any of:
string
string
null
null
companystring | null
Show properties
Any of:
string
string
null
null
companyNamestring | null
Show properties
Any of:
string
string
null
null
contactNamestring | null
Show properties
Any of:
string
string
null
null
countrystring | null
Show properties
Any of:
string
string
null
null
countryCodestring | null
Show properties
Any of:
string
string
null
null
emailstring | null
Show properties
Any of:
string
string
null
null
namestring | null
Show properties
Any of:
string
string
null
null
phonestring | null
Show properties
Any of:
string
string
null
null
postalCodestring | null
Show properties
Any of:
string
string
null
null
regionstring | null
Show properties
Any of:
string
string
null
null
statestring | null
Show properties
Any of:
string
string
null
null
street1string | null
Show properties
Any of:
string
string
null
null
street2string | null
Show properties
Any of:
string
string
null
null
street3string | null
Show properties
Any of:
string
string
null
null
storeLinkIdstring
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
storeRefstring
min length 1 · max length 64
visibleOrderNumberstring
min length 1 · max length 100
shippingQuoteobject
Show properties
deliveryConfirmationstring
Allowed:nonedeliverysignatureadult_signaturedirect_signature
insuranceobject
Show properties
One of:
object
kindstringrequired
object
kindstringrequired
packagesobject[]required
min items 1 · max items 100
Show properties
Array of object
amountstringrequired
matches ^(0|[1-9]\d{0,8})(\.\d{1,4})?$
currencystringrequired
matches ^[A-Z]{3}$
providerstringrequired
Allowed:carrierparcelguardshipsurancexcover
reviewstringrequired
matches ^[0-9a-f]{64}$
requestedShippingServicestringrequired
min length 1 · max length 200
requestedShippingServiceReviewstringrequired
matches ^[0-9a-f]{64}$
requestedShippingServicestring
max length 200
requestedShippingServiceReviewstring
matches ^[0-9a-f]{64}$
fulfillmentSourceobject
Show properties
Any of:
object
configurationRevisionstringrequired
matches ^[1-9][0-9]*$
sourceSignaturestringrequired
matches ^[0-9a-f]{64}$
physicalOriginEquivalenceRefstringrequired
min length 1 · max length 200
v1WarehouseIdintegerrequired
max 9007199254740991
object
modestringrequired
configurationRevisionstringrequired
matches ^[1-9][0-9]*$
sourceSignaturestringrequired
matches ^[0-9a-f]{64}$
physicalOriginEquivalenceRefstringrequired
min length 1 · max length 200
externalIdentityobject
Show properties
referencestringrequired
sourcestringrequired
Allowed:original_47_column_csv
holdboolean
submissionKeystringrequired
min length 8 · max length 128 · matches ^[A-Za-z0-9_.:-]+$
Responses
200

Success

dataobjectrequired
Show properties
effectsstring[]required
operationIdstringrequired
outcomestringrequired
orderobjectrequired
Show properties
customerLabelstring | nullrequired
idstringrequired
kindstringrequired
Allowed:ordinaryredemptionreshipship_back
receiptobjectrequired
Show properties
operationIdstring | nullrequired
recordedAtstringrequired
visibleOrderNumberstring | nullrequired
cancellationobject | null
Show properties
Any of:
object
deadlineAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
eligiblebooleanrequired
null
null
currentobject | nullrequired
Show properties
Any of:
object
insuranceobject | null
Show properties
Any of:
object
insuredbooleanrequired

Whether the order asks the warehouse to insure its one parcel. False is the explicit no-additional-insurance choice.

insuredValueobject | nullrequired

Declared value to insure, independent of goods and customs values. Null when not insured.

Show properties
Any of:
object
amountstringrequired
currencystringrequired
null
null
labelobject | nullrequired

Null until the warehouse buys the one label for this order, or when the order has more than one active shipment.

Show properties
Any of:
object
insuredboolean | nullrequired

Whether the warehouse's label reports additional coverage. Null when the label does not report it.

insuredValueobject | nullrequired
Show properties
Any of:
object
amountstringrequired
currencystringrequired
null
null
providerstring | nullrequired
Show properties
Any of:
string
string
null
null
null
null
providerstring | nullrequired

Coverage provider. carrier is the carrier's declared-value coverage.

Show properties
Any of:
string
string
null
null
null
null
requestedDeliveryConfirmationstring | null
Show properties
Any of:
string
string
null
null
orderDatestring | nullrequired
providerOrderNumberstring | nullrequired
recipientNamestring | nullrequired
statusstringrequired
Allowed:on_holdreadyshippedcanceledunknown
trackingobject[]required
Show properties
Array of object
deliveryConfirmationstring | null
Show properties
Any of:
string
string
null
null
carrierstring | nullrequired
numberstringrequired
shipDatestring | nullrequired
parcelEvidenceobject
Show properties
allParcelsCollectedboolean | nullrequired
coveragestringrequired
Allowed:completeincomplete
membershipObservedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
statestringrequired
Allowed:confirmedpendingincompletestaleunavailableunknown
parcelsobject[]required
Show properties
Array of object
idstringrequired
carrierstring | nullrequired
numberstringrequired
statestringrequired
Allowed:confirmedpendingunavailableunknown
eventobject | nullrequired
Show properties
Any of:
object
detailCodestringrequired
occurredAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
reportedAtstring | nullrequired
null
null
detailCodestring | nullrequired
observedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
establishedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
refreshstringrequired
Allowed:currentunavailableunknownstale
simulatedbooleanrequired
customerNotesstring | nullrequired
holdUntilDatestring | nullrequired
itemsobject[]required
Show properties
Array of object
declaredUnitValuestring | null
namestring | nullrequired
productIdstring | null
quantityinteger | nullrequired
Show properties
Any of:
integer
integer
null
null
skustring | nullrequired
unitPricestring | null
recipientobject | nullrequired
Show properties
Any of:
object
citystring | nullrequired
companystring | nullrequired
countrystring | nullrequired
emailstring | nullrequired
namestring | nullrequired
phonestring | nullrequired
postalCodestring | nullrequired
statestring | nullrequired
street1string | nullrequired
street2string | nullrequired
null
null
revisionstringrequired
requestedShippingServicestring | nullrequired
null
null
packingExceptionobject | null

Redemption cards held while packing, each with its offer, response deadline and outcome. Null when no card was held.

Show properties
Any of:
object
estimateobject | nullrequired
Show properties
Any of:
object
amountstring | nullrequired

Estimated total in currency units. Null when a component is not yet known; unknown is never reported as zero.

asOfstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
basisstringrequired
completebooleanrequired

True only when every affected unit is applied and the amount is known. False while any unit is not applied, because that card is priced as ordered, and when the amount is null.

componentsobject[]required
Show properties
Array of object
amountstring | nullrequired
codestringrequired
currencystringrequired
min length 3 · max length 3
revisionintegerrequired
min 1 · max 9007199254740991
null
null
idstringrequired
recordedAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
resolvedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
revisionintegerrequired
min 1 · max 9007199254740991
statusstringrequired

held keeps the order from shipping until every unit settles.

Allowed:heldresolved
unitsobject[]required
Show properties
Array of object
decisionobject | nullrequired
Show properties
Any of:
object
answerstringrequired
Allowed:accept_offerremove_card
decidedAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
offerRevisionintegerrequired
min 1 · max 9007199254740991
operationIdstring | nullrequired

Operation ID of the answer that made this decision. Retry or recover an answer by this ID. Null when the warehouse or the deadline decided.

sourcestringrequired

answer is the customer's own answer; warehouse is a decision the warehouse recorded on the customer's instruction; deadline_default removes the card when the response window closes without one.

Allowed:answerwarehousedeadline_default
null
null
foundConditionstring | nullrequired
Show properties
Any of:
string
string
null
null
idstringrequired
lineIndexintegerrequired
min 0 · max 9007199254740991
offerobjectrequired
Show properties
conditionstring | nullrequired

Condition of the offered replacement card, when graded.

Show properties
Any of:
string
string
null
null
idstringrequired
kindstringrequired

replacement offers one reserved card; no_offer means the only choice is removing the card.

Allowed:replacementno_offer
productstring | nullrequired

The SKU of the offered replacement card, or null for no_offer.

readableAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
responseDeadlineAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
revisionintegerrequired
min 1 · max 9007199254740991
orderedobjectrequired
Show properties
conditionstring | nullrequired
Show properties
Any of:
string
string
null
null
productstringrequired
skustring | nullrequired
outcomestringrequired
Allowed:awaiting_answerreceivedpendingappliedrefused
packCardOrdinalinteger | nullrequired
Show properties
Any of:
integer
integer
null
null
reasonstringrequired
Allowed:condition_mismatchmissingdamaged
responseDeadlineAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
unitIndexintegerrequired
min 0 · max 9007199254740991
null
null
sourceOrderIdstring | nullrequired
placementobjectrequired
Show properties
statestringrequired
Allowed:releasedon_holdrelease_unconfirmed
metaobjectrequired
Show properties
requestIdstringrequired
default

Error

errorobjectrequired
Show properties
codestringrequired
Allowed:forbiddeninternal_errornot_foundprovider_data_invalidprovider_outcome_unknownprovider_unavailablerate_limitedstate_conflictunauthenticatedvalidation_errorwarehouse_not_ready
fieldsobject[]
Show properties
Array of object
codestringrequired
messagestringrequired
pathstringrequired
messagestringrequired
operationIdstring
metaobjectrequired
Show properties
requestIdstringrequired
Request
curl -X POST '/v1/organizations/org_example/orders' \
  -H 'Authorization: Basic YOUR_CREDENTIALS' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
}'
Response
{
  "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"
  }
}

Was this page helpful?