Objects reference

Every object the API returns — fields, types and descriptions, generated from the API schema.

The objects below are returned by the API and embedded in events. Field lists are generated from the API's OpenAPI schema, so they always match the API. Types: string | null means the field is always present but may be null.

Conventions

Every object has an object field naming its type, and most have an id with a type prefix (ord_, prod_, …).
Amounts are integers in cents with a lowercase currency (usd).
Timestamps are ISO-8601 strings in UTC; fields that do not apply are null.
New fields can be added at any time — ignore fields you do not know.

List

List endpoints return a list object. See Pagination.

Field	Type	Description
`object`	string	Always `list`.
`data`	array	The objects of this page.
`has_more`	boolean	Whether more objects exist beyond this page (in the paging direction).
`url`	string	Path of the list endpoint.

Account

Your account as seen by the API key, including its mode and wallet summary.

Returned by: GET /account.

Field	Type	Description
`object`	"account"	Type of the object: always `account`.
`id`	string	Unique identifier (starts with `org_`).
`name`	string	Your account (organization) name.
`brand_name`	string \| null	Brand printed on packing slips and shown on the tracking page.
`support_email`	string \| null	Support email shown to your customers (packing slips, tracking page, shipment emails).
`website`	string \| null	Your website.
`country`	string \| null	Country of your business (ISO 3166-1 alpha-2).
`mode`	string	Mode of the API key used for this request. One of: `live`, `test`.
`livemode`	boolean	`true` in live mode, `false` in test mode.
`live_mode_enabled`	boolean	Whether live mode is enabled for the account (live keys work and live orders are produced).
`settings`	object	Order settings that change how the API behaves (Settings → Orders in the dashboard).
`settings.auto_confirm_orders`	boolean	Default of `confirm` when creating orders.
`settings.insufficient_funds_behavior`	string	What happens to an order your credits don't cover. hold: it waits on hold and is released automatically (oldest first) when credits arrive; hold_manual: it waits on hold until you release it (dashboard, or POST /orders/{id}/confirm); reject: POST /orders answers 402 insufficient_funds and nothing is created. One of: `hold`, `hold_manual`, `reject`.
`wallet`	Wallet	Wallet of the key's mode.
`created_at`	string	When the object was created (ISO-8601, UTC).

Example account

JSON

{
  "object": "account",
  "id": "org_01k8x3q8m4h2c9t6v5r7w1y0za",
  "name": "Company A",
  "brand_name": "Company A Apparel",
  "support_email": "help@company-a.example",
  "website": "https://company-a.example",
  "country": "US",
  "mode": "live",
  "livemode": true,
  "live_mode_enabled": true,
  "settings": {
    "auto_confirm_orders": true,
    "insufficient_funds_behavior": "hold"
  },
  "wallet": {
    "object": "wallet",
    "mode": "live",
    "livemode": true,
    "currency": "usd",
    "available": 482550,
    "held": 12480,
    "total": 495030,
    "low_balance_threshold": 10000
  },
  "created_at": "2026-10-21T14:32:05.000Z"
}

Wallet

Prepaid credit balance of one mode (live and test have separate wallets).

Returned by: GET /wallet, POST /test/wallet/fund, event wallet.low_balance.

Field	Type	Description
`object`	"wallet"	Type of the object: always `wallet`.
`mode`	string	`live` or `test`. One of: `live`, `test`.
`livemode`	boolean	`true` in live mode, `false` in test mode.
`currency`	string	Three-letter currency code, lowercase (`usd`).
`available`	integer	Spendable credits in cents. May be negative after a payment dispute.
`held`	integer	Credits reserved for in-flight orders, in cents.
`total`	integer	available + held, in cents.
`low_balance_threshold`	integer \| null	Low-balance notification threshold in cents.

Example wallet

JSON

{
  "object": "wallet",
  "mode": "live",
  "livemode": true,
  "currency": "usd",
  "available": 482550,
  "held": 12480,
  "total": 495030,
  "low_balance_threshold": 10000
}

Transaction

An immutable wallet ledger entry: every change to your balance is one transaction.

Returned by: GET /wallet/transactions, event wallet.credited.

Field	Type	Description
`object`	"transaction"	Type of the object: always `transaction`.
`id`	string	Unique identifier (starts with `txn_`).
`type`	string	Kind of balance change. One of: `topup`, `bonus`, `hold`, `release`, `capture`, `charge`, `refund`, `adjustment`, `reversal`, `test_credit`.
`amount`	integer	Signed change to available credits (cents).
`held_delta`	integer	Signed change to held credits (cents).
`balance_after`	integer	Available credits after this transaction (cents).
`currency`	string	Three-letter currency code, lowercase (`usd`).
`description`	string	Human-readable description.
`order_id`	string \| null	Order the transaction belongs to, if any.
`topup_id`	string \| null	Top-up the transaction belongs to, if any.
`created_at`	string	When the object was created (ISO-8601, UTC).

Example transaction

JSON

{
  "object": "transaction",
  "id": "txn_01k8x4b2q8w0e2r4t6y8u0i2o4",
  "type": "hold",
  "amount": -2598,
  "held_delta": 2598,
  "balance_after": 479952,
  "currency": "usd",
  "description": "Credits reserved for order ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
  "order_id": "ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
  "topup_id": null,
  "created_at": "2026-10-21T14:32:05.000Z"
}

Top-up

A credit purchase (made in the dashboard).

Returned by: GET /topups, GET /topups/{id}, events topup.*.

Field	Type	Description
`object`	"topup"	Type of the object: always `topup`.
`id`	string	Unique identifier (starts with `top_`).
`status`	string	Payment status of the top-up. One of: `pending`, `processing`, `succeeded`, `failed`, `canceled`, `refunded`, `partially_refunded`, `disputed`.
`amount`	integer	Amount paid (cents).
`bonus`	integer	Bonus credits granted (cents).
`bonus_percent`	number	Bonus percentage, e.g. 5 for 5%.
`credits`	integer	Credits added = amount + bonus (cents).
`currency`	string	Three-letter currency code, lowercase (`usd`).
`payment_method_type`	string \| null	How it was paid (e.g. `card`, `us_bank_account`).
`receipt_url`	string \| null	Payment receipt, when available.
`created_at`	string	When the object was created (ISO-8601, UTC).
`succeeded_at`	string \| null	When the credits were added.

Example top-up

JSON

{
  "object": "topup",
  "id": "top_01k8x1q3w5e7r9t1y3u5i7o9p1",
  "status": "succeeded",
  "amount": 500000,
  "bonus": 25000,
  "bonus_percent": 5,
  "credits": 525000,
  "currency": "usd",
  "payment_method_type": "us_bank_account",
  "receipt_url": null,
  "created_at": "2026-10-21T14:32:05.000Z",
  "succeeded_at": "2026-10-21T14:32:05.000Z"
}

Catalog category

A group of catalog products (categories can be nested with parent_id).

Returned by: GET /catalog/categories.

