{
  "openapi": "3.0.3",
  "info": {
    "title": "Printeers API V2",
    "contact": {
      "name": "Printeers API team",
      "email": "support@printeers.com"
    },
    "description": "The Printeers API lets you automate your interaction with Printeers, for example to place orders or generate product renders.\n\nIf you are new to the API, start with the [Getting Started guide](/guides/getting-started). For topics like creating orders or rendering, see the [Guides index](/guides).\n\nIf something is not working nicely or can be improved, send a message to support@printeers.com.\n\n### Legacy fields\n\nSome responses include fields prefixed with `legacy` (e.g. `legacyCode`, `legacySku`). These exist to help you map data from v1 to the new v2+ references during migration.\n\nUse them while you migrate, but plan to switch to the v2+ references over time. Legacy fields will be removed in v3.\n\n### Forward compatibility\n\nThis spec is designed so that an older copy of it stays compatible with a newer server within the same major version. Response schemas follow OpenAPI's default `additionalProperties: true` behavior, allowing the server to add new fields in a minor version without breaking clients that decoded their types from an older version of the spec. Request schemas explicitly set `additionalProperties: false` so the server rejects undocumented input fields, catching typos and obsolete fields at the boundary.\n\nSee the [API Versioning guide](/guides/api-versioning#forward-compatibility-within-a-major-version) for the full forward-compatibility contract and the complete list of what counts as a non-breaking change within v2.\n\n## Changelog\n\n- **2026-09-28 v2.7.0**:\n  - Add `annotations` to the orderlines in `GET /orders/{orderReference}`: the key-value annotations that were given for the orderline when the order was created, as v1 already returned them. The array is always present and empty when the orderline has no annotations. See the [Creating Orders guide](/guides/creating-orders#annotations).\n  - Add `POST /quote` to calculate the shipping options and shipping prices of an order before placing it. It takes the fields of `POST /orders` that determine shipping, under the same names. See the [Creating Orders guide](/guides/creating-orders#quoting-shipping-costs).\n- **2026-09-27 v2.6.0**:\n  - Add `PUT /orders/{orderReference}/dropship-address` to change the destination address of a dropship order that has not shipped yet. See the [Creating Orders guide](/guides/creating-orders#changing-the-dropship-address).\n- **2026-09-22 v2.5.2**:\n  - `GET /renders/{renderReference}/media` and `GET /renders/{renderReference}/thumbnail` now send `Cache-Control: private, max-age=31536000, immutable`. A completed render's files never change, so HTTP clients and proxies can keep them cached instead of downloading them again.\n  - `GET /products/{productReference}/media/{filename}` now sends cache headers: `Cache-Control: private, max-age=31536000, immutable` for renders, and `Cache-Control: private, no-cache` with `ETag` and `Last-Modified` for example images so a cached copy can be revalidated.\n  - The layer image URLs from `GET /products/{productReference}` now send `ETag` and `Last-Modified` and answer `304 Not Modified` to `If-None-Match` / `If-Modified-Since`, so cached layer images can be revalidated without re-downloading them. Use `layersModified` from `GET /products` to decide which products to re-check; see the [Products guide](/guides/products#syncing-your-catalog).\n- **2026-09-10 v2.5.1**:\n  - `POST /claim-item-issues` now returns dedicated `400` error codes for three input mistakes that previously came back as `unknown_input_error` or a `500`: `order_not_in_shipment` (no items of the order were shipped in the shipment), `orderline_not_in_shipment` (an `orderlineIndex` is not in the shipment) and `package_missing_category_not_allowed` (the \"Package missing\" claimcategory is reserved for `POST /claim-package-missing`).\n- **2026-07-23 v2.5.0**:\n  - Add `weightGrams` to `GET /products/{productReference}`: the weight of one unit of the product in grams, for example to calculate shipping costs. It is `null` for products whose weight has not been measured yet.\n- **2026-07-14 v2.4.0**:\n  - Render creation now consumes **rendertokens** against a weekly per-organization limit. Every composition has a `tokenCost` (now included in `GET /lookup-composition` and `GET /compositions/{compositionReference}`), and `POST /renders` returns `429` with code `rendertoken_limit_exceeded` when the weekly limit is reached. The limit resets every Monday at 00:00 Europe/Amsterdam; a rendertoken subscription with a higher limit can be activated in the Printeers Dashboard.\n  - Add `GET /rendertokens` to check your organization's rendertoken usage, weekly limit, and the next reset moment.\n  - Add `evidenceRequired` to the claimcategories in `GET /claimcategories`. Evidence is no longer required for every item in an item-issues claim: categories with `evidenceRequired: false` (such as \"Item missing\") accept claimlines without evidence. The minimum for `evidenceReferences` in `POST /claim-item-issues` claimlines is relaxed accordingly; submitting no evidence for a category that requires it returns error code `evidence_required`.\n- **2026-07-12 v2.4.0**:\n  - Add `evidenceUrls` to the claim and claimlines in `GET /claims/{claimReference}`, listing the evidence images that were uploaded when the claim was created. Evidence is stored for a limited time: roughly four months after a claim is decided or retracted the images are purged, the lists become empty and previously returned URLs stop working.\n- **2026-06-29 v2.3.0**:\n  - Add `layersModified` and `printModified` to `GET /products` so you can tell which products changed and only re-pull what you need when syncing your catalog. The same timestamps are mirrored on `GET /products/{productReference}` as `layers.modified` and `print.modified`. See the [Products guide](/guides/products#syncing-your-catalog).\n  - Add `onHold` to `GET /orders/{orderReference}`. It is set when production for the order is on hold and carries a human-readable `reason`, and is `null` when the order is not on hold.\n- **2026-06-12 v2.2.0**:\n  - Add `POST /orders/{orderReference}/cancel` to cancel (part of) the quantity of one or more orderlines. See the [Creating Orders guide](/guides/creating-orders#canceling-orderlines).\n- **2026-06-08 v2.1.0**:\n  - Add `media` to `GET /products/{productReference}` listing the images available for a product, and `GET /products/{productReference}/media/{filename}` to download them.\n  - Add `availableQuantity` to `GET /products` so you can read stock levels without fetching each product individually.\n- **2026-05-08 v2.0.0**:\n  - V2 is no longer in Beta Preview. The API is stable: from this release onward, breaking changes are reserved for a future v3 and additive changes ship as minor or patch versions within v2. V1 enters its one-year deprecation period; see the [API Versioning guide](/guides/api-versioning) for details.\n\nFor the Beta Preview release history, see the [V2 Beta Changelog](/guides/v2-beta-changelog).\n\n## API errors\n\n- `4xx` errors always return a Standard Error object with an error code and message.\n- `501 Not Implemented` is returned by endpoints that are not publicly available yet.\n- `5xx` errors other than `501 Not Implemented` are not documented by this OpenAPI spec. API clients must be able to gracefully handle 5xx errors, retrying later if needed. If you encounter a 5xx error, please contact our support team.\n",
    "version": "2.7.0"
  },
  "servers": [
    {
      "url": "https://api.test-printeers.com/v2",
      "description": "Test environment, use this if you are developing an integration with our API. Orders are never produced or\ninvoiced. Stock and product information is not complete.\n"
    },
    {
      "url": "https://api.printeers.com/v2",
      "description": "Production environment. Created orders are produced, delivered and billed.\n"
    }
  ],
  "tags": [
    {
      "name": "Auth",
      "description": "Authentication and authorization endpoints for validating API credentials."
    },
    {
      "name": "Organization",
      "description": "Endpoints for retrieving information about your organization, accounts, stores, and brands.\n\nYou can modify these objects through the Printeers Dashboard.\n"
    },
    {
      "name": "Catalog",
      "description": "Endpoints for browsing available products and packaging that can be ordered through the API.\n"
    },
    {
      "name": "Addresses",
      "description": "Endpoints for managing and validating addresses."
    },
    {
      "name": "Renders",
      "description": "Endpoints for creating and retrieving product mockup/preview renders.\n\nThe render system is built around four concepts: **scenes**, **perspectives**, **compositions**, and **renders**.\n\n- A **scene** is a 3D environment (e.g. a desk, a living room, a flat lay) in which products are placed for rendering.\n- A **perspective** defines the camera angle and output settings (resolution, format). There are two types: **scene perspectives** have cameras that come with the scene and are shared across products, while **product perspectives** have cameras specific to individual products.\n- A **composition** is a valid combination of a scene, a product, and a perspective. Use `GET /lookup-composition` to find the composition for a specific combination, and `GET /compositions/{compositionReference}` to retrieve its details.\n\nTo create a render, first look up the composition using `GET /lookup-composition`, then call `POST /renders` with the composition reference and an image reference.\n\nRender creation consumes **rendertokens**: every call to `POST /renders` deducts the composition's `tokenCost` from your organization's weekly rendertoken limit. The limit resets every Monday at 00:00 Europe/Amsterdam, aligned with the billing week. Check your usage with `GET /rendertokens`. A rendertoken subscription with a higher weekly limit can be activated in the Printeers Dashboard.\n\nRenders are not immediately available. Poll the `GET /renders/{renderReference}` endpoint until the render status is completed, use a 60 second interval to poll that endpoint. Or poll the `GET /renders/{renderReference}/media` endpoint until it returns HTTP 200. If the render is not ready yet, the media endpoint will return HTTP 202 with a Retry-After header. Wait the amount of seconds indicated by the Retry-After header before calling the media endpoint again.\n\nAn upcoming webhook system will allow you to be notified of completed renders, avoiding the need for polling.\n"
    },
    {
      "name": "Images",
      "description": "Endpoints for managing print images.\n\nUpload images before creating orders that contain print products. List uploaded images to review your image library.\n"
    },
    {
      "name": "Orders",
      "description": "Endpoints for creating and retrieving orders.\n"
    },
    {
      "name": "Shipments",
      "description": "Endpoints for retrieving shipment information including tracking details and shipped items.\n"
    },
    {
      "name": "Claims",
      "description": "Endpoints for managing claims on shipments (damaged, missing, or incorrect items).\n\nView existing claims and their status. Create new claims for issues with received shipments.\n"
    },
    {
      "name": "Warehouse",
      "description": "Endpoints for managing warehouse items.\n\nItems represent goods and materials that are owned by the partner and stored at Printeers.\n"
    },
    {
      "name": "Utilities",
      "description": "Utility endpoints for looking up references by legacy identifiers.\n\nThese endpoints help converting from v1 API (which uses legacy codes like store codes and order codes)\nto v2+ APIs (which use references like `Order_xxx`, `Store_xxx`, etc.).\n"
    }
  ],
  "components": {
    "securitySchemes": {
      "SecretKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Printeers-Secret-Key",
        "description": "V2 Secret Key. A V1/Legacy storeCore+storeKey will not work here."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request data",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication credentials are missing or invalid",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Access denied - insufficient permissions for the requested resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Requested resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Gone": {
        "description": "Resource no longer available (archived)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Conflict": {
        "description": "The request conflicts with the current state of the target resource. The request itself is well-formed; the conflict is in the resource state (uniqueness violation, archived store, claim already exists, etc.).\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. The request was rejected because the caller has consumed too many requests against one or more rate-limit policies.\n\nHonor `Retry-After` before retrying. See the Rate Limiting guide for policy details and header parsing.\n",
        "headers": {
          "Retry-After": {
            "description": "Number of seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            },
            "example": 60
          },
          "X-RateLimit-Policy": {
            "description": "Active rate-limit policies. See the Rate Limiting guide for the structured-fields format.",
            "schema": {
              "type": "string"
            },
            "example": "\"default\";q=3000;w=60"
          },
          "X-RateLimit": {
            "description": "Remaining quota per policy at response time.",
            "schema": {
              "type": "string"
            },
            "example": "\"default\";r=0;t=42"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "description": "Standard error response object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "lower_snake_case_error_code"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Human readable error message"
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "AddressReference": {
        "type": "string",
        "pattern": "^Address_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Address_xxx` that refers to an Address.\n",
        "example": "Address_hcxgz4ztnc4msg3v3qcad36xwr"
      },
      "AccountReference": {
        "type": "string",
        "pattern": "^Account_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Account_xxx` that refers to an Account.\n",
        "example": "Account_zt7cdqy06zecmwh2shry4cpq04"
      },
      "BrandReference": {
        "type": "string",
        "pattern": "^Brand_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Brand_xxx` that refers to a Brand.\n",
        "example": "Brand_vrt79tcztmh23bert2k2qw72b4"
      },
      "ClaimReference": {
        "type": "string",
        "pattern": "^Claim_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Claim_xxx` that refers to a Claim.\n",
        "example": "Claim_yvtazxbe3m9nrp409a96x9bxh4"
      },
      "ClaimcategoryReference": {
        "type": "string",
        "pattern": "^Claimcategory_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Claimcategory_xxx` that refers to a Claimcategory.\n",
        "example": "Claimcategory_zt7cdqy06zecmwh2shry4cpq04"
      },
      "EvidenceReference": {
        "type": "string",
        "pattern": "^Evidence_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "Reference to an uploaded evidence file. Upload evidence using `POST /evidence` before submitting a claim. Unused evidence is automatically deleted after 1 day.\n",
        "example": "Evidence_hcxgz4ztnc4msg3v3qcad36xwr"
      },
      "ImageReference": {
        "type": "string",
        "pattern": "^Image_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Image_xxx` that refers to an Image.\n",
        "example": "Image_pdcptbw3k48sv03wy338bb8jzm"
      },
      "PackagingReference": {
        "type": "string",
        "pattern": "^Packaging_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Packaging_xxx` that refers to a Packaging option.\n",
        "example": "Packaging_9dee0jkmvv1mxby1b7x40f9sbm"
      },
      "PerspectiveReference": {
        "type": "string",
        "pattern": "^Perspective_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Perspective_xxx` that refers to a Perspective.\n",
        "example": "Perspective_6rv2mc8yqw3nt5xk9hpz1bdfgs"
      },
      "ProductReference": {
        "type": "string",
        "pattern": "^Product_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Product_xxx` that refers to a Product.\n",
        "example": "Product_6rgpv1t48gswz36g7apj12xygc"
      },
      "ProductgroupReference": {
        "type": "string",
        "pattern": "^Productgroup_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Productgroup_xxx` that refers to a Productgroup.\n",
        "example": "Productgroup_7yrcm5hd2w8pz4x6k3qf9b1tnv"
      },
      "RenderReference": {
        "type": "string",
        "pattern": "^Render_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Render_xxx` that refers to a Render.\n",
        "example": "Render_8eksvwek9pc58r1qmqqf3492mg"
      },
      "SceneReference": {
        "type": "string",
        "pattern": "^Scene_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Scene_xxx` that refers to a Scene.\n",
        "example": "Scene_8hm3pz5wkr1yv7xn4btq9cdfsj"
      },
      "StoreReference": {
        "type": "string",
        "pattern": "^Store_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Store_xxx` that refers to a Store.\n",
        "example": "Store_x04rwj6knrhks8m19s8j6nc4z8"
      },
      "ShipmentReference": {
        "type": "string",
        "pattern": "^Shipment_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Shipment_xxx` that refers to a Shipment.\n",
        "example": "Shipment_8eksvwek9pc58r1qmqqf3492mg"
      },
      "OrderReference": {
        "type": "string",
        "pattern": "^Order_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Order_xxx` that refers to an Order.\n",
        "example": "Order_5x4rwj6knrhks8m19s8j6nc4z8"
      },
      "ItemReference": {
        "type": "string",
        "pattern": "^Item_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Item_xxx` that refers to an Item.\n",
        "example": "Item_7yrcm5hd2w8pz4x6k3qf9b1tnv"
      },
      "CompositionReference": {
        "type": "string",
        "pattern": "^Composition_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Composition_xxx` that refers to a Composition.\n",
        "example": "Composition_8hm3pz5wkr1yv7xn4btq9cdfsj"
      },
      "KeyReference": {
        "type": "string",
        "pattern": "^Key_[0123456789abcdefghjkmnpqrstvwxyz]{26}$",
        "description": "A string in the form of `Key_xxx` that refers to an API key.\n",
        "example": "Key_hcxgz4ztnc4msg3v3qcad36xwr"
      },
      "Address": {
        "type": "object",
        "additionalProperties": false,
        "description": "Address schema with required field validation.\n",
        "properties": {
          "company": {
            "type": "string",
            "description": "Recipient company name",
            "example": "Johns Company BV"
          },
          "firstname": {
            "type": "string",
            "description": "Recipient first name",
            "example": "John"
          },
          "lastname": {
            "type": "string",
            "description": "Recipient last name",
            "example": "Doe"
          },
          "streetname": {
            "type": "string",
            "description": "Address streetname. Can be used for: Address 1",
            "example": "Koelmalaan"
          },
          "housenumber": {
            "type": "string",
            "description": "House number",
            "example": "330"
          },
          "housenumberAddition": {
            "type": "string",
            "description": "House number addition/suffix",
            "example": "D"
          },
          "additionalInfo": {
            "type": "string",
            "description": "Additional information for the delivery. Can be used for: Address 2",
            "example": "PO box 12345"
          },
          "state": {
            "type": "string",
            "description": "When an address is inside the United States or Italy, this field must be set to the state or province name of the recipient.\n\nWe strongly prefer 2-letter codes, some examples:\n- \"CA\" for the state of California in the United States.\n- \"TX\" for the state of Texas in the United States.\n- \"BZ\" for the province Bolzano in Italy.\n\nSetting the full name (e.g. \"California\") is allowed, but may cause delivery delays or failures when the state or province name was misspelled or could not be recognized. Using 2-letter codes is always safer.\n",
            "example": "TX"
          },
          "zipcode": {
            "type": "string",
            "description": "Zipcode/Postcode/Postal code",
            "example": "1812 PS"
          },
          "city": {
            "type": "string",
            "description": "City name",
            "example": "Alkmaar"
          },
          "countryCode": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Country code ISO ALPHA-2 format",
            "example": "NL"
          },
          "phonenumber": {
            "type": "string",
            "description": "Phone number in international format with leading plus.",
            "example": "+31612345678"
          },
          "email": {
            "type": "string",
            "description": "Email address to contact recipient for delivery.",
            "example": "someone@domain.example"
          }
        },
        "required": [
          "company",
          "firstname",
          "lastname",
          "streetname",
          "housenumber",
          "housenumberAddition",
          "additionalInfo",
          "state",
          "zipcode",
          "city",
          "countryCode",
          "phonenumber",
          "email"
        ]
      },
      "RenderStatus": {
        "type": "string",
        "description": "The current status of a render.\n\n**Strict enum:** the set of values is fixed within a major version. See [Forward Compatibility](https://api-docs.printeers.com/guides/api-versioning#forward-compatibility-within-a-major-version).\n",
        "enum": [
          "pending",
          "failed",
          "completed"
        ],
        "example": "completed"
      },
      "ShippingLevel": {
        "type": "string",
        "description": "The shipping level/speed for an order.\n\n**Strict enum:** the set of values is fixed within a major version. See [Forward Compatibility](https://api-docs.printeers.com/guides/api-versioning#forward-compatibility-within-a-major-version).\n",
        "enum": [
          "basic",
          "tracked",
          "express"
        ],
        "example": "tracked"
      },
      "ShipmentKind": {
        "type": "string",
        "description": "The kind of shipment.\n\n**Strict enum:** the set of values is fixed within a major version. See [Forward Compatibility](https://api-docs.printeers.com/guides/api-versioning#forward-compatibility-within-a-major-version).\n",
        "enum": [
          "dropship",
          "combined"
        ],
        "example": "dropship"
      },
      "OrderStatus": {
        "type": "object",
        "additionalProperties": false,
        "description": "Status information for the order",
        "properties": {
          "open": {
            "type": "boolean",
            "description": "Whether the order is still open. An order is open until all lines have been shipped or canceled.",
            "example": true
          },
          "code": {
            "$ref": "#/components/schemas/OrderStatusCode"
          },
          "expectedShipping": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Expected shipping date/time. Set when we have an expected shipping moment. May be null when an exception occurred (e.g., address errors causing the order to be put on hold).",
            "example": "2025-01-15T17:00:00Z"
          }
        },
        "required": [
          "open",
          "code",
          "expectedShipping"
        ]
      },
      "OrderOnHold": {
        "type": "object",
        "additionalProperties": false,
        "description": "Details about why production for the order is on hold.",
        "properties": {
          "reason": {
            "type": "string",
            "description": "Human-readable reason production is on hold. When multiple parts of the order are on hold, their reasons are joined with newlines.",
            "example": "Awaiting address correction"
          }
        },
        "required": [
          "reason"
        ]
      },
      "OrderStatusCode": {
        "type": "string",
        "description": "Fine-grained status code for the order. Describes the state of the remaining (unshipped) portion of the order.\n\n- `pending`: Order is pending processing.\n- `backorder`: Order is waiting for stock to become available.\n- `in_production`: Order is currently being produced.\n- `printed`: Order has been printed and is awaiting combined shipment. This status only applies to combined orders; dropship orders are shipped immediately after printing.\n- `completed`: All orderlines have been fully shipped or canceled.\n- `canceled`: All orderlines have been canceled.\n\n**Strict enum:** the set of values is fixed within a major version. See [Forward Compatibility](https://api-docs.printeers.com/guides/api-versioning#forward-compatibility-within-a-major-version).\n",
        "enum": [
          "pending",
          "backorder",
          "in_production",
          "printed",
          "completed",
          "canceled"
        ],
        "example": "in_production"
      },
      "GetOrganization_Organization": {
        "type": "object",
        "additionalProperties": false,
        "description": "Organization information returned by GetOrganization",
        "properties": {
          "name": {
            "type": "string",
            "description": "Organization name",
            "example": "My Organization"
          }
        },
        "required": [
          "name"
        ]
      },
      "ListAccounts_Account": {
        "type": "object",
        "additionalProperties": false,
        "description": "Account information returned by ListAccounts",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/AccountReference"
          },
          "legacyCode": {
            "type": "string",
            "description": "Legacy account code. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "NLD12785623"
          },
          "invoiceAddressReference": {
            "$ref": "#/components/schemas/AddressReference"
          },
          "balance": {
            "type": "integer",
            "description": "Account balance in EUR cents.",
            "example": 150000
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the account was created",
            "example": "2025-01-15T10:30:00Z"
          },
          "archived": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the account was archived (null if not archived)",
            "example": "2025-03-20T14:30:00Z"
          }
        },
        "required": [
          "reference",
          "legacyCode",
          "invoiceAddressReference",
          "balance",
          "created",
          "archived"
        ]
      },
      "ListStores_Store": {
        "type": "object",
        "additionalProperties": false,
        "description": "Store information returned by ListStores",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/StoreReference"
          },
          "accountReference": {
            "$ref": "#/components/schemas/AccountReference"
          },
          "legacyCode": {
            "type": "string",
            "description": "Legacy store code.\n\nThe store code has been replaced by Store Reference in all new systems. This field is here for backwards compatibility to api v1.\nDon't use this field for new systems as it will be removed in the next major version of this API.\n",
            "example": "MYSTORE"
          },
          "name": {
            "type": "string",
            "description": "Store name",
            "example": "My Online Store"
          },
          "integration": {
            "type": "string",
            "description": "Store integration type. Using the API to create Orders is only possible for stores with integration \"api\".\n\n**Open enum:** new values may appear without notice. Known values at this time: 'api', 'shopify', 'teeinblue', 'woocommerce'. Your client must handle unknown values gracefully. See [Forward Compatibility](https://api-docs.printeers.com/guides/api-versioning#forward-compatibility-within-a-major-version).\n",
            "example": "api"
          },
          "defaultBrandReference": {
            "$ref": "#/components/schemas/BrandReference"
          },
          "defaultPreferredPackagingReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PackagingReference"
              }
            ],
            "nullable": true,
            "description": "Default preferred packaging reference (null indicates no default is set)"
          },
          "defaultMinimalShippingLevel": {
            "$ref": "#/components/schemas/ShippingLevel"
          },
          "combinedAddressReference": {
            "$ref": "#/components/schemas/AddressReference"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the store was created",
            "example": "2025-01-15T10:30:00Z"
          },
          "archived": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the store was archived (null if not archived)",
            "example": "2025-03-20T14:30:00Z"
          }
        },
        "required": [
          "reference",
          "accountReference",
          "legacyCode",
          "name",
          "integration",
          "defaultBrandReference",
          "defaultPreferredPackagingReference",
          "defaultMinimalShippingLevel",
          "combinedAddressReference",
          "created",
          "archived"
        ]
      },
      "ListBrands_Brand": {
        "type": "object",
        "additionalProperties": false,
        "description": "Brand information returned by ListBrands",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/BrandReference"
          },
          "name": {
            "type": "string",
            "description": "Brand name",
            "example": "My Brand"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the brand was created",
            "example": "2025-01-15T10:30:00Z"
          }
        },
        "required": [
          "reference",
          "name",
          "created"
        ]
      },
      "CreateRender_Render": {
        "type": "object",
        "additionalProperties": false,
        "description": "Render details for creation",
        "properties": {
          "compositionReference": {
            "$ref": "#/components/schemas/CompositionReference"
          },
          "imageReference": {
            "$ref": "#/components/schemas/ImageReference"
          }
        },
        "required": [
          "compositionReference",
          "imageReference"
        ]
      },
      "GetRender_Render": {
        "type": "object",
        "additionalProperties": false,
        "description": "Render information returned by GetRender",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/RenderReference"
          },
          "compositionReference": {
            "$ref": "#/components/schemas/CompositionReference"
          },
          "imageReference": {
            "$ref": "#/components/schemas/ImageReference"
          },
          "status": {
            "$ref": "#/components/schemas/RenderStatus"
          },
          "thumbhash": {
            "type": "string",
            "nullable": true,
            "description": "Base64-encoded [thumbhash](https://evanw.github.io/thumbhash/) for the rendered image (only available when status is 'completed')",
            "example": "1QcSHQRnh493V4dIh4eXh4aTh0eHJ4dnhw=="
          },
          "media": {
            "$ref": "#/components/schemas/GetRender_FileMetadata"
          },
          "thumbnail": {
            "$ref": "#/components/schemas/GetRender_FileMetadata"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the render was created",
            "example": "2025-10-18T12:34:56Z"
          },
          "completed": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the render was completed (only available when status is 'completed')",
            "example": "2025-10-18T12:35:10Z"
          }
        },
        "required": [
          "reference",
          "compositionReference",
          "imageReference",
          "status",
          "thumbhash",
          "media",
          "thumbnail",
          "created",
          "completed"
        ]
      },
      "GetRender_FileMetadata": {
        "type": "object",
        "additionalProperties": false,
        "description": "Metadata about a file",
        "properties": {
          "mimeType": {
            "type": "string",
            "description": "MIME type of the file",
            "example": "image/png"
          },
          "extension": {
            "type": "string",
            "description": "File extension",
            "example": "png"
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "nullable": true,
            "description": "File size in bytes (only available when status is 'completed')",
            "example": 524288
          }
        },
        "required": [
          "mimeType",
          "extension",
          "size"
        ]
      },
      "ListScenes_Scene": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/SceneReference"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the scene",
            "example": "Studio White Backdrop"
          }
        },
        "required": [
          "reference",
          "name"
        ]
      },
      "ListPerspectives_Perspective": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/PerspectiveReference"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the perspective",
            "example": "Upper Right"
          }
        },
        "required": [
          "reference",
          "name"
        ]
      },
      "GetScene_Scene": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/SceneReference"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the scene",
            "example": "Studio White Backdrop"
          },
          "description": {
            "type": "string",
            "description": "Longer human-readable description of the scene",
            "example": "A simple photo studio with white backdrop"
          },
          "private": {
            "type": "boolean",
            "description": "True if this scene is private to your organization. False if it's part of the public Printeers catalog.",
            "example": false
          },
          "allowsProductPerspectives": {
            "type": "boolean",
            "description": "True if this scene supports product-specific perspectives. Product-specific perspectives provide better renders for individual products.",
            "example": false
          },
          "compatibleProductgroups": {
            "type": "array",
            "description": "Productgroups this scene can render. An empty array means the scene is compatible with all productgroups.",
            "example": [
              {
                "reference": "Productgroup_7yrcm5hd2w8pz4x6k3qf9b1tnv"
              }
            ],
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "reference": {
                  "$ref": "#/components/schemas/ProductgroupReference"
                }
              },
              "required": [
                "reference"
              ]
            }
          },
          "perspectives": {
            "type": "array",
            "description": "Perspectives available within this scene.",
            "example": [
              {
                "reference": "Perspective_6rv2mc8yqw3nt5xk9hpz1bdfgs"
              },
              {
                "reference": "Perspective_3qn8yw1kfh6mp5xr7vzb9ctdsj"
              },
              {
                "reference": "Perspective_9xt4rm7wkh2np1v6qz3ybcfdsj"
              },
              {
                "reference": "Perspective_2hk5vr8wnm9ct3x7qz1ybpfdsj"
              }
            ],
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "reference": {
                  "$ref": "#/components/schemas/PerspectiveReference"
                }
              },
              "required": [
                "reference"
              ]
            }
          }
        },
        "required": [
          "reference",
          "name",
          "description",
          "private",
          "allowsProductPerspectives",
          "compatibleProductgroups",
          "perspectives"
        ]
      },
      "GetPerspective_Perspective": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/PerspectiveReference"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the perspective",
            "example": "Upper Right"
          },
          "output": {
            "type": "object",
            "additionalProperties": false,
            "description": "Output dimensions and format produced when rendering with this perspective",
            "properties": {
              "widthPx": {
                "type": "integer",
                "description": "Output width in pixels",
                "example": 2560
              },
              "heightPx": {
                "type": "integer",
                "description": "Output height in pixels",
                "example": 2560
              },
              "format": {
                "type": "string",
                "description": "Output format (e.g. 'png')",
                "example": "png"
              }
            },
            "required": [
              "widthPx",
              "heightPx",
              "format"
            ]
          },
          "scenes": {
            "type": "array",
            "nullable": true,
            "description": "Scenes this perspective is linked to (only for scene perspectives, null for product perspectives)",
            "example": [
              {
                "reference": "Scene_8hm3pz5wkr1yv7xn4btq9cdfsj"
              }
            ],
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "reference": {
                  "$ref": "#/components/schemas/SceneReference"
                }
              },
              "required": [
                "reference"
              ]
            }
          },
          "products": {
            "type": "array",
            "nullable": true,
            "description": "Products this perspective is linked to (only for product perspectives, null for scene perspectives)",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "reference": {
                  "$ref": "#/components/schemas/ProductReference"
                }
              },
              "required": [
                "reference"
              ]
            }
          }
        },
        "required": [
          "reference",
          "name",
          "output",
          "scenes",
          "products"
        ]
      },
      "LookupComposition_Composition": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/CompositionReference"
          },
          "tokenCost": {
            "type": "integer",
            "description": "Number of rendertokens a render of this composition consumes against your organization's weekly rendertoken limit.",
            "example": 10
          }
        },
        "required": [
          "reference",
          "tokenCost"
        ]
      },
      "GetComposition_Composition": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/CompositionReference"
          },
          "productReference": {
            "$ref": "#/components/schemas/ProductReference"
          },
          "sceneReference": {
            "$ref": "#/components/schemas/SceneReference"
          },
          "perspectiveReference": {
            "$ref": "#/components/schemas/PerspectiveReference"
          },
          "tokenCost": {
            "type": "integer",
            "description": "Number of rendertokens a render of this composition consumes against your organization's weekly rendertoken limit.",
            "example": 10
          }
        },
        "required": [
          "reference",
          "productReference",
          "sceneReference",
          "perspectiveReference",
          "tokenCost"
        ]
      },
      "GetRendertokens_Rendertokens": {
        "type": "object",
        "additionalProperties": false,
        "description": "Your organization's rendertoken usage within the current weekly period.",
        "properties": {
          "used": {
            "type": "integer",
            "description": "Rendertokens consumed so far in the current weekly period.",
            "example": 120
          },
          "limit": {
            "type": "integer",
            "description": "Your organization's rendertoken limit for the current weekly period.",
            "example": 1000
          },
          "remaining": {
            "type": "integer",
            "description": "Rendertokens still available in the current weekly period.",
            "example": 880
          },
          "resets": {
            "type": "string",
            "format": "date-time",
            "description": "Moment the current weekly period ends and usage resets (Monday 00:00 Europe/Amsterdam).",
            "example": "2026-07-13T00:00:00+02:00"
          }
        },
        "required": [
          "used",
          "limit",
          "remaining",
          "resets"
        ]
      },
      "ListProductgroups_Productgroup": {
        "type": "object",
        "additionalProperties": false,
        "description": "Productgroup information returned by ListProductgroups",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ProductgroupReference"
          },
          "name": {
            "type": "string",
            "description": "The productgroup name",
            "example": "Phone Soft cases (back printed, black)"
          },
          "private": {
            "type": "boolean",
            "description": "True if this productgroup is private to your organization. False if it's part of the public Printeers catalog.",
            "example": false
          },
          "suggestedRetailPrice": {
            "type": "integer",
            "nullable": true,
            "description": "Suggested retail price in EUR cents. Null if no price is configured.",
            "example": 1299
          },
          "price": {
            "type": "integer",
            "nullable": true,
            "description": "Product price in EUR cents for this productgroup. Null if no price is configured.",
            "example": 450
          }
        },
        "required": [
          "reference",
          "name",
          "private",
          "suggestedRetailPrice",
          "price"
        ]
      },
      "ListProducts_Product": {
        "type": "object",
        "additionalProperties": false,
        "description": "Product information returned by ListProducts",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ProductReference"
          },
          "productgroupReference": {
            "$ref": "#/components/schemas/ProductgroupReference"
          },
          "name": {
            "type": "string",
            "description": "The product name",
            "example": "Fairphone 5 Soft case (back printed, transparent)"
          },
          "legacyItemSKU": {
            "type": "string",
            "description": "Legacy SKU identifier for what v1 API exposes as an 'item'. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "B68200000"
          },
          "status": {
            "type": "string",
            "description": "Current lifecycle status of the product",
            "example": "launched"
          },
          "availableQuantity": {
            "type": "integer",
            "minimum": 0,
            "description": "Available quantity in stock. For detailed availability (backorder support and expected restock date) use `GET /products/{productReference}`.",
            "example": 150
          },
          "layersModified": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp at which this product's print layers (the layer image assets) last changed. Compare against the value you stored on your last sync to decide whether to re-download the layers from `GET /products/{productReference}`.",
            "example": "2026-06-29T11:00:00Z"
          },
          "printModified": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp at which this product's print dimensions last changed. Compare against the value you stored on your last sync to decide whether to re-pull the `print` section from `GET /products/{productReference}`.",
            "example": "2026-06-29T11:00:00Z"
          }
        },
        "required": [
          "reference",
          "productgroupReference",
          "name",
          "legacyItemSKU",
          "status",
          "availableQuantity",
          "layersModified",
          "printModified"
        ]
      },
      "GetProduct_Product": {
        "type": "object",
        "additionalProperties": false,
        "description": "Product information returned by GetProduct",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ProductReference"
          },
          "productgroupReference": {
            "$ref": "#/components/schemas/ProductgroupReference"
          },
          "name": {
            "type": "string",
            "description": "The product name",
            "example": "Fairphone 5 Soft case (back printed, transparent)"
          },
          "legacyItemSKU": {
            "type": "string",
            "description": "Legacy SKU identifier for what v1 API exposes as an 'item'. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "B68200000"
          },
          "weightGrams": {
            "type": "integer",
            "nullable": true,
            "description": "Weight of one unit of the product in grams, excluding the shipping box. Null for products whose weight has not been measured yet.",
            "example": 30
          },
          "print": {
            "type": "object",
            "additionalProperties": false,
            "nullable": true,
            "description": "Print area dimensions. Null for products that are not printable, such as distribution-only products.",
            "properties": {
              "widthMm": {
                "type": "integer",
                "description": "Print area width in millimeters",
                "example": 70
              },
              "heightMm": {
                "type": "integer",
                "description": "Print area height in millimeters",
                "example": 140
              },
              "modified": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp at which the print dimensions last changed. Matches `printModified` from `GET /products`.",
                "example": "2026-06-29T11:00:00Z"
              }
            },
            "required": [
              "widthMm",
              "heightMm",
              "modified"
            ]
          },
          "status": {
            "type": "string",
            "description": "Current lifecycle status of the product",
            "example": "launched"
          },
          "statusTimeline": {
            "$ref": "#/components/schemas/GetProduct_ProductStatusTimeline"
          },
          "layers": {
            "nullable": true,
            "description": "URLs to product layer images. Null for products that are not printable (when `print` is null).",
            "allOf": [
              {
                "$ref": "#/components/schemas/GetProduct_Layers"
              }
            ]
          },
          "availability": {
            "$ref": "#/components/schemas/GetProduct_Availability"
          },
          "media": {
            "type": "array",
            "description": "Marketing and preview media for the product. Hand-uploaded examples come first, then auto-generated example renders. Download the bytes from `/products/{productReference}/media/{filename}`.\n\nToday every entry is an image, but the array can include videos in the future — use `contentType` to discriminate.\n\nFilenames are opaque and may stop being valid at any time as uploads happen or example renders are replaced. Always re-fetch this array before downloading; do not store the filenames long-term.\n",
            "items": {
              "$ref": "#/components/schemas/GetProduct_Media"
            }
          }
        },
        "required": [
          "reference",
          "productgroupReference",
          "name",
          "legacyItemSKU",
          "weightGrams",
          "print",
          "status",
          "statusTimeline",
          "layers",
          "availability",
          "media"
        ]
      },
      "GetProduct_Media": {
        "type": "object",
        "additionalProperties": false,
        "description": "A single piece of product media. Use `filename` to construct the download URL: `/products/{productReference}/media/{filename}`.",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Opaque filename for this entry, used as-is in the download URL. Do not parse, derive, or store this value — it may stop being valid at any time. Re-fetch the product's `media` array before downloading.\n",
            "example": "front.jpg"
          },
          "kind": {
            "type": "string",
            "enum": [
              "example",
              "render"
            ],
            "description": "`example` for hand-uploaded marketing media. `render` for auto-generated previews built from a composition (scene + perspective). Hand-uploaded examples are typically higher quality and should generally be preferred for customer-facing display.\n",
            "example": "example"
          },
          "contentType": {
            "type": "string",
            "description": "MIME type of the bytes (e.g. `image/jpeg`, `image/png`, and in future possibly `video/mp4`).",
            "example": "image/jpeg"
          },
          "description": {
            "type": "string",
            "description": "Human-readable label. Empty string for hand-uploaded examples (no metadata available). For renders this is the scene name followed by the perspective name (e.g. `Studio White, Upper Right`).\n",
            "example": "Studio White, Upper Right"
          }
        },
        "required": [
          "filename",
          "kind",
          "contentType",
          "description"
        ]
      },
      "GetProduct_Layers": {
        "type": "object",
        "additionalProperties": false,
        "description": "URLs to product layer images and mask positioning metadata. Each layer URL is null if the layer does not exist. Mask positioning fields are null if the mask layer does not exist.",
        "properties": {
          "top": {
            "type": "string",
            "nullable": true,
            "description": "URL to the top layer image",
            "example": "https://files.printeers.com/layers/Product_xxx/top.png"
          },
          "mask": {
            "type": "string",
            "nullable": true,
            "description": "URL to the mask layer image",
            "example": null
          },
          "bottom": {
            "type": "string",
            "nullable": true,
            "description": "URL to the bottom layer image",
            "example": "https://files.printeers.com/layers/Product_xxx/bottom.png"
          },
          "mockup": {
            "type": "string",
            "nullable": true,
            "description": "URL to the mockup layer image",
            "example": "https://files.printeers.com/layers/Product_xxx/mockup.png"
          },
          "maskWidthPx": {
            "type": "integer",
            "nullable": true,
            "description": "Width of the mask layer in pixels. Null if the mask layer does not exist.",
            "example": 800
          },
          "maskHeightPx": {
            "type": "integer",
            "nullable": true,
            "description": "Height of the mask layer in pixels. Null if the mask layer does not exist.",
            "example": 1600
          },
          "maskOffsetXPx": {
            "type": "integer",
            "nullable": true,
            "description": "Horizontal offset of the mask area from the left edge of the layer images, in pixels. Null if the mask layer does not exist.",
            "example": 50
          },
          "maskOffsetYPx": {
            "type": "integer",
            "nullable": true,
            "description": "Vertical offset of the mask area from the top edge of the layer images, in pixels. Null if the mask layer does not exist.",
            "example": 100
          },
          "ppmm": {
            "type": "number",
            "format": "double",
            "nullable": true,
            "description": "Pixels per millimeter. Calculated as maskHeightPx / print.heightMm. Use this to convert between pixel coordinates in layer images and physical millimeters on the product. Null if the mask layer does not exist.",
            "example": 11.428
          },
          "modified": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp at which the layer images last changed. Matches `layersModified` from `GET /products`.",
            "example": "2026-06-29T11:00:00Z"
          }
        },
        "required": [
          "top",
          "mask",
          "bottom",
          "mockup",
          "maskWidthPx",
          "maskHeightPx",
          "maskOffsetXPx",
          "maskOffsetYPx",
          "ppmm",
          "modified"
        ]
      },
      "GetProduct_ProductStatusTimeline": {
        "type": "object",
        "additionalProperties": false,
        "description": "Product lifecycle timeline with timestamps for each status transition. All fields are always present but will be null if the product has not yet reached that stage.",
        "properties": {
          "announced": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the product was announced (became visible to partners)",
            "example": "2025-01-15T10:30:00Z"
          },
          "prelaunched": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the product was prelaunched (became orderable for pre-orders)",
            "example": "2025-02-01T10:30:00Z"
          },
          "launched": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the product was launched (fully available)",
            "example": "2025-03-01T10:30:00Z"
          },
          "sunsetted": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the product was sunsetted (no longer recommended for new orders)",
            "example": null
          },
          "ended": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the product was ended (no longer orderable)",
            "example": null
          }
        },
        "required": [
          "announced",
          "prelaunched",
          "launched",
          "sunsetted",
          "ended"
        ]
      },
      "GetProduct_Availability": {
        "type": "object",
        "additionalProperties": false,
        "description": "Product availability information",
        "properties": {
          "quantity": {
            "type": "integer",
            "minimum": 0,
            "description": "Available quantity",
            "example": 150
          },
          "expectedAvailableDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Expected date when out-of-stock product will be available. Only populated when quantity is 0.",
            "example": null
          },
          "canBackorder": {
            "type": "boolean",
            "description": "Whether the product can be backordered",
            "example": true
          }
        },
        "required": [
          "quantity",
          "expectedAvailableDate",
          "canBackorder"
        ]
      },
      "ListPackagings_Packaging": {
        "type": "object",
        "additionalProperties": false,
        "description": "Packaging information returned by ListPackagings",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/PackagingReference"
          },
          "name": {
            "type": "string",
            "description": "The packaging name",
            "example": "Custom Branded Box"
          },
          "legacyCode": {
            "type": "string",
            "description": "Legacy packaging code. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "PARTNER_COEX_BAG"
          }
        },
        "required": [
          "reference",
          "name",
          "legacyCode"
        ]
      },
      "GetPackaging_Packaging": {
        "type": "object",
        "additionalProperties": false,
        "description": "Packaging information returned by GetPackaging",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/PackagingReference"
          },
          "name": {
            "type": "string",
            "description": "The packaging name",
            "example": "Custom Branded Box"
          },
          "legacyCode": {
            "type": "string",
            "description": "Legacy packaging code. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "PARTNER_COEX_BAG"
          },
          "price": {
            "type": "integer",
            "description": "Packaging price in EUR cents",
            "example": 48
          }
        },
        "required": [
          "reference",
          "name",
          "legacyCode",
          "price"
        ]
      },
      "ListOrders_Order": {
        "type": "object",
        "additionalProperties": false,
        "description": "Order summary for list responses",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/OrderReference"
          },
          "storeReference": {
            "$ref": "#/components/schemas/StoreReference"
          },
          "legacyOrderCode": {
            "type": "string",
            "description": "Legacy order code in the format STORECODE-1234. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "TESTCODE-1234"
          },
          "customIdentifier": {
            "type": "string",
            "nullable": true,
            "description": "Custom identifier provided when creating the order. Must be unique within the store.",
            "example": "MyOrder-A1B2C3"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the order was created",
            "example": "2025-01-15T10:30:00Z"
          },
          "dashboardUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to view this order in the Printeers Dashboard",
            "example": "https://dashboard.printeers.com/orders/Order_01arz3ndektsv4rrffq69g5fav"
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus"
          }
        },
        "required": [
          "reference",
          "storeReference",
          "legacyOrderCode",
          "customIdentifier",
          "created",
          "dashboardUrl",
          "status"
        ]
      },
      "GetOrder_Order": {
        "type": "object",
        "additionalProperties": false,
        "description": "Order information returned by GetOrder",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/OrderReference"
          },
          "storeReference": {
            "$ref": "#/components/schemas/StoreReference"
          },
          "legacyOrderCode": {
            "type": "string",
            "description": "Legacy order code in the format STORECODE-1234. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "TESTCODE-1234"
          },
          "customIdentifier": {
            "type": "string",
            "nullable": true,
            "description": "Custom identifier provided when creating the order. Must be unique within the store.",
            "example": "MyOrder-A1B2C3"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the order was created",
            "example": "2025-01-15T10:30:00Z"
          },
          "dashboardUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to view this order in the Printeers Dashboard",
            "example": "https://dashboard.printeers.com/orders/Order_01arz3ndektsv4rrffq69g5fav"
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus"
          },
          "onHold": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OrderOnHold"
              }
            ],
            "nullable": true,
            "description": "Set when production for the order is on hold (one or more parts of the order are held and unresolved). Null when the order is not on hold."
          },
          "shippingKind": {
            "$ref": "#/components/schemas/ShipmentKind"
          },
          "dropshipAddressReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AddressReference"
              }
            ],
            "nullable": true,
            "description": "Destination address reference. Only set for dropship orders."
          },
          "dropshipMinimalShippingLevel": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ShippingLevel"
              }
            ],
            "nullable": true,
            "description": "Minimum shipping level requested. Only set for dropship orders."
          },
          "dropshipPreferredPackagingReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PackagingReference"
              }
            ],
            "nullable": true,
            "description": "Preferred packaging reference. Only set for dropship orders."
          },
          "replacementForOrderReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OrderReference"
              }
            ],
            "nullable": true,
            "description": "If set, this order is a replacement for the referenced order."
          },
          "replacedByOrderReferences": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderReference"
            },
            "description": "If replacement orders were created for this order, their references appear here."
          },
          "orderlines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GetOrder_Orderline"
            },
            "description": "List of orderlines"
          },
          "shipments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GetOrder_Shipment"
            },
            "description": "List of shipments for this order. Use GET /shipments/{reference} for full details."
          }
        },
        "required": [
          "reference",
          "storeReference",
          "legacyOrderCode",
          "customIdentifier",
          "created",
          "dashboardUrl",
          "status",
          "onHold",
          "shippingKind",
          "dropshipAddressReference",
          "dropshipMinimalShippingLevel",
          "dropshipPreferredPackagingReference",
          "replacementForOrderReference",
          "replacedByOrderReferences",
          "orderlines",
          "shipments"
        ]
      },
      "GetOrder_Orderline": {
        "type": "object",
        "additionalProperties": false,
        "description": "Orderline information",
        "properties": {
          "index": {
            "type": "integer",
            "description": "Sequential index of the orderline within the order",
            "example": 1
          },
          "productReference": {
            "$ref": "#/components/schemas/ProductReference"
          },
          "legacySku": {
            "type": "string",
            "description": "Legacy SKU identifier. Deprecated: use productReference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "H20250000"
          },
          "imageReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ImageReference"
              }
            ],
            "nullable": true,
            "description": "Reference to the print image (null for non-print products)"
          },
          "renderReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RenderReference"
              }
            ],
            "nullable": true,
            "description": "Reference to the product render/mockup (null if not available)"
          },
          "quantity": {
            "type": "integer",
            "description": "Ordered quantity",
            "example": 10
          },
          "canceledQuantity": {
            "type": "integer",
            "description": "Canceled quantity",
            "example": 2
          },
          "shippedQuantity": {
            "type": "integer",
            "description": "Shipped quantity",
            "example": 5
          },
          "annotations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GetOrder_Annotation"
            },
            "description": "Key-value annotations given for this orderline when the order was created. Empty when the orderline has no annotations."
          }
        },
        "required": [
          "index",
          "productReference",
          "legacySku",
          "imageReference",
          "renderReference",
          "quantity",
          "canceledQuantity",
          "shippedQuantity",
          "annotations"
        ]
      },
      "GetOrder_Annotation": {
        "type": "object",
        "additionalProperties": false,
        "description": "Key-value annotation of an orderline",
        "properties": {
          "key": {
            "type": "string",
            "description": "Annotation key, unique per orderline.",
            "example": "shop-line-id"
          },
          "value": {
            "type": "string",
            "description": "Annotation value.",
            "example": "4711"
          }
        },
        "required": [
          "key",
          "value"
        ]
      },
      "GetOrder_Shipment": {
        "type": "object",
        "additionalProperties": false,
        "description": "Shipment reference within an order. Use GET /shipments/{reference} for full details.",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ShipmentReference"
          }
        },
        "required": [
          "reference"
        ]
      },
      "CreateOrder_Order": {
        "type": "object",
        "additionalProperties": false,
        "description": "Order creation request",
        "properties": {
          "storeReference": {
            "$ref": "#/components/schemas/StoreReference"
          },
          "shippingKind": {
            "$ref": "#/components/schemas/ShipmentKind"
          },
          "customIdentifier": {
            "type": "string",
            "description": "Custom identifier for the order. Must be unique per store. Can be used to look up the order later.",
            "pattern": "^[a-zA-Z0-9_-]{1,30}$",
            "example": "my-order-123"
          },
          "brandReference": {
            "$ref": "#/components/schemas/BrandReference"
          },
          "dropshipAddress": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "Destination address for the order. Required when shippingKind is `dropship`. Must not be set when shippingKind is `combined`."
          },
          "dropshipMinimalShippingLevel": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ShippingLevel"
              }
            ],
            "description": "Minimal shipping level. Only applicable when shippingKind is `dropship`."
          },
          "dropshipPreferredPackagingReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PackagingReference"
              }
            ],
            "description": "Preferred packaging. Only applicable when shippingKind is `dropship`."
          },
          "orderlines": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/CreateOrder_Orderline"
            },
            "description": "List of orderlines. At least one orderline is required."
          }
        },
        "required": [
          "storeReference",
          "shippingKind",
          "orderlines"
        ]
      },
      "CreateOrder_Orderline": {
        "type": "object",
        "additionalProperties": false,
        "description": "Orderline in an order creation request",
        "properties": {
          "productReference": {
            "$ref": "#/components/schemas/ProductReference"
          },
          "imageReference": {
            "$ref": "#/components/schemas/ImageReference"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "description": "Quantity to order",
            "example": 10
          },
          "annotations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateOrder_Annotation"
            },
            "maxItems": 10,
            "description": "Optional key-value annotations for this orderline (max 10)"
          }
        },
        "required": [
          "productReference",
          "quantity"
        ]
      },
      "CreateOrder_Annotation": {
        "type": "object",
        "additionalProperties": false,
        "description": "Key-value annotation for an orderline",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_-]{1,63}$",
            "description": "Annotation key. Must be unique per orderline.",
            "example": "shop-line-id"
          },
          "value": {
            "type": "string",
            "maxLength": 1048576,
            "description": "Annotation value. Any printable UTF-8 characters (letters, marks, numbers, punctuation, symbols including emoji) and plain spaces are allowed; control characters and other whitespace are not. Max 1 MiB (1048576 bytes). A value with disallowed characters is rejected with error code annotation_value_illegal_characters; a value that is too large is rejected with annotation_value_too_long.",
            "example": "4711"
          }
        },
        "required": [
          "key",
          "value"
        ]
      },
      "QuoteOrder_Quote": {
        "type": "object",
        "additionalProperties": false,
        "description": "Order to quote. Carries the fields of an order creation request that determine shipping, under the same names.",
        "properties": {
          "storeReference": {
            "$ref": "#/components/schemas/StoreReference"
          },
          "shippingKind": {
            "$ref": "#/components/schemas/ShipmentKind"
          },
          "dropshipAddress": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "Destination address of the order. Required when shippingKind is `dropship`. Must not be set when shippingKind is `combined`."
          },
          "dropshipMinimalShippingLevel": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ShippingLevel"
              }
            ],
            "description": "Minimal shipping level. Only applicable when shippingKind is `dropship`. Defaults to `basic`."
          },
          "orderlines": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/QuoteOrder_Orderline"
            },
            "description": "List of orderlines. At least one orderline is required."
          }
        },
        "required": [
          "storeReference",
          "shippingKind",
          "orderlines"
        ]
      },
      "QuoteOrder_Orderline": {
        "type": "object",
        "additionalProperties": false,
        "description": "Orderline in a quote request",
        "properties": {
          "productReference": {
            "$ref": "#/components/schemas/ProductReference"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "description": "Quantity to order",
            "example": 10
          }
        },
        "required": [
          "productReference",
          "quantity"
        ]
      },
      "QuoteOrder_ShippingOption": {
        "type": "object",
        "additionalProperties": false,
        "description": "A shipping level the quoted order can ship with, and its price",
        "properties": {
          "level": {
            "$ref": "#/components/schemas/ShippingLevel"
          },
          "price": {
            "type": "integer",
            "description": "Shipping price in EUR cents for this level",
            "example": 495
          }
        },
        "required": [
          "level",
          "price"
        ]
      },
      "GetShipment_Shipment": {
        "type": "object",
        "additionalProperties": false,
        "description": "Shipment information returned by GetShipment",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ShipmentReference"
          },
          "kind": {
            "$ref": "#/components/schemas/ShipmentKind"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the shipment was created",
            "example": "2025-01-15T10:30:00Z"
          },
          "destinationAddressReference": {
            "$ref": "#/components/schemas/AddressReference"
          },
          "shippingLevel": {
            "$ref": "#/components/schemas/ShippingLevel"
          },
          "carrier": {
            "type": "string",
            "description": "Name of the shipping carrier",
            "example": "PostNL"
          },
          "trackingNumber": {
            "type": "string",
            "nullable": true,
            "description": "Carrier tracking number (null if not available)",
            "example": "3SPOST1234567890"
          },
          "trackingUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to track the shipment on the print&ship tracking page",
            "example": "https://printandship.link/Shipment_8eksvwek9pc58r1qmqqf3492mg"
          },
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GetShipment_ShippedOrder"
            },
            "description": "Orders that have items in this shipment"
          }
        },
        "required": [
          "reference",
          "kind",
          "created",
          "destinationAddressReference",
          "shippingLevel",
          "carrier",
          "trackingNumber",
          "trackingUrl",
          "orders"
        ]
      },
      "GetShipment_ShippedOrderline": {
        "type": "object",
        "additionalProperties": false,
        "description": "An orderline that is part of the shipment",
        "properties": {
          "orderlineIndex": {
            "type": "integer",
            "description": "The orderline index within the order",
            "example": 1
          },
          "quantity": {
            "type": "integer",
            "description": "The quantity of this orderline shipped in this shipment",
            "example": 2
          }
        },
        "required": [
          "orderlineIndex",
          "quantity"
        ]
      },
      "GetShipment_ShippedOrder": {
        "type": "object",
        "additionalProperties": false,
        "description": "An order that has items in this shipment",
        "properties": {
          "orderReference": {
            "$ref": "#/components/schemas/OrderReference"
          },
          "orderlines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GetShipment_ShippedOrderline"
            },
            "description": "Orderlines from this order that are in this shipment"
          }
        },
        "required": [
          "orderReference",
          "orderlines"
        ]
      },
      "ListItems_Item": {
        "type": "object",
        "additionalProperties": false,
        "description": "Warehouse item information returned by ListItems",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ItemReference"
          },
          "sku": {
            "type": "string",
            "description": "The item's SKU code.",
            "example": "PART0001"
          },
          "name": {
            "type": "string",
            "description": "The item name",
            "example": "Partner Case Blank"
          },
          "logicalQuantity": {
            "type": "integer",
            "description": "The logical quantity available for ordering (accounts for reserved stock)",
            "example": 100
          },
          "physicalQuantity": {
            "type": "integer",
            "description": "The physical quantity in the warehouse",
            "example": 120
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListItems_Product"
            },
            "description": "Products that use this item as their stock source. Only includes published, non-archived products."
          },
          "packagings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListItems_Packaging"
            },
            "description": "Packagings that use this item as their stock source. Only includes non-archived packagings."
          }
        },
        "required": [
          "reference",
          "sku",
          "name",
          "logicalQuantity",
          "physicalQuantity",
          "products",
          "packagings"
        ]
      },
      "ListItems_Product": {
        "type": "object",
        "additionalProperties": false,
        "description": "A product linked to a warehouse item",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ProductReference"
          }
        },
        "required": [
          "reference"
        ]
      },
      "ListItems_Packaging": {
        "type": "object",
        "additionalProperties": false,
        "description": "A packaging linked to a warehouse item",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/PackagingReference"
          }
        },
        "required": [
          "reference"
        ]
      },
      "ListImages_Image": {
        "type": "object",
        "additionalProperties": false,
        "description": "Image information returned by ListImages",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ImageReference"
          },
          "library": {
            "type": "boolean",
            "description": "Whether this image is a library image",
            "example": false
          },
          "name": {
            "type": "string",
            "description": "User-provided name for the image",
            "example": "My design front"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "When the image was uploaded"
          },
          "purged": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the image was purged. Null if the image is still active."
          },
          "legacyCode": {
            "type": "string",
            "nullable": true,
            "description": "Legacy image code in the form `{storeCode}-img-{number}`. Null for images without a legacy code. Deprecated: use reference instead. This field is provided to ease the transition away from api v1 to v2+, it will be removed in v3.",
            "example": "AB12-img-42"
          }
        },
        "required": [
          "reference",
          "library",
          "name",
          "created",
          "purged",
          "legacyCode"
        ]
      },
      "Claimcategory": {
        "type": "object",
        "additionalProperties": false,
        "description": "A claim category with its reference and name",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ClaimcategoryReference"
          },
          "name": {
            "type": "string",
            "description": "The display name of the claimcategory",
            "example": "Damage (broken)"
          }
        },
        "required": [
          "reference",
          "name"
        ]
      },
      "ListClaimcategories_Claimcategory": {
        "type": "object",
        "additionalProperties": false,
        "description": "A claim category as listed for claim submission",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ClaimcategoryReference"
          },
          "name": {
            "type": "string",
            "description": "The display name of the claimcategory",
            "example": "Damage (broken)"
          },
          "evidenceRequired": {
            "type": "boolean",
            "description": "Whether item-issues claimlines in this category must carry at least one evidence reference"
          }
        },
        "required": [
          "reference",
          "name",
          "evidenceRequired"
        ]
      },
      "CreateClaimPackageMissing_Claim": {
        "type": "object",
        "additionalProperties": false,
        "description": "Claim details for a package missing claim",
        "properties": {
          "shipmentReference": {
            "$ref": "#/components/schemas/ShipmentReference"
          },
          "evidenceReferences": {
            "type": "array",
            "description": "Evidence references (0-3). Upload evidence first using `POST /evidence`.",
            "minItems": 0,
            "maxItems": 3,
            "items": {
              "$ref": "#/components/schemas/EvidenceReference"
            }
          }
        },
        "required": [
          "shipmentReference",
          "evidenceReferences"
        ]
      },
      "CreateClaimItemIssues_Claim": {
        "type": "object",
        "additionalProperties": false,
        "description": "Claim details for an item issues claim",
        "properties": {
          "shipmentReference": {
            "$ref": "#/components/schemas/ShipmentReference"
          },
          "orderReference": {
            "$ref": "#/components/schemas/OrderReference"
          },
          "comment": {
            "type": "string",
            "description": "Optional comment describing the issues",
            "maxLength": 1000,
            "example": "Items arrived damaged"
          },
          "claimlines": {
            "type": "array",
            "description": "Items to claim (1 or more required)",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/CreateClaimItemIssues_Claimline"
            }
          }
        },
        "required": [
          "shipmentReference",
          "orderReference",
          "claimlines"
        ]
      },
      "CreateClaimItemIssues_Claimline": {
        "type": "object",
        "additionalProperties": false,
        "description": "A claimline in an item issues claim",
        "properties": {
          "orderlineIndex": {
            "type": "integer",
            "description": "The orderline index within the order",
            "minimum": 1,
            "example": 1
          },
          "quantity": {
            "type": "integer",
            "description": "Quantity of items with this problem",
            "minimum": 1,
            "example": 1
          },
          "claimcategoryReference": {
            "$ref": "#/components/schemas/ClaimcategoryReference"
          },
          "evidenceReferences": {
            "type": "array",
            "description": "Evidence references for this item (0-3). At least 1 is required when the claimcategory has `evidenceRequired: true` in `GET /claimcategories`; omitting it there returns error code `evidence_required`. Upload evidence first using `POST /evidence`.",
            "minItems": 0,
            "maxItems": 3,
            "items": {
              "$ref": "#/components/schemas/EvidenceReference"
            }
          }
        },
        "required": [
          "orderlineIndex",
          "quantity",
          "claimcategoryReference",
          "evidenceReferences"
        ]
      },
      "ListClaims_Claim": {
        "type": "object",
        "additionalProperties": false,
        "description": "Summary information about a claim",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ClaimReference"
          },
          "orderReference": {
            "$ref": "#/components/schemas/OrderReference"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "resolved",
              "rejected",
              "retracted"
            ],
            "description": "Current status of the claim.\n\nClaims can have the following statuses:\n- `pending`: Claim is being reviewed by support\n- `resolved`: Claim was awarded at least one refund or replacement\n- `rejected`: Claim was reviewed and denied\n- `retracted`: Claim was canceled by the partner\n\n**Strict enum:** the set of values is fixed within a major version. See [Forward Compatibility](https://api-docs.printeers.com/guides/api-versioning#forward-compatibility-within-a-major-version).\n",
            "example": "pending"
          },
          "claimcategories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claimcategory"
            },
            "description": "Claimcategories for this claim"
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "When the claim was created",
            "example": "2025-12-15T10:30:00Z"
          },
          "retracted": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the claim was retracted (null if not retracted)"
          },
          "decided": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When support made a decision on the claim (null if pending)"
          }
        },
        "required": [
          "reference",
          "orderReference",
          "status",
          "claimcategories",
          "created",
          "retracted",
          "decided"
        ]
      },
      "GetClaim_Claim": {
        "type": "object",
        "additionalProperties": false,
        "description": "Detailed information about a claim",
        "properties": {
          "reference": {
            "$ref": "#/components/schemas/ClaimReference"
          },
          "orderReference": {
            "$ref": "#/components/schemas/OrderReference"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "resolved",
              "rejected",
              "retracted"
            ],
            "description": "Current status of the claim.\n\nClaims can have the following statuses:\n- `pending`: Claim is being reviewed by support\n- `resolved`: Claim was awarded at least one refund or replacement\n- `rejected`: Claim was reviewed and denied\n- `retracted`: Claim was canceled by the partner\n\n**Strict enum:** the set of values is fixed within a major version. See [Forward Compatibility](https://api-docs.printeers.com/guides/api-versioning#forward-compatibility-within-a-major-version).\n",
            "example": "pending"
          },
          "comment": {
            "type": "string",
            "description": "Comment provided by the partner when creating the claim",
            "example": "Customer reported this and that"
          },
          "createdBy": {
            "description": "Identifies who created this claim",
            "oneOf": [
              {
                "type": "string",
                "format": "email",
                "description": "Email of dashboard user that created this claim",
                "example": "user@example.com"
              },
              {
                "$ref": "#/components/schemas/KeyReference"
              }
            ]
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "When the claim was created",
            "example": "2025-12-15T10:30:00Z"
          },
          "retracted": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the claim was retracted (null if not retracted)",
            "example": null
          },
          "decision": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GetClaim_ClaimDecision"
              }
            ],
            "nullable": true,
            "description": "Decision made by a support agent (null when no decision has been made yet)"
          },
          "claimlines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GetClaim_Claimline"
            },
            "description": "Details of each claimline"
          },
          "shipmentReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ShipmentReference"
              }
            ],
            "description": "Reference to the shipment for this claim. Use GET /shipments/{shipmentReference} to retrieve full shipment details."
          },
          "evidenceUrls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "URLs of the evidence images attached to the claim itself, as uploaded when the claim was created (only package-missing claims carry claim-level evidence; empty otherwise). Evidence is purged roughly four months after the claim is decided or retracted; the list is then empty and previously returned URLs stop working.",
            "example": [
              "https://files.printeers.com/evidence/Evidence_0fa7gephpy70zt0qanfja9hvqt.jpeg"
            ]
          }
        },
        "required": [
          "reference",
          "orderReference",
          "status",
          "comment",
          "createdBy",
          "created",
          "retracted",
          "decision",
          "claimlines",
          "shipmentReference",
          "evidenceUrls"
        ]
      },
      "GetClaim_Claimline": {
        "type": "object",
        "additionalProperties": false,
        "description": "Details about a specific claimline",
        "properties": {
          "productReference": {
            "$ref": "#/components/schemas/ProductReference"
          },
          "orderlineIndex": {
            "type": "integer",
            "description": "The orderline index within the order",
            "example": 1
          },
          "quantity": {
            "type": "integer",
            "description": "Quantity claimed",
            "example": 2
          },
          "imageReference": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ImageReference"
              }
            ],
            "nullable": true,
            "description": "Reference to the print image (null for non-print products)"
          },
          "claimcategory": {
            "$ref": "#/components/schemas/Claimcategory"
          },
          "decision": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GetClaim_ClaimlineDecision"
              }
            ],
            "nullable": true,
            "description": "Decision made by a support agent (null when no decision has been made yet)"
          },
          "evidenceUrls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "URLs of the evidence images attached to this claimline, as uploaded when the claim was created. Evidence is purged roughly four months after the claim is decided or retracted; the list is then empty and previously returned URLs stop working.",
            "example": [
              "https://files.printeers.com/evidence/Evidence_sq3bkad1t0hq3q83s7897bs8cg.jpeg"
            ]
          }
        },
        "required": [
          "productReference",
          "orderlineIndex",
          "quantity",
          "imageReference",
          "claimcategory",
          "decision",
          "evidenceUrls"
        ]
      },
      "GetClaim_ClaimDecision": {
        "type": "object",
        "additionalProperties": false,
        "description": "Decision made by a support agent for a claim",
        "properties": {
          "decided": {
            "type": "string",
            "format": "date-time",
            "description": "When support made a decision on the claim"
          },
          "refundShippingCosts": {
            "type": "boolean",
            "description": "Whether shipping costs were refunded"
          },
          "comment": {
            "type": "string",
            "description": "Comment from the support agent"
          }
        },
        "required": [
          "decided",
          "refundShippingCosts",
          "comment"
        ]
      },
      "GetClaim_ClaimlineDecision": {
        "type": "object",
        "additionalProperties": false,
        "description": "Decision made by a support agent for a claimline",
        "properties": {
          "replacementQuantity": {
            "type": "integer",
            "description": "Quantity approved for replacement"
          },
          "refundQuantity": {
            "type": "integer",
            "description": "Quantity approved for refund"
          },
          "rejectionQuantity": {
            "type": "integer",
            "description": "Quantity rejected"
          },
          "comment": {
            "type": "string",
            "description": "Comment for this claimline from the support agent"
          }
        },
        "required": [
          "replacementQuantity",
          "refundQuantity",
          "rejectionQuantity",
          "comment"
        ]
      }
    }
  },
  "paths": {
    "/auth/validate": {
      "get": {
        "summary": "Validate authentication",
        "operationId": "validateAuthentication",
        "description": "Use this endpoint to verify your Secret Key is valid.",
        "tags": [
          "Auth"
        ],
        "responses": {
          "200": {
            "description": "Authentication is valid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "Success message",
                      "example": "Authentication is valid"
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/organization": {
      "get": {
        "summary": "Get organization",
        "operationId": "getOrganization",
        "description": "Retrieve information about your organization.",
        "tags": [
          "Organization"
        ],
        "responses": {
          "200": {
            "description": "Organization information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "organization": {
                      "$ref": "#/components/schemas/GetOrganization_Organization"
                    }
                  },
                  "required": [
                    "organization"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/accounts": {
      "get": {
        "summary": "List accounts",
        "operationId": "listAccounts",
        "description": "Retrieve a list of all accounts for your organization.",
        "tags": [
          "Organization"
        ],
        "responses": {
          "200": {
            "description": "List of accounts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListAccounts_Account"
                      }
                    }
                  },
                  "required": [
                    "accounts"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/stores": {
      "get": {
        "summary": "List stores",
        "operationId": "listStores",
        "description": "Retrieve a list of all stores for your organization.",
        "tags": [
          "Organization"
        ],
        "responses": {
          "200": {
            "description": "List of stores",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "stores": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListStores_Store"
                      }
                    }
                  },
                  "required": [
                    "stores"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/brands": {
      "get": {
        "summary": "List brands",
        "operationId": "listBrands",
        "description": "Retrieve a list of all brands for your organization.",
        "tags": [
          "Organization"
        ],
        "responses": {
          "200": {
            "description": "List of brands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "brands": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListBrands_Brand"
                      }
                    }
                  },
                  "required": [
                    "brands"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/addresses/{addressReference}": {
      "get": {
        "summary": "Get address",
        "operationId": "getAddress",
        "description": "Retrieve address details.\n",
        "tags": [
          "Addresses"
        ],
        "parameters": [
          {
            "name": "addressReference",
            "in": "path",
            "required": true,
            "description": "The address reference identifier",
            "schema": {
              "$ref": "#/components/schemas/AddressReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Address details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "Response object for the `GetAddress` method. Printeers purges addresses from their systems after the guarantee period has expired. If the address was purged (indicated by the `purged` field), then the address will be null.\n",
                  "properties": {
                    "address": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Address"
                        }
                      ],
                      "nullable": true,
                      "description": "Address details (null if purged)"
                    },
                    "purged": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true,
                      "description": "Timestamp when the address was purged from Printeers' systems (null if not purged)",
                      "example": "2025-02-15T12:34:56Z"
                    }
                  },
                  "required": [
                    "address",
                    "purged"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/scenes": {
      "get": {
        "summary": "List scenes",
        "operationId": "listScenes",
        "description": "Retrieve a list of all available preview scenes.\n\nA scene is a 3D environment (e.g. a desk setup, a living room, a flat lay background) in which products are placed for rendering. Each scene is linked to one or more productgroups, determining which products can be rendered in that scene. Scenes can be public (available to everyone) or private (owned by you).\n\nUse the optional `productgroupReference` filter to find scenes that support a specific productgroup's products.\n",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "productgroupReference",
            "in": "query",
            "required": false,
            "description": "Filter scenes linked to this productgroup",
            "schema": {
              "$ref": "#/components/schemas/ProductgroupReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of scenes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "scenes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListScenes_Scene"
                      }
                    }
                  },
                  "required": [
                    "scenes"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/scenes/{sceneReference}": {
      "get": {
        "summary": "Get scene",
        "operationId": "getScene",
        "description": "Retrieve detailed information about a scene, including its description, enabled productgroups, and linked perspectives.\n\nThe `compatibleProductgroups` list shows which productgroups' products can be rendered in this scene. The `perspectives` list shows the scene's own camera angles. When `allowsProductPerspectives` is true, product-specific perspectives can also be used with this scene in addition to the scene's own perspectives.\n",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "sceneReference",
            "in": "path",
            "required": true,
            "description": "The scene reference identifier",
            "schema": {
              "$ref": "#/components/schemas/SceneReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scene details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "scene": {
                      "$ref": "#/components/schemas/GetScene_Scene"
                    }
                  },
                  "required": [
                    "scene"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/perspectives": {
      "get": {
        "summary": "List perspectives",
        "operationId": "listPerspectives",
        "description": "Retrieve a list of all available preview perspectives.\n\nA perspective defines a camera angle and output settings (resolution, format) for renders. There are two types:\n\n- **Scene perspectives** are linked to scenes and provide camera angles that are shared across all products rendered in that scene.\n- **Product perspectives** are linked directly to specific products and provide camera angles unique to those products.\n\nUse the optional `productReference` filter to find product perspectives for a specific product, or `sceneReference` to find scene perspectives for a specific scene.\n\nWhen both `sceneReference` and `productReference` are provided, the scene must allow product perspectives. If it does not, a `400` error with code `scene_does_not_allow_product_perspectives` is returned.\n",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "productReference",
            "in": "query",
            "required": false,
            "description": "Filter perspectives linked to this product",
            "schema": {
              "$ref": "#/components/schemas/ProductReference"
            }
          },
          {
            "name": "sceneReference",
            "in": "query",
            "required": false,
            "description": "Filter perspectives linked to this scene",
            "schema": {
              "$ref": "#/components/schemas/SceneReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of perspectives",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "perspectives": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListPerspectives_Perspective"
                      }
                    }
                  },
                  "required": [
                    "perspectives"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/perspectives/{perspectiveReference}": {
      "get": {
        "summary": "Get perspective",
        "operationId": "getPerspective",
        "description": "Retrieve detailed information about a perspective, including its output settings (resolution and format) and linked scenes or products.\n\nFor scene perspectives, the `scenes` field lists which scenes this perspective is available in (and `products` is null). For product perspectives, the `products` field lists which products have this perspective (and `scenes` is null).\n",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "perspectiveReference",
            "in": "path",
            "required": true,
            "description": "The perspective reference identifier",
            "schema": {
              "$ref": "#/components/schemas/PerspectiveReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Perspective details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "perspective": {
                      "$ref": "#/components/schemas/GetPerspective_Perspective"
                    }
                  },
                  "required": [
                    "perspective"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/lookup-composition": {
      "get": {
        "summary": "Lookup composition",
        "operationId": "lookupComposition",
        "description": "Look up a composition for a specific scene, product, and perspective combination.\nReturns the composition if found and available.\nReturns 404 if the combination does not exist, or 410 if the combination exists but is no longer available.\n",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "sceneReference",
            "in": "query",
            "required": true,
            "description": "The scene reference",
            "schema": {
              "$ref": "#/components/schemas/SceneReference"
            }
          },
          {
            "name": "productReference",
            "in": "query",
            "required": true,
            "description": "The product reference",
            "schema": {
              "$ref": "#/components/schemas/ProductReference"
            }
          },
          {
            "name": "perspectiveReference",
            "in": "query",
            "required": true,
            "description": "The perspective reference",
            "schema": {
              "$ref": "#/components/schemas/PerspectiveReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Composition found and available",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "composition": {
                      "$ref": "#/components/schemas/LookupComposition_Composition"
                    }
                  },
                  "required": [
                    "composition"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/compositions/{compositionReference}": {
      "get": {
        "summary": "Get composition",
        "operationId": "getComposition",
        "description": "Retrieve detailed information about a composition, including the scene, product,\nand perspective it combines.\n",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "compositionReference",
            "in": "path",
            "required": true,
            "description": "The composition reference identifier",
            "schema": {
              "$ref": "#/components/schemas/CompositionReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Composition details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "composition": {
                      "$ref": "#/components/schemas/GetComposition_Composition"
                    }
                  },
                  "required": [
                    "composition"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/renders": {
      "post": {
        "summary": "Create a render",
        "operationId": "createRender",
        "description": "Create a render by providing a composition reference and an image reference. If a render with the same combination already exists, the existing render reference is returned.\n\nUse `GET /lookup-composition` to find the composition reference for a scene, product, and perspective combination.\n\nEvery call consumes the composition's `tokenCost` rendertokens from your organization's weekly rendertoken limit. When the limit is reached, the request is rejected with `429` and code `rendertoken_limit_exceeded`; the limit resets every Monday at 00:00 Europe/Amsterdam. Use `GET /rendertokens` to check your current usage.\n\nThe render will be processed asynchronously. Use the render reference to poll the `/renders/{renderReference}` endpoint to check the render has completed.\n",
        "tags": [
          "Renders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "render": {
                    "$ref": "#/components/schemas/CreateRender_Render"
                  }
                },
                "required": [
                  "render"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Render created or already exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "render": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "reference": {
                          "$ref": "#/components/schemas/RenderReference"
                        }
                      },
                      "required": [
                        "reference"
                      ]
                    }
                  },
                  "required": [
                    "render"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. Possible error codes:\n- `composition_not_found`: The specified composition does not exist.\n- `composition_not_available`: The specified composition is no longer available.\n- `image_not_found`: The specified image does not exist.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "description": "Too many requests. Possible error codes:\n- `rate_limited`: A rate-limit policy was exceeded. The `X-RateLimit` headers carry the policy state; see the Rate Limiting guide.\n- `rendertoken_limit_exceeded`: Your organization's weekly rendertoken limit is reached. The limit resets every Monday at 00:00 Europe/Amsterdam; retrying earlier will not succeed. A rendertoken subscription with a higher limit can be activated in the Printeers Dashboard.\n\nIn both cases, honor `Retry-After` before retrying.\n",
            "headers": {
              "Retry-After": {
                "description": "Number of seconds to wait before retrying. For `rendertoken_limit_exceeded` this is the time until the weekly limit resets.",
                "schema": {
                  "type": "integer"
                },
                "example": 60
              },
              "X-RateLimit-Policy": {
                "description": "Active rate-limit policies, sent with `rate_limited` responses. See the Rate Limiting guide for the structured-fields format.",
                "schema": {
                  "type": "string"
                },
                "example": "\"default\";q=3000;w=60"
              },
              "X-RateLimit": {
                "description": "Remaining quota per policy at response time, sent with `rate_limited` responses.",
                "schema": {
                  "type": "string"
                },
                "example": "\"default\";r=0;t=42"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/rendertokens": {
      "get": {
        "summary": "Get rendertoken usage",
        "operationId": "getRendertokens",
        "description": "Retrieve your organization's rendertoken usage for the current weekly period: tokens used, the weekly limit, tokens remaining, and the moment the period resets.\n\nRendertokens are consumed by `POST /renders`; each composition's cost is its `tokenCost`. The weekly period follows the billing week and resets every Monday at 00:00 Europe/Amsterdam.\n",
        "tags": [
          "Renders"
        ],
        "responses": {
          "200": {
            "description": "Current rendertoken usage",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "rendertokens": {
                      "$ref": "#/components/schemas/GetRendertokens_Rendertokens"
                    }
                  },
                  "required": [
                    "rendertokens"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/renders/{renderReference}": {
      "get": {
        "summary": "Get render",
        "operationId": "getRender",
        "description": "Retrieve information about a render, including the composition reference, its status, thumbhash (when available), and timestamps. Use this endpoint to poll for render completion.\n",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "renderReference",
            "in": "path",
            "required": true,
            "description": "The render reference identifier",
            "schema": {
              "$ref": "#/components/schemas/RenderReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Render information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "render": {
                      "$ref": "#/components/schemas/GetRender_Render"
                    }
                  },
                  "required": [
                    "render"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/renders/{renderReference}/media": {
      "get": {
        "summary": "Download render media",
        "operationId": "downloadRenderMedia",
        "x-printeers-ratelimit-policies": [
          "default",
          "downloads"
        ],
        "description": "Download the rendered media file. Returns HTTP \"202 Accepted\" when the render is not yet complete. You can poll this endpoint directly or check the status first using `/renders/{renderReference}`.\n\n**Rate-limit policies:** `default`, `downloads`. See the [Rate Limiting guide](/guides/rate-limiting).",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "renderReference",
            "in": "path",
            "required": true,
            "description": "The render reference identifier",
            "schema": {
              "$ref": "#/components/schemas/RenderReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rendered media file",
            "headers": {
              "Cache-Control": {
                "description": "The file never changes once the render is complete, so it can be cached until it is purged. Always `private, max-age=31536000, immutable`.",
                "schema": {
                  "type": "string"
                },
                "example": "private, max-age=31536000, immutable"
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "202": {
            "description": "Render is not yet complete",
            "headers": {
              "Retry-After": {
                "description": "Suggested number of seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                },
                "example": 25
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/renders/{renderReference}/thumbnail": {
      "get": {
        "summary": "Download render thumbnail",
        "operationId": "downloadRenderThumbnail",
        "x-printeers-ratelimit-policies": [
          "default",
          "downloads"
        ],
        "description": "Download the rendered thumbnail. Returns HTTP \"202 Accepted\" when the render is not yet complete. You can poll this endpoint directly or check the status first using `/renders/{renderReference}`.\n\n**Rate-limit policies:** `default`, `downloads`. See the [Rate Limiting guide](/guides/rate-limiting).",
        "tags": [
          "Renders"
        ],
        "parameters": [
          {
            "name": "renderReference",
            "in": "path",
            "required": true,
            "description": "The render reference identifier",
            "schema": {
              "$ref": "#/components/schemas/RenderReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rendered thumbnail file",
            "headers": {
              "Cache-Control": {
                "description": "The file never changes once the render is complete, so it can be cached until it is purged. Always `private, max-age=31536000, immutable`.",
                "schema": {
                  "type": "string"
                },
                "example": "private, max-age=31536000, immutable"
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "202": {
            "description": "Render is not yet complete",
            "headers": {
              "Retry-After": {
                "description": "Suggested number of seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                },
                "example": 25
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/productgroups": {
      "get": {
        "summary": "List productgroups",
        "operationId": "listProductgroups",
        "description": "Retrieve a list of all productgroups available to your organization.\n\nProductgroups define a category of products with shared pricing. Use `GET /products` with a productgroup filter to list the individual products within a group.\n",
        "tags": [
          "Catalog"
        ],
        "responses": {
          "200": {
            "description": "List of productgroups",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "productgroups": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListProductgroups_Productgroup"
                      },
                      "description": "Sorted by name."
                    }
                  },
                  "required": [
                    "productgroups"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/products": {
      "get": {
        "summary": "List products",
        "operationId": "listProducts",
        "description": "Retrieve a paginated list of all products that can be ordered through the API.\n\nResults are paginated. See [Pagination Guide](https://api-docs.printeers.com/guides/pagination).\n",
        "tags": [
          "Catalog"
        ],
        "parameters": [
          {
            "name": "productgroupReference",
            "in": "query",
            "required": false,
            "description": "Filter products by productgroup.",
            "schema": {
              "$ref": "#/components/schemas/ProductgroupReference"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor from a previous response's `nextCursor` field.\nOmit this parameter to get the first page.\n",
            "schema": {
              "type": "string",
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of products",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListProducts_Product"
                      },
                      "description": "Sorted by `announced`, newest first."
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Pagination cursor for the next page of results. Null if this is the last page."
                    }
                  },
                  "required": [
                    "products",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/products/{productReference}": {
      "get": {
        "summary": "Get product",
        "operationId": "getProduct",
        "description": "Retrieve product details by reference.\n\nBoth public products and products owned by your organization are accessible.\n",
        "tags": [
          "Catalog"
        ],
        "parameters": [
          {
            "name": "productReference",
            "in": "path",
            "required": true,
            "description": "The product reference identifier",
            "schema": {
              "$ref": "#/components/schemas/ProductReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "product": {
                      "$ref": "#/components/schemas/GetProduct_Product"
                    }
                  },
                  "required": [
                    "product"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/products/{productReference}/media/{filename}": {
      "get": {
        "summary": "Download product media",
        "operationId": "downloadProductMedia",
        "x-printeers-ratelimit-policies": [
          "default",
          "downloads"
        ],
        "description": "Download the bytes for a single piece of product media. The `filename` is taken verbatim from the `filename` field of an entry in the product's `media` array (returned by `GET /products/{productReference}`).\n\nFilenames are opaque and may stop being valid at any time. If a filename stops resolving, re-fetch the product's `media` array and retry with a current filename. The response is served as `application/octet-stream`; use the `contentType` of the matching `media` entry to interpret the bytes.\n\n**Rate-limit policies:** `default`, `downloads`. See the [Rate Limiting guide](/guides/rate-limiting).",
        "tags": [
          "Catalog"
        ],
        "parameters": [
          {
            "name": "productReference",
            "in": "path",
            "required": true,
            "description": "The product reference identifier",
            "schema": {
              "$ref": "#/components/schemas/ProductReference"
            }
          },
          {
            "name": "filename",
            "in": "path",
            "required": true,
            "description": "The media filename, taken from the product's `media[].filename`",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product media bytes",
            "headers": {
              "Cache-Control": {
                "description": "`private, max-age=31536000, immutable` for a render, which never changes under its filename. `private, no-cache` for an example image, which may be replaced under the same filename: cache it, but revalidate with the validators below.",
                "schema": {
                  "type": "string"
                },
                "example": "private, no-cache"
              },
              "ETag": {
                "description": "Strong validator of an example image; changes whenever the file is replaced. Absent for renders.",
                "schema": {
                  "type": "string"
                },
                "example": "\"1758536215123456\""
              },
              "Last-Modified": {
                "description": "When an example image was last replaced. Absent for renders.",
                "schema": {
                  "type": "string"
                },
                "example": "Mon, 22 Sep 2026 10:30:15 GMT"
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/packagings": {
      "get": {
        "summary": "List packagings",
        "operationId": "listPackagings",
        "description": "Retrieve a list of all packaging options for your organization.\n",
        "tags": [
          "Catalog"
        ],
        "responses": {
          "200": {
            "description": "List of packagings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "packagings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListPackagings_Packaging"
                      },
                      "description": "Sorted by `name`."
                    }
                  },
                  "required": [
                    "packagings"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/packagings/{packagingReference}": {
      "get": {
        "summary": "Get packaging",
        "operationId": "getPackaging",
        "description": "Retrieve packaging details by reference.\n\nOnly packaging options owned by your organization are accessible.\n",
        "tags": [
          "Catalog"
        ],
        "parameters": [
          {
            "name": "packagingReference",
            "in": "path",
            "required": true,
            "description": "The packaging reference identifier",
            "schema": {
              "$ref": "#/components/schemas/PackagingReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Packaging details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "packaging": {
                      "$ref": "#/components/schemas/GetPackaging_Packaging"
                    }
                  },
                  "required": [
                    "packaging"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/orders": {
      "get": {
        "summary": "List orders",
        "operationId": "listOrders",
        "description": "List orders for your organization. Sorted by `created`, newest first.\n\nResults are paginated. See [Pagination Guide](https://api-docs.printeers.com/guides/pagination).\n",
        "tags": [
          "Orders"
        ],
        "parameters": [
          {
            "name": "storeReference",
            "in": "query",
            "required": false,
            "description": "Filter orders by store.",
            "schema": {
              "$ref": "#/components/schemas/StoreReference"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor from a previous response's `nextCursor` field.\nOmit this parameter to get the first page.\n",
            "schema": {
              "type": "string",
              "nullable": true
            },
            "example": "c1UAQQ5R7FJQKYDW6ETFOFJECTNEMSBHC6DYVL7VO4D3BTNSM32XZGNVEYTSHQXN7YZ3YATDA"
          }
        ],
        "responses": {
          "200": {
            "description": "List of orders",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "orders": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListOrders_Order"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Pagination cursor for the next page of results. Null if this is the last page.",
                      "example": "c1UAQQ5R7FJQKYDW6ETFOFJECTNEMSBHC6DYVL7VO4D3BTNSM32XZGNVEYTSHQXN7YZ3YATDA"
                    }
                  },
                  "required": [
                    "orders",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      },
      "post": {
        "summary": "Create order",
        "operationId": "createOrder",
        "description": "Create a new order for the specified store.\n\n**Shipping kinds:**\n- `dropship`: Ship directly to the customer. Requires a `dropshipAddress`. Optionally set `dropshipMinimalShippingLevel` and `dropshipPreferredPackagingReference`.\n- `combined`: Consolidate with other orders and ship to the partner's business address. No address or shipping options needed.\n\n**Print products:**\nOrderlines for print products must include an `imageReference`. Upload images beforehand and use the returned reference.\n",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "order": {
                    "$ref": "#/components/schemas/CreateOrder_Order"
                  }
                },
                "required": [
                  "order"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "order": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "reference": {
                          "$ref": "#/components/schemas/OrderReference"
                        }
                      },
                      "required": [
                        "reference"
                      ]
                    }
                  },
                  "required": [
                    "order"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. Returned when the request body fails input validation (missing required fields, malformed values, references that do not exist or are not accessible). State conflicts (uniqueness violations, claim already exists, store archived, etc.) are returned as 409 instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Store not found or not accessible",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/orders/{orderReference}": {
      "get": {
        "summary": "Get order",
        "operationId": "getOrder",
        "description": "Retrieve order details including orderlines and shipment references.\n",
        "tags": [
          "Orders"
        ],
        "parameters": [
          {
            "name": "orderReference",
            "in": "path",
            "required": true,
            "description": "The order reference identifier",
            "schema": {
              "$ref": "#/components/schemas/OrderReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "order": {
                      "$ref": "#/components/schemas/GetOrder_Order"
                    }
                  },
                  "required": [
                    "order"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/orders/{orderReference}/cancel": {
      "post": {
        "summary": "Cancel orderlines",
        "operationId": "cancelOrderlines",
        "description": "Cancel (part of) the quantity of one or more orderlines.\n\nFor every listed orderline, `canceledQuantity` is the desired **total** canceled quantity of that line, mirroring the `canceledQuantity` field returned by Get order. It is not the amount to cancel on top of the current value. Repeating the same request succeeds without canceling more items, which makes retries safe. Orderlines that are not listed keep their current canceled quantity; omitting a line does not set its canceled quantity to 0.\n\nThe request is atomic: if any listed orderline fails validation, nothing is canceled.\n\nCanceling cannot be undone. A `canceledQuantity` below the current canceled quantity of the line is rejected with `canceled_quantity_below_current`; this usually means the order changed since you last retrieved it. Retrieve the order again to see the current state.\n\nPossible `400` error codes:\n- `orderline_not_found`: an `index` does not exist on this order\n- `duplicate_orderline_index`: the same `index` is listed more than once\n- `canceled_quantity_exceeds_quantity`: `canceledQuantity` is larger than the `quantity` of the orderline\n\nPossible `409` error codes:\n- `canceled_quantity_below_current`: `canceledQuantity` is below the current canceled quantity of the orderline\n- `canceled_quantity_exceeds_shippable`: `canceledQuantity` is larger than the quantity that has not been shipped\n- `already_in_production`: the order is in production and cannot be canceled at this time\n",
        "tags": [
          "Orders"
        ],
        "parameters": [
          {
            "name": "orderReference",
            "in": "path",
            "required": true,
            "description": "The order reference identifier",
            "schema": {
              "$ref": "#/components/schemas/OrderReference"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "orderlines": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "index": {
                          "type": "integer",
                          "minimum": 1,
                          "description": "Sequential index of the orderline within the order, as returned by Get order",
                          "example": 1
                        },
                        "canceledQuantity": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "The desired total canceled quantity of the orderline (absolute value, not a delta)",
                          "example": 2
                        }
                      },
                      "required": [
                        "index",
                        "canceledQuantity"
                      ]
                    }
                  }
                },
                "required": [
                  "orderlines"
                ]
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Canceled quantities applied successfully"
          },
          "400": {
            "description": "Invalid request. Returned when the request body fails input validation (malformed values, an orderline index that does not exist on the order, duplicate indexes, or a canceled quantity larger than the orderline quantity). State conflicts are returned as 409 instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/orders/{orderReference}/dropship-address": {
      "put": {
        "summary": "Set order dropship address",
        "operationId": "setOrderDropshipAddress",
        "description": "Replace the destination address of a dropship order.\n\nThe address is validated like at order creation and replaces the previous address completely; every field is taken from the request. The order gets a new `dropshipAddressReference`, which `GET /orders/{orderReference}` returns. The previous address is no longer linked to the order and its reference no longer resolves, unless a shipment of the order was already created with it.\n\nThe address can be changed as long as the order is open: until every orderline has been shipped or canceled. A shipment that was already created keeps the address it was created with. Replacement orders cannot change their address, they are sent to the destination of the claim they settle.\n\nPossible `400` error codes are the address error codes of `POST /orders`, such as `invalid_address`, `invalid_address_missing_email`, `invalid_address_missing_phonenumber`, `invalid_address_missing_state`, `invalid_address_denied_country`, `invalid_address_eu_destination` and `invalid_country_code`.\n\nPossible `409` error codes:\n- `order_not_dropship`: the order is a combined order and has no destination address\n- `order_completed`: every orderline of the order has been shipped or canceled\n- `replacement_address_locked`: the order is a replacement order\n",
        "tags": [
          "Orders"
        ],
        "parameters": [
          {
            "name": "orderReference",
            "in": "path",
            "required": true,
            "description": "The order reference identifier",
            "schema": {
              "$ref": "#/components/schemas/OrderReference"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "dropshipAddress": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Address"
                      }
                    ],
                    "description": "The new destination address of the order"
                  }
                },
                "required": [
                  "dropshipAddress"
                ]
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Dropship address replaced successfully"
          },
          "400": {
            "description": "Invalid request. Returned when the address fails input validation. State conflicts are returned as 409 instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/quote": {
      "post": {
        "summary": "Quote order",
        "operationId": "quoteOrder",
        "description": "Calculate the shipping options of an order before placing it. Nothing is stored. The request takes only the fields of `POST /orders` that determine shipping (store, shipping kind, destination address, minimal shipping level and the products with their quantities), under the same names. The other order fields, such as images, annotations and the custom identifier, are not accepted.\n\nFor a `dropship` order, `shippingOptions` lists every shipping level the order can ship with, each with its shipping price in EUR cents. The first option is the lowest possible level: the requested `dropshipMinimalShippingLevel` (default `basic`), raised or lowered where the destination, the weight or the value of the order requires it. The higher levels follow as alternatives, but only when an order asking for that level would ship with it: a Packstation, for example, is served by `tracked` only. A level for which no shipping price is configured for the destination is left out.\n\nA `combined` order is consolidated with other orders and shipped to your business address, so it has no shipping options of its own: `shippingOptions` is empty.\n\nThe store, the products and the destination country are checked the way `POST /orders` checks them, with the same error codes. Possible `400` error codes: `store_archived`, `invalid_product_reference`, `product_not_orderable`, `orderline_quantity_zero`, `missing_address`, `unwanted_address`, `unwanted_shipping_minimal_level`, `invalid_address_denied_country` and `invalid_country_code`. A store whose orders originate in an upstream platform answers `403` with `store_not_writable_via_api`, like order creation. The full address validation of `POST /orders` (phone number, email address, field lengths) is not applied to a quote.\n",
        "tags": [
          "Orders"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "quote": {
                    "$ref": "#/components/schemas/QuoteOrder_Quote"
                  }
                },
                "required": [
                  "quote"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shipping options of the quoted order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "shippingOptions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/QuoteOrder_ShippingOption"
                      },
                      "description": "Shipping levels the order can ship with, lowest level first. Empty for `combined` orders."
                    }
                  },
                  "required": [
                    "shippingOptions"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. Returned when the request body fails input validation (missing required fields, malformed values, references that do not exist or are not accessible, a destination we cannot ship to).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Store not found or not accessible",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/images": {
      "get": {
        "summary": "List images",
        "operationId": "listImages",
        "description": "Retrieve a paginated list of images uploaded by your organization.\n\nResults are paginated. See [Pagination Guide](https://api-docs.printeers.com/guides/pagination).\n",
        "tags": [
          "Images"
        ],
        "parameters": [
          {
            "name": "library",
            "in": "query",
            "required": false,
            "description": "Filter images by library status. Omit to return all images.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor from a previous response's `nextCursor` field.\nOmit this parameter to get the first page.\n",
            "schema": {
              "type": "string",
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of images",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "images": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListImages_Image"
                      },
                      "description": "Sorted by `created`, newest first."
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Pagination cursor for the next page of results. Null if this is the last page."
                    }
                  },
                  "required": [
                    "images",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      },
      "post": {
        "summary": "Upload a print image",
        "operationId": "uploadImage",
        "x-printeers-ratelimit-policies": [
          "default",
          "uploads"
        ],
        "description": "Upload a print image for use in order creation.\nReturns an image reference that can be passed when creating an order with print products.\n\n**Accepted formats:** JPEG, PNG (sent as `Content-Type: application/octet-stream`).\n\n**Max dimensions:** 7000x7000 pixels (images exceeding this are automatically downsized).\n\n**Max file size:** 50 MiB. Larger uploads return `400` with code `file_too_large`.\n\n**Deduplication:** Uploading the same image twice returns the same image reference.\n\n**Rate-limit policies:** `default`, `uploads`. See the [Rate Limiting guide](/guides/rate-limiting).",
        "tags": [
          "Images"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Image uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "image": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "reference": {
                          "$ref": "#/components/schemas/ImageReference"
                        }
                      },
                      "required": [
                        "reference"
                      ]
                    }
                  },
                  "required": [
                    "image"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Possible error codes:\n- `failed_to_read_file`: the request body could not be read.\n- `file_too_large`: the image exceeds the maximum upload size.\n- `invalid_image`: the file could not be decoded or uses an unsupported format.\n- `unsupported_color_model`: the image uses an unsupported color model (e.g. CMYK).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/images/{imageReference}": {
      "patch": {
        "summary": "Update image",
        "operationId": "updateImage",
        "description": "Update the name and/or library status of an existing image. Only fields present in the request body are updated; omitted fields are left unchanged. At least one field must be provided.\n",
        "tags": [
          "Images"
        ],
        "parameters": [
          {
            "name": "imageReference",
            "in": "path",
            "required": true,
            "description": "The image reference identifier",
            "schema": {
              "$ref": "#/components/schemas/ImageReference"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "minProperties": 1,
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "User-provided name for the image",
                    "example": "My design front"
                  },
                  "library": {
                    "type": "boolean",
                    "description": "Whether this image is a library image",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Image updated successfully"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/shipments/{shipmentReference}": {
      "get": {
        "summary": "Get shipment",
        "operationId": "getShipment",
        "description": "Retrieve shipment details including tracking information and the list of orders and orderlines contained in the shipment.\n\nOnly dropship and combined shipments are accessible through this endpoint.\n",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "name": "shipmentReference",
            "in": "path",
            "required": true,
            "description": "The shipment reference identifier",
            "schema": {
              "$ref": "#/components/schemas/ShipmentReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "shipment": {
                      "$ref": "#/components/schemas/GetShipment_Shipment"
                    }
                  },
                  "required": [
                    "shipment"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/items": {
      "get": {
        "summary": "List items",
        "operationId": "listItems",
        "description": "Retrieve a list of all warehouse items (stock items) owned by your organization.\n\nItems are physical goods stored in the warehouse. Each item can be linked to one or more\nproducts and/or packagings, indicating that these products or packagings draw their stock\nfrom this item. The `products` array lists the orderable products that use this item as\ntheir stock source, and the `packagings` array lists the packaging options that use this\nitem as their stock source.\n\nResults are paginated. See [Pagination Guide](https://api-docs.printeers.com/guides/pagination).\n",
        "tags": [
          "Warehouse"
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor from a previous response's `nextCursor` field.\nOmit this parameter to get the first page.\n",
            "schema": {
              "type": "string",
              "nullable": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of warehouse items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListItems_Item"
                      },
                      "description": "Sorted by `created`, newest first."
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Pagination cursor for the next page of results. Null if this is the last page."
                    }
                  },
                  "required": [
                    "items",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/utilities/lookup-order-reference-by-legacy-code": {
      "get": {
        "summary": "Look up order reference by legacy order code",
        "operationId": "lookupOrderReferenceByLegacyCode",
        "description": "Look up an order's reference using the legacy order code from v1 API.\n\nLegacy order codes have the format `STORECODE-NUMBER` (e.g., \"MYSTORE-1234\").\n\nThe order must belong to a store owned by your organization.\n\nThis endpoint is provided to help ease migration from v1 to v2+. It will be removed in v3.\n",
        "tags": [
          "Utilities"
        ],
        "parameters": [
          {
            "name": "legacyOrderCode",
            "in": "query",
            "required": true,
            "description": "The legacy order code in format STORECODE-NUMBER",
            "schema": {
              "type": "string"
            },
            "example": "MYSTORE-1234"
          }
        ],
        "responses": {
          "200": {
            "description": "Order reference found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "orderReference": {
                      "$ref": "#/components/schemas/OrderReference"
                    }
                  },
                  "required": [
                    "orderReference"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/utilities/lookup-order-reference-by-custom-identifier": {
      "get": {
        "summary": "Look up order reference by store reference and custom identifier",
        "operationId": "lookupOrderReferenceByCustomIdentifier",
        "description": "Look up an order's reference using the store reference and custom identifier.\n\nThe custom identifier must have been provided when the order was created.\nThe store must belong to your organization.\n",
        "tags": [
          "Utilities"
        ],
        "parameters": [
          {
            "name": "storeReference",
            "in": "query",
            "required": true,
            "description": "The store reference",
            "schema": {
              "$ref": "#/components/schemas/StoreReference"
            }
          },
          {
            "name": "customIdentifier",
            "in": "query",
            "required": true,
            "description": "The custom identifier that was provided when the order was created",
            "schema": {
              "type": "string",
              "maxLength": 30
            },
            "example": "MyOrder-A1B2C3"
          }
        ],
        "responses": {
          "200": {
            "description": "Order reference found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "orderReference": {
                      "$ref": "#/components/schemas/OrderReference"
                    }
                  },
                  "required": [
                    "orderReference"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/utilities/lookup-store-reference-by-legacy-code": {
      "get": {
        "summary": "Look up store reference by legacy store code",
        "operationId": "lookupStoreReferenceByLegacyCode",
        "description": "Look up a store's reference using the legacy store code from v1 API.\n\nLegacy store codes are short alphanumeric strings (e.g., \"MYSTORE\").\n\nThe store must belong to your organization.\n\nThis endpoint is provided to help ease migration from v1 to v2+. It will be removed in v3.\n",
        "tags": [
          "Utilities"
        ],
        "parameters": [
          {
            "name": "legacyStoreCode",
            "in": "query",
            "required": true,
            "description": "The legacy store code",
            "schema": {
              "type": "string"
            },
            "example": "MYSTORE"
          }
        ],
        "responses": {
          "200": {
            "description": "Store reference found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "storeReference": {
                      "$ref": "#/components/schemas/StoreReference"
                    }
                  },
                  "required": [
                    "storeReference"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/utilities/lookup-product-reference-by-legacy-sku": {
      "get": {
        "summary": "Look up product reference by legacy item SKU",
        "operationId": "lookupProductReferenceByLegacySku",
        "description": "Look up a product's reference using the legacy item SKU from v1 API.\n\nLegacy item SKUs are alphanumeric strings (e.g., \"B68200000\").\n\nBoth public products and products owned by your organization can be looked up.\n\nThis endpoint is provided to help ease migration from v1 to v2+. It will be removed in v3.\n",
        "tags": [
          "Utilities"
        ],
        "parameters": [
          {
            "name": "legacyItemSku",
            "in": "query",
            "required": true,
            "description": "The legacy item SKU",
            "schema": {
              "type": "string"
            },
            "example": "B68200000"
          }
        ],
        "responses": {
          "200": {
            "description": "Product reference found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "productReference": {
                      "$ref": "#/components/schemas/ProductReference"
                    }
                  },
                  "required": [
                    "productReference"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/utilities/lookup-image-reference-by-legacy-code": {
      "get": {
        "summary": "Look up image reference by legacy image code",
        "operationId": "lookupImageReferenceByLegacyCode",
        "description": "Look up an image's reference using the legacy image code from v1 API.\n\nLegacy image codes have the format `STORECODE-img-NUMBER` (e.g., \"MYSTORE-img-42\").\n\nThe image must belong to your organization.\n\nThis endpoint is provided to help ease migration from v1 to v2+. It will be removed in v3.\n",
        "tags": [
          "Utilities"
        ],
        "parameters": [
          {
            "name": "legacyImageCode",
            "in": "query",
            "required": true,
            "description": "The legacy image code in format STORECODE-img-NUMBER",
            "schema": {
              "type": "string"
            },
            "example": "MYSTORE-img-42"
          }
        ],
        "responses": {
          "200": {
            "description": "Image reference found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "imageReference": {
                      "$ref": "#/components/schemas/ImageReference"
                    }
                  },
                  "required": [
                    "imageReference"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/utilities/lookup-account-reference-by-legacy-code": {
      "get": {
        "summary": "Look up account reference by legacy account code",
        "operationId": "lookupAccountReferenceByLegacyCode",
        "description": "Look up an account's reference using the legacy account code from v1 API.\n\nLegacy account codes are 11-character strings consisting of a 3-letter entity code followed by an 8-digit encoded ID (e.g., \"NLD12785623\").\n\nThe account must belong to your organization.\n\nThis endpoint is provided to help ease migration from v1 to v2+. It will be removed in v3.\n",
        "tags": [
          "Utilities"
        ],
        "parameters": [
          {
            "name": "legacyAccountCode",
            "in": "query",
            "required": true,
            "description": "The legacy account code",
            "schema": {
              "type": "string"
            },
            "example": "NLD12785623"
          }
        ],
        "responses": {
          "200": {
            "description": "Account reference found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "accountReference": {
                      "$ref": "#/components/schemas/AccountReference"
                    }
                  },
                  "required": [
                    "accountReference"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/utilities/lookup-packaging-reference-by-legacy-code": {
      "get": {
        "summary": "Look up packaging reference by legacy packaging code",
        "operationId": "lookupPackagingReferenceByLegacyCode",
        "description": "Look up a packaging's reference using the legacy packaging code from v1 API.\n\nBoth public packagings and packagings owned by your organization can be looked up.\n\nThis endpoint is provided to help ease migration from v1 to v2+. It will be removed in v3.\n",
        "tags": [
          "Utilities"
        ],
        "parameters": [
          {
            "name": "legacyPackagingCode",
            "in": "query",
            "required": true,
            "description": "The legacy packaging code",
            "schema": {
              "type": "string"
            },
            "example": "PARTNER_COEX_BAG"
          }
        ],
        "responses": {
          "200": {
            "description": "Packaging reference found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "packagingReference": {
                      "$ref": "#/components/schemas/PackagingReference"
                    }
                  },
                  "required": [
                    "packagingReference"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/claims": {
      "get": {
        "summary": "List claims",
        "operationId": "listClaims",
        "description": "List claims for your organization. By default returns all open claims and closed claims from the last 14 days. Sorted by `created`, newest first.\n\nResults are paginated. See [Pagination Guide](https://api-docs.printeers.com/guides/pagination).\n",
        "tags": [
          "Claims"
        ],
        "parameters": [
          {
            "name": "closedAfter",
            "in": "query",
            "required": false,
            "description": "Only include closed claims (resolved/rejected/retracted) after this date-time.\nDefaults to 14 days ago if omitted. Set to an earlier date to retrieve older closed claims.\nFormat: RFC3339 (ISO 8601)\n",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2025-12-01T00:00:00Z"
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Pagination cursor from a previous response's `nextCursor` field.\nOmit this parameter to get the first page.\n",
            "schema": {
              "type": "string",
              "nullable": true
            },
            "example": "c1UAQQ5R7FJQKYDW6ETFOFJECTNEMSBHC6DYVL7VO4D3BTNSM32XZGNVEYTSHQXN7YZ3YATDA"
          }
        ],
        "responses": {
          "200": {
            "description": "List of claims",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "claims": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListClaims_Claim"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Pagination cursor for the next page of results. Null if this is the last page.",
                      "example": "c1UAQQ5R7FJQKYDW6ETFOFJECTNEMSBHC6DYVL7VO4D3BTNSM32XZGNVEYTSHQXN7YZ3YATDA"
                    }
                  },
                  "required": [
                    "claims",
                    "nextCursor"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/claimcategories": {
      "get": {
        "summary": "List claimcategories",
        "operationId": "listClaimcategories",
        "description": "Retrieve the list of valid claim categories that can be used when submitting a claim with item issues.\n",
        "tags": [
          "Claims"
        ],
        "responses": {
          "200": {
            "description": "List of claimcategories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "claimcategories": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ListClaimcategories_Claimcategory"
                      },
                      "description": "Available claimcategories for claims"
                    }
                  },
                  "required": [
                    "claimcategories"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/claims/{claimReference}": {
      "get": {
        "summary": "Get claim",
        "operationId": "getClaim",
        "description": "Retrieve detailed information about a specific claim, including all claimlines and a reference to the related shipment.\n\nUse `GET /shipments/{shipmentReference}` to retrieve full shipment details including tracking information and delivery address.\n",
        "tags": [
          "Claims"
        ],
        "parameters": [
          {
            "name": "claimReference",
            "in": "path",
            "required": true,
            "description": "The claim reference identifier",
            "schema": {
              "$ref": "#/components/schemas/ClaimReference"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Claim details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "claim": {
                      "$ref": "#/components/schemas/GetClaim_Claim"
                    }
                  },
                  "required": [
                    "claim"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/evidence": {
      "post": {
        "summary": "Upload claim evidence",
        "x-printeers-ratelimit-policies": [
          "default",
          "uploads"
        ],
        "operationId": "uploadClaimEvidence",
        "description": "Upload an evidence file for use in a claim submission.\nReturns an evidence reference that must be passed when submitting the claim.\n\nUploaded evidence that is not used in a claim within 1 day is automatically deleted.\n\n**Accepted formats:** JPEG, PNG (sent as `Content-Type: application/octet-stream`).\n\n**Rate-limit policies:** `default`, `uploads`. See the [Rate Limiting guide](/guides/rate-limiting).",
        "tags": [
          "Claims"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Evidence uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "evidence": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "reference": {
                          "$ref": "#/components/schemas/EvidenceReference"
                        }
                      },
                      "required": [
                        "reference"
                      ]
                    }
                  },
                  "required": [
                    "evidence"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Possible error codes:\n- `failed_to_read_file`: the request body could not be read.\n- `invalid_file_type`: the file is not a JPEG or PNG.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/claim-package-missing": {
      "post": {
        "summary": "Create a package missing claim",
        "operationId": "createClaimPackageMissing",
        "description": "Create a claim for a completely missing package. This automatically claims all items in the shipment.\n\nUse this endpoint when the entire package never arrived. For issues with specific items (damaged, defective, etc.), use the `/claim-item-issues` endpoint instead.\n\n**Requirements:**\n- The promised delivery window for the shipment's destination and shipping level must have passed (never earlier than two calendar days after the ship day); the `shipment_too_recent` error message states the date from which the claim can be filed\n- Shipment must be within 100-day warranty period\n- No existing claims on the shipment\n- Order must not have a replacement order already\n- 0-3 evidence references may be provided optionally (upload evidence first using `POST /evidence`)\n",
        "tags": [
          "Claims"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "claim": {
                    "$ref": "#/components/schemas/CreateClaimPackageMissing_Claim"
                  }
                },
                "required": [
                  "claim"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Claim created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "claim": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "reference": {
                          "$ref": "#/components/schemas/ClaimReference"
                        }
                      },
                      "required": [
                        "reference"
                      ]
                    }
                  },
                  "required": [
                    "claim"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. Returned when the request body fails input validation (missing required fields, malformed values, references that do not exist or are not accessible). State conflicts (uniqueness violations, claim already exists, store archived, etc.) are returned as 409 instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Shipment not found or not accessible",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/claim-item-issues": {
      "post": {
        "summary": "Create an item issues claim",
        "operationId": "createClaimItemIssues",
        "description": "Create a claim for specific item issues (damaged, defective, wrong item, etc.).\n\nUse this endpoint when specific items have problems. For a completely missing package, use the `/claim-package-missing` endpoint instead.\n\n**Requirements:**\n- Shipment must be within 100-day warranty period\n- Claim quantity per item must not exceed shipped quantity (other open claims count toward this limit)\n- Up to 3 evidence references per claimed item; at least 1 is required when the item's claimcategory has `evidenceRequired: true` in `GET /claimcategories` (upload evidence first using `POST /evidence`)\n\nPossible `400` error codes:\n- `order_not_in_shipment`: no items of `orderReference` were shipped in `shipmentReference`\n- `orderline_not_in_shipment`: an `orderlineIndex` is not among the items of `orderReference` shipped in `shipmentReference`\n- `package_missing_category_not_allowed`: the \"Package missing\" claimcategory cannot be used here; use `POST /claim-package-missing` instead\n",
        "tags": [
          "Claims"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "claim": {
                    "$ref": "#/components/schemas/CreateClaimItemIssues_Claim"
                  }
                },
                "required": [
                  "claim"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Claim created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "claim": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "reference": {
                          "$ref": "#/components/schemas/ClaimReference"
                        }
                      },
                      "required": [
                        "reference"
                      ]
                    }
                  },
                  "required": [
                    "claim"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. Returned when the request body fails input validation (missing required fields, malformed values, references that do not exist or are not accessible). State conflicts (uniqueness violations, claim already exists, store archived, etc.) are returned as 409 instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Shipment not found or not accessible",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    },
    "/claims/{claimReference}/retract": {
      "post": {
        "summary": "Retract a claim",
        "operationId": "retractClaim",
        "description": "Retract (cancel) a pending claim. This action cannot be undone.\n\nOnly claims with status `pending` can be retracted. Claims that have already been decided (resolved or rejected) cannot be retracted.\n\nPossible `409` error codes:\n- `incomplete_package_missing_claim`: the underlying shipment has gained shipmentlines since this `package missing` claim was created, so the claim no longer covers all shipmentlines. Contact support to reconcile.\n",
        "tags": [
          "Claims"
        ],
        "parameters": [
          {
            "name": "claimReference",
            "in": "path",
            "required": true,
            "description": "The claim reference identifier",
            "schema": {
              "$ref": "#/components/schemas/ClaimReference"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Claim retracted successfully"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Claim not found, already decided, already retracted, or not accessible. Returns code `claim_not_found`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "SecretKey": []
          }
        ]
      }
    }
  }
}