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

Create fulfillments from CSV

Upload a UTF-8 CSV with a header row. Columns: qid, sku, quantity, recipient_name, street, street_2, city, state, zip, country, external_ref, special_instructions, deliver_by. Each row provides either qid or sku plus quantity, never both forms. Missing, foreign-partner, and cross-environment QIDs fail that row with the same generic not_found code and no existence detail; unsupported destinations fail that row with unsupported_destination.

POST/fulfillments/csv
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
requiredmultipart/form-data
filestringrequired
Responses
200Rows processed independently.
createdFulfillment[]required
Show properties
Array of Fulfillment
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
errorsCsvRowError[]required
Show properties
Array of CsvRowError
codeErrorCoderequired
Stable machine-readable error vocabulary for v1.
Allowed:validation_errorstate_conflictenvironment_mismatchunsupported_destinationinvalid_api_keynot_foundrate_limited
fieldsobjectrequired
messagestringrequired
rowintegerrequired
One-based CSV data-row number, excluding the header.
min 1
totalsCsvBatchTotalsrequired
Show properties
createdintegerrequired
min 0
failedintegerrequired
min 0
submittedintegerrequired
min 0
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.
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
Authorization
Parameters
Bodymultipart/form-data
Request
curl -X POST "https://api.vault.stashtab.gg/v1/fulfillments/csv" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: multipart/form-data" \
  -d '{
  "file": "string"
}'
Response
{
  "created": [
    {
      "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"
    }
  ],
  "errors": [
    {
      "code": "validation_error",
      "fields": {
        "property1": [
          "string"
        ],
        "property2": [
          "string"
        ]
      },
      "message": "string",
      "row": 1
    }
  ],
  "totals": {
    "created": 0,
    "failed": 0,
    "submitted": 0
  }
}