Field	Type	Description
`object`	"catalog_category"	Type of the object: always `catalog_category`.
`id`	string	Unique identifier (starts with `cat_`).
`slug`	string	URL-friendly identifier; use it as the `category` filter of `GET /catalog/products`.
`name`	string	Category name.
`parent_id`	string \| null	Parent category (null for top-level categories).
`description`	string \| null	Category description.
`image_url`	string \| null	Category image.
`sort_order`	integer	Display order (ascending).
`product_count`	integer	Active products in this category and its sub-categories.
`created_at`	string \| null	When the object was created (ISO-8601, UTC).
`updated_at`	string \| null	When the object was last changed (ISO-8601, UTC).

Example catalog category

JSON

{
  "object": "catalog_category",
  "id": "cat_01k8w0q1w2e3r4t5y6u7i8o9p0",
  "slug": "t-shirts",
  "name": "T-Shirts",
  "parent_id": null,
  "description": "Classic and premium tees.",
  "image_url": null,
  "sort_order": 0,
  "product_count": 12,
  "created_at": "2026-10-21T14:32:05.000Z",
  "updated_at": "2026-10-21T14:32:05.000Z"
}

Catalog product

A product you can customize and sell, with your wholesale prices, print areas and mockup templates.

Returned by: GET /catalog/products, GET /catalog/products/{id_or_slug}.

Field	Type	Description
`object`	"catalog_product"	Type of the object: always `catalog_product`.
`id`	string	Unique identifier (starts with `cp_`).
`slug`	string	URL-friendly identifier; can be used instead of the id in `GET /catalog/products/{id_or_slug}`.
`title`	string	Product title.
`subtitle`	string \| null	Short tagline.
`description`	string \| null	Markdown.
`category`	CatalogCategoryRef	Category of the product.
`tags`	array of string	Tags (e.g. `bestseller`).
`images`	array of object	Product photos.
`images[].url`	string	Image URL.
`images[].alt`	string \| null	Alt text.
`features`	array of string	Selling points.
`techniques`	array of string	Print techniques used (e.g. `dtg`, `embroidery`, `sublimation`, `digital`).
`material`	string \| null	Material.
`care_instructions`	string \| null	Care instructions.
`size_guide`	map of any \| null	Size chart data, when available.
`options`	array of object	Option names and values (e.g. Color, Size) in display order.
`options[].name`	string	Option name (e.g. `Color`).
`options[].values`	array of object	Values of the option.
`options[].values[].value`	string	Value as used in variant `options`.
`options[].values[].label`	string	Display label.
`options[].values[].hex`	string \| null	Color swatch (hex), for color options.
`production_days`	object	Business days to produce before shipping.
`production_days.min`	integer	Fastest production time in business days.
`production_days.max`	integer	Slowest production time in business days.
`featured`	boolean	Featured products are listed first.
`placements`	array of Placement	Print areas you can put artwork on.
`variants`	array of CatalogVariant	Active variants with your wholesale price and availability.
`mockup_templates`	array of MockupTemplate	Templates to render previews.
`price_range`	object \| null	Lowest and highest wholesale variant price (first placement).
`price_range.min`	integer	Lowest variant price in cents.
`price_range.max`	integer	Highest variant price in cents.
`price_range.currency`	string	Currency of the prices.
`price_from`	integer \| null	Lowest wholesale price over active variants (cents).
`currency`	string	Three-letter currency code, lowercase (`usd`).
`created_at`	string \| null	When the object was created (ISO-8601, UTC).
`updated_at`	string \| null	When the object was last changed (ISO-8601, UTC).

Example catalog product

JSON

{
  "object": "catalog_product",
  "id": "cp_01k8w1a2s3d4f5g6h7j8k9m0n1",
  "slug": "classic-unisex-tee",
  "title": "Classic Unisex Tee",
  "subtitle": "100% combed cotton",
  "description": "A soft, everyday tee.",
  "category": {
    "object": "catalog_category",
    "id": "cat_01k8w0q1w2e3r4t5y6u7i8o9p0",
    "slug": "t-shirts",
    "name": "T-Shirts",
    "parent_id": null
  },
  "tags": [
    "bestseller"
  ],
  "images": [
    {
      "url": "https://swaglists.com/f/file_01k8w1c2v4b6n8m0q2w4e6r8t1/1767225600.9b1c/tee.png",
      "alt": "Classic tee"
    }
  ],
  "features": [
    "Pre-shrunk",
    "Side-seamed"
  ],
  "techniques": [
    "dtg"
  ],
  "material": "100% cotton",
  "care_instructions": "Machine wash cold, inside out.",
  "size_guide": null,
  "options": [
    {
      "name": "Color",
      "values": [
        {
          "value": "Black",
          "label": "Black",
          "hex": "#111111"
        }
      ]
    },
    {
      "name": "Size",
      "values": [
        {
          "value": "M",
          "label": "M",
          "hex": null
        }
      ]
    }
  ],
  "production_days": {
    "min": 2,
    "max": 4
  },
  "featured": true,
  "placements": [
    {
      "object": "placement",
      "key": "front",
      "label": "Front",
      "description": "Front print area",
      "technique": "dtg",
      "aspect_ratio": 0.833333,
      "width_in": 15,
      "height_in": 18,
      "recommended_width_px": 4500,
      "recommended_height_px": 5400,
      "min_dpi": 150,
      "required": false,
      "file_requirements": {
        "formats": [
          "png",
          "jpeg",
          "webp",
          "tiff",
          "svg"
        ],
        "max_file_size_bytes": 104857600,
        "max_dimension_px": 30000,
        "recommended_width_px": 4500,
        "recommended_height_px": 5400,
        "recommended_dpi": 300,
        "min_dpi": 150,
        "color_profile": "sRGB",
        "transparent_background": true
      }
    }
  ],
  "variants": [
    {
      "object": "catalog_variant",
      "id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
      "catalog_product_id": "cp_01k8w1a2s3d4f5g6h7j8k9m0n1",
      "sku": "TEE-CLASSIC-BLK-M",
      "title": "Black / M",
      "options": {
        "Color": "Black",
        "Size": "M"
      },
      "color": "Black",
      "color_hex": "#111111",
      "size": "M",
      "image_url": null,
      "available": true,
      "price": 1299,
      "currency": "usd"
    }
  ],
  "mockup_templates": [
    {
      "object": "mockup_template",
      "id": "cmt_01k8w1b3c5v7b9n1m3a5s7d9f1",
      "placement_key": "front",
      "color": "Black",
      "label": "Front",
      "image_url": "https://swaglists.com/f/file_01k8w1c2v4b6n8m0q2w4e6r8t0/1767225600.3f9a/tee-front.png",
      "image_width_px": 1600,
      "image_height_px": 2000,
      "print_area": {
        "x": 0.3,
        "y": 0.25,
        "width": 0.4,
        "height": 0.48
      },
      "blend_mode": "multiply",
      "is_primary": true
    }
  ],
  "price_range": {
    "min": 1299,
    "max": 1599,
    "currency": "usd"
  },
  "price_from": 1299,
  "currency": "usd",
  "created_at": "2026-10-21T14:32:05.000Z",
  "updated_at": "2026-10-21T14:32:05.000Z"
}

Catalog variant

One color/size (or other option combination) of a catalog product.

Returned by: GET /catalog/products/{id_or_slug}.

