Advance an item's lifecycle (sandbox only)

Sandbox-only. Moves a fixture item to the given lifecycle status so you can simulate intake → available → fulfillment → delivered without physical product. Emits the same webhooks the production system would. Returns 404 in production.

POST/sandbox/items/{qid}/advance

Authorization

X-API-KeyAPI key · headerrequired

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

Path parameters

qidQIDrequired

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

to_statusItemStatusrequired

Custody lifecycle for one physical item. New statuses may be added compatibly within v1.

Allowed:receiveddigitizedavailablein_fulfillmentin_transitdeliveredpending_transferreleasedwithdrawn

Responses

200The item in its new status.

One of:

GradedSlabItem

active_fulfillment_idstring<uuid> | null

The fulfillment currently holding this item, if any.

categorystring

Item category.

external_refstring | null

Your identifier for this item, echoed from the manifest line when matched.

image_assetsImageAsset[]required

Per-item intake imagery for graded slabs or catalog imagery for product items.

Show properties

Array of ImageAsset

variantstringrequired

Which view of the slab this asset shows.

Allowed:frontbacklabel

urlstring<uri>required

Permanent CDN URL.

widthintegerrequired

Pixel width.

heightintegerrequired

Pixel height.

formatstringrequired

Allowed:webpjpegpng

intake_atstring<date-time>required

When the item completed intake and entered the system.

manifest_line_idstring<uuid> | null

The expected-manifest line this item matched at intake, if any.

model_3dstring<uri> | null

Reserved for future render assets and always null today so clients can keep a stable schema.

namestringrequired

Display name, clean enough to show to your end customers.

qidQIDrequired

Vault's canonical identifier for one physical item. It is assigned at intake and remains stable for the item's lifetime.

setstring | null

card_numberstring | null

skustringrequired

Warehouse SKU. Product items reference the partner catalog; graded slabs use their graded-item SKU.

statusItemStatusrequired

Custody lifecycle for one physical item. New statuses may be added compatibly within v1.

Allowed:receiveddigitizedavailablein_fulfillmentin_transitdeliveredpending_transferreleasedwithdrawn

typestringrequired

Allowed:graded_slab

updated_atstring<date-time>required

cert_numberstringrequired

Grader certification number.

gradestringrequired

graderstringrequired

Grading company.

ProductItem

active_fulfillment_idstring<uuid> | null

The fulfillment currently holding this item, if any.

categorystring

Item category.

external_refstring | null

Your identifier for this item, echoed from the manifest line when matched.

image_assetsImageAsset[]required

Per-item intake imagery for graded slabs or catalog imagery for product items.

Show properties

Array of ImageAsset

variantstringrequired

Which view of the slab this asset shows.

Allowed:frontbacklabel

urlstring<uri>required

Permanent CDN URL.

widthintegerrequired

Pixel width.

heightintegerrequired

Pixel height.

formatstringrequired

Allowed:webpjpegpng

intake_atstring<date-time>required

When the item completed intake and entered the system.

manifest_line_idstring<uuid> | null

The expected-manifest line this item matched at intake, if any.

model_3dstring<uri> | null

Reserved for future render assets and always null today so clients can keep a stable schema.

namestringrequired

Display name, clean enough to show to your end customers.

qidQIDrequired

Vault's canonical identifier for one physical item. It is assigned at intake and remains stable for the item's lifetime.

setstring | null

card_numberstring | null

skustringrequired

Warehouse SKU. Product items reference the partner catalog; graded slabs use their graded-item SKU.

statusItemStatusrequired

Custody lifecycle for one physical item. New statuses may be added compatibly within v1.

Allowed:receiveddigitizedavailablein_fulfillmentin_transitdeliveredpending_transferreleasedwithdrawn

typestringrequired

Allowed:product

updated_atstring<date-time>required

cert_numberstring | nullrequired

Allowed:null

gradestring | nullrequired

Allowed:null

graderstring | nullrequired

Allowed: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.

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

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

Bodyapplication/json

to_statusstring*Custody lifecycle for one physical item. New statuses may be added compatibly within v1.

Request

curl -X POST "https://api.vault.stashtab.gg/v1/sandbox/items/7c9e6679-7425-40de-944b-e07fc1f90ae7/advance" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "to_status": "available"
}'

const response = await fetch("https://api.vault.stashtab.gg/v1/sandbox/items/7c9e6679-7425-40de-944b-e07fc1f90ae7/advance", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "to_status": "available"
})
});

Response

{
  "active_fulfillment_id": "bcb367cb-b94e-4e20-973d-e3de4f574083",
  "category": "sports-card",
  "external_ref": "string",
  "image_assets": [
    {
      "variant": "front",
      "url": "http://example.com",
      "width": 0,
      "height": 0,
      "format": "webp"
    }
  ],
  "intake_at": "2019-08-24T14:15:22Z",
  "manifest_line_id": "e1bcc1ed-284d-4866-b8d7-5633b41d43ea",
  "model_3d": "http://example.com",
  "name": "2018 Panini Prizm Luka Doncic",
  "qid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "set": "2018-19 Panini Prizm",
  "card_number": "280",
  "sku": "string",
  "status": "available",
  "type": "graded_slab",
  "updated_at": "2019-08-24T14:15:22Z",
  "cert_number": "string",
  "grade": "string",
  "grader": "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"
}