Skip to content
Docs

Introduction

What you can build with the Swaglists API and how an order flows from your store to your customer's door.

Swaglists manufactures print-on-demand products for your brand. You design products once, sell them in your own store, and every time a customer buys, your backend sends us the order. We print it, pack it with your branding and ship it to your customer — your customers never see our name.

The API is a JSON REST API at https://swaglists.com/api/v1. Everything you can do in the dashboard for products and orders, you can do with it.

What you can build

  • Automatic order forwarding from Shopify, WooCommerce, BigCommerce or a custom checkout: a paid order in your store becomes a production order here within seconds. See Integrations.
  • Personalized products — names, photos or generated artwork per order, uploaded on the fly with the order. See Personalized orders.
  • Your own product builder on top of our catalog: list products with your wholesale prices, render previews from mockup templates, create products with your own SKUs.
  • Customer-facing order tracking in your store or app using our webhooks, shipment objects and branded tracking page.
  • Back-office tooling: reconcile your prepaid credit wallet, export products to your store, reprocess failed orders.

How it works

Text
 Your customer            Your store / backend                    Swaglists
 ─────────────            ────────────────────                    ─────────────────
  pays for an order  ──►  receives "order paid"
                          POST /orders  (SKUs, address)    ──►    price it (estimate = charge)
                                                                   reserve credits from your wallet
                                                                   produce print files at the exact size
                                                                   accept for production (credits spent)
                          webhook order.in_production       ◄──    print, pack with your branding
                          webhook order.shipped (tracking)  ◄──    ship
  gets tracking email ◄─  (or your own email)
  & branded tracking page                                          webhook order.delivered
  1. Set up once. Pick products from the catalog, upload artwork and create products — each variant gets a SKU (yours, or one we generate). Export them to your store as a CSV, or create them in your store yourself with the same SKUs.
  2. Fund your wallet. Orders are paid from prepaid credits. Bigger top-ups earn bonus credits.
  3. Forward orders. When a customer pays, call POST /orders with the shipping address and the SKUs. Prices are deterministic: POST /orders/estimate returns exactly what you will be charged.
  4. Track. Subscribe to webhooks to update your store when the order goes into production, ships and is delivered.

Key concepts

Concept What it is
Catalog product A blank product we make (a tee, a poster, a mug) with variants (colors, sizes) and print areas called placements.
Design Your artwork placed on a placement, with a position and size.
Product A catalog product + your designs + your SKUs. What you sell.
Order Items (SKUs) shipped to one recipient. Moves through processing → in_production → shipped → delivered.
Wallet Your prepaid credits. Orders reserve credits when confirmed and spend them once accepted for production.
Test mode A full sandbox with test keys, free test credits and simulated production.

API at a glance

Endpoint What it does
GET /account Retrieve your account
GET /catalog/categories List catalog categories
GET /catalog/products List catalog products
GET /catalog/products/{id_or_slug} Retrieve a catalog product
GET /files List files
POST /files Upload a file
GET /files/{id} Retrieve a file
DELETE /files/{id} Delete a file
GET /products List products
POST /products Create a product
GET /products/{id} Retrieve a product
PATCH /products/{id} Update a product
DELETE /products/{id} Archive a product
GET /products/by_sku/{sku} Find a product variant by SKU
GET /products/{id}/variants List product variants
POST /products/{id}/variants Add product variants
PATCH /products/{id}/variants/{variant_id} Update a product variant
GET /product_variants/{id} Retrieve a product variant
POST /shipping/rates Get shipping rates
POST /orders/estimate Estimate an order
GET /orders List orders
POST /orders Create an order
GET /orders/{id} Retrieve an order
PATCH /orders/{id} Update a draft order
POST /orders/{id}/confirm Confirm a draft, or release an order waiting for credits
POST /orders/{id}/cancel Cancel an order
GET /orders/{id}/events List order events
GET /wallet Retrieve the wallet
GET /wallet/transactions List wallet transactions
GET /topups List top-ups
GET /topups/{id} Retrieve a top-up
GET /webhook_endpoints List webhook endpoints
POST /webhook_endpoints Create a webhook endpoint
GET /webhook_endpoints/{id} Retrieve a webhook endpoint
PATCH /webhook_endpoints/{id} Update a webhook endpoint
DELETE /webhook_endpoints/{id} Delete a webhook endpoint
POST /webhook_endpoints/{id}/rotate_secret Rotate the signing secret
POST /webhook_endpoints/{id}/test Send a test event
GET /events List events
GET /events/{id} Retrieve an event
POST /test/wallet/fund Add test credits
POST /test/orders/{id}/advance Advance a test order

Next steps