Play photographer in Test mode and throw real-world surprises at your integration.
Real photographers submit corrections at midnight, forget the order number and let downloads expire. The simulator lets you rehearse all of that on purpose, so your integration has seen every surprise before it meets a real one.
The simulator endpoints need a test key with sandbox:manage. Everything else
in Test mode (reads, downloads, receipts, confirmation, unlock and webhooks)
uses the normal endpoints and scopes.
Every simulator write accepts an optional Idempotency-Key. Send one whenever
your code might retry:
uuidgen makes a
good one.Idempotency-Replayed: true. Nothing happens twice.409 IDEMPOTENCY_CONFLICT.Every snippet below first stores a new key in COMMAND_ID. To retry a command,
run its curl line again with the same COMMAND_ID. A new value makes a new
command.
In Test mode, these writes run one at a time per lab: every simulator command,
download links, receipts, confirmation, unlock and webhook secret rotation.
Rendering files, recording a webhook result and the daily cleanup wait their
turn too. While one is running, another answers 409 SANDBOX_BUSY. Retry the
same request shortly, with its original idempotency key where it has one.
Export reads, the event feed and creating, changing, deleting or testing a webhook endpoint never wait for this.
COMMAND_ID="$(uuidgen)"
curl --fail-with-body -sS -X POST "$API/sandbox/exports" \
-H "Authorization: Bearer $SPREADU_KEY" -H "Idempotency-Key: $COMMAND_ID" \
-H "Content-Type: application/json" -d '{"scenario":"pages-pdf"}'Returns { "reference": "...", "revision": 1 } while the files are being
generated. Pick a scenario from the
scenario table.
The photographer found a typo. This withdraws the published revision and
queues revision n+1 under the same export reference.
COMMAND_ID="$(uuidgen)"
curl --fail-with-body -sS -X POST "$API/sandbox/exports/$REFERENCE/revisions" \
-H "Authorization: Bearer $SPREADU_KEY" -H "Idempotency-Key: $COMMAND_ID"Expect export.withdrawn, export.requested, then export.available.
COMMAND_ID="$(uuidgen)"
curl --fail-with-body -sS -X POST "$API/sandbox/exports/$REFERENCE/withdraw" \
-H "Authorization: Bearer $SPREADU_KEY" -H "Idempotency-Key: $COMMAND_ID"The revision becomes unavailable and export.withdrawn goes out. Your
integration should cancel any production work it hasn't already committed.
COMMAND_ID="$(uuidgen)"
curl --fail-with-body -sS -X PUT "$API/sandbox/exports/$REFERENCE/order" \
-H "Authorization: Bearer $SPREADU_KEY" -H "Idempotency-Key: $COMMAND_ID" \
-H "Content-Type: application/json" \
-d '{"orderNumber":"TEST-1001","externalOrderId":"test-order-1001","orderedCopies":2}'Each field can also be null. orderNumber and externalOrderId take 1 to
120 characters after trimming, the same as a live order and confirmation. The
next export read shows the new order, while existing revisions keep their
frozen snapshot. Like a photographer's order change in live mode, this sends no
event.
These fields exist only to set up test data. In live mode the photographer
enters the order number and copies, and externalOrderId is written only by
your lab's own confirmation.
Unlock first
A correction, a withdrawal and an order change all play a photographer, so
they hit your lab lock just like the real thing. While you hold the lock,
they answer 409 SANDBOX_EXPORT_LOCKED. Call
DELETE /exports/{reference}/lock first.
COMMAND_ID="$(uuidgen)"
curl --fail-with-body -sS -X POST "$API/sandbox/exports/$REFERENCE/expiring" \
-H "Authorization: Bearer $SPREADU_KEY" -H "Idempotency-Key: $COMMAND_ID"Sends export.expiring without touching the real clock.
COMMAND_ID="$(uuidgen)"
curl --fail-with-body -sS -X POST "$API/sandbox/exports/$REFERENCE/expire" \
-H "Authorization: Bearer $SPREADU_KEY" -H "Idempotency-Key: $COMMAND_ID"Closes the download window at once and queues the normal retention process,
which deletes the files and sends export.expired. A download link you still
hold is not permission to produce an expired revision.
COMMAND_ID="$(uuidgen)"
curl --fail-with-body -sS -X POST "$API/sandbox/reset" \
-H "Authorization: Bearer $SPREADU_KEY" -H "Idempotency-Key: $COMMAND_ID" \
-H "Content-Type: application/json" -d '{}'Returns { "deletedExports": 0 } with the number removed. A reset removes test
exports, events, webhook deliveries and checklist progress, and schedules their
files for cleanup. Keys and endpoints stay.
A test export is removed, with its events, delivery records and files, 30 days after its latest activity: its newest revision change or its newest event, such as a receipt, confirmation or retention warning. Reads, download links and simulated order changes don't count as activity. Older events of an active export still leave the feed after 30 days, as usual. The daily cleanup takes care of this. Keys and endpoints stay until you remove them.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy