# Objects reference

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

Source: https://swaglists.com/docs/objects

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](https://swaglists.com/docs/pagination.md).

| 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](https://swaglists.com/docs/objects.md#wallet) | Wallet of the key's mode. |
| `created_at` | string | When the object was created (ISO-8601, UTC). |

<details><summary>Example account</summary>

```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"
}
```

</details>

## 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. |

<details><summary>Example wallet</summary>

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

</details>

## 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). |

<details><summary>Example transaction</summary>

```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"
}
```

</details>

## 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. |

<details><summary>Example top-up</summary>

```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"
}
```

</details>

## 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). |

<details><summary>Example catalog category</summary>

```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"
}
```

</details>

## 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](https://swaglists.com/docs/objects.md#catalog_category) | 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](https://swaglists.com/docs/objects.md#placement) | Print areas you can put artwork on. |
| `variants` | array of [CatalogVariant](https://swaglists.com/docs/objects.md#catalog_variant) | Active variants with your wholesale price and availability. |
| `mockup_templates` | array of [MockupTemplate](https://swaglists.com/docs/objects.md#mockup_template) | 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). |

<details><summary>Example catalog product</summary>

```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"
}
```

</details>

## 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`). |

<details><summary>Example catalog variant</summary>

```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"
}
```

</details>

## 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](https://swaglists.com/docs/objects.md#file_requirements) | Artwork requirements of this placement. |

<details><summary>Example placement</summary>

```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
  }
}
```

</details>

## 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. |

<details><summary>Example file requirements</summary>

```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
}
```

</details>

## 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. |

<details><summary>Example mockup template</summary>

```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
}
```

</details>

## 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). |

<details><summary>Example file</summary>

```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"
}
```

</details>

## 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](https://swaglists.com/docs/objects.md#design) | Artwork per placement. |
| `variants` | array of [ProductVariant](https://swaglists.com/docs/objects.md#product_variant) | 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](https://swaglists.com/docs/objects.md#product_warning) | 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). |

<details><summary>Example product</summary>

```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"
}
```

</details>

## 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. |

<details><summary>Example product variant</summary>

```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
}
```

</details>

## 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). |

<details><summary>Example product warning</summary>

```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
}
```

</details>

## 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](https://swaglists.com/docs/objects.md#transform) | Position of the layer in the print area. |
| `layers[].opacity` | number | Opacity from 0 to 1. |

<details><summary>Example design</summary>

```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
    }
  ]
}
```

</details>

## 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. |

<details><summary>Example transform</summary>

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

</details>

## 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. |

<details><summary>Example shipping rate</summary>

```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
  }
}
```

</details>

## 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](https://swaglists.com/docs/objects.md#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](https://swaglists.com/docs/objects.md#order_item) | Line items of the order. |
| `shipments` | array of [Shipment](https://swaglists.com/docs/objects.md#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). |

<details><summary>Example order</summary>

```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
}
```

</details>

## 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](https://swaglists.com/docs/objects.md#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). |

<details><summary>Example order item</summary>

```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": {}
}
```

</details>

## 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). |

<details><summary>Example recipient</summary>

```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"
}
```

</details>

## 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). |

<details><summary>Example shipment</summary>

```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"
}
```

</details>

## 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). |

<details><summary>Example order event</summary>

```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"
}
```

</details>

## 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](https://swaglists.com/docs/objects.md#shipping_rate) | 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`. |

<details><summary>Example order estimate</summary>

```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
}
```

</details>

## 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. |

<details><summary>Example webhook endpoint</summary>

```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"
}
```

</details>

## 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). |

<details><summary>Example webhook delivery</summary>

```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"
}
```

</details>

## 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. |

<details><summary>Example event</summary>

```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
    }
  }
}
```

</details>

## 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. |

<details><summary>Example error</summary>

```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"
  }
}
```

</details>

## 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`. |