Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

  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.

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

  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.

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:

  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:

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

Was this page helpful?