Field	Type	Description
`object`	"catalog_variant"	Type of the object: always `catalog_variant`.
`id`	string	Unique identifier (starts with `cv_`).
`catalog_product_id`	string	Catalog product of the variant.
`sku`	string	Catalog SKU (ours). Your own SKUs live on product variants.
`title`	string	Variant title (e.g. `Black / M`).
`options`	map of string	Option values (e.g. `{"Color": "Black", "Size": "M"}`).
`color`	string \| null	Color name, when the product has colors.
`color_hex`	string \| null	Color swatch (hex).
`size`	string \| null	Size, when the product has sizes.
`image_url`	string \| null	Photo of this variant, when available.
`available`	boolean	Currently in stock and orderable.
`price`	integer \| null	Your wholesale price per unit in cents, printed on the first placement. Null when not purchasable.
`currency`	string	Three-letter currency code, lowercase (`usd`).

Example catalog variant

JSON

{
  "object": "catalog_variant",
  "id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
  "catalog_product_id": "cp_01k8w1a2s3d4f5g6h7j8k9m0n1",
  "sku": "TEE-CLASSIC-BLK-M",
  "title": "Black / M",
  "options": {
    "Color": "Black",
    "Size": "M"
  },
  "color": "Black",
  "color_hex": "#111111",
  "size": "M",
  "image_url": null,
  "available": true,
  "price": 1299,
  "currency": "usd"
}

Placement

A printable area of a catalog product (front, back, sleeve, …) with its recommended artwork size.

Returned by: GET /catalog/products/{id_or_slug}.

Field	Type	Description
`object`	"placement"	Type of the object: always `placement`.
`key`	string	Use this key as `placement` in designs.
`label`	string	Display name (e.g. `Front`).
`description`	string \| null	Description of the print area.
`technique`	string	Print technique, e.g. dtg, embroidery, sublimation, digital.
`aspect_ratio`	number \| null	Width / height of the print area.
`width_in`	number \| null	Print area width in inches.
`height_in`	number \| null	Print area height in inches.
`recommended_width_px`	integer \| null	Artwork width (px) that covers the full print area at 300 DPI.
`recommended_height_px`	integer \| null	Artwork height (px) that covers the full print area at 300 DPI.
`min_dpi`	integer	Below this effective DPI you get a `dpi_low` warning.
`required`	boolean	Products must include a design for this placement.
`file_requirements`	FileRequirements	Artwork requirements of this placement.

Example placement

JSON

{
  "object": "placement",
  "key": "front",
  "label": "Front",
  "description": "Front print area",
  "technique": "dtg",
  "aspect_ratio": 0.833333,
  "width_in": 15,
  "height_in": 18,
  "recommended_width_px": 4500,
  "recommended_height_px": 5400,
  "min_dpi": 150,
  "required": false,
  "file_requirements": {
    "formats": [
      "png",
      "jpeg",
      "webp",
      "tiff",
      "svg"
    ],
    "max_file_size_bytes": 104857600,
    "max_dimension_px": 30000,
    "recommended_width_px": 4500,
    "recommended_height_px": 5400,
    "recommended_dpi": 300,
    "min_dpi": 150,
    "color_profile": "sRGB",
    "transparent_background": true
  }
}

File requirements

Artwork requirements of a placement (placement.file_requirements).

Returned by: GET /catalog/products/{id_or_slug}.

Field	Type	Description
`formats`	array of string	Accepted artwork formats. SVG is rasterized; PNG with transparency is recommended.
`max_file_size_bytes`	integer	Maximum upload size in bytes.
`max_dimension_px`	integer	Maximum width or height of an image in pixels.
`recommended_width_px`	integer \| null	Artwork width (px) that covers the full print area at 300 DPI.
`recommended_height_px`	integer \| null	Artwork height (px) that covers the full print area at 300 DPI.
`recommended_dpi`	integer	Recommended print resolution.
`min_dpi`	integer	Below this effective DPI, prints may look blurry (you receive a warning).
`color_profile`	string	Color profile artwork is printed in.
`transparent_background`	boolean	Transparent pixels are not printed.

Example file requirements

JSON

{
  "formats": [
    "png",
    "jpeg",
    "webp",
    "tiff",
    "svg"
  ],
  "max_file_size_bytes": 104857600,
  "max_dimension_px": 30000,
  "recommended_width_px": 4500,
  "recommended_height_px": 5400,
  "recommended_dpi": 300,
  "min_dpi": 150,
  "color_profile": "sRGB",
  "transparent_background": true
}

Mockup template

A background photo plus the print-area rectangle on it, to render previews.

Returned by: GET /catalog/products/{id_or_slug}.

Field	Type	Description
`object`	"mockup_template"	Type of the object: always `mockup_template`.
`id`	string	Unique identifier (starts with `cmt_`).
`placement_key`	string	Placement the template shows.
`color`	string \| null	Variant color the photo shows (null = any color).
`label`	string \| null	Display name.
`image_url`	string	Background photo URL.
`image_width_px`	integer \| null	Photo width in pixels.
`image_height_px`	integer \| null	Photo height in pixels.
`print_area`	object	Where the print area sits on the photo, as fractions of the photo.
`print_area.x`	number \| null	Left edge (fraction of the photo width).
`print_area.y`	number \| null	Top edge (fraction of the photo height).
`print_area.width`	number \| null	Width (fraction of the photo width).
`print_area.height`	number \| null	Height (fraction of the photo height).
`blend_mode`	string	How artwork is blended onto the photo (e.g. `multiply`).
`is_primary`	boolean	Default template for the placement.

Example mockup template

JSON

{
  "object": "mockup_template",
  "id": "cmt_01k8w1b3c5v7b9n1m3a5s7d9f1",
  "placement_key": "front",
  "color": "Black",
  "label": "Front",
  "image_url": "https://swaglists.com/f/file_01k8w1c2v4b6n8m0q2w4e6r8t0/1767225600.3f9a/tee-front.png",
  "image_width_px": 1600,
  "image_height_px": 2000,
  "print_area": {
    "x": 0.3,
    "y": 0.25,
    "width": 0.4,
    "height": 0.48
  },
  "blend_mode": "multiply",
  "is_primary": true
}

File

An uploaded image (artwork or logo) or a generated mockup. Use its id as file_id in designs.

Returned by: POST /files, GET /files, GET /files/{id}, event file.processed.

Field	Type	Description
`object`	"file"	Type of the object: always `file`.
`id`	string	Unique identifier (starts with `file_`).
`filename`	string	File name.
`mime_type`	string	Media type (images are stored as PNG, JPEG or WebP).
`size_bytes`	integer	Size in bytes.
`width_px`	integer \| null	Width in pixels.
`height_px`	integer \| null	Height in pixels.
`dpi`	number \| null	Resolution stored in the image metadata, when present (informational — print resolution depends on the placed size).
`status`	string	ready to use, still processing (pending), failed processing, or deleted. One of: `pending`, `ready`, `failed`, `deleted`.
`purpose`	string	artwork or logo (your uploads), or mockup (generated product mockups). One of: `artwork`, `logo`, `mockup`.
`url`	string \| null	Signed download URL, valid for about 24 hours.
`created_at`	string	When the object was created (ISO-8601, UTC).

Example file

JSON

