FAQ
Short answers to the questions developers ask most.
Getting started
Do I need to create products before I can order?
No. You can order a catalog variant with inline designs (personalized orders). For a regular store, creating products is easier: each variant gets a SKU your store sends with orders.
Does test mode cost anything?
No. Test keys use a separate wallet with free test credits, and production is simulated. See Test mode.
Can I use the API from my storefront's JavaScript?
No. Secret keys must stay on your server. Call the API from your backend and expose only what your frontend needs (for example shipping options).
Is there an SDK?
The API is plain JSON over HTTPS and works with any HTTP client; every page has cURL, Node.js and Python examples. You can generate a typed client from the OpenAPI document. For webhooks, use the official Standard Webhooks libraries (Webhooks).
Orders
How do I avoid duplicate orders?
Set external_id to your store's order id and send an Idempotency-Key derived from it. A duplicate returns 409 duplicate_external_id with the existing_id. See Idempotency.
When are credits taken?
They are reserved when the order is confirmed and spent once it is accepted for production; canceled or failed orders give them back. See Credits & billing.
My order is on_hold. What do I do?
Check hold_reason. insufficient_funds resolves automatically when you add credits; most other reasons are handled by our team. See hold reasons.
Can I change an order after creating it?
Only drafts can be changed (PATCH /orders/{id}). A confirmed order can be canceled while it is not yet in production; create a corrected order afterwards.
Can I cancel an order?
Yes, while it is draft, on_hold or processing. Once it is in_production it can no longer be canceled. Credits are returned to your wallet immediately.
How long does production and delivery take?
Each catalog product lists production_days; shipping rates list transit time and estimated_delivery_days (production + transit, in business days).
Which countries do you ship to?
POST /shipping/rates tells you for any destination and set of items. If nothing can ship there, order creation fails with shipping_method_unavailable.
Products & artwork
What artwork resolution do I need?
300 DPI at the printed size is ideal; the placement's recommended_width_px × recommended_height_px covers the full area. Below 150 DPI you get a warning, below 75 DPI the artwork is rejected. See Designs.
Which file formats are accepted?
PNG (recommended, with transparency), JPEG, WebP, TIFF, GIF and SVG, up to 100 MB.
Can I use my existing store SKUs?
Yes — set sku on each variant when you create the product, or change it later. SKUs must be unique in your account. See Products & SKUs.
Do my customers see your name anywhere?
We never put our name in front of your customers: the tracking page and shipment emails use your branding, packing slips carry your brand wherever the product ships with one, and tracking links go to the carrier.
Webhooks
My webhook signatures do not verify.
Almost always the body was parsed and re-serialized before verification. Verify the raw bytes, use the secret of the right endpoint and mode (test and live differ), and make sure your server clock is correct (5-minute tolerance).
I missed webhooks while my server was down.
We retry for about 28 hours. After that, list missed events with GET /events (30 days) or resend them from Developers → Events.
Can events arrive twice or out of order?
Yes. Deduplicate by event id and compare statuses/timestamps instead of assuming order. See best practices.
Account
How do I go live?
Verify your email, buy credits, create a live key and a live webhook endpoint, then follow the going live checklist.
Who can see or rotate API keys?
Every member can see the list of keys (never the secrets) in Developers → API keys; owners, admins and developers can create, roll and revoke them.
Where do I get help?
Email support@swaglists.com and include the request_id of any failing request.