---
seo:
  description: >-
    The Vault by Stashtab API lets partner applications declare expected
    arrivals, observe every physical item held in custody, request parcel
    fulfillment or…
sidebar:
  label: Overview
title: Vault by Stashtab API
---
The Vault by Stashtab API lets partner applications declare expected
arrivals, observe every physical item held in custody, request parcel
fulfillment or withdrawal, transfer items through supported exit paths, and
receive signed event notifications. Responses are suitable for mirroring into
partner systems.

## Authentication

Every request is authenticated with an API key in the `X-API-Key` header.
Keys are managed in the partner console, are named, may carry an expiry, and
can be deactivated at any time. Keys must only be used server-side.

## Idempotency

Every POST accepts an `Idempotency-Key` header. Reusing the same key on the
same endpoint returns the original result instead of repeating the action.
Keys are retained long enough for any reasonable retry policy.

## Forward compatibility

Within v1, new fields, enum values, error codes, item types, and endpoints are
non-breaking additions. Clients must tolerate values they do not yet know.
Breaking changes use a new version prefix and are announced in advance.

## Environments & data partitioning

Production and sandbox use separate hosts and fully partitioned data.
`sk_live_*` keys work only on production and `sk_test_*` keys work only on
sandbox. Using a key on the wrong host returns `401 environment_mismatch`.
A QID from the other environment returns a plain `404` so existence is not
disclosed.

## Error codes

Errors use a stable machine-readable vocabulary: `validation_error`,
`state_conflict`, `environment_mismatch`, `unsupported_destination`,
`invalid_api_key`, `not_found`, and `rate_limited`. Each operation lists
its possible HTTP error codes in `x-error-codes`; partial-success batch responses
carry row-result codes in their result body.

## Pagination

Bounded collections use a page envelope with `page` and `page_size` query
parameters. The event stream uses the `starting_after` cursor instead.

## Rate limits

Requests are rate limited per API key. A `429` response carries
`Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
`X-RateLimit-Reset`. Default limits are confirmed during onboarding and
sized to the integration.

## Item lifecycle

Items move through intake and custody before they ship, withdraw, or complete
a sell-back transfer. Returned items re-enter at `received` and repeat intake.
The status vocabulary is additive under the forward-compatibility policy.

## Fulfillment lifecycle

Fulfillments move through `pending`, `processing`, `shipped`, and
`delivered`, or end as `cancelled`, `exception`, or `returned`.
`processing_stage` may be null when granular telemetry is unavailable;
`status` is always authoritative.

<ApiOverview source="reference" />

## Intake

Digitization completions, with the same payloads available through signed events.

<ApiTagOperations source="reference" tag="intake" />

## Manifests

Declare immutable expected arrivals and reconcile physical intake against them.

<ApiTagOperations source="reference" tag="manifests" />

## Inventory

Inspect physical-item custody records and SKU-level computed stock.

<ApiTagOperations source="reference" tag="inventory" />

## Fulfillment

Create parcel shipments or withdrawals and follow their execution.

<ApiTagOperations source="reference" tag="fulfillment" />

## Webhooks

Manage signed event delivery and replay the event stream.

<ApiTagOperations source="reference" tag="webhooks" />

## Sandbox

Sandbox API keys are issued during partner onboarding. Sandbox access is not self-service, but the full contract is public so an integration can be planned before keys are issued.

<ApiTagOperations source="reference" tag="sandbox" />

## Transfers

Request and follow sell-back transfers for items in custody.

<ApiTagOperations source="reference" tag="transfers" />

## Account

Inspect the authenticated partner organization and API key metadata.

<ApiTagOperations source="reference" tag="account" />

## Products

Define catalog records before product inventory reaches the vault.

<ApiTagOperations source="reference" tag="products" />