Create a fulfillment

Address inventory by exact QIDs or SKU-and-quantity lines. Standard fulfillment uses a recipient shipping address; withdrawal uses the organization’s primary verified address or a verified_address_id and never accepts a free-form address. Everything downstream — allocation, warehouse order, pick, pack, verification, label, and carrier handoff — happens on our side, and progress flows back through GET /fulfillments/{fulfillment_id} and the fulfillment.status.changed webhook.

Send an Idempotency-Key header; retries with the same key return the original fulfillment instead of shipping twice.

POST/fulfillments

Authorization

X-API-KeyAPI key · headerrequired

API key in format `sk_*`. Scoped to your partner account; server-side use only.

Header parameters

Idempotency-Keystringrequired

Unique key for safe retries. Reusing a key on the same endpoint returns the original result.

max length 255

Request body

requiredapplication/json

deliver_bystring<date> | null

Advisory requested delivery date.

external_refstring | null

Partner order reference echoed on the fulfillment and its events.

special_instructionsstring | null

Free text surfaced to warehouse staff during pick and pack.

Responses

201Fulfillment accepted and queued for the warehouse.

idstring<uuid>required

qidsQID[]required

statusFulfillmentStatusrequired

Fulfillment lifecycle. Returned means custody has resumed and the item will repeat intake.

Allowed:pendingprocessingshippeddeliveredcancelledexceptionreturned

processing_stageProcessingStage | null

Warehouse sub-stage while status is processing. It may be null when granular telemetry is unavailable; status is always authoritative.

Allowed:pickedpackedverifiedlabeledqueued_for_carrier

shipping_addressShippingAddress | any

Show properties

Any of:

ShippingAddress

recipient_namestringrequired

streetstringrequired

street_2string | null

citystringrequired

statestringrequired

zipstringrequired

countrystringrequired

any

any

carrierstring | null

Carrier code once the label exists.

servicestring | null

Service code once the label exists.

tracking_numberstring | null

tracking_urlstring<uri> | null

issueFulfillmentIssue | any

Show properties

Any of:

FulfillmentIssue

codestringrequired

Machine-readable issue type.

messagestringrequired

occurred_atstring<date-time>required

any

any

external_refstring | null

created_atstring<date-time>required

updated_atstring<date-time>required

typeFulfillmentTyperequired

Allowed:standardwithdrawal

special_instructionsstring | null

deliver_bystring<date> | null

verified_address_idstring<uuid> | null

400Validation failed.

codeErrorCoderequired

Stable machine-readable error vocabulary for v1.

Allowed:validation_errorstate_conflictenvironment_mismatchunsupported_destinationinvalid_api_keynot_foundrate_limited

extraobjectrequired

Structured details such as field errors or SKU availability.

messagestringrequired

Human-readable summary.

401Missing, invalid, expired, or environment-mismatched API key.

codeErrorCoderequired

Stable machine-readable error vocabulary for v1.

Allowed:validation_errorstate_conflictenvironment_mismatchunsupported_destinationinvalid_api_keynot_foundrate_limited

extraobjectrequired

Structured details such as field errors or SKU availability.

messagestringrequired

Human-readable summary.

404No such resource exists for this partner and environment.

codeErrorCoderequired

Stable machine-readable error vocabulary for v1.

Allowed:validation_errorstate_conflictenvironment_mismatchunsupported_destinationinvalid_api_keynot_foundrate_limited

extraobjectrequired

Structured details such as field errors or SKU availability.

messagestringrequired

Human-readable summary.

409An item owned by this partner is not available to ship — for example it already has an active fulfillment, or it has not completed intake. Missing, foreign-partner, and cross-environment QIDs or verified addresses return the same plain 404.

codeErrorCoderequired

Stable machine-readable error vocabulary for v1.

Allowed:validation_errorstate_conflictenvironment_mismatchunsupported_destinationinvalid_api_keynot_foundrate_limited

extraobjectrequired

Structured details such as field errors or SKU availability.

messagestringrequired

Human-readable summary.

422The request is valid but cannot be fulfilled from available inventory.

codeErrorCoderequired

Stable machine-readable error vocabulary for v1.

Allowed:validation_errorstate_conflictenvironment_mismatchunsupported_destinationinvalid_api_keynot_foundrate_limited

extraobjectrequired

Structured details such as field errors or SKU availability.

messagestringrequired

Human-readable summary.

429Rate limit exceeded for this API key.

codeErrorCoderequired

Stable machine-readable error vocabulary for v1.

Allowed:validation_errorstate_conflictenvironment_mismatchunsupported_destinationinvalid_api_keynot_foundrate_limited

extraobjectrequired

Structured details such as field errors or SKU availability.

messagestringrequired

Human-readable summary.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Parameters

Idempotency-Keyheader*Unique key for safe retries. Reusing a key on the same endpoint returns the original result.

Bodyapplication/json

deliver_bystringAdvisory requested delivery date.external_refstringPartner order reference echoed on the fulfillment and its events.special_instructionsstringFree text surfaced to warehouse staff during pick and pack.

Request

curl -X POST "https://api.vault.stashtab.gg/v1/fulfillments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "deliver_by": "2019-08-24",
  "external_ref": "string",
  "special_instructions": "string",
  "qids": [
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ],
  "shipping_address": {
    "recipient_name": "Jordan Alvarez",
    "street": "480 Cedar St",
    "street_2": "Apt 12",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "type": "standard"
}'

const response = await fetch("https://api.vault.stashtab.gg/v1/fulfillments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "deliver_by": "2019-08-24",
  "external_ref": "string",
  "special_instructions": "string",
  "qids": [
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ],
  "shipping_address": {
    "recipient_name": "Jordan Alvarez",
    "street": "480 Cedar St",
    "street_2": "Apt 12",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "type": "standard"
})
});

Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "qids": [
    "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  ],
  "status": "shipped",
  "processing_stage": "picked",
  "shipping_address": {
    "recipient_name": "Jordan Alvarez",
    "street": "480 Cedar St",
    "street_2": "Apt 12",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "carrier": "usps",
  "service": "usps_priority_mail",
  "tracking_number": "9400111899223857267224",
  "tracking_url": "http://example.com",
  "issue": {
    "code": "address_undeliverable",
    "message": "string",
    "occurred_at": "2019-08-24T14:15:22Z"
  },
  "external_ref": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "type": "standard",
  "special_instructions": "string",
  "deliver_by": "2019-08-24",
  "verified_address_id": "e92daf1e-afde-425b-aaf7-6374949522b4"
}

{
  "code": "validation_error",
  "extra": {},
  "message": "string"
}

{
  "code": "validation_error",
  "extra": {},
  "message": "string"
}

{
  "code": "validation_error",
  "extra": {},
  "message": "string"
}

{
  "code": "validation_error",
  "extra": {},
  "message": "string"
}

{
  "code": "validation_error",
  "extra": {},
  "message": "string"
}

{
  "code": "validation_error",
  "extra": {},
  "message": "string"
}