Test with a sandbox

A workspace can have a sandbox: a second, separate workspace for trying things out. Point a staging store at it and the store’s test orders are safe, because an order placed in a sandbox never reaches a printshop.

Nothing in the sandbox is visible from your live workspace, or the other way round. What ties them together is who may work there. Everyone who is a member of your live workspace is a member of its sandbox, with the same roles; members, roles and invitations are managed on the live side only. The sandbox has your live plan, and shares its limits (see Limits), but its credits are its own: it never spends your live workspace’s, and gets none with the plan, so anything that spends credits is refused there until it has some. Your workspace’s admin can move credits from live into it on the sandbox’s Credits page: they leave the live balance at once, keep the date they expire on, and never move back. We can also grant the sandbox some. The sandbox is listed right after its live workspace in the studio’s workspace switcher, and a bar across the top of every studio page says Sandbox while you are in it.

What a sandbox can’t do

A sandbox behaves like your live workspace, except:

• Credits: it has its own, and never spends your live workspace’s. See above for how it gets some.
• Printshops: it never reaches one. Its orders stop at submitted (see Sandbox orders).
• Email: it sends none to anyone who is not a member of the workspace (see Sandbox automations).
• Members and roles: they are your live workspace’s, managed there.
• Keys: its API keys are test keys, pk_test_, sk_test_, ik_test_ and mcp_test_ (see Test keys).
• Sync from live: each sync erases everything in it (see Fill the sandbox with Sync from live).
• Limits: it shares your plan’s limits with live, and has small caps of its own: 10 print files a day, 50 a month and 50 orders a month (see Limits).
• Speed: its print files are made after every live workspace’s.

Create the sandbox

A workspace has no sandbox until you ask for one. Under Settings, the Sandbox card has a Create sandbox button, for members who may change the workspace’s settings. Creating it asks how the sandbox starts:

• A copy of live runs its first Sync from live, so it starts with your live workspace’s templates, blanks, printshops and settings.
• Empty starts it as a new workspace starts, with none of those. It has no printshop until you connect one there or sync it from live.

A workspace has one sandbox at most; once it exists, the card on your live workspace says so.

Delete the sandbox

Under Settings, the Sandbox card has a Delete sandbox button, on your live workspace and inside the sandbox, for members who may change the workspace’s settings. After you confirm, the sandbox is deleted with everything in it: its templates, test designs, prints and orders, its API keys, connected stores and webhook endpoints, and its credits. Your live workspace is not touched, and files it uses that a sync copied stay.

You can create a new sandbox afterwards. Its caps go on from the old one’s: the print files and orders the deleted sandbox made this day and month still count.

Connect a staging store

Connect a store as you would a live one (see Getting started). Under Connect to, choose Sandbox instead of Live. The store receives its keys from the sandbox, and everything it does stays in the sandbox.

Develop on your own machine

Pixonaut can’t reach a shop on your own machine, such as http://shop.local. You can still connect it to a sandbox: it connects, and because its webhook address doesn’t answer, no webhooks are sent to it. The store reads its events by pulling them instead, and its webhook endpoint under Settings, Webhooks reads Not sending.

To receive webhooks, run a tunnel to the shop, such as ngrok or cloudflared, and give Pixonaut its address:

• when you approve the store, in Webhook address, or
• later, with Change address on the endpoint, or with PATCH /v1/webhooks/{id} and a url.

Use the tunnel’s origin with the path Pixonaut proposed, so https://abc123.ngrok.app/wp-json/pixonaut/v1/webhook. Saving calls the address. If it answers, events from then on are delivered, signed with the same secret; the store catches up on earlier ones by pulling them, so no backlog is sent. When a tunnel’s address changes, change it here too. To check an address again once it answers, save it unchanged.

On your live workspace, a webhook address stays on the store’s own site, and must answer.

Test keys

A key made in the sandbox says so: where a live key reads pk_live_, sk_live_, ik_live_ or mcp_live_, a sandbox key reads pk_test_, sk_test_, ik_test_ or mcp_test_. A test key works on the sandbox alone. Make them under API Keys while the sandbox is selected.

An MCP key made there lets your AI assistant try its changes on the sandbox first. It acts as you, with the roles you hold in your live workspace, and stops working when you leave the team (see Connect an AI assistant).

Fill the sandbox with Sync from live

To bring the sandbox up to date with live, switch to the sandbox. Under Settings, its Sandbox card has a Sync from live button, for members who may change your live workspace’s settings, and shows when the sandbox was last synced.

Sync first erases everything in the sandbox, then copies your live workspace’s authoring data into it:

• templates, with all their versions and drafts, and their assets and fonts;
• blanks, with their placements and mockups;
• shapes, inks, palettes, categories and tags;
• printshop connections, without their credentials, and your settings;
• your automations, with their versions, each one disabled, so you switch on the ones you want to try in the sandbox.

Every copy keeps the id it has live. A product on your staging store that names a template, blank and placement therefore names the same ones in production, and you can move a working setup to your live store unchanged.

Sync never copies customer data: designs, proofs, uploads, prints, orders, deliveries, recipients and addresses. It erases the sandbox’s own test copies of those. What connects a staging store to the sandbox survives: its API keys, connected stores and webhook endpoints, and its audit record, as well as its credits.

Nothing keeps the two in step between syncs. A change made live reaches the sandbox at the next sync, and a change made in the sandbox is lost at the next one.

Limits

Your live workspace and its sandbox share one pool of your plan’s limits: storage, prints made a month, templates, API keys, share links and connected stores count what both hold together. What a sync copied shares live’s files and is live’s template, so it costs no more storage and is no second template.

On top, a sandbox has small caps of its own, since it is for rehearsing a flow: 10 print files a day, 50 a month, and 50 orders a month. Past one, the print or order is refused 403 plan_limit_reached, its limit naming the cap: sandboxPrintsPerDay, sandboxPrintsPerMonth or sandboxOrdersPerMonth. Days and months are UTC calendar ones. The counts are your live workspace’s, so a sync starts none of them over.

Sandbox orders and prints are never billed. A sandbox’s print files are made after every live workspace’s, so one may take a little longer to finish.

Sandbox orders

An order placed in the sandbox is routed and checked like a live one, then stops at submitted and stays there; no printshop is reached. Cancelling one cancels it at once. You can connect, edit, disconnect and delete printshops in the sandbox as on live; the copies a sync makes hold no credentials, and a sync replaces whatever printshops the sandbox has with live’s. An order that nothing names a printshop for is placed with none (adapter is none) rather than refused, so an empty sandbox takes your staging store’s orders at once.

To see the rest of an order’s life, move it yourself. In the studio, open the order in the sandbox and use Change status. From your staging store, send its status with the store’s own key (ik_test_), or with a sandbox secret key (sk_test_) made on the sandbox’s API Keys page:

PATCH /v1/orders/{id}
Authorization: Bearer ik_test_...
Content-Type: application/json

{ "status": "shipped", "tracking": { "number": "00370725001234567890" } }

A reason goes with any status, and with failed becomes the order’s error; tracking goes with shipped. In your live workspace the same key may only settle an order whose outcome is unknown: see Design to order. See Orders for the statuses.

Sandbox automations

An automation you switch on in the sandbox runs as it would live, against the sandbox’s own events. Its orders stop at submitted like any sandbox order, and its notifications and webhook calls are sent. An email to someone who is not a member, such as a printshop’s contact, is not sent: the firing records the step as done, with the message it would have sent, so you can read it before the automation runs live. A sync replaces every automation in the sandbox, with whatever you changed there, by live’s.