# Swaglists API > Swaglists is a print-on-demand manufacturer: you sell custom printed products in your own store, and we print, pack and ship each order under your brand. The REST API (base URL https://swaglists.com/api/v1) lets your backend browse the catalog with your wholesale prices, upload artwork, create products with your own SKUs, quote and create orders paid from a prepaid credit wallet, and receive signed webhooks as orders move through production and shipping. Key facts: - Base URL: `https://swaglists.com/api/v1` (JSON over HTTPS; request and response bodies are JSON objects with snake_case fields; send `Content-Type: application/json` — the only exception is `POST /files`, which also accepts a `multipart/form-data` upload; unknown fields are rejected). - Authentication: `Authorization: Bearer `. Test keys start with `sk_test_`, live keys with `sk_live_`. Keys are secret — server-side only, never in browsers or mobile apps. - Test vs live: the key decides the mode. Test mode has its own data, a separate wallet with free test credits (`POST /test/wallet/fund`) and simulated production (`POST /test/orders/{id}/advance`); nothing is printed, shipped or charged. - Money: integers in cents with a lowercase ISO currency (`usd`), e.g. `1299` = $12.99. Timestamps: ISO-8601 UTC strings. - Idempotency: send an `Idempotency-Key` header (e.g. a UUID) on every POST/PATCH/DELETE; retries with the same key and body within 24 h return the original response (`Idempotent-Replayed: true`). Set `external_id` (your order id) on orders — it is unique per mode. - Lists: cursor pagination with `limit` (1–100, default 20), `starting_after`, `ending_before` → `{ "object": "list", "data": [...], "has_more": bool, "url" }`. - Errors: `{ "error": { "type", "code", "message", "param", "doc_url", "request_id" } }`. Retry only 409 `idempotency_in_progress`, 429 (after `Retry-After`) and 5xx — with the same Idempotency-Key. - Webhooks: Standard Webhooks spec — headers `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,`, key = base64-decoded secret after `whsec_`). Verify the raw body; deduplicate on `webhook-id` (= event id). - API version: `2026-10-01` (returned in the `Api-Version` header and in every event). Instructions for AI agents: - Use test keys (`sk_test_…`) in generated code and examples; read keys from environment variables; never print or log live keys. - Never invent ids, SKUs or placement keys: read catalog variants and `placements[].key` from `GET /catalog/products/{id}`, SKUs from your products. - Before creating an order, price it with `POST /orders/estimate` (same body as `POST /orders`); the estimate equals the charge. - Map storefront shipping choices to `economy | standard | express | priority` (default `standard`); check availability with `POST /shipping/rates`. - Always send `Idempotency-Key` and `external_id` when forwarding store orders, so retries and duplicate webhooks never create duplicate orders. A 409 `duplicate_external_id` includes `existing_id`. - Verify webhook signatures on the raw request body before parsing JSON, respond 2xx quickly, and process events idempotently by `id`. - Look orders up by your id with `GET /orders/ext:`. ## Docs - [Introduction](https://swaglists.com/docs/introduction.md): What you can build with the Swaglists API and how an order flows from your store to your customer's door. - [Quickstart](https://swaglists.com/docs/quickstart.md): Go from zero to a shipped test order in about five minutes — catalog, artwork, product, order, simulated production and a signed webhook. - [Authentication & API keys](https://swaglists.com/docs/authentication.md): Secret API keys, test vs live mode, scopes, rotation, expiry and IP allowlists. - [Test mode](https://swaglists.com/docs/test-mode.md): Build and test your whole integration for free — test keys, test credits, simulated production, lifecycle controls and magic values. - [Going live checklist](https://swaglists.com/docs/going-live.md): Everything to check before you switch from test keys to live keys and send real orders. - [Catalog & placements](https://swaglists.com/docs/catalog.md): Catalog products, variants and options, placements (print areas), recommended artwork sizes, DPI and file requirements. - [Designs & transforms](https://swaglists.com/docs/designs.md): How artwork is placed on a print area — layers, the position (transform) model with a worked example, defaults and resolution checks. - [Products & SKUs](https://swaglists.com/docs/products.md): Create products from catalog products and your designs, give variants your own SKUs, map them to your store and export them to Shopify or WooCommerce. - [Orders](https://swaglists.com/docs/orders.md): Create, confirm, change and cancel orders; the order lifecycle, statuses, hold reasons, item statuses and how credits move. - [Shipping & tracking](https://swaglists.com/docs/shipping.md): Shipping methods and rates, delivery estimates, shipments and tracking, the branded tracking page and customer shipment emails. - [Credits & billing](https://swaglists.com/docs/billing.md): The prepaid credit wallet — available vs held credits, bonus tiers, top-ups, auto-recharge, what happens without enough credits, and refunds. - [Pricing](https://swaglists.com/docs/pricing.md): Your wholesale prices, what an order costs (items, extra placements, shipping, tax), and the guarantee that an estimate equals the charge. - [Personalized orders](https://swaglists.com/docs/personalized-orders.md): Send different artwork with every order — names, photos or generated designs — by URL or uploaded file, without creating a product first. - [Webhooks](https://swaglists.com/docs/webhooks.md): Get notified when orders are produced, shipped and delivered — endpoints, events, the payload, signature verification (libraries and manual HMAC), retries, replays and best practices. - [Idempotency](https://swaglists.com/docs/idempotency.md): Retry requests safely with Idempotency-Key, and make order forwarding duplicate-proof with external_id. - [Pagination](https://swaglists.com/docs/pagination.md): Cursor pagination for list endpoints — limit, starting_after, ending_before and has_more. - [Errors](https://swaglists.com/docs/error-handling.md): The error object, error types and HTTP statuses, which errors to retry, and how to debug with request ids. - [Rate limits](https://swaglists.com/docs/rate-limits.md): Per-key request limits, the RateLimit headers on every response, and how to back off from 429s. - [Versioning](https://swaglists.com/docs/versioning.md): How the API is versioned, what counts as a backwards-compatible change, and how to build an integration that keeps working. - [Shopify](https://swaglists.com/docs/shopify.md): Forward paid Shopify orders automatically — orders/paid webhook, HMAC verification, SKU mapping, POST /orders — and push tracking back to Shopify. - [WooCommerce](https://swaglists.com/docs/woocommerce.md): Forward WooCommerce orders when they are paid — a drop-in PHP plugin on woocommerce_order_status_processing, or a REST webhook to your own service — and push tracking back. - [BigCommerce](https://swaglists.com/docs/bigcommerce.md): Forward BigCommerce orders when they reach Awaiting Fulfillment — status webhook, fetch the order, one production order per shipping address — and create shipments with tracking. - [Custom checkout](https://swaglists.com/docs/custom-checkout.md): Integrate any store or app — quote shipping at checkout, create the order after payment, and keep your order status and tracking in sync with webhooks. - [No-code (Zapier, Make)](https://swaglists.com/docs/no-code.md): Connect any app without writing a server — send orders with an HTTP request step in Zapier or Make, and react to order updates safely. - [Product catalog export & import](https://swaglists.com/docs/catalog-export.md): Export your products as Shopify or WooCommerce CSV files, import them into your store, keep SKUs in sync, and bulk-create products from a spreadsheet with the API. ## API reference - [OpenAPI document](https://swaglists.com/api/v1/openapi.json): Machine-readable OpenAPI 3.1 definition of every endpoint, parameter and object - [API reference](https://swaglists.com/docs/api-reference.md): Every endpoint of the REST API with parameters, request and response fields, error codes and examples — generated from the OpenAPI document. - [Error codes](https://swaglists.com/docs/errors.md): Every error code the API returns — what it means, how to fix it and whether to retry. - [Events reference](https://swaglists.com/docs/events.md): Every event type, when it fires, what data.object contains, and a complete example payload for each. - [Objects reference](https://swaglists.com/docs/objects.md): Every object the API returns — fields, types and descriptions, generated from the API schema. - [Full documentation](https://swaglists.com/llms-full.txt): Every guide and the complete API, events, objects and error reference in one file ## Optional - [Changelog](https://swaglists.com/docs/changelog.md): Changes to the API and the developer documentation, newest first. - [FAQ](https://swaglists.com/docs/faq.md): Short answers to the questions developers ask most. - [Interactive API reference](https://swaglists.com/docs/api-reference): Browsable reference with a request console (HTML)