{
  "object": "file",
  "id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9",
  "filename": "logo-front.png",
  "mime_type": "image/png",
  "size_bytes": 482113,
  "width_px": 4500,
  "height_px": 5400,
  "dpi": 300,
  "status": "ready",
  "purpose": "artwork",
  "url": "https://swaglists.com/f/file_01k8x3y1q3w5e7r9t1y3u5i7o9/1767225600.ab12cd/logo-front.png",
  "created_at": "2026-10-21T14:32:05.000Z"
}

Product

Your product: a catalog product + your designs + variants with your SKUs.

Returned by: POST /products, GET /products, GET /products/{id}, PATCH /products/{id}, events product.*.

Field	Type	Description
`object`	"product"	Type of the object: always `product`.
`id`	string	Unique identifier (starts with `prod_`).
`title`	string	Product title.
`description`	string \| null	Product description (plain text or markdown).
`status`	string	draft, active, or archived (archived products can no longer be ordered). One of: `draft`, `active`, `archived`.
`catalog_product_id`	string	Catalog product this product is made from.
`external_id`	string \| null	Your id for the product (e.g. your store's product id).
`tags`	array of string	Your tags.
`metadata`	map of string	Your key/value pairs (string values).
`retail_price`	integer \| null	Default retail price of the variants (informational, used in exports), in cents.
`currency`	"usd"	Three-letter currency code, lowercase (`usd`).
`designs`	array of Design	Artwork per placement.
`variants`	array of ProductVariant	Sellable variants with your SKUs.
`mockups`	array of object	Generated preview images. Rendered in the background; `product.updated` fires when they are ready.
`mockups[].url`	string	Image URL that does not expire (use it in your store). Replaced when the mockups are re-rendered; the old URL then returns 404.
`mockups[].placement`	string	Placement shown.
`mockups[].color`	string \| null	Variant color shown (null when not color-specific).
`mockups[].is_primary`	boolean	Main image of the product.
`warnings`	array of ProductWarning	Only on create/update responses: non-blocking design issues.
`created_at`	string	When the object was created (ISO-8601, UTC).
`updated_at`	string	When the object was last changed (ISO-8601, UTC).

Example product

JSON

{
  "object": "product",
  "id": "prod_01k8x3z7r1t3y5u7i9o1p3a5s7",
  "title": "Company A Logo Tee",
  "description": "Our classic logo on a soft tee.",
  "status": "active",
  "catalog_product_id": "cp_01k8w1a2s3d4f5g6h7j8k9m0n1",
  "external_id": "shopify-product-9921",
  "tags": [
    "logo"
  ],
  "metadata": {},
  "retail_price": 2900,
  "currency": "usd",
  "designs": [
    {
      "placement": "front",
      "layers": [
        {
          "file_id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9",
          "transform": {
            "x": 0.1,
            "y": 0.05,
            "width": 0.8,
            "height": 0.6,
            "rotation": 0
          },
          "opacity": 1
        }
      ]
    }
  ],
  "variants": [
    {
      "object": "product_variant",
      "id": "pvar_01k8x3z7r4f6g8h0j2k4l6z8x0",
      "product_id": "prod_01k8x3z7r1t3y5u7i9o1p3a5s7",
      "sku": "CA-TEE-BLK-M",
      "catalog_variant_id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
      "title": "Black / M",
      "options": {
        "Color": "Black",
        "Size": "M"
      },
      "retail_price": 2900,
      "price": 1299,
      "currency": "usd",
      "external_id": "shopify-variant-4410",
      "enabled": true,
      "available": true
    }
  ],
  "mockups": [
    {
      "url": "https://swaglists.com/f/file_01k8x3y9a1s3d5f7g9h1j3k5l7/1782777600.c0ffee/mockup-front.png",
      "placement": "front",
      "color": "Black",
      "is_primary": true
    }
  ],
  "created_at": "2026-10-21T14:32:05.000Z",
  "updated_at": "2026-10-21T14:32:05.000Z"
}

Product variant

A sellable variant of your product with your SKU.

Returned by: GET /products/{id}/variants, GET /product_variants/{id}, GET /products/by_sku/{sku}.

Field	Type	Description
`object`	"product_variant"	Type of the object: always `product_variant`.
`id`	string	Unique identifier (starts with `pvar_`).
`product_id`	string	Product the variant belongs to.
`sku`	string	Your SKU (unique in your account). Order items can reference it.
`catalog_variant_id`	string	Catalog variant that is produced for this SKU.
`title`	string	Variant title (e.g. `Black / M`).
`options`	map of string	Option values (e.g. `{"Color": "Black", "Size": "M"}`).
`retail_price`	integer \| null	Your retail price (informational), cents.
`price`	integer \| null	Your wholesale price per unit with this product's designs, cents.
`currency`	"usd"	Three-letter currency code, lowercase (`usd`).
`external_id`	string \| null	Your id for the variant (e.g. your store's variant id).
`enabled`	boolean	Disabled variants cannot be ordered (their SKU stays reserved).
`available`	boolean	Whether the variant can be ordered right now: enabled, product not archived, and the catalog variant offered and in stock. `false` while it is temporarily out of stock — mark it sold out in your store; `product.updated` fires when this changes.

Example product variant

JSON

{
  "object": "product_variant",
  "id": "pvar_01k8x3z7r4f6g8h0j2k4l6z8x0",
  "product_id": "prod_01k8x3z7r1t3y5u7i9o1p3a5s7",
  "sku": "CA-TEE-BLK-M",
  "catalog_variant_id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
  "title": "Black / M",
  "options": {
    "Color": "Black",
    "Size": "M"
  },
  "retail_price": 2900,
  "price": 1299,
  "currency": "usd",
  "external_id": "shopify-variant-4410",
  "enabled": true,
  "available": true
}

Product warning

A non-blocking design issue returned on product create/update.

Returned by: POST /products, PATCH /products/{id}.

Field	Type	Description
`code`	string	Warning code: `dpi_low` (artwork below the recommended resolution) or `layer_outside_area` (a layer is outside the print area and will not print).
`message`	string	Human-readable explanation.
`param`	string	The design layer the warning is about.
`placement`	string	Placement key.
`effective_dpi`	number \| null	Effective resolution of the artwork at its placed size (resolution warnings only).

Example product warning

JSON

{
  "code": "dpi_low",
  "message": "Artwork on Front is 120 DPI at this size (recommended 150+). It may print slightly blurry.",
  "param": "designs[0].layers[0]",
  "placement": "front",
  "effective_dpi": 120
}

Design

Artwork layers on one placement (as returned on products and order items).

Returned by: Product.designs, OrderItem.designs.

Field	Type	Description
`placement`	string	Placement key (e.g. `front`).
`layers`	array of object	Layers, bottom to top.
`layers[].file_id`	string	Artwork file.
`layers[].transform`	Transform	Position of the layer in the print area.
`layers[].opacity`	number	Opacity from 0 to 1.

Example design

JSON

{
  "placement": "front",
  "layers": [
    {
      "file_id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9",
      "transform": {
        "x": 0.1,
        "y": 0.05,
        "width": 0.8,
        "height": 0.6,
        "rotation": 0
      },
      "opacity": 1
    }
  ]
}

Transform

Where a layer sits in the print area, as fractions of the area (see Designs & transforms).

Returned by: Design.layers[].transform.

Field	Type	Description
`x`	number	Left edge of the artwork box as a fraction of the print area width.
`y`	number	Top edge of the artwork box as a fraction of the print area height.
`width`	number	Artwork width as a fraction of the print area width.
`height`	number	Artwork height as a fraction of the print area height.
`rotation`	number	Clockwise rotation in degrees around the artwork center.

Example transform

JSON

{
  "x": 0.1,
  "y": 0.05,
  "width": 0.8,
  "height": 0.6,
  "rotation": 0
}

Shipping rate

Price and delivery time of one shipping method for a destination and items.

Returned by: POST /shipping/rates, OrderEstimate.available_shipping_methods.

Field	Type	Description
`object`	"shipping_rate"	Type of the object: always `shipping_rate`.
`method`	string	Shipping method (use it as `shipping_method` on orders). One of: `economy`, `standard`, `express`, `priority`.
`name`	string	Display name of the method.
`price`	integer	Shipping price for these items (cents).
`currency`	string	Three-letter currency code, lowercase (`usd`).
`min_days`	integer	Minimum transit time in business days.
`max_days`	integer	Maximum transit time in business days.
`estimated_delivery_days`	object	Business days from order to delivery, including production time.
`estimated_delivery_days.min`	integer	Fastest estimate in business days.
`estimated_delivery_days.max`	integer	Slowest estimate in business days.

Example shipping rate

JSON

{
  "object": "shipping_rate",
  "method": "standard",
  "name": "Standard",
  "price": 475,
  "currency": "usd",
  "min_days": 3,
  "max_days": 5,
  "estimated_delivery_days": {
    "min": 5,
    "max": 9
  }
}

Order

An order for your end customer: items, recipient, totals, status, shipments and tracking.

Returned by: POST /orders, GET /orders, GET /orders/{id}, events order.*.

Field	Type	Description
`object`	"order"	Type of the object: always `order`.
`id`	string	Unique identifier (starts with `ord_`).
`number`	integer	Sequential human-friendly order number.
`external_id`	string \| null	Your order id (unique per mode). Look the order up with `GET /orders/ext:<external_id>`.
`livemode`	boolean	`true` in live mode, `false` in test mode.
`status`	string	draft → processing → in_production → (partially_)shipped → delivered; on_hold (see hold_reason), canceled, failed. One of: `draft`, `on_hold`, `processing`, `in_production`, `partially_shipped`, `shipped`, `delivered`, `canceled`, `failed`.
`hold_reason`	string \| null	Why the order is on hold; only set while `status` is `on_hold`. One of: `insufficient_funds`, `manual_review`, `artwork_issue`, `address_issue`, `fulfillment_issue`.
`funds_status`	string	State of the credits for this order: `none` (draft), `awaiting` (on hold for credits), `held` (reserved), `partially_captured`/`captured` (spent), `released` (returned unspent), `partially_refunded`/`refunded`. One of: `none`, `awaiting`, `held`, `partially_captured`, `captured`, `released`, `partially_refunded`, `refunded`.
`source`	string	Where the order was created. One of: `api`, `dashboard`, `import`, `admin`.
`recipient`	Recipient	Shipping address of the end customer.
`shipping_method`	string	Shipping speed of the order. One of: `economy`, `standard`, `express`, `priority`.
`currency`	string	Three-letter currency code, lowercase (`usd`).
`subtotal`	integer	Items total in cents.
`shipping`	integer	Shipping price in cents.
`tax`	integer	Tax in cents (0 unless tax applies to the destination).
`discount`	integer	Discount in cents.
`total`	integer	Credits charged for this order (cents).
`refunded`	integer	Credits refunded to your wallet for this order, in cents.
`items`	array of OrderItem	Line items of the order.
`shipments`	array of Shipment	Parcels shipped so far (an order can ship in several parcels).
`tracking_page_url`	string \| null	Your branded tracking page for the end customer. null while the order is a draft (the page exists once it is confirmed).
`packing_slip`	object \| null	Packing slip overrides of this order (null when none were sent).
`packing_slip.message`	string \| null	Message printed on the packing slip.
`packing_slip.brand_name`	string \| null	Brand name printed instead of your account brand name.
`packing_slip.logo_file_id`	string \| null	The uploaded file printed as the logo on the packing slip (null: your account logo).
`packing_slip.customer_order_number`	string \| null	Order number your customer knows (e.g. `#1042`), printed on the slip.
`gift_message`	string \| null	Gift message included with the parcel.
`customer_note`	string \| null	Note from your customer.
`metadata`	map of string	Your key/value pairs (string values).
`created_at`	string \| null	When the object was created (ISO-8601, UTC).
`updated_at`	string \| null	When the object was last changed (ISO-8601, UTC).
`placed_at`	string \| null	When the order was confirmed (credits reserved, or the order put on hold for funds).
`in_production_at`	string \| null	When production started.
`shipped_at`	string \| null	When the order shipped.
`delivered_at`	string \| null	When every shipment was delivered.
`canceled_at`	string \| null	When the order was canceled.
`cancel_reason`	string \| null	Reason given when the order was canceled.
`failed_at`	string \| null	When the order failed.
`failure_reason`	string \| null	Why the order failed (reserved credits were released).

Example order

JSON

{
  "object": "order",
  "id": "ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
  "number": 1042,
  "external_id": "1042",
  "livemode": true,
  "status": "shipped",
  "hold_reason": null,
  "funds_status": "captured",
  "source": "api",
  "recipient": {
    "name": "Jane Doe",
    "company": null,
    "address1": "123 Market St",
    "address2": "Apt 4",
    "city": "San Francisco",
    "state_code": "CA",
    "postal_code": "94107",
    "country_code": "US",
    "phone": null,
    "email": "jane@example.com"
  },
  "shipping_method": "standard",
  "currency": "usd",
  "subtotal": 2598,
  "shipping": 700,
  "tax": 0,
  "discount": 0,
  "total": 3298,
  "refunded": 0,
  "items": [
    {
      "object": "order_item",
      "id": "oi_01k8x4b2qa3s5d7f9g1h3j5k7l",
      "product_id": "prod_01k8x3z7r1t3y5u7i9o1p3a5s7",
      "product_variant_id": "pvar_01k8x3z7r4f6g8h0j2k4l6z8x0",
      "catalog_product_id": "cp_01k8w1a2s3d4f5g6h7j8k9m0n1",
      "catalog_variant_id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
      "sku": "CA-TEE-BLK-M",
      "title": "Company A Logo Tee",
      "variant_title": "Black / M",
      "quantity": 2,
      "shipped_quantity": 2,
      "unit_price": 1299,
      "total_price": 2598,
      "retail_price": 2500,
      "status": "shipped",
      "designs": [
        {
          "placement": "front",
          "layers": [
            {
              "file_id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9",
              "transform": {
                "x": 0.1,
                "y": 0.05,
                "width": 0.8,
                "height": 0.6,
                "rotation": 0
              },
              "opacity": 1
            }
          ]
        }
      ],
      "mockup_url": null,
      "external_line_id": "line-1",
      "metadata": {}
    }
  ],
  "shipments": [
    {
      "object": "shipment",
      "id": "shp_01k8x9z1m3n5b7v9c1x3z5a7s9",
      "order_id": "ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
      "status": "in_transit",
      "carrier": "usps",
      "service": "USPS Ground Advantage",
      "tracking_number": "9400111899223197428490",
      "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223197428490",
      "items": [
        {
          "order_item_id": "oi_01k8x4b2qa3s5d7f9g1h3j5k7l",
          "quantity": 2
        }
      ],
      "shipped_at": "2026-10-23T09:12:44.000Z",
      "estimated_delivery_at": null,
      "delivered_at": null,
      "created_at": "2026-10-23T09:12:44.000Z"
    }
  ],
  "tracking_page_url": "https://swaglists.com/track/Zx81kLm2pQ",
  "packing_slip": {
    "message": "Thanks for shopping with Company A!",
    "brand_name": null,
    "logo_file_id": null,
    "customer_order_number": "#1042"
  },
  "gift_message": null,
  "customer_note": null,
  "metadata": {},
  "created_at": "2026-10-21T14:32:05.000Z",
  "updated_at": "2026-10-23T09:12:44.000Z",
  "placed_at": "2026-10-21T14:32:05.000Z",
  "in_production_at": "2026-10-21T14:32:05.000Z",
  "shipped_at": "2026-10-23T09:12:44.000Z",
  "delivered_at": null,
  "canceled_at": null,
  "cancel_reason": null,
  "failed_at": null,
  "failure_reason": null
}

Order item

A line of an order (prices and designs are snapshotted when the order is created).

Returned by: Order.items.

Field	Type	Description
`object`	"order_item"	Type of the object: always `order_item`.
`id`	string	Unique identifier (starts with `oi_`).
`product_id`	string \| null	Your product (null for items ordered by catalog variant with inline designs).
`product_variant_id`	string \| null	Your product variant (null for inline catalog items).
`catalog_product_id`	string	Catalog product of the item.
`catalog_variant_id`	string	Catalog variant of the item.
`sku`	string \| null	Your SKU (null for inline catalog items).
`title`	string	Product title at order time.
`variant_title`	string \| null	Variant title at order time (e.g. `Black / M`).
`quantity`	integer	Units ordered.
`shipped_quantity`	integer	Units shipped so far.
`unit_price`	integer	Wholesale unit price (cents).
`total_price`	integer	`unit_price` × `quantity`, in cents.
`retail_price`	integer \| null	Your retail unit price to the end customer (cents), as given on the order or taken from the product; null when unknown.
`status`	string	Production status of the item. One of: `draft`, `pending`, `in_production`, `shipped`, `delivered`, `canceled`, `failed`.
`designs`	array of Design	Snapshot of the designs at order time.
`mockup_url`	string \| null	Preview image of the item, when available (signed URL).
`external_line_id`	string \| null	Your line item id.
`metadata`	map of string	Your key/value pairs (string values).

Example order item

JSON

{
  "object": "order_item",
  "id": "oi_01k8x4b2qa3s5d7f9g1h3j5k7l",
  "product_id": "prod_01k8x3z7r1t3y5u7i9o1p3a5s7",
  "product_variant_id": "pvar_01k8x3z7r4f6g8h0j2k4l6z8x0",
  "catalog_product_id": "cp_01k8w1a2s3d4f5g6h7j8k9m0n1",
  "catalog_variant_id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
  "sku": "CA-TEE-BLK-M",
  "title": "Company A Logo Tee",
  "variant_title": "Black / M",
  "quantity": 2,
  "shipped_quantity": 2,
  "unit_price": 1299,
  "total_price": 2598,
  "retail_price": 2500,
  "status": "shipped",
  "designs": [
    {
      "placement": "front",
      "layers": [
        {
          "file_id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9",
          "transform": {
            "x": 0.1,
            "y": 0.05,
            "width": 0.8,
            "height": 0.6,
            "rotation": 0
          },
          "opacity": 1
        }
      ]
    }
  ],
  "mockup_url": null,
  "external_line_id": "line-1",
  "metadata": {}
}

Recipient

The end customer's shipping address.

Returned by: Order.recipient.

Field	Type	Description
`name`	string	Full name of the recipient.
`company`	string \| null	Company name.
`address1`	string	Street address.
`address2`	string \| null	Apartment, suite, unit, etc.
`city`	string	City.
`state_code`	string \| null	State/province code (e.g. `CA`), where applicable.
`postal_code`	string	Postal / ZIP code (empty for countries without postal codes).
`country_code`	string	ISO 3166-1 alpha-2 country code.
`phone`	string \| null	Phone number (carriers may use it for delivery questions).
`email`	string \| null	Email address (used for shipment notifications, when enabled).

Example recipient

JSON

{
  "name": "Jane Doe",
  "company": null,
  "address1": "123 Market St",
  "address2": "Apt 4",
  "city": "San Francisco",
  "state_code": "CA",
  "postal_code": "94107",
  "country_code": "US",
  "phone": null,
  "email": "jane@example.com"
}

Shipment

A parcel with carrier tracking. An order can ship in several parcels.

Returned by: Order.shipments, events shipment.*.

Field	Type	Description
`object`	"shipment"	Type of the object: always `shipment`.
`id`	string	Unique identifier (starts with `shp_`).
`order_id`	string	Order the parcel belongs to.
`status`	string	Tracking status of the parcel. One of: `pending`, `label_created`, `in_transit`, `out_for_delivery`, `delivered`, `exception`, `returned`.
`carrier`	string \| null	Carrier code (e.g. `usps`, `ups`, `fedex`, `dhl`).
`service`	string \| null	Carrier service name (e.g. `USPS Ground Advantage`).
`tracking_number`	string \| null	Carrier tracking number.
`tracking_url`	string \| null	Carrier tracking page.
`items`	array of object	Order items (and quantities) in this parcel.
`items[].order_item_id`	string	Order item in the parcel.
`items[].quantity`	integer	Units of that item in the parcel.
`shipped_at`	string \| null	When the parcel was handed to the carrier.
`estimated_delivery_at`	string \| null	Carrier's estimated delivery date, when known.
`delivered_at`	string \| null	When the parcel was delivered.
`created_at`	string \| null	When the object was created (ISO-8601, UTC).

Example shipment

JSON

{
  "object": "shipment",
  "id": "shp_01k8x9z1m3n5b7v9c1x3z5a7s9",
  "order_id": "ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
  "status": "in_transit",
  "carrier": "usps",
  "service": "USPS Ground Advantage",
  "tracking_number": "9400111899223197428490",
  "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223197428490",
  "items": [
    {
      "order_item_id": "oi_01k8x4b2qa3s5d7f9g1h3j5k7l",
      "quantity": 2
    }
  ],
  "shipped_at": "2026-10-23T09:12:44.000Z",
  "estimated_delivery_at": null,
  "delivered_at": null,
  "created_at": "2026-10-23T09:12:44.000Z"
}

Order event

An entry of an order's timeline.

Returned by: GET /orders/{id}/events.

Field	Type	Description
`object`	"order_event"	Type of the object: always `order_event`.
`id`	string	Unique identifier (starts with `oev_`).
`type`	string	Kind of entry (for example `confirmed`, `status_changed`, `on_hold`, `shipment_created`, `canceled`).
`message`	string	Human-readable description.
`from_status`	string \| null	Order status before the change (status changes only).
`to_status`	string \| null	Order status after the change (status changes only).
`created_at`	string \| null	When the object was created (ISO-8601, UTC).

Example order event

JSON

{
  "object": "order_event",
  "id": "oev_01k8x4b2qc5v7b9n1m3k5j7h9g",
  "type": "status_changed",
  "message": "Order is in production",
  "from_status": "processing",
  "to_status": "in_production",
  "created_at": "2026-10-21T14:32:05.000Z"
}

Order estimate

Exactly what an order would cost; nothing is created.

Returned by: POST /orders/estimate.

Field	Type	Description
`object`	"order_estimate"	Type of the object: always `order_estimate`.
`livemode`	boolean	`true` in live mode, `false` in test mode.
`currency`	string	Three-letter currency code, lowercase (`usd`).
`shipping_method`	string	Shipping method the estimate was priced with. One of: `economy`, `standard`, `express`, `priority`.
`items`	array of object	Priced items, in the order you sent them.
`items[].index`	integer	Position of the item in your `items` array.
`items[].catalog_variant_id`	string	Catalog variant that will be produced.
`items[].product_variant_id`	string \| null	Your product variant (null for inline catalog items).
`items[].sku`	string \| null	Your SKU (null for inline catalog items).
`items[].title`	string	Product title.
`items[].variant_title`	string \| null	Variant title.
`items[].quantity`	integer	Units.
`items[].unit_price`	integer	Wholesale unit price in cents.
`items[].total_price`	integer	`unit_price` × `quantity`, in cents.
`subtotal`	integer	Items total in cents.
`shipping`	integer	Shipping price in cents.
`tax`	integer	Tax in cents.
`total`	integer	Exactly what POST /orders would charge.
`available_shipping_methods`	array of ShippingRate	Every shipping method you could choose, with its price.
`estimated_delivery_days`	object	Business days from order to delivery, including production.
`estimated_delivery_days.min`	integer	Fastest estimate in business days.
`estimated_delivery_days.max`	integer	Slowest estimate in business days.
`wallet_available`	integer	Available credits (cents).
`sufficient_funds`	boolean	Whether your available credits cover `total`.

Example order estimate

JSON

{
  "object": "order_estimate",
  "livemode": true,
  "currency": "usd",
  "shipping_method": "standard",
  "items": [
    {
      "index": 0,
      "catalog_variant_id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
      "product_variant_id": "pvar_01k8x3z7r4f6g8h0j2k4l6z8x0",
      "sku": "CA-TEE-BLK-M",
      "title": "Company A Logo Tee",
      "variant_title": "Black / M",
      "quantity": 2,
      "unit_price": 1299,
      "total_price": 2598
    }
  ],
  "subtotal": 2598,
  "shipping": 700,
  "tax": 0,
  "total": 3298,
  "available_shipping_methods": [
    {
      "object": "shipping_rate",
      "method": "standard",
      "name": "Standard",
      "price": 475,
      "currency": "usd",
      "min_days": 3,
      "max_days": 5,
      "estimated_delivery_days": {
        "min": 5,
        "max": 9
      }
    }
  ],
  "estimated_delivery_days": {
    "min": 5,
    "max": 9
  },
  "wallet_available": 482550,
  "sufficient_funds": true
}

Webhook endpoint

A URL we POST events to.

Returned by: POST /webhook_endpoints, GET /webhook_endpoints, GET /webhook_endpoints/{id}.

Field	Type	Description
`object`	"webhook_endpoint"	Type of the object: always `webhook_endpoint`.
`id`	string	Unique identifier (starts with `we_`).
`url`	string	URL we POST events to.
`description`	string \| null	Your description.
`enabled_events`	array of string	Event types delivered to this endpoint; ["*"] = all.
`status`	string	`enabled` endpoints receive events. One of: `enabled`, `disabled`.
`disabled_reason`	string \| null	Why the endpoint was disabled: `disabled_by_user`, `failing_deliveries` (every delivery failed for 5 days) or `endpoint_gone` (it answered HTTP 410).
`mode`	string	`live` or `test`. One of: `live`, `test`.
`livemode`	boolean	`true` in live mode, `false` in test mode.
`created_at`	string	When the object was created (ISO-8601, UTC).
`secret`	string	Signing secret (whsec_…). Only returned when the endpoint is created and when the secret is rotated — store it safely.

Example webhook endpoint

JSON

{
  "object": "webhook_endpoint",
  "id": "we_01k8x2m4n6b8v0c2x4z6a8s0d2",
  "url": "https://company-a.example/webhooks/print",
  "description": "Production order updates",
  "enabled_events": [
    "order.shipped",
    "order.delivered"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "mode": "live",
  "livemode": true,
  "created_at": "2026-10-21T14:32:05.000Z"
}

Webhook delivery

One event delivered (or being delivered) to one endpoint.

Returned by: POST /webhook_endpoints/{id}/test.

Field	Type	Description
`object`	"webhook_delivery"	Type of the object: always `webhook_delivery`.
`id`	string	Unique identifier (starts with `whd_`).
`event_id`	string	Event delivered.
`endpoint_id`	string	Endpoint delivered to.
`status`	string	`pending`, `retrying`, `succeeded` or `failed`. One of: `pending`, `retrying`, `succeeded`, `failed`.
`attempts`	integer	Attempts made so far.
`response_status`	integer \| null	HTTP status of the last attempt.
`next_attempt_at`	string \| null	When the next attempt is scheduled.
`last_attempt_at`	string \| null	When the last attempt was made.
`created_at`	string	When the object was created (ISO-8601, UTC).

Example webhook delivery

JSON

{
  "object": "webhook_delivery",
  "id": "whd_01k8x4b2r3e5w7q9a1s3d5f7g9",
  "event_id": "evt_01k8x4b2r1t3y5u7i9o1p3a5s7",
  "endpoint_id": "we_01k8x2m4n6b8v0c2x4z6a8s0d2",
  "status": "pending",
  "attempts": 0,
  "response_status": null,
  "next_attempt_at": "2026-10-21T14:32:05.000Z",
  "last_attempt_at": null,
  "created_at": "2026-10-21T14:32:05.000Z"
}

Event

Something that happened in your account — also the exact JSON body POSTed to your webhook endpoints.

Returned by: GET /events, GET /events/{id}, webhook deliveries.

Field	Type	Description
`id`	string	Event id. Also sent as the `webhook-id` header and stable across retries — deduplicate on it.
`object`	"event"	Type of the object: always `event`.
`type`	string	Event type (e.g. `order.shipped`).
`api_version`	string	API version the payload was rendered with.
`created_at`	string	When the event happened (ISO-8601, UTC).
`livemode`	boolean	`true` in live mode, `false` in test mode.
`data`	map of any	`object` is the resource as of the event (same shape as the API returns); `previous_attributes` lists changed fields on *.updated events.

Example event

JSON

{
  "id": "evt_01k8x4b2r1t3y5u7i9o1p3a5s7",
  "object": "event",
  "type": "order.shipped",
  "api_version": "2026-10-01",
  "created_at": "2026-10-21T14:32:05.000Z",
  "livemode": true,
  "data": {
    "object": {
      "object": "order",
      "id": "ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
      "number": 1042,
      "external_id": "1042",
      "livemode": true,
      "status": "shipped",
      "hold_reason": null,
      "funds_status": "captured",
      "source": "api",
      "recipient": {
        "name": "Jane Doe",
        "company": null,
        "address1": "123 Market St",
        "address2": "Apt 4",
        "city": "San Francisco",
        "state_code": "CA",
        "postal_code": "94107",
        "country_code": "US",
        "phone": null,
        "email": "jane@example.com"
      },
      "shipping_method": "standard",
      "currency": "usd",
      "subtotal": 2598,
      "shipping": 700,
      "tax": 0,
      "discount": 0,
      "total": 3298,
      "refunded": 0,
      "items": [
        {
          "object": "order_item",
          "id": "oi_01k8x4b2qa3s5d7f9g1h3j5k7l",
          "product_id": "prod_01k8x3z7r1t3y5u7i9o1p3a5s7",
          "product_variant_id": "pvar_01k8x3z7r4f6g8h0j2k4l6z8x0",
          "catalog_product_id": "cp_01k8w1a2s3d4f5g6h7j8k9m0n1",
          "catalog_variant_id": "cv_01k8w1a2s7d9f1g3h5j7k9m1n3",
          "sku": "CA-TEE-BLK-M",
          "title": "Company A Logo Tee",
          "variant_title": "Black / M",
          "quantity": 2,
          "shipped_quantity": 2,
          "unit_price": 1299,
          "total_price": 2598,
          "retail_price": 2500,
          "status": "shipped",
          "designs": [
            {
              "placement": "front",
              "layers": [
                {
                  "file_id": "file_01k8x3y1q3w5e7r9t1y3u5i7o9",
                  "transform": {
                    "x": 0.1,
                    "y": 0.05,
                    "width": 0.8,
                    "height": 0.6,
                    "rotation": 0
                  },
                  "opacity": 1
                }
              ]
            }
          ],
          "mockup_url": null,
          "external_line_id": "line-1",
          "metadata": {}
        }
      ],
      "shipments": [
        {
          "object": "shipment",
          "id": "shp_01k8x9z1m3n5b7v9c1x3z5a7s9",
          "order_id": "ord_01k8x4b2q9w7e3r5t1y8u6i0pa",
          "status": "in_transit",
          "carrier": "usps",
          "service": "USPS Ground Advantage",
          "tracking_number": "9400111899223197428490",
          "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223197428490",
          "items": [
            {
              "order_item_id": "oi_01k8x4b2qa3s5d7f9g1h3j5k7l",
              "quantity": 2
            }
          ],
          "shipped_at": "2026-10-23T09:12:44.000Z",
          "estimated_delivery_at": null,
          "delivered_at": null,
          "created_at": "2026-10-23T09:12:44.000Z"
        }
      ],
      "tracking_page_url": "https://swaglists.com/track/Zx81kLm2pQ",
      "packing_slip": {
        "message": "Thanks for shopping with Company A!",
        "brand_name": null,
        "logo_file_id": null,
        "customer_order_number": "#1042"
      },
      "gift_message": null,
      "customer_note": null,
      "metadata": {},
      "created_at": "2026-10-21T14:32:05.000Z",
      "updated_at": "2026-10-23T09:12:44.000Z",
      "placed_at": "2026-10-21T14:32:05.000Z",
      "in_production_at": "2026-10-21T14:32:05.000Z",
      "shipped_at": "2026-10-23T09:12:44.000Z",
      "delivered_at": null,
      "canceled_at": null,
      "cancel_reason": null,
      "failed_at": null,
      "failure_reason": null
    }
  }
}

Error

Every error response has this body.

Returned by: any 4xx/5xx response.

Field	Type	Description
`error`	object	The error.
`error.type`	string	Category of the error. One of: `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `conflict_error`, `idempotency_error`, `rate_limit_error`, `insufficient_funds_error`, `api_error`.
`error.code`	string	Stable, machine-readable error code (see doc_url).
`error.message`	string	Human-readable explanation; safe to log, not meant for end customers.
`error.param`	string	The request parameter the error relates to, e.g. items[0].quantity.
`error.doc_url`	string	Documentation for this error code.
`error.request_id`	string	Id of the request (also in the Request-Id header). Quote it when contacting support.
`error.required_amount`	integer	insufficient_funds only: credits required (cents).
`error.available_amount`	integer	insufficient_funds only: credits available (cents).
`error.currency`	string	Currency of the amounts (insufficient_funds only).
`error.existing_id`	string	duplicate_external_id / resource_already_exists only: id of the existing resource (e.g. the order that already has this external_id).
`error.required_scope`	string	insufficient_scope only: the scope the key is missing.
`error.errors`	array of object	Validation errors only: every problem found in the request (at most 50); the first one is the top-level code / param / message. Fix them all before retrying. Up to 50 items.
`error.errors[].param`	string \| null	The parameter of this problem (null for the request as a whole).
`error.errors[].code`	string	Error code of this problem (usually parameter_invalid).
`error.errors[].message`	string	Human-readable explanation of this problem.
`error.allowed_values`	array of string or number or boolean	For a value outside a fixed set (e.g. a placement key): the accepted values (`[true, false]` for a yes/no customization).
`error.available_shipping_methods`	array of string	shipping_method_unavailable: the shipping methods that are available for this request; recipient errors another method would avoid (po_box_not_supported, recipient_phone_required, recipient_email_required): the methods that would deliver.
`error.max_length`	integer	For a field that is too long: the largest length (in characters) that can be accepted.
`error.max_quantity`	integer	For a quantity that is too large: the largest quantity that can be accepted.

Example error

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid items[0].quantity: must be greater than or equal to 1.",
    "param": "items[0].quantity",
    "doc_url": "https://swaglists.com/docs/errors#parameter_invalid",
    "request_id": "req_01k8x4b2q7w9e1r3t5y7u9i1o3"
  }
}

Catalog price change

The data.object of catalog.price_changed events.

Field	Type	Description
`object`	string	Always `catalog_price_change`.
`catalog_product_id`	string	Catalog product whose wholesale prices changed.
`catalog_variant_ids`	array of string	Changed catalog variants that your products use.
`reason`	string	One of: `cost_increase`, `cost_decrease`, `cost_change`, `pricing_change`.

Objects reference

#Conventions

#List

#Account

#Wallet

#Transaction

#Top-up

#Catalog category

#Catalog product

#Catalog variant

#Placement

#File requirements

#Mockup template

#File

#Product

#Product variant

#Product warning

#Design

#Transform

#Shipping rate

#Order

#Order item

#Recipient

#Shipment

#Order event

#Order estimate

#Webhook endpoint

#Webhook delivery

#Event

#Error

#Catalog price change

Conventions

List

Account

Wallet

Transaction

Top-up

Catalog category

Catalog product

Catalog variant

Placement

File requirements

Mockup template

File

Product

Product variant

Product warning

Design

Transform

Shipping rate

Order

Order item

Recipient

Shipment

Order event

Order estimate

Webhook endpoint

Webhook delivery

Event

Error

Catalog price change