---
title: Place and track Test orders
description: Set up your own Test API key, place a manual or API order, review it, and follow simulated shipment tracking.
sidebar:
  order: 2.1
---

Use this walkthrough to try the complete order flow with synthetic inventory
before connecting Live fulfillment. The [original 47-column CSV
walkthrough](/original-47-column-csv) covers the preserved import profile.

## Open your workspace

1. Sign in to Vault with your normal Vault account.
2. Select the organization you want to test in the workspace switcher.
3. Switch to **Test** and open **Orders**. Keep the **Test** mode indicator visible throughout this walkthrough.

If the organization is missing, ask your Stashtab contact for an invitation.
An API key does not create a console account or organization membership.

## Get your Test API key

An organization Owner or Admin can manage keys in **Settings**:

1. Select the **API keys** tab. Settings opens on Company details; the tab does not have a separate URL.
2. Rotate an existing Test integration key, or create a separate key with **Test** environment and **Read/write** permission.
3. Copy the secret shown after creation or rotation. Vault cannot reveal that secret again.
4. Store the key in your integration's secret store and use it as a Bearer credential.

Rotation invalidates the old secret. Update any integration using that key.
You do not need a key sent separately by Stashtab. Return to **Test** mode
and open **Orders** before continuing; opening organization Settings does not
create a Live order.

Test and Live use the same HTTP and MCP endpoints. The key's immutable **Test**
mode selects Test data; a header cannot turn it into a Live key.

| Connection | Value |
| --- | --- |
| Vault origin / `VAULT_BASE_URL` | `https://vault.stashtab.gg` |
| HTTP API base | `https://vault.stashtab.gg/v1` |
| MCP endpoint | `https://vault.stashtab.gg/mcp` |
| Authentication | `Authorization: Bearer <your Test API key>` |

Use the organization ID supplied with your workspace setup as `ORG_ID` below.
It is an ID, not the organization name or slug. Keep it separate from the key.

```bash
export VAULT_BASE_URL="https://vault.stashtab.gg"
export ORG_ID="your-organization-id"

curl --fail-with-body \
  --header "Authorization: Bearer $VAULT_ORGANIZATION_API_KEY" \
  "$VAULT_BASE_URL/v1/organizations/$ORG_ID/inventory?limit=50"
```

