Place and track Test orders
Set up your own Test API key, place a manual or API order, review it, and follow simulated shipment tracking.
Use this walkthrough to try the complete order flow with synthetic inventory before connecting Live fulfillment. The original 47-column CSV walkthrough covers the preserved import profile.
Open your workspace
- Sign in to Vault with your normal Vault account.
- Select the organization you want to test in the workspace switcher.
- 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:
- Select the API keys tab. Settings opens on Company details; the tab does not have a separate URL.
- Rotate an existing Test integration key, or create a separate key with Test environment and Read/write permission.
- Copy the secret shown after creation or rotation. Vault cannot reveal that secret again.
- 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.
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
explains permission and revocation behavior.
Place a manual order
- In Test mode, open Orders and choose New order.
- Enter a fictional recipient and complete shipping address.
- Choose products from the current Test catalog and enter their quantities.
- Review the fulfillment source, obtain the shipping quote and select a returned service.
- For international shipments, review each line’s declared unit value. This is the USD customs value per item, separate from its sale unit price.
- 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.
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 and MCP tool catalog 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.
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
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 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:
- In Test mode, open Test actions.
- In Simulate a shipment, choose your released Test order.
- Select Simulate shipment once, then read the result.
- 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:
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:
- In Test mode, open Test actions.
- In Simulate carrier collection, choose your shipped Test order.
- 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.stateisconfirmed.current.parcelEvidence.allParcelsCollectedistrue.- Each
parcels[].eventhas detail codeSIMULATED_COLLECTIONand 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 explains each evidence field.
Try a redemption packing exception
The packing exceptions guide 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.