Test mode

Build and test your whole integration for free — test keys, test credits, simulated production, lifecycle controls and magic values.

Test mode is a complete copy of the platform for development. Use a test key (sk_test_…) and every request runs the real pipeline — validation, pricing, credit reservations, print-file generation, events and webhooks — but production is simulated: nothing is printed, shipped or charged, and your customers never get emails.

#What is separate in test mode

Because products are shared, you can build and test everything in test mode and go live by swapping the key — no need to recreate products.

#Test credits

The test wallet starts empty. Add free test credits — $1,000 per call by default:

curl -X POST https://swaglists.com/api/v1/test/wallet/fund \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 250000 }'

await fetch("https://swaglists.com/api/v1/test/wallet/fund", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ amount: 250000 }), // $2,500.00; omit for the default grant
});

requests.post(
    "https://swaglists.com/api/v1/test/wallet/fund",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"amount": 250000},  # $2,500.00; omit for the default grant
)

This endpoint needs a full-access test key. In the dashboard, switch to test mode and use Wallet → Add test credits. Orders waiting for credits (on_hold / insufficient_funds) resume automatically after credits are added — which makes this the easiest way to test your on-hold handling: create an order with an empty test wallet, then fund it.

#Simulated production

A confirmed test order goes through the same states as a live one. On its own it advances roughly like this:

Tracking numbers are generated test numbers — the carrier's tracking page will not find them.

The simulator advances on its own clock, and we check its progress periodically — just like the production of a live order. When it moves several steps between two checks, you still get every step, in order and exactly once — the same lifecycle guarantee as live orders, where data.object already shows the latest state (a late order.shipped can carry "status": "delivered").

#Advance an order on demand

Don't want to wait? POST /test/orders/{id}/advance moves an order one step forward and sends the same webhooks as a real order. Call it repeatedly: processing → in_production → shipped → delivered. The {id} can also be ext:<your external_id>.

curl -X POST https://swaglists.com/api/v1/test/orders/ext:quickstart-1001/advance \
  -H "Authorization: Bearer $API_KEY"

const res = await fetch("https://swaglists.com/api/v1/test/orders/ext:quickstart-1001/advance", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const order = await res.json();
console.log(order.status); // in_production, then shipped, then delivered

order = requests.post(
    "https://swaglists.com/api/v1/test/orders/ext:quickstart-1001/advance",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
).json()
print(order["status"])  # in_production, then shipped, then delivered

It needs the orders:write scope and returns 409 order_not_advanceable for drafts, finished orders (delivered, canceled, failed) and orders on hold for a reason that needs action (for example waiting for credits — fund the wallet instead).

Advancing an order moves it ahead of the simulator's clock. When the simulator later reaches the same steps, nothing is sent again: no second shipment, no repeated event. Only real changes — for example an updated estimated delivery date — still produce a shipment.updated.

#Simulate problems

Send a JSON body to choose what the simulated factory does next. Every outcome goes through the same pipeline as a real factory update — timeline, webhooks, credit refunds and notifications — and the simulator keeps to it afterwards:

curl -X POST https://swaglists.com/api/v1/test/orders/ext:quickstart-1001/advance \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "partial_shipment", "expected_status": "in_production" }'

An outcome that doesn't fit the order's current state returns 409 order_not_advanceable. Add expected_status — the status you last saw — to make the call safe to retry: if the order has moved on in the meantime (the simulator also advances on its own), nothing happens and the call returns 409 order_status_changed with the current status.

#Magic values

Put one of these words anywhere in recipient.name of a test order to simulate production problems (case-insensitive, e.g. "Jane FAIL_SUBMIT Doe"):

Use them to test that your integration handles failures, holds and refused cancellations — before a real customer runs into them.

#Other ways to test

• Insufficient credits — create an order with an empty test wallet. With the default setting the order is held (on_hold, hold_reason: insufficient_funds); if your account rejects such orders (Settings → Orders), the API answers 402 insufficient_funds. Then fund the wallet — a rejected order must be sent again with a new Idempotency-Key, because the original key replays the 402 for 24 hours.
• Drafts — send "confirm": false, change the draft with PATCH /orders/{id}, then POST /orders/{id}/confirm.
• Cancellations — cancel an order while it is processing (before it reaches in_production).
• Webhooks — test endpoints may use http:// URLs. POST /webhook_endpoints/{id}/test sends a webhook_endpoint.test event to one endpoint. Replay any event from Developers → Events.
• Idempotency — send the same request twice with the same Idempotency-Key and check you get Idempotent-Replayed: true.

#Limits of test mode

• Test orders are never produced, so print quality, packaging and delivery times can only be checked with a live order — order a sample to yourself before launch.
• Test tracking numbers do not work on carrier sites; the branded tracking page (tracking_page_url) works.
• Customer shipment emails are only sent for live orders.