Set `VAULT_ORGANIZATION_API_KEY` through your local secret manager before
running the command. A successful inventory read checks your host, organization
and key together. The [authentication guide](/authentication#organization-api-keys)
explains permission and revocation behavior.

## Place a manual order

1. In **Test** mode, open **Orders** and choose **New order**.
2. Enter a fictional recipient and complete shipping address.
3. Choose products from the current Test catalog and enter their quantities.
4. Review the fulfillment source, obtain the shipping quote and select a returned service.
5. For international shipments, review each line's **declared unit value**. This is the USD customs value per item, separate from its sale unit price.
6. Create the order. In Test, creation releases the order (status **Ready**)
   and makes it eligible for simulated shipment. To review or correct it
   first, check **Create on hold**; the order then waits **On hold** until you
   release it.

:::note[New, 2026-11-19]
Existing API and MCP callers see no change: an ordinary create still starts
**On hold**. Send `hold: false` to release the order to the warehouse at once.
Vault never buys a shipping label; the warehouse buys it after packing. Read
`placement.state` in the create response: `released`, `on_hold` or
`release_unconfirmed`. A retry with the same `submissionKey` must repeat the
same hold choice; switching between released and held conflicts.
:::

An explicit declared-value override applies only to that order. Omitting it
uses the product's current default. Changing an order never changes the
product's default declaration.

Use the catalog and available inventory currently returned for your workspace.
Test quotes and rates are examples, not agreed Live commercial terms.

## Create the same flow through HTTP or MCP

The [generated HTTP reference](/reference) and
[MCP tool catalog](/warehouse-mcp-tools.json) own the exact current schemas.
Use values returned by your own reads and quote; do not copy placeholder
product IDs, source signatures or review values into a real request.

| Step | HTTP | MCP tool |
| --- | --- | --- |
| Read inventory | `GET /v1/organizations/{orgId}/inventory` | `inventory_list` |
| Quote the exact recipient, items and quantities | `POST /v1/organizations/{orgId}/shipping-quotes` | `shipping_quotes_create` |
| Create an order On hold, or release it at once with `hold: false` | `POST /v1/organizations/{orgId}/orders` | `orders_create` |
| Read the saved order and revision | `GET /v1/organizations/{orgId}/orders/{orderId}` | `orders_get` |
| Correct an eligible held order | `PATCH /v1/organizations/{orgId}/orders/{orderId}` | `orders_update` |
| Release the reviewed order | `POST /v1/organizations/{orgId}/orders/{orderId}/release` | `orders_release` |

Carry the quote's exact selection, service, review values and fulfillment
source into creation. Review freshness is checked again before the effect.
The create response's `placement.state` is `released`, `on_hold` or
`release_unconfirmed`. `release_unconfirmed` means the order exists but its
release could not be confirmed; read the order before any other write. A
retry with the same submission key must repeat the same hold choice;
switching between released and held conflicts. The
response includes the order and its warehouse order number
(`order.current.providerOrderNumber`), never tracking.
For MCP client connection instructions, see [MCP setup](https://docs.stashtab.gg/mcp).
An organization key can call its permitted tools over the same MCP endpoint.

Use a stable external order reference. To address the same business order as
an original 47-column CSV import, use the fixed source shown in
[CSV replay identity](/original-47-column-csv#re-imports-corrections-and-api-identity)
and the CSV's exact `Order #` as its reference. An identical initial intent
returns the original order and receipt. Changed content under the same identity
conflicts instead of creating another order.

Keep create, edit and release submission keys separate. After a correction,
read the latest order revision before release. Replaying an original create
does not undo an accepted correction. See [outcomes and errors](/reliability)
if a request times out or its result is unknown; changing the submission key
is not a safe retry.

## Review, correct and release

In **Test** mode, open the order from **Orders** and
check the recipient, products, quantities, declarations and selected service.
Correct eligible orders while they are **On hold**, so create the order on hold
when you expect to correct it. API updates send the
complete intended item list and the current revision, rather than a partial
line patch.

When a held order is correct, choose **Release** and confirm the reviewed
action. In Test this makes the order eligible for simulated shipment. A quote,
CSV preview, CSV import, API or MCP create request without `hold: false` or
copied recipient update does not release an order.

## Simulate shipment and check tracking

An organization Owner or Admin can run the simulator:

1. In **Test** mode, open **Test actions**.
2. In **Simulate a shipment**, choose your released Test order.
3. Select **Simulate shipment** once, then read the result.
4. Return to the order. Check its Shipped status and `TEST-...` tracking number.

If an order is missing from the simulator, check that you released it and are
still in the same organization's active Test workspace. Ask an Owner or Admin
to run the action if your role cannot use Test actions. An API key does not
grant access to that administration page.

Read the same order through `orders_get` or HTTP:

```bash
curl --fail-with-body \
  --header "Authorization: Bearer $VAULT_ORGANIZATION_API_KEY" \
  "$VAULT_BASE_URL/v1/organizations/$ORG_ID/orders/$ORDER_ID"
```

Set `ORDER_ID` to the saved order's ID. Treat empty or unavailable tracking as
the reported current fact; it does not establish shipment or delivery.

From order details, choose **Copy recipient update** to copy a confirmation
and the tracking currently available. Send that text through your own channel.
Vault does not automatically email that recipient update.

## Simulate carrier collection

A simulated shipment alone does not count as collected. Its
`current.parcelEvidence` stays `incomplete` and `allParcelsCollected` stays
`null`. To test the step where the carrier has the parcel, an organization
Owner or Admin can simulate a collection scan:

1. In **Test** mode, open **Test actions**.
2. In **Simulate carrier collection**, choose your shipped Test order.
3. Select **Simulate carrier collection** once, then read the result.

You can also open the shipped Test order and choose **Simulate carrier
collection** in **Order controls**. The action is disabled, with the reason,
when the order has no simulated shipment or every parcel is already collected.

Read the order again through `orders_get` or HTTP. The simulated scan counts
toward collection in Test:

- `current.parcelEvidence.state` is `confirmed`.
- `current.parcelEvidence.allParcelsCollected` is `true`.
- Each `parcels[].event` has detail code `SIMULATED_COLLECTION` and the scan time.
- Each parcel keeps `simulated: true`, so it is never real carrier proof.

The order status stays Shipped, as it does after a real collection scan. Live
orders cannot use this action, and simulated events never count for a Live
order. The [polling guide](/polling#read-carrier-collection-evidence) explains
each evidence field.

## Try a redemption packing exception

The [packing exceptions guide](/packing-exceptions#test-walkthrough) has a
Test walkthrough for a redemption that the warehouse cannot pack as ordered.
An organization Owner or Admin records the exception from the Test order's
**Order controls** with **Record packing exception**, which simulates the
warehouse step. Then you read the exception and answer each card with your Test
key.

## Test boundaries and reset

Test inventory, shipping quotes, documents and tracking are synthetic. This
walkthrough does not buy carrier labels, dispatch physical goods or create
Live billing charges. Live catalog, customs, packing, origin, carrier services
and commercial terms need their own setup and verification.

Coordinate any workspace reset with your team. A reset removes the active
Test orders, imports and receipts and starts a new Test generation. Old order
IDs and receipts do not become Live data or valid new-generation orders.
Do not reset the workspace as a retry for an unknown operation.

If you cannot complete a step, send your Stashtab contact the organization,
order or operation ID, time and visible error. Keep API keys and recipient
details out of that report.
