{ "openapi": "3.0.0", "info": { "version": "1.0", "title": "API Documentation | Printful", "description": "# About the Printful API\n\nThe Printful API is a RESTful API, that uses an HTTP protocol for communication. HTTP GET, POST, PUT and DELETE methods are used to access the API resources.\n\n## Postman Collection\n\nYou can explore the API using the Postman collection:\n\nDownload Postman Collection\n\n## Requests and responses\n\n### Request endpoint\nAll API requests have to be sent to this URL:\n```\nhttps://api.printful.com/\n```\nIf you are using a proxy, make sure that all requests have host header set to **api.printful.com**.\n\n### Request parameters\nSome mandatory parameters (like object identifiers) must be included in the request URL path\n```\nGET /orders/123\n```\nAdditional parameters can be passed as GET variables:\n```\nGET /orders?offset=10&limit=5\n```\nFor POST and PUT requests, a more complex data structure can be passed as JSON encoded data in the request body:\n```\nPOST /orders\n\n{\"recipient\":{...},\"items\":[...]}\n```\n\n### Response body\nThe response body is always a JSON object that contains a response status code (identical to the HTTP status code) and the result of the action. If the status code is 200, then the action was successful.\n```\n{\n \"code\": 200, //Response status code\n \"result\":{\n //API method return data\n\t //...\n }\n}\n```\n\nSometimes the response includes paging information to allow to browse larger result sets by adding offset and limit GET parameters to the request URL.\n```\n{\n \"code\": 200, //Response status code\n \"result\":[\n\t {\n\t //Item 11\n\t },\n\t {\n\t //Item 12\n\t }\n ]\n \"paging\": {\n \"total\": 12, //Total items available\n \"offset\": 10, //Items skipped from the beginning\n \"limit\": 20 //Number of items per page\n }\n}\n```\n\n## Error response\nIf the API call is not successful, then the response code is not in the 2xx range and the `result` attribute contains an error description.\n```\n{\n \"code\": 404,\n \"result\": \"Not Found\",\n \"error\": {\n \"reason\": \"NotFound\",\n \"message\": \"Not Found\"\n }\n}\n```\n\nIn general, response codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with Printful's servers.\n\n### Timestamps\nAll timestamps from the API are returned as integers in UNIX timestamp format.\n\n## Rate Limits\nPrintful API has a general rate limit of 120 API calls per minute. Additionally, endpoints that perform resource intensive operations (such as mockup generator) have a lower allowed request limit.", "contact": { "name": "Printful developer support", "url": "https://developers.printful.com/docs/#tag/Other-resources/Developer-support" }, "x-logo": { "url": "https://static.cdn.printful.com/dist-pf/image-assets/off-center-full-color-black.1de1e822b15b8e74075c8d1fa631d4e3.svg", "backgroundColor": "#FFFFFF", "altText": "Printful" } }, "servers": [ { "url": "https://api.printful.com", "description": "The Printful API is a RESTful API, that uses the HTTP protocol for communication. HTTP GET, POST, PUT and DELETE methods are used to access the API." } ], "tags": [ { "name": "Localisation", "description": "Some of the resources returned by the API are translated into several languages. By default, they are returned in\nEnglish in the API responses.\n\nIf you want to get a response with texts in another language, you can use the `X-PF-Language`\nHTTP header. Its value should be the long version of the locale to use (e.g. `es_ES` for Spanish).\nPossible localisation parameters:\n- en_US\n- en_GB\n- en_CA\n- es_ES\n- fr_FR\n- de_DE\n- it_IT\n- ja_JP\n\n### Example\n\nProduct details (`GET https://api.printful.com/products/71`) response with default locale (`en_US`):\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product\": {\n \"type_name\": \"T-Shirt\",\n \"title\": \"Unisex Staple T-Shirt | Bella + Canvas 3001\",\n ...\n }\n }\n}\n```\n\nProduct details response with Spanish locale (`X-PF-Language: es_ES`):\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product\": {\n ...\n \"type_name\": \"Camiseta\",\n \"title\": \"Camiseta esencial unisex | Bella + Canvas 3001\",\n ...\n }\n }\n}\n```\n" }, { "name": "Authorization", "description": "This guide introduces the key concepts behind Printful OAuth, including\nthe differences between **Private Tokens** and **Public Apps**, available **client types**,\nand how **scopes** control API access.\n\nWe'll start by defining the terminology used throughout this documentation and then\nwalk through the **Developer Portal**, where you can create and manage your tokens and apps\nand acquire the credentials needed to authenticate API requests.\n\n## Private tokens and public apps\n\nThere are two different ways of using Printful OAuth – **Private Token** and **Public App**.\n\nUse a **Private Token** if you are developing an API solution for your personal store\nand only your own services will connect to this API.\n\nUse a **Public App** if you are building a public OAuth application that will be used\nby a wider audience and connected by third-party users.\n\n## Client types\n\nThere are two different client types – **Store** and **Account**.\n\nA **Store** access level client can only access a specific store.\nFor _Private Token_, this store is specified when the token is created,\nbut for _Public App_, it is specified when the app is installed.\n\nAn **Account** level token, on the other hand, can manage all stores associated with the account.\nFor endpoints that require a specific store context, requests should include the `X-PF-Store-Id` header.\nAccount-level access is currently available for _Private Token_ only.\n\n## Scopes\n\nScopes are used to limit access to specific resources and methods.\nScopes are defined in the **Developer Portal** when creating a **Private Token** or **Public App**.\nCustomers installing a **Public App** will see all requested permissions on the grant screen,\nso be thoughtful about which scopes you request.\n\nList of currently available scopes:\n\n| Scope | Client type | Description |\n|--------------------------|-----------------|----------------------------------------------|\n| `orders` | Store & Account | Read and Write access to Orders |\n| `orders/read` | Store & Account | Read access to Orders |\n| `sync_products` | Store & Account | Read and Write access to SyncProducts |\n| `sync_products/read` | Store & Account | Read access to SyncProducts |\n| `file_library` | Store & Account | Read and Write access access to File library |\n| `file_library/read` | Store & Account | Read access to File library |\n| `webhooks` | Store & Account | Read and Write access to Webhooks |\n| `webhooks/read` | Store & Account | Read access to Webhooks |\n| `product_templates` | Account | Read and Write access to Product templates |\n| `product_templates/read` | Account | Read access to Product templates |\n\n## Developer Portal\n\n[Developer Portal](https://developers.printful.com) is designed for developers who want\nto interact with the **Printful API**. In the **Developer Portal**, you can create and manage\nyour **Private Tokens** and **Public Apps**.\n\n### Acquiring Private Tokens\n\n**Private Tokens** can be generated in the **Developer Portal** on [Your tokens](https://developers.printful.com/tokens) page.\nThese tokens do not require refreshing and remain valid until they expire or are manually deleted.\nCopy the token after creation, as it will not be available for viewing later in the **Developer Portal**.\nInstructions on how to use them are provided in the [Using Private Token](#tag/Using-Private-Token) section.\n\n### Acquiring OAuth tokens for Public Apps\n\nFor a **Public App** to make API requests on behalf of a customer, the customer must first authorize the app.\nAfter the customer approves the requested scopes, your application can exchange\nthe returned `code` for OAuth access and refresh tokens.\n\nTo set this up, follow these steps:\n\n- create an app in the **Developer Portal** on [Your apps](https://developers.printful.com/apps) page\n- generate an app-specific installation URL using the `Client id`, `Client secret`, and other parameters\n- redirect the user to the app installation url\n- once the users returns to `redirect_url`, use the `code` parameter to acquire OAuth tokens\n\nThis section covers the initial setup steps. For details on authorizing users and exchanging\nthe `code` for tokens, see [Public App authorization](#tag/Public-App-authorization).\n" }, { "name": "Using Private Token", "description": "\nOnce you have generated a **Private Token** in the **Developer Portal**,\nyou can use it to authenticate your API requests.\n\nFor the **Store** access level token:\n\n```bash\ncurl --location \\\n --request GET 'https://api.printful.com/{request_path}' \\\n --header 'Authorization: Bearer {private_token}'\n```\n\nFor an **Account** access level token, a store context is required:\n\n```bash\ncurl --location \\\n --request GET 'https://api.printful.com/{request_path}' \\\n --header 'Authorization: Bearer {private_token}' \\\n --header 'X-PF-Store-Id: {store_id}'\n```\n\n**Private Tokens** have an expiration date. Make sure to generate a new token and update\nit in your service before the current one expires, as expired tokens cannot be refreshed\nand must be replaced manually.\n" }, { "name": "Public App authorization", "description": "#### Public App installation flow\nPublic App installation starts with a user redirection to an app-specific installation URL. Installation URL has to be\ngenerated in the following format:\n\n`https://www.printful.com/oauth/authorize?client_id={clientId}&state={stateValue}&redirect_url={redirectUrl}`\n\n| Parameter | Description |\n|--------------|----------------------------------------------------------------------------------------------------------------|\n| client_id | the `Client id` of your app |\n| state | use the optional state parameter to help keep track of the customer throughout the installation process |\n| redirect_url | URL to where the customer should be taken after the authorization step. This URL must be registered in the app |\n\nIn this URL, the customer is asked to register or log in to an existing account. After authorization, the customer is redirected to the OAuth grant screen. This screen shows information about your app, and the customer is asked to accept the requested scopes. If the customer rejects the app installation, he is redirected back to your provided `redirect_url` with `success=0` parameter. If the customer accepts app installation, he is redirected to your `redirect_url` with `state={stateValue}&code={authorizationCode}&success=1` parameters.\n\n| Parameter | Description |\n|-----------|---------------------------------------------------------------------------|\n| state | state parameter that was provided when installation flow was initialized |\n| code | authorization code that will be used to request access and refresh tokens |\n| success | flag indicating that authorization flow was successful |\n\nAfter receiving `authorization code`, apps should request `access` and `refresh` tokens. To request these tokens, the app should make a `POST` request to `https://www.printful.com/oauth/token` page with the following parameters:\n\n- grant_type=authorization_code\n- client_id={clientId}\n- client_secret={clientSecret}\n- code={authorizationCode}\n\nIf the request is successful, the following response is returned:\n```json\n{\n \"access_token\": \"smk_GN0I1Os3OdfqzjJnTOWn1wlbqqq2Y2Pc10TS\",\n \"expires_at\": \"1562157895\",\n \"token_type\": \"bearer\",\n \"refresh_token\": \"902LmW0sWNlY-mbrLhb6AgexkI6K4OFo3Hknak8HDhTy_ifB5SdoLH1QgV9\"\n}\n```\n| Field | Description |\n|---------------|--------------------------------------------------------------------------------------------------------------------|\n| access_token | this token should be used to make authorized API calls |\n| expires_at | timestamp for the date when the `access_token` will expire |\n| token_type | type of the token. Currently only `bearer`. Use it together with the `access_token` in authorized requests headers |\n| refresh_token | a token that can be used to refresh the `access_token` once it expires |\n\n### Refreshing tokens\nThe `access_token` will expire in **one hour**. When `access_token` expires you must refresh it with the `refresh_token`. After refreshing tokens, you will receive a new set of `access_token` and `refresh_token`. If tokens are not refreshed within **90** days, `refresh_token` will expire, and the app will have to ask the user to reauthorize it. To refresh tokens you must make a `POST` request to `https://www.printful.com/oauth/token` with the parameters:\n\n- grant_type=refresh_token\n- client_id=`{clientId}`\n- client_secret=`{clientSecret}`\n- refresh_token=`{refreshToken}`\n\nThe successful refresh request will result in a similar response that you received previously:\n```json\n{\n \"access_token\": \"smk_GN0I1Os3OdfqzjJnTOWn1wlbqqq2Y2Pc10TS\",\n \"expires_at\": \"1562157895\",\n \"token_type\": \"bearer\",\n \"refresh_token\": \"902LmW0sWNlY-mbrLhb6AgexkI6K4OFo3Hknak8HDhTy_ifB5SdoLH1QgV9\"\n}\n```" }, { "name": "OAuth API", "description": "OAuth API allows receiving data for token" }, { "name": "Catalog API", "description": "Printful has a substantial catalog of blank Products and Variants. A Product can describe a specific type, model and manufacturer of the item, while the Variant specifies the more detailed attributes of the product like the exact size/color of a\nT-shirt or the dimensions of a poster. Moreover, each item in the Printful Catalog has a unique Variant ID. When managing Sync Products or orders, you will need to specify the Variant ID of the specific blank item, hence you can use this API resource\nto find the needed Variant ID.\n\n
\nIt is critically important to always refer to the Variant IDs (NOT Product IDs) when creating products or orders. Mixing up and using the Product ID instead of the Variant ID can lead to an entirely different product created or item ordered. \nThe Product entity is only meant to allow of easier browsing of what Printful offers.\n
\n\nYou can also use this API resource to find out the types of print files a product can be configured for as well as the\nadditional price each print file would cost (e.g. the back print or inside label print for T-shirts). Moreover, some\nproduct types allow for additional options (e.g. embroidery type and thread colors) - these options are listed in the\nresponses as well.\n\n
\nPlease note that the current Catalog API does not reflect the discounted pricing available in the Printful subscription plans.\n
\n\n**Important**: Jewelry products are not supported via API.\n\n**Rate limiting**: For unauthenticated usages, up to 30 requests per 60 seconds. A 60 seconds lockout is applied if\nrequest count is exceeded.\n\n### Size guides\n\nThe [Get Product Size Guide](#operation/getProductSizeGuideById) endpoint will return size guide data for the selected\nproduct.\n\nThere are three types of size tables available, as described by the following table:\n\n| Table type | API name | Description |\n|-------------------------------|--------------------|---------------------------------------------------------------------------------------------|\n| Measure yourself | `measure_yourself` | Measurements of the product to measure the body provided by the supplier. |\n| Product measurements | `product_measure` | Measurements of the product provided by the supplier. |\n| International size conversion | `international` | International size conversion – e.g. US, EU or UK sizes corresponding to the product sizes. |\n\nNot each table type might be available for the selected product.\n\n[See examples](#tag/Examples/Catalog-API-examples/Using-size-guides)" }, { "name": "Products API", "description": "**The Products API resource lets you create, modify and delete products in a Printful store based on the Manual orders /\nAPI platform** (you can create such store by going to the Stores section at your Printful dashboard.)\n\n**Important**: Jewelry products are not supported via API.\n\n
\nTo configure products and variants at a Printful store based on Shopify, WooCommerce or another supported integration platform, please see Ecommerce Platform Sync API.\n
\n\nTo manage Warehouse products, please see Warehouse Products API.\n\n### The basics\n\nEach product in your Printful store must contain one or multiple variants (imagine multiple sizes or colors of the same\nt-shirt design). Furthermore, for each variant, you have to specify both a blank product variant from our Printful\nCatalog and a print file. These two properties together with price and External ID (more on that later) will allow the\nvariant to be purchasable. Please, see the following sections for more details. Finally, please note that for technical\nreasons a product in your Printful store is called a Sync Product and a variant of that product is called a Sync Variant. The maximum supported amount of Sync Variants a Sync Product can have is 100.\n\n### Assigning a blank product variant\nPrintful has a substantial catalog of blank products and variants, where each variant (e.g. size and color combination\nof a particular product) has a unique ID, which we call variant_id. You can browse through the catalog via Catalog API\nto find a specific variant_id. Moreover, when creating a Sync Product at your Printful store, each of its Sync Variants\nmust be associated with a variant_id from the Printful Catalog. Furthermore, to assign a specific variant_id to a\nspecific Sync Variant, simply add it to the HTTP request body (see examples at the specific endpoint).\n\n### Assigning a single print file\nThere are two ways to assign a print file to a Sync Variant. One is to specify the File ID if the file already exists in the File library of the authorized store;\n\n### Limitations\n\n**Important**: The Products API is not intended and will never support creating and managing products in external platforms such as Shopify, WooCommerce and others. For managing your products from external platforms please refer to [Ecommerce Platform Sync API](#tag/Ecommerce-Platform-Sync-API)\n\n```\n{\n ...\n \"files\": [\n {\n \"id\": 12345\n }\n ],\n ...\n}\n```\nThe second and most convenient method is to specify the file URL. If a file with the same URL already exists, it will be reused.\n\n```\n{\n ...\n \"files\": [\n {\n \"url\": \"http://example.com/t-shirts/123/front.pdf\"\n }\n ],\n ...\n}\n```\nMoreover, each Sync Variant has to be linked with one or multiple print files. The available file types for each product are available from the Printful Catalogue API. You can add one file for each type by specifying the type attribute. For the\ndefault type, this attribute can be skipped.\n\n```\n...\n\"files\":[\n {\n \"type\": \"default\",\n \"url\": \"http://example.com/t-shirts/123/front.pdf\"\n },\n {\n \"type\": \"back\"\n \"url\": \"http://example.com/t-shirts/123/back.pdf\"\n }\n],\n...\n```\nRemember that using additional files can increase the price of the item.\n\n### External ID\nWhen creating a Sync Product and/or Sync Variant you can specify an External ID, which you can then use as a reference when managing or even ordering the specific Sync Product or Sync Variant. In particular, when requesting a specific Sync Product\nand Sync Variant, you can use either the internal Printful ID or your External ID (prefixed with an @ symbol) at the request URL.\n\n### Native inside label\nPrintful previously allowed customers to upload a fully customized inside label. Since these labels had to contain specific information about fabric composition, manufacturing, etc. to meet the legal requirements, users usually encountered issues to\nget their labels printed.\n\nInside labels are printed on the inside of the garment and require the removal of the original manufacturer's tag. They're only available for apparel with tear-away labels. An inside label must include the country of manufacturing origin, original\ngarment size, and material information. To use our native label template you only need to upload a graphic (such as your brand's logo). The mandatory content will be generated and placed automatically.\n\n```\n...\n\"files\":[\n {\n \"type\": \"label_inside\",\n \"url\": \"http://example.com/logo/123/image.jpg\",\n \"options\": [{\n \"id\": \"template_type\",\n \"value\": \"native\"\n }]\n },\n],\n...\n```\nPrintful previously supported fully customized inside labels. These have now been deprecated. The ability to create orders with fully customized inside labels has been limited to only users who were actively using them in their stores before April\n2020. This feature is no longer accessible to new users.\n\n[See examples](#tag/Examples/Products-API-examples)\n" }, { "name": "Product Templates API", "description": "The Product Templates API resource lets you retrieve the product templates information.\n\n### External Product ID\n\nIn case of a single template retrieval it is possible to get it by the External Product ID. In order to do this, the ID needs to be prepended with the '@' character. Here are the examples of how to get the template data by the Template ID and by the External Product ID.\n\n```\nGET /product-templates/11001 - reference by Printful Template ID\nGET /product-templates/@988123 - reference by External ID\n```\n\n[See examples](#tag/Product-Templates-API)\n" }, { "name": "Orders API", "description": "The Orders API is the most important part of the Printful API - it allows you to create new orders and confirm them for\nfulfillment.\n\n**Important**: Jewelry products are not supported via API.\n\n### Order life cycle and statuses\n\nEach order will go through different states while being processed. The following order status types indicate those\nstates:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
draftThe order is created but is not yet submitted for fulfillment. You still can edit it and confirm later.
inreviewThe order is being reviewed. It's not possible to cancel the order at this point. It will be possible to cancel the order when the review process is finished.
pendingThe order has been submitted for fulfillment, but is not yet accepted for fulfillment. You can still cancel the order if you need.
failedOrder was submitted for fulfillment but was returned for review because of an error (problem with address, missing printfiles, charging has failed, etc.).
canceledThe order has been canceled and can no longer be processed. If the order was charged then the amount has been returned to your credit card.
inprocessThe order is being fulfilled and can no longer be cancelled or modified. Contact customer support if there are any issues with the order at this point.
onholdThe order has encountered a problem during the fulfillment that needs to be resolved together with Printful customer service before fulfillment can continue.
partialThe order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilledAll items have been shipped successfully
archivedThe order has been archived and hidden from the UI
\n\nTo sum up, the API allows you to create orders with status `draft` and then move them to state `pending` (both steps can\nbe done with a single action). You are only charged for orders that have been confirmed. If the order encounters a\nproblem after it has been submitted, then it is moved to the failed state so that the problem can be fixed and the order\ncan be resubmitted.\n\n### Asynchronous order cost calculation\n\nMost of the times, when you submit an order, we'll perform the cost calculation and return it in the response.\n\nHowever, we might not be able to calculate all the costs immediately, for example if the order contains a new advanced\nembroidery design. If that's the case, we'll automatically put your order on hold, calculate the order costs once it's\npossible, and then remove the order from hold.\n\nSuch an order will return to a draft status (even if it was created with the auto-confirm option) and will need to be\nconfirmed.\n\nYou can subscribe to the `order_remove_hold` event (see [Webhook API](#tag/Webhook-API)) to be notified when the order is removed from hold.\n\n### External ID\n\nExternal ID is an optional feature that allows you to link your Printful order with the Order ID from your system\nwithout the need to store additional data on your side. External ID can be up to 32 characters long and contain digits,\nLatin alphabet letters, dashes and underscores, however it is recommended to use integer numbers. Each order's External\nID must be unique within the store.\n\nTo use the External ID feature, you just add the `external_id` attribute when creating the order. Later, when you need\nto access the order through the API, you can reference it by both the Order ID and by External ID (if you prefix it with\nthe `@` symbol).\n\n```\nGET /orders/11001 - reference by Printful Order ID\nGET /orders/@988123 - reference by External ID\nGET /orders/@AA123123 - reference by External ID\n```\n\nYou can assign the `external_id` attribute to line items as well. In this case they have to be unique per order.\n\n### Specifying products\n\nThere are three general ways to specify a product’s variant when creating, updating or estimating an order:\n\n(A) **Using an existing product variant (sync variant) in your Printful store or warehouse.** To specify the existing\nproduct please use its `sync_variant_id` or `external_variant_id`, or `warehouse_product_variant_id`.\n\n[Example using Sync Variant ID](#tag/Examples/Orders-API-examples/Using-a-sync-variant)\n[Example using External Variant ID](#tag/Examples/Orders-API-examples/Using-sync-variant-with-external-ID)\n\n(B) **Using a Catalog API variant without adding a product to the store.** This method can be used when a Printful store\nhas no products in it. To construct a variant on-the-fly retrieve a specific `variant_id` from the\n[Catalog API](#tag/Catalog-API) together with print files and an additional options.\n\n[Example](#tag/Examples/Orders-API-examples/Using-a-catalog-variant)\n\n(C) **Using an existing template ID.** This method can be used when a Printful store has assigned templates without the\nneed to create products. To create an order please use the `product_template_id` and `variant_id` that will be added to\nthe order.\n\n[Example](#tag/Examples/Orders-API-examples/Using-a-product-template)\n\n### Adding print files\n\nThere are two ways to assign a print file to the item. One is to specify the File ID if the file already exists in the\nfile library of the authorized store:\n\n```\n...\n\"files\": [\n {\n \"id\": 12345\n },\n],\n...\n```\n\nThe second and the most convenient method is to specify the file URL. If a file with the same URL already exists, it will be reused.\n\n```\n...\n\"files\": [\n {\n \"url\": \"http://example.com/t-shirts/123/front.pdf\"\n },\n],\n...\n```\n\n### Specifying file position\n\nYou can specify the image position inside the print area by providing a position object.\n\nImportant
\n* Each print area has specific dimensions, by default Orders API will assume that your file has to stick to those limitations and not exceed them. In some cases you would want to position your file outside the print area - to be able to do so use the `limit_to_print_area` and set it to: `false`.\n* `limit_to_print_area` determines if the image can cross the print area border. If `limit_to_print_area` is set to `true` then the request will result in `400 Bad Request` with \"Invalid position\" in `error.message` once the image crosses the print area borders. If `limit_to_print_area` is set to `false` then it will be possible to place image partially or fully outside the print area.\n* The (0,0) point is always located in top left corner of the print area.\n\nSteps
\n1.Retrieve printfile dimensions [Printfiles](#operation/getPrintfiles)\n```\n...\n\"printfiles\":\n [\n {\n \"printfile_id\": 1,\n \"width\": 1800,\n \"height\": 2400,\n \"dpi\": 150,\n \"fill_mode\": \"fit\",\n \"can_rotate\": false\n }\n ],\n...\n```\n2.Specify file position for specific print placement while creating an order. Use `items` -> `files` -> `position` object as in the example:\n```\n...\n\"items\": [\n {\n \"variant_id\":4011,\n \"quantity\":\"1\",\n \"files\": [\n {\n \"type\": \"front\",\n \"url\": \"http://example.com/t-shirts/123/front.pdf\",\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0,\n \"limit_to_print_area\": true\n }\n }\n ]\n }\n]\n...\n```\n\n#### Example of positioning the 450x450 image on the front placement\n\n\n \n \n \n \n \n \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Position Mockup Payload
Top left \"Top \n\n```\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 450,\n \"height\": 450,\n \"top\": 0,\n \"left\": 0,\n \"limit_to_print_area\": true\n }\n```\n\n
Top middle \"Top \n\n```\n\"position\": {\n\"area_width\": 1800,\n\"area_height\": 2400,\n\"width\": 450,\n\"height\": 450,\n\"top\": 0,\n\"left\": 675,\n\"limit_to_print_area\": true\n}\n```\n\n
Top right \"Top \n\n```\n\"position\": {\n\"area_width\": 1800,\n\"area_height\": 2400,\n\"width\": 450,\n\"height\": 450,\n\"top\": 0,\n\"left\": 1350,\n\"limit_to_print_area\": true\n}\n```\n\n
Middle \"Top \n\n```\n\"position\": {\n\"area_width\": 1800,\n\"area_height\": 2400,\n\"width\": 450,\n\"height\": 450,\n\"top\": 975,\n\"left\": 675,\n\"limit_to_print_area\": true\n}\n```\n\n
Bottom left \"Top \n\n```\n\"position\": {\n\"area_width\": 1800,\n\"area_height\": 2400,\n\"width\": 450,\n\"height\": 450,\n\"top\": 1950,\n\"left\": 0,\n\"limit_to_print_area\": true\n}\n```\n\n
Bottom middle \"Top \n\n```\n\"position\": {\n\"area_width\": 1800,\n\"area_height\": 2400,\n\"width\": 450,\n\"height\": 450,\n\"top\": 1950,\n\"left\": 675,\n\"limit_to_print_area\": true\n}\n```\n\n
Bottom right \"Top \n\n```\n\"position\": {\n\"area_width\": 1800,\n\"area_height\": 2400,\n\"width\": 450,\n\"height\": 450,\n\"top\": 1950,\n\"left\": 1350,\n\"limit_to_print_area\": true\n}\n```\n\n
\n\n### Specifying multiple files per item\n\nEach item in the order has to be linked with one or multiple files. The available file types for each product are\navailable from the [Catalog API](#tag/Catalog-API).\n\nYou can add one file for each type by specifying the `type` attribute. For the `default` type, this attribute can be\nskipped.\n\n```\n...\n\"files\":[\n\t{\n\t\t\"type\": \"default\",\n\t\t\"url\": \"http://example.com/t-shirts/123/front.pdf\"\n\t},\n\t{\n\t\t\"type\": \"back\"\n\t\t\"url\": \"http://example.com/t-shirts/123/back.pdf\"\n\t},\n\t{\n\t\t\"type\": \"preview\"\n\t\t\"url\": \"http://example.com/t-shirts/123/preview.png\"\n\t}\n],\n...\n```\n\nRemember that using additional files can increase the price of the item.\n\n### Creating orders from a template\n\nOrders API allows also creating orders based on the product template created in the Printful account without the need to\nadd the product to the Printful store.\n\nTo retrieve available templates for your account please use the\n[Products Templates API](#tag/Product-Templates-API).\n\nTo create an order from a template you need to specify a variant or variants that will be added to the order. It is\npossible to use multiple templates with different variants in one request. To achieve that please use the `items` object\nbelow:\n\n```\n ...\n \"items\": [\n {\n \"variant_id\": 4012,\n \"quantity\": 1,\n \"product_template_id\": 123456789\n },\n {\n \"variant_id\": 1,\n \"quantity\": 2,\n \"product_template_id\": 11235813\n },\n ]\n ...\n```\n\n**Important note**: you can only create orders from templates for variant IDs from the Catalog API.\n\nMore examples are available [here](#tag/Examples/Orders-API-examples/Using-a-product-template).\n\n### Retail costs\n\nPrintful allows you to specify your retail costs for the order so that the packing slip for international orders can\ncontain your correct retail prices. To enable retail costs, each item in the order has to contain the `retail_price`\nattribute. You can also specify a custom discount sum, shipping costs and taxes in the `retail_costs` object when\ncreating the order. If the retail costs are missing, the packing slip will contain the Printful prices instead.\n\n### Native inside label\n\nPrintful previously allowed customers to upload a fully customized inside label. Since these labels had to contain\nspecific information about fabric composition, manufacturing, etc. to meet the legal requirements, users usually\nencountered issues to get their labels printed.\n\nInside labels are printed on the inside of the garment and require the removal of the original manufacturer's tag.\nThey're only available for apparel with tear-away labels. An inside label must include the country of manufacturing\norigin, original garment size, and material information. To use our native label template you only need to upload a\ngraphic (such as your brand's logo). The mandatory content will be generated and placed automatically.\n\n```\n...\n\"files\":[\n {\n \"type\": \"label_inside\",\n \"url\": \"http://example.com/logo/123/image.jpg\",\n \"options\": [{\n \"id\": \"template_type\",\n \"value\": \"native\"\n }]\n },\n],\n...\n```\n\nPrintful previously supported fully customized inside labels. These have now been deprecated. The ability to create orders with fully customized inside labels has been limited to only users who were actively using them in their stores before April 2020. This feature is no longer accessible to new users.\n\n### Ordering embroidery products\n\nEmbroidery is a technique which uses colored threads, sewn into a product, to recreate provided design. In order to use embroidery technique you first need to check if selected product support embroidery technique.\n\nIn order to do that you need to use [Catalog API](#tag/Catalog-API) to determine if the selected product or variant contains `EMBROIDERY` technique.\n```\n\"techniques\": [\n {\n \"key\": \"EMBROIDERY\",\n \"display_name\": \"Embroidery\",\n \"is_default\": true\n }\n ]\n```\nAfter that you need to also get list of available embroidery placements. Those are listed under `file` property with `embroidery_` prefix. You can get list of all available placements in [Placements](#tag/Common/Placements).\n\n
\n Example of file property\n\n```\n\"files\": [\n {\n \"id\": \"default\",\n \"type\": \"embroidery_front\",\n \"title\": \"Front\",\n \"additional_price\": null\n },\n {\n \"id\": \"back\",\n \"type\": \"embroidery_back\",\n \"title\": \"Back\",\n \"additional_price\": \"3.75\"\n },\n {\n \"id\": \"left\",\n \"type\": \"embroidery_left\",\n \"title\": \"Left side\",\n \"additional_price\": \"3.75\"\n },\n {\n \"id\": \"right\",\n \"type\": \"embroidery_right\",\n \"title\": \"Right side\",\n \"additional_price\": \"3.75\"\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null\n }\n ]\n```\n\n
\n\nTo create an order using embroidery technique you can:\n\n- Provide thread colors manually [See example](#tag/Common/Embroidery/Manually-defining-thread-colors)\n- Use automatic thread color detection [See example](#tag/Common/Embroidery/Automatic-thread-color)\n\nFinally, you can make an order using embroidery\ntechnique [See example](#tag/Examples/Orders-API-examples/Using-embroidery-products). Depending on the placement that you've\nused you need to specify the correct [thread color option](#tag/Common/Options).\n\n### Packing slip\n\nThe packing slip fields can be configured at the store level and overridden for a specific order.\n\nThe packing slip settings can be found in Dashboard at **Settings > Stores > Branding > Packing slip section**.\n\nTo override the packing slip settings for the order, you can use `packing_slip` or `gift` fields.\n\nBelow you can find an example or a packing slip for a shipment with explained fields.\n\n![packing slip](images/sample_packing_slip.png)\n\nField annotations:\n\n* **(1)** Barcode unique for the shipment.\n* **(2)** Store logo defined in the store settings or overridden using `packing_slip.logo_url` field. The provided image is converted to a grayscale/1-bit monochrome image.\n* **(3)** The date of the shipment.\n* **(4)** Packing slip number consisting of order and shipment IDs in Printful database, divided with a hyphen.\n* **(5)** The country from which the shipment is made. If the recipient is in the United States, this field will be\n absent.\n* **(6)** Recipient address with phone, without email address.\n* **(7)** Store name. This can be overridden using `packing_slip.store_name`.\n* **(8)** The address to which the shipment should be returned. By default it will be a Printful’s return address, but\n you can set your own address in the store settings (**Settings > Stores > Returns > Return address section**).\n* **(9)** The customer service phone number defined in the store settings or overridden using `packing_slip.phone`\n field.\n* **(10)** The customer service email address defined in the store settings or overridden using `packing_slip.email`\n field.\n* **(11)** Gift message. This is only present if the `gift` field was provided in the order request.\n* **(12)** The order creation date.\n* **(13)** Printful Order ID which can be overridden using `packing_slip.custom_order_id` field.\n* **(14)** The list of order items with quantities. The items’ display names are localized, using the recipient’s\n country and include variant information such as color and size e.g. „Unisex Staple T-Shirt | Bella + Canvas 3001 (\n Lilac / M)”.\n* **(15)** The packing slip message defined in the store settings or overridden using `packing_slip.message` field.\n\n### More Orders API examples\n\nSee the [examples section](#tag/Examples/Orders-API-examples) for more sample requests on how Orders API can be used in\ndifferent scenarios.\n\n### Custom border color option\n\nStickers can have a different border color which can be set by using the `thread_colors_outline` option.\nThis option is available in `options` for stickers. To showcase the usage we will use the order flow\nwhich will create order with a sticker that will have a red border color:\n\nEndpoint `POST https://api.printful.com/orders`\n
\n Request body\n\n```\n{\n \"shipping\": \"STANDARD\",\n \"recipient\": {\n \"name\": \"John Smith\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"country_code\": \"US\",\n \"state_code\": \"CA\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 10163,\n \"files\": [\n {\n \"type\": \"default\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ],\n \"options\": [\n {\n \"id\": \"custom_border_color\",\n \"value\": \"#FF0000\"\n }\n ]\n }\n ]\n}\n```\n\n
" }, { "name": "File Library API", "description": "To avoid the need to upload every file again when the same item is ordered,\nyour print files are stored in the File Library and can be reused.\n\nYou can use this API to directly add files to the library, and later use\nFile IDs when creating orders. However, the more convenient way is to specify\nthe files by URL at the same time the order is created.\n\n
\nMost probably you will never need to use this API - just specify the file URL\nwhen creating orders and the files will be added automatically.\n
\n\nFile processing can be very time-consuming, so they are processed\nasynchronously. After you add a file, it is saved with the status\n`waiting` and downloaded and processed later. Afterward, the status\nis changed to `ok` if the file was loaded successfully and was a valid\nimage file or `failed` if the process did not succeed. Some file\nmetadata fields like dimensions and resolution are only filled in\nafter the file has been processed.\n\nIf an order with a file has been confirmed before the file was processed,\nand the file turns out to be invalid, then the order is reverted to a failed\nstate and needs to be corrected and confirmed again.\n\nIf you try to add a file that has an identical URL to an already\nexisting file, then no new file is created, and the system returns\nthe old one without refreshing its contents.\n\n
\nRemember
\nIf you have changed the original, make sure that the URL is changed as well\nfor future orders, otherwise the old version will be reused.\n
\n\nYou can add a “last modified” timestamp to the end of the URL to ensure\nthat the URL is different for changed files.\n\nFiles that are added through the API can be set not to show up in the\nFile library on the web,\njust set the visible attribute to false when creating them.\n\n**Caution: API endpoint \"Get list of files\" (/files) is removed and can no longer be used. Calling this endpoint will return a HTTP 410 (Gone) response.**\n" }, { "name": "Shipping Rate API", "description": "The Shipping rate API calculates the shipping rates for an order based on the recipient's location and the contents of\nthe order.\n\nThe returned shipping rate ID can be used to specify the shipping method when creating an order.\n\nSee [Country/State Code API](#tag/CountryState-Code-API) for information about the Country codes.\n\nSee [Catalog API](#tag/Catalog-API) for information about the Variant IDs.\n\n
\n

Note: The shipping rates endpoints are meant to be called only right before placing an order to display\navailable shipping rates and methods.

\n\nDynamic shipping rates can change even in the span of one hour because it takes live facility and carrier information\ninto account. Different rates may be calculated for different products, quantities and recipient data.\n\nEven daily downloads of this data, reused only for identical orders, can result in mismatches between the displayed\nrates and the charged rates, potentially resulting in customer dissatisfaction.\n\nA CSV file containing flat rates data for different categories of products may be downloaded\nfrom https://www.printful.com/shipping-rates-report/shipping-rates-report/download and hardcoded to reduce the shipping\nrate volume massively if you use flat rate shipping.\n
\n\n**Rate limiting:** The default rate limit is 120 requests per 60 seconds.\n\n
\n Warning: If the summary item quantity count exceeds 100 then the rate limit\nis changed to 5 requests per 60 seconds.\n
\n\nA 60 seconds lockout is applied if request count is exceeded." }, { "name": "Ecommerce Platform Sync API", "description": "The ecommerce platform sync API allows you to automatically assign Printful\nproducts and print files to the products in your online store (Shopify, Woocommerce, etc.)\nthat is linked to Printful.\n\n### Sync Products & Sync Variants explained\n\nEach product in your store can contain one or multiple variants\n(some ecommerce platforms would call these options) that the customer can purchase\n(imagine multiple sizes or colors of the same t-shirt design). When you link your\necommerce store to Printful, we create a copy of your product and variant lists\non our side - we call it Sync Products and Sync Variants.\n\nSimilar to your store, products that are sold by Printful also consist of multiple variants.\nEach t-shirt model is available in many sizes and colors.\n\n![Image](images/variants.png?center)\n\nThe purpose of Sync Variants is to let you link each variant from your store that\nwill be fulfilled by Printful with a design file(s) and specific variant from Printful\nproduct catalogue. When synced products are ordered, we'll know which Printful product\nneeds to be printed, and the order is imported into Printful for fulfillment.\n\nYou can configure each Sync Variant in the Printful Dashboard manually. However,\nthat can be quite a tedious and repetitive task if your store sells hundreds of products.\nThis API is designed to help you automate this process.\n\n
\nRemember
\nProduct data is not imported to Printful immediately after the product is \ncreated/updated in your ecommerce platform. Depending on the platform, it can take from\na couple of seconds up to a few hours for the products to be available on Printful.\nBefore the products are imported, you will not be able to update product information \nthrough this API.\n
\n\n### External ID\n\nExternal ID is a feature that allows you to reference Sync Products and Sync Variants\nby using the ID from your store.\n\nWhen requesting Sync Products and Sync Variants, you can use both the Printful ID\nand your External ID (if you prefix it with the `@` symbol).\n\n```\nGET /sync/products/11001 - reference by Printful Sync Product ID\nGET /sync/products/@988123 - reference by Shopify (or other platform's) Product ID\nGET /sync/variant/123456 - reference by Printful Sync Variant ID\nGET /sync/variant/@123123 - reference by Shopify (or other platform's) Variant ID\n```\n\n### Specifying products\n\nTo specify the exact variant of the product, you have to use the `variant_id` attribute of the order item. Each\navailable unique item (including size/color) has its own Variant ID that can be acquired through\nthe [Catalog API](#tag/Catalog-API).\n\n### Adding print files\n\nThere are two ways to assign a print file to the item.\nOne is to specify the File ID if the file already exists in the file library of the authorized store:\n\n```json\n...\n\"files\":\n [\n {\n \"id\": 12345\n },\n ],\n...\n```\n\nSecond, and the most convenient method is to specify the file URL.\nIf a file with the same URL already exists, it will be reused:\n\n```json\n...\n\"files\":\n [\n {\n \"url\": \"http://example.com/t-shirts/123/front.pdf\"\n },\n ],\n...\n```\n\n### Specifying multiple files per item\n\nEach item in the order has to be linked with one or multiple files. The available file types for each product are\navailable from the [Catalog API](#tag/Catalog-API).\n\nYou can add one file for each type by specifying the `type` attribute. For the `default` type, this attribute can be\nskipped.\n\n```json\n...\n\"files\":\n [\n {\n \"type\": \"default\",\n \"url\": \"http://example.com/t-shirts/123/front.pdf\"\n },\n {\n \"type\": \"back\",\n \"url\": \"http://example.com/t-shirts/123/back.pdf\"\n }\n ],\n...\n```\n\nRemember that using additional files can increase the price of the item.\n\n[See examples](#tag/Examples/Ecommerce-Platform-Sync-API-examples/Modify-a-Sync-Variant)\n" }, { "name": "Country/State Code API", "description": "To create an order, you have to use country and state codes to specify the recipient address. Both country code and state code are mandatory for orders to the USA, Canada and Australia. For other countries only the country code is needed to create an order.\n\nCountry codes are based on the ISO 3166-1 alpha-2 standard and are two letters long.\n\nState codes are based on the ISO 3166-2 standard by omitting the country code part of the code and are used only for the USA, Canada, Japan and Australia.\n\nAll state/country codes that Printful accepts can be listed by this API.\n" }, { "name": "Tax Rate API", "description": " " }, { "name": "Webhook API", "description": "Webhooks are an API feature that allows your system to receive notifications about certain events.\n\nWhen an event occurs, the Printful server ([Webhook Simulator](https://www.printful.com/api/webhook-simulator))\nwill make a POST request to your defined\nURL that will contain a JSON object in the request body.\nYour server has to respond with HTTP status `2xx OK`,\notherwise, the request will be retried in increasing intervals\n(after 1, 4, 16, 64, 256 and 1024 minutes).\n\nThe JSON object will always contain these attributes:\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
typestringEvent type
createdtimestampEvent time
retriesintegerNumber of previous attempts to deliver this webhook event
storeintegerID of the store that the event occured to
dataObjectAdditional data, depending on the event type
\n\nPlease use [Webhook Simulator](https://www.printful.com/api/webhook-simulator) to test your webhook event receiver.\n\nTo set up webhooks, use API requests described below:" }, { "name": "Store Information API", "description": " " }, { "name": "Mockup Generator API", "description": "To generate mockups, first, you need to decide on which products you want them. API methods on retrieving products and\nvariants can be found in the [Catalog API](#tag/Catalog-API).\n\n**Note**: Remember to distinguish the difference between a product id and a variant id. Some API endpoints require an id\nfrom a variant and some from a product.\n\n**Important**: Jewelry products are not supported via API.\n\n### Print files\n\nA print file defines resolution which should be used to create a mockup or to submit an actual order.\n\nInformation about product variant print files can be retrieved from the [print file endpoint](#operation/getPrintfiles).\n\nFor example, a 10×10 poster requires a 1500×1500 pixel print file to produce a 150 DPI print. You can use higher\nresolution files to achieve a better result, but keep the side aspect ratio the same as the defined for the print file.\nThat means, if you use a 3000×3000 pixel file, it will produce a 300 DPI print. But if you use a 3000×1500 pixel file (\ndifferent aspect ratio) on a 10×10 poster, some cropping will occur. Print file's `fill_mode` parameter defines if\ncropping will happen, or the file will be fitted on the resulting print area of the product.\n\nSome print files can be rotated. `can_rotate` field defines this feature. This mostly applies to wall art products and\nshould be used if you want to generate a horizontal or a vertical product mockup.\n\nWall art print files are defined horizontally. If you wish to create a vertical mockup, you can rotate the file's print\nfile and the generated mockup will be in the given orientation. For example, 16×12 poster print file is 2400×1800 pixels\nwhich generate it horizontally. If you wish to get a vertical mockup, you create the print file as 1800×2400 pixels. The\nsame strategy applies when you submit an order.\n\nPrint files are often re-used for multiple variants and products. For example, a 14×14 poster uses the same print file\nas a framed poster. Most of the t-shirt front prints use the same print file too.\n\n**Note**: When you generate mockups there is no need to provide a full-sized print file. Mockups are generated up to\n2000px wide, so you can downscale your print file to 2000px. This will reduce the processing time on your and Printful's\nside. Print file image file size limit: 50MB.\n\n### Mockup generation\n\nMockup generation requires some time, that is why it cannot happen in real-time.\n\nWhen you request a mockup to be generated, a task is created and you receive the task key which can then be used to\nretrieve the generated mockup list. We cannot guarantee that after a certain time the mockups will be generated, so you\nwill have to check frequently if the task is done. The first request for a result should not be sooner than 10 seconds.\nSo plan that the generation task will be done in two steps - creating a task and the checking with intervals if the task\nis ready.\n\n
\nImportant
\nURLs to mockup images are temporary, they will expire after 72h, so you have to store them on your\nserver.\n
\n\n### Process flow\n\n1. Decide which product variants you want to generate.\n\n2. Retrieve the list of print files for chosen product and variants. Use the variant print file mappings to determine\n which print file you need to generate for specific placement on a specific product's variant.\n\n3. Upload your file to a public URL that matches the print file size ratio (or provide positions for the generation\n request)\n\n4. Create a mockup generation task and store the task key.\n\n5. Use the task key to check if the task is completed. If still pending, repeat after an interval.\n\n6. When the task is done, download and store mockups on your server. Mockup URLs are temporary and will be removed after\n a day.\n\n### Available techniques\n\nThe `/mockup-generator/printfiles/{id}` and `/mockup-generator/templates/{id}` endpoint accept `technique` parameter.\n\nThe following table presents the available values of this parameter.\n\n| Value | Description |\n|---------------|-----------------------|\n| `DIGITAL` | Digital printing |\n| `CUT-SEW` | Cut & sew sublimation |\n| `UV` | UV printing |\n| `EMBROIDERY` | Embroidery |\n| `SUBLIMATION` | Sublimation |\n| `ENGRAVING` | Engraving |\n| `DTG` | DTG printing |\n\n### Usage example\n\nLet's take an example. You want to offer users to design of their t-shirt.\n\nWe'll pick this shirt as an example\n[Bella + Canvas 3001 Unisex T-shirt](https://www.printful.com/custom/mens/t-shirts/unisex-staple-t-shirt-bella-canvas-3001)\n\nIts product id is `71`.\n\nLet's fetch some variants available for this shirt:\n`https://api.printful.com/products/71`\n\nWe'll choose a white and black shirt in M, L, XL sizes. Respective variant ids:\n`4012`, `4013`, `4014`, `4017`, `4018` and `4019`.\n\nNext, we need to get the print file sizes for these variants:\n`https://api.printful.com/mockup-generator/printfiles/71`\n\nWe see that there are two placements available for this product - `front` and `back`. Posters, for example, will only\nhave one placement called `default`.\n\nBy looking up our picked variant ids, we see that they all use the same print file for back and front prints:\n\n```json\n{\n \"product_id\": 71,\n \"available_placements\": {\n \"front\": \"Front print\",\n \"back\": \"Back print\",\n \"label_outside\": \"Outside label\"\n },\n \"printfiles\": [\n {\n \"printfile_id\": 1,\n \"width\": 1800,\n \"height\": 2400,\n \"dpi\": 150,\n \"fill_mode\": \"fit\",\n \"can_rotate\": false\n }\n ],\n \"variant_printfiles\": [\n {\n \"variant_id\": 4012,\n \"placements\": {\n \"front\": 1,\n \"back\": 1\n }\n }\n ]\n}\n```\n\n- `dpi` For given width and height, this is the resulting DPI on the actual product.\n\n- `fill_mode` Possible values: \"fit\" or \"cover\". Indicates in what mode mockups will be generated.\n\n- `can_rotate` Posters, for example, allow rotation. If you pass the image in horizontal positions.\n\n- `placements.front` Printfile id.\n\nWe can see that the full print file size is 1800×2400 for back and front prints for chosen variants.\n\nWhen we know the size of the print file, we need to calculate the positions. Position values are relative here, image\nsize does not have to match the width and height of positions. When mockup is generated we will fit the position area\ninside the print area or will cover it, depending on the print file `fill_mode` value.\n\nPositions given below would result in a square image centered vertically within the print area.\n\n```json\n{\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n}\n```\n\n- `area_width` Relative width of the print area.\n\n- `area_height` Relative height of the print area.\n\n- `width` Relative width of your image.\n\n- `height` Relative height of your image.\n\n- `top` Relative image top offset within the area.\n\n- `left` Relative image left offset within the area.\n\n
\nImportant
\nFor posters, canvas, and other products which print files allow rotation (can_rotate value in print file response) you\ncan flip width and height to create a product mockup that is horizontal or vertical.\n
\n\nOnce we have calculated the positions, we can perform the actual mockup generation using\nthe [mockup generator endpoint](#operation/createGeneratorTask):\n`POST` to `https://api.printful.com/mockup-generator/create-task/71` with body parameters:\n\n```json\n{\n \"variant_ids\": [\n 4012,\n 4013,\n 4014,\n 4017,\n 4018,\n 4019\n ],\n \"format\": \"jpg\",\n \"files\": [\n {\n \"placement\": \"front\",\n \"image_url\": \"http://your-site/path-to-front-printfile.jpg\",\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n }\n },\n {\n \"placement\": \"back\",\n \"image_url\": \"http://your-site/path-to-back-printfile.jpg\",\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n }\n }\n ]\n}\n```\n\nIn response, you will receive the task key and current task status:\n\n```json\n{\n \"task_key\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n \"status\": \"pending\"\n}\n```\n\nAfter an interval of a few seconds, you can try to check for the result by calling a `GET` request\non `https://api.printful.com/mockup-generator/task?task_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`\nIf the task is completed, the response will be like this:\n\n```json\n{\n \"task_key\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n \"status\": \"completed\",\n \"mockups\": [\n {\n \"variant_ids\": [\n 4011,\n 4012,\n 4013\n ],\n \"placement\": \"front\",\n \"mockup_url\": \"https://url-to/front-mockup.png\"\n },\n {\n \"variant_ids\": [\n 4011,\n 4012,\n 4013\n ],\n \"placement\": \"back\",\n \"mockup_url\": \"https://url-to/back-mockup.png\"\n },\n {\n \"variant_ids\": [\n 4016,\n 4017,\n 4018\n ],\n \"placement\": \"front\",\n \"mockup_url\": \"https://url-to/front-mockup.png\"\n },\n {\n \"variant_ids\": [\n 4016,\n 4017,\n 4018\n ],\n \"placement\": \"back\",\n \"mockup_url\": \"https://url-to/back-mockup.png\"\n }\n ]\n}\n```\n\nAt this point, you just have to download the mockup URLs and store them on your server and you're good to go!\n\n### Layout templates\n\nIf you wish to build your mockup generator UI, this is the place to start. Using\nthe [layout template endpoint](#operation/getPrintfiles)\nyou can get template images and positions necessary to create a tool where your users can position their files on.\n\nIf you want to create a mug generator, for example, you call the endpoint `/mockup-generator/templates/19` with mug\nproduct ID. By looking at the variant mapping field, we can determine that for variant `1320` 11oz mug we have to use\nthe template with ID `919`. This is what template structure looks like:\n\n```json\n{\n \"template_id\": 919,\n \"image_url\": \"https://www.printful.com/files/generator/40/11oz_template.png\",\n \"background_url\": null,\n \"background_color\": null,\n \"printfile_id\": 43,\n \"template_width\": 560,\n \"template_height\": 295,\n \"print_area_width\": 520,\n \"print_area_height\": 202,\n \"print_area_top\": 18,\n \"print_area_left\": 20,\n \"is_template_on_front\": true\n}\n```\n\n- `printfile_id` We can retrieve the actual printfile size from the printfiles endpoint.\n\n- `template_width` This is the main container width, pixels.\n\n- `template_height` Main container height.\n\n- `print_area_width` Inner area where positioning happens.\n\n- `print_area_height` Inner area.\n\n- `print_area_top` Offset from the main container.\n\n- `print_area_left` Offset from the main container.\n\n- `is_template_on_front` This indicates if we should show the user image below or above the template image.\n\nGiven this information, we can create a simple HTML markup:\n\n```html\n\n
\n
\n \"Printful\n
\n
\n
\n```\n\nWhich would look like this in the browser:\n\n
\n
\n \"Printful\n
\n
\n
\n\nTo generate mockups with positions above, we perform a `POST` request\nto `https://api.printful.com/mockup-generator/create-task/19` with body parameters:\n\n```json\n{\n \"variant_ids\": [\n 1320\n ],\n \"format\": \"jpg\",\n \"files\": [\n {\n \"placement\": \"default\",\n \"image_url\": \"https://www.printful.test/static/images/layout/logo-printful.png\",\n \"position\": {\n \"area_width\": 520,\n \"area_height\": 202,\n \"width\": 140,\n \"height\": 63,\n \"top\": 77,\n \"left\": 43\n }\n }\n ]\n}\n```\n\n- `area_width` Value of print_area_width in the template.\n- `area_height` Value of print_area_height in the template.\n- `width` Image width.\n- `height` Image height.\n- `top` Image top offset in area.\n- `left` Image left offset in area.\n\n\n### Choosing mockup styles\n\nTo choose which mockup styles to generate, you have to specify `options` and `option_groups` parameters in the request. If these parameters are not present in the request, the system will generate the first available mockup. If you are not planning to utilize all available mockups, it is advised to limit the requested mockups. Not limiting requested mockups will cause bigger task processing times and overall resource waste.\n\nTo find available `options` and `option_groups` for a given product, you have to use `/mockup-generator/printfiles/{id}` endpoint and search for `options` and `option_groups` fields in the response. See examples below.\n\n```\n{\n \"variant_ids\": [4021],\n \"format\": \"png\",\n \"option_groups\": [\"Flat\"],\n \"options\": [\"Front\"],\n \"files\": [\n {\n \"placement\": \"front\",\n \"image_url\": \"https://www.printful.com/static/images/layout/logo-printful.png\"\n }\n ]\n}\n```\n\n### Using lifelike effect\n\nLifelike is a feature that simulates how dark designs will look over dark colour products and is only used in mockup generation. For that, an extra file with special effect is created for each placement.\n\n```\n{\n \"variant_ids\": [4018],\n \"format\": \"png\",\n \"product_options\": {\n \"lifelike\": true\n },\n \"files\": [\n {\n \"placement\": \"front\",\n \"image_url\": \"https://www.printful.com/static/images/layout/logo-printful.png\"\n }\n ]\n}\n```\n\n| Mockup without lifelike | Mockup with lifelike |\n|------------------------------------------------|---------------------------------------------|\n| ![Image](images/lifelike/without_lifelike.png) | ![Image](images/lifelike/with_lifelike.png) |\n" }, { "name": "Warehouse Products API", "description": "Warehouse Products API" }, { "name": "Reports API", "description": "The Reports API lets you retrieve reports like the statistics related to the orders fulfilled for your stores.\n" }, { "name": "Approval Sheets API", "description": "Approval Sheets API" }, { "name": "Common", "description": "# Options\nOptions allow for additional modification of how product will look.\n\n
\n List of currently available thread color options\n\n|
Option
|
Placement
| Description |\n|---------------------------------------|------------------------------------------|-----------------------------------------------------------|\n| `thread_colors` | `embroidery_front` | Thread colors for embroidery front placement |\n| `thread_colors_back` | `embroidery_back` | Thread colors for embroidery back placement |\n| `thread_colors_right` | `embroidery_right` | Thread colors for embroidery right placement |\n| `thread_colors_left` | `embroidery_left` | Thread colors for embroidery left placement |\n| `thread_colors_apparel` | `embroidery_apparel_front` | Thread colors for embroidery apparel front placement |\n| `thread_colors_apparel_back` | `embroidery_apparel_back` | Thread colors for embroidery apparel back placement |\n| `thread_colors_chest_center` | `embroidery_chest_center` | Thread colors for embroidery chest center placement |\n| `thread_colors_large_center` | `embroidery_large_center` | Thread colors for embroidery large center placement |\n| `thread_colors_large_corner_right` | `embroidery_large_corner_right` | Thread colors for embroidery large corner right placement |\n| `thread_colors_chest_left` | `embroidery_chest_left` | Thread colors for embroidery chest left placement |\n| `thread_colors_corner_left` | `embroidery_corner_left` | Thread colors for embroidery corner left placement |\n| `thread_colors_chest_top_left` | `embroidery_chest_top_left` | Thread colors for embroidery chest top left placement |\n| `thread_colors_corner_right` | `embroidery_corner_right` | Thread colors for embroidery corner right placement |\n| `thread_colors_outside_left` | `embroidery_outside_left` | Thread colors for embroidery outside left placement |\n| `thread_colors_outside_right` | `embroidery_outside_right` | Thread colors for embroidery outside right placement |\n| `thread_colors_inside_left` | `embroidery_inside_left` | Thread colors for embroidery inside left placement |\n| `thread_colors_inside_right` | `embroidery_inside_right` | Thread colors for embroidery inside right placement |\n| `thread_colors_patch_front` | `embroidery_patch_front` | Thread colors for embroidery patch front placement |\n| `thread_colors_sleeve_left_top` | `embroidery_sleeve_left_top` | Thread colors for embroidery sleeve left top placement |\n| `thread_colors_sleeve_right_top` | `embroidery_sleeve_right_top` | Thread colors for embroidery sleeve right top placement |\n| `thread_colors_wrist_left` | `embroidery_wrist_left` | Thread colors for embroidery wrist left placement |\n| `thread_colors_wrist_right` | `embroidery_wrist_right` | Thread colors for embroidery wrist right placement |\n| `thread_colors_outline` | Not applicable (Embroidery patches) | Thread colors for embroidery patch outline |\n\n
\n\n
\n List of currently available Text thread color options\n\n|
Option
|
Placement
| Description |\n|-----------------------------------------|------------------------------------------|----------------------------------------------------------------|\n| `text_thread_colors` | `embroidery_front` | Text thread colors for embroidery front placement |\n| `text_thread_colors_back` | `embroidery_back` | Text thread colors for embroidery back placement |\n| `text_thread_colors_right` | `embroidery_right` | Text thread colors for embroidery right placement |\n| `text_thread_colors_left` | `embroidery_left` | Text thread colors for embroidery left placement |\n| `text_thread_colors_apparel` | `embroidery_apparel_front` | Text thread colors for embroidery apparel front placement |\n| `text_thread_colors_apparel_back` | `embroidery_apparel_back` | Text thread colors for embroidery apparel back placement |\n| `text_thread_colors_chest_center` | `embroidery_chest_center` | Text thread colors for embroidery chest center placement |\n| `text_thread_colors_large_center` | `embroidery_large_center` | Text thread colors for embroidery large center placement |\n| `text_thread_colors_large_corner_right` | `embroidery_large_corner_right` | Text thread colors for embroidery large corner right placement |\n| `text_thread_colors_chest_left` | `embroidery_chest_left` | Text thread colors for embroidery chest left placement |\n| `text_thread_colors_corner_left` | `embroidery_corner_left` | Text thread colors for embroidery corner left placement |\n| `text_thread_colors_chest_top_left` | `embroidery_chest_top_left` | Text thread colors for embroidery chest top left placement |\n| `text_thread_colors_corner_right` | `embroidery_corner_right` | Text thread colors for embroidery corner right placement |\n| `text_thread_colors_outside_left` | `embroidery_outside_left` | Text thread colors for embroidery outside left placement |\n| `text_thread_colors_outside_right` | `embroidery_outside_right` | Text thread colors for embroidery outside right placement |\n| `text_thread_colors_inside_left` | `embroidery_inside_left` | Text thread colors for embroidery inside left placement |\n| `text_thread_colors_inside_right` | `embroidery_inside_right` | Text thread colors for embroidery inside right placement |\n| `text_thread_colors_patch_front` | `embroidery_patch_front` | Text thread colors for embroidery patch front placement |\n| `text_thread_colors_sleeve_left_top` | `embroidery_sleeve_left_top` | Text thread colors for embroidery sleeve left top placement |\n| `text_thread_colors_sleeve_right_top` | `embroidery_sleeve_right_top` | Text thread colors for embroidery sleeve right top placement |\n| `text_thread_colors_wrist_left` | `embroidery_wrist_left` | Text thread colors for embroidery wrist left placement |\n| `text_thread_colors_wrist_right` | `embroidery_wrist_right` | Text thread colors for embroidery wrist right placement |\n\n
\n\n
\n List of currently available other options\n\n|
Option
|
Placement
| Description |\n|---------------------------------------|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `thread_colors_3d` | Not applicable | 3D Puff thread colors |\n| `embroidery_type` | Not applicable | Type of embroidery technique (flat, 3d, both) |\n| `notes` | Not applicable | This box is for you to enter specific instructions about your print files or to warn us that the graphic may not perfectly match the mock-up. If you would like our graphics department to edit anything you can also notate those details in this box and someone from our team will contact you with an editing quote. |\n| `stitch_color` | Not applicable | Zipper & Stitch color |\n| `inside_pocket` | Not applicable | Should inside pocket be added |\n| `lifelike` | Not applicable | Adds \"washed out\" effect to the generated mockups |\n\n
\n\n
\n List of currently available file options\n\n|
Option
|
Placement
| Description |\n|---------------------------------------|------------------------------------------|--------------------------------------------------------------------------------------------|\n| `full_color` | Not applicable | Allows you to embroider multi-color, gradient, or simple designs with no color limitations |\n| `auto_thread_color` | Not applicable | Automatically match available thread colors to provided image | \n\n
\n\n# Placements\n\n
\n Complete list of every placement\n\n|
Placement
| Description |\n|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|\n| `default` | Default placement is different for every product. For example for T-SHIRT with id `71` the default placement is `front` |\n| `front` | Front placement |\n| `back` | Front placement |\n| `sleeve_left` | Sleeve left placement |\n| `sleeve_right` | Sleeve right placement |\n| `embroidery_chest_left` | Placement on left side of the chest made in `embroidery` technique |\n| `embroidery_chest_center` | Placement on the center of the chest made in `embroidery` technique |\n| `label_outside` | Label outside placement |\n| `embroidery_large_center` | Large placement in center made in `embroidery` technique |\n| `label_inside` | Label inside placement |\n| `front_large` | Large front placement |\n| `embroidery_front` | Front placement made in `embroidery` technique |\n| `embroidery_back` | Back placement made in `embroidery` technique |\n| `embroidery_right` | Right side placement made in `embroidery` technique |\n| `embroidery_left` | Left side placement made in `embroidery` technique |\n| `belt_front` | Front of the belt |\n| `belt_back` | Back of the belt |\n| `top` | Top placement |\n| `pocket` | Pocket placement |\n| `bottom` | Bottom placement |\n| `embroidery_apparel_front` | Apparel front placement made in `embroidery` technique |\n| `belt` | Belt placement |\n| `top_front` | Top front placement |\n| `top_back` | Top back placement |\n| `leg_right` | Right leg placement |\n| `leg_left` | Left leg placement |\n| `embroidery_sleeve_left_top` | Placement on left top side of sleeve made in `embroidery` technique |\n| `embroidery_sleeve_right_top` | Placement on right top side of sleeve made in `embroidery` technique |\n| `embroidery_wrist_left` | Placement on wrist area of left sleeve made in `embroidery` technique |\n| `embroidery_wrist_right` | Placement on wrist area of right sleeve made in `embroidery` technique |\n| `hood` | Hood placement |\n| `details` | Details placement |\n| `leg_front_left` | Placement on front left leg |\n| `leg_front_right` | Placement on front right leg |\n| `leg_back_left` | Placement on back left leg |\n| `leg_back_right` | Placement on back right leg |\n| `ear_left` | Left ear placement |\n| `ear_right` | Right ear placement |\n| `embroidery_apparel_back` | Apparel back placement made in `embroidery` technique |\n| `embroidery_chest_top_left` | Top left chest placement made in `embroidery` technique |\n| `embroidery_corner_right` | Right corner placement made in `embroidery` technique |\n| `sides` | Sides placement |\n| `bottom_front` | Bottom front placement |\n| `bottom_back` | Bottom back placement |\n| `lining_top` | Lining top placement |\n| `lining_bottom` | Lining bottom placement |\n| `embroidery_corner_left` | Left corner placement made in `embroidery` technique |\n| `embroidery_outside_left` | Outside left placement made in `embroidery` technique |\n| `embroidery_outside_right` | Outside right placement made in `embroidery` technique |\n| `embroidery_inside_left` | Inside left placement made in `embroidery` technique |\n| `embroidery_inside_right` | Inside right placement made in `embroidery` technique |\n| `background` | Background placement |\n| `shoe_quarters_left` | Quarters left placement of shoe |\n| `shoe_quarters_right` | Quarters right placement of shoe |\n| `shoe_tongue_left` | Shoe left tongue placement |\n| `shoe_tongue_right` | Shoe right tongue placement |\n| `embroidery_patch_front` | Front patch placement made in `embroidery` technique |\n| `embroidery_large_corner_right` | Large right corner placement made in `embroidery` technique |\n| `inside1` | Inside placement |\n| `inside2` | Inside placement |\n| `shoe_left` | Left shoe placement |\n| `shoe_right` | Right shoe placement |\n| `side_right` | Right side placement |\n| `side_left` | Left side placement |\n\n
\n\n# Embroidery\n\n## Manually defining thread colors\nWhenever the embroidery placement is used it's also necessary to specify thread colors which should be used.\nThread color option must be matched with [appropriate placement](#tag/Common/Options).\n
\nTo determine what thread colors could be used you can use [thread color suggestion endpoint](#tag/Examples/File-Library-API-examples/Suggest-thread-colors) and then adjust thread colors manually according to your taste.\n
\nNote that you can specify max 6 thread colors\n```\n\"files\": [\n {\n \"type\": \"embroidery_outside_left\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n],\n\"options\": [\n {\n \"id\": \"thread_colors_outside_left\",\n \"value\": [\"#FFFFFF\", \"#000000\", \"#96A1A8\", \"#A67843\", \"#FFCC00\", \"#E25C27\"]\n }\n]\n```\n\n## Automatic thread color\nInstead of providing thread colors manually you can also use the `auto_thread_color` which will match available thread colors to provided image.\n\n```\n\"files\": [\n {\n \"type\": \"embroidery_outside_left\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\",\n \"options\": [\n {\n \"id\": \"auto_thread_color\",\n \"value\": true\n }\n ]\n }\n]\n```\n\n## Unlimited color\nWhen using the embroidery technique you are limited to a range of predefined thread colors. If you would like to use an unlimited range of thread colors please use Unlimited Color (additional cost will be added). To use Unlimited Color add for each file object an extra parameter in options with id: `full_color`.\nWhile using Unlimited Color you don’t need to specify thread colors. The `full_color` option can be used in Orders, Products, Mockup Generator and Ecommerce Platform Sync API.\n\n```\n\"items\": [\n {\n \"variant_id\": 4468,\n \"quantity\": 1,\n \"files\": [\n {\n \"type\": \"embroidery_back\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\",\n \"options\": [\n {\n \"id\": \"full_color\",\n \"value\": true\n }\n ]\n }\n ]\n }\n]\n```\n\n
\n Unlimited color is available for selected products.\n To distinguish products with unlimited color option and pricing please \n see catalog example \n response for a product with this option available.\n
\n\n[Example order](#tag/Examples/Orders-API-examples/Using-full-color-option)\n\n| Mockup without Unlimited Color | Mockup with Unlimited Color |\n|--------------------------------------------------------------|-----------------------------------------------------------|\n| ![Image](images/unlimited-color/without-unlimited-color.png) | ![Image](images/unlimited-color/with-unlimited-color.png) |\n" }, { "name": "Other resources", "description": "## Developer support\n\nThe previous dedicated developer support channel is not currently monitored.\n\nWith all questions, including ones related to our API, please contact our Customer Support\nat [https://www.printful.com/contacts](https://www.printful.com/contacts).\n\n## Bug reporting\n\nTo report a potential security vulnerability, please send a detailed email to the contacts\ndescribed in our [security.txt](https://printful.com/.well-known/security.txt) file.\n\nTo help us investigate and validate your findings, please include the following information in your report:\n\n- **A clear description** of the vulnerability, including its potential impact.\n- **Detailed steps to reproduce** the vulnerability, including any URLs, parameters, or screenshots.\n- Your contact information, so we can follow up with you.\n\nFor security reasons, please encrypt your submission with the following [PGP key](https://keys.openpgp.org/search?q=security%40printful.com).\n\n### Guidelines for Responsible Testing\n\nTo protect our systems and users, we ask that you act in good faith and follow these guidelines\nwhile conducting your research:\n\n- Avoid actions that could disrupt our services, such as denial-of-service (DoS) attacks.\n- Do not access, modify, or delete data more than it is necessary to demonstrate the impact of the issue.\n\n### Recognition and Bounties\n\nWe are grateful for the community's efforts in helping us to keep our platform safe.\nYour suggestions and reports are thoroughly investigated, and we will work with you to resolve\nvalid security issues in our platform.\n\n**Please note that we do not offer a bug bounty program\nor provide monetary compensation for vulnerability disclosures.**\n\nThank you for helping us keep **Printful** and our users safe.\n\n## Webhook Simulator\n\n[Webhook Simulator](https://www.printful.com/api/webhook-simulator) is a tool that allows you to test your webhook functionality.\nIt will send a selected event type to your webhook URL.\nThis way you will be able to easily develop and test your webhook handlers.\n" }, { "name": "Basic use cases", "description": "# Basic use cases\n\nAll the API integrations begin with a decision on how to authenticate with the Printful API. The most common use cases for Printful API integrations are:\n\n
\n    graph TD\n    A[Authentication Methods] --> B[Private API Token]\n    A --> C[Public App OAuth]\n    B --> D[Single Printful Account]\n    C --> G[Single Printful Account of Marketplace Owner]\n    G --> E[Multiple Printful Accounts]\n    E --> H[Merchant 1]\n    E --> I[Merchant 2]\n    E --> J[Merchant 3]\n
\n\n- Private API token\nMeans that you are building a solution for your own store, using a single Printful account.\n\n
\n    sequenceDiagram\n    participant User as End User\n    participant Shop as Single Shop\n    participant Printful as Printful API\n\n    User->>Shop: Access Single Shop\n    Shop->>User: User Account Linked Successfully\n\n    Shop->>Printful: Authenticate with API Token\n    Printful->>Shop: Return Authentication Success\n\n    User->>Shop: Request Product Catalog\n    Shop->>Printful: Retrieve Product Catalog\n    Printful->>Shop: Return Product Catalog\n    Shop->>User: Display Product Catalog\n\n    Note over Shop,User: User can now design and order products\n\n    User->>Shop: Place Order\n    Shop->>Printful: Create Order\n    Printful->>Shop: Order Created Successfully\n    Shop->>User: Order Confirmation and Tracking\n
\n\n- Public App OAuth\nIs used for more complex integrations, where you are building an app that will be used by multiple users, each with their own Printful account. For example a merchant platform.\n\n
\nsequenceDiagram\n    participant User as End User\n    participant App as Public App (Marketplace)\n    participant Printful as Printful API\n\n    User->>App: Access Public App (Marketplace)\n    App->>User: Redirect to Printful Authorization Page\n    User->>Printful: Authorize App (Grant Permissions)\n    Printful->>User: Return Authorization Code\n    User->>App: Provide Authorization Code\n    App->>Printful: Exchange Authorization Code for Access Token\n    Printful->>App: Return Access Token\n    App->>User: User Account Linked Successfully\n\n    User->>Printful: Request Product Catalog\n    Printful->>User: Return Product Catalog\n\n    Note over App,User: User can now design and order products\n\n    User->>App: Place Order\n    App->>Printful: Create Order on Behalf of User\n    Printful->>App: Order Created Successfully\n    App->>User: Order Confirmation and Tracking\n\n    Note over App,Printful: App manages multiple users independently\n
\n\nBoth private api token and public app can be created in https://developers.printful.com\n\n## Webshop integration offering pre-designed products to the end customers\n1.Authenticate: Obtain your private API key from the Printful dashboard.\n\n2.Set Up Webhooks: Configure webhooks to receive updates about orders, products, and other events.\n\n3.Sync Products: Use the API to fetch and create designed products in the Printful.\n\n4.Create Orders: Send order data to Printful when a customer places an order on a sync product.\n\n5.Track Orders: Use the API to track the status of orders and shipments.\n\n
\n    graph LR\n    A[Obtain API Key] --> B[Set Up Webhooks]\n    B --> C[Sync Products]\n    C --> D[Create Orders]\n    D --> E[Track Orders]\n    E --> F[Update Webshop]\n
\n\n## Webshop integration with the products designed on the fly by the end customers\n1.Authenticate: Obtain your private API key from the Printful dashboard. \n\n2.Retrieve Catalog Products: Use the API to fetch available catalog products and display them to customers for customization. \n\n3.Customize Products: Allow customers to design products (e.g., upload images, select colors, etc.) using your webshop interface. \n\n4.Create Orders on the Fly: When a customer places an order, send the customized product details and order data directly to Printful. \n\n5.Track Orders: Use the API to track the status of orders and shipments. \n\n6.Update Webshop: Update your webshop with order statuses and shipment tracking information.\n\n
\n    graph LR\n    A[Obtain API Key] --> B[Retrieve Catalog Products]\n    B --> C[Customize Products]\n    C --> D[Create Orders on the Fly]\n    D --> E[Track Orders]\n    E --> F[Update Webshop]\n
\n\n## Webshop integration with the product catalog created by the merchant\n
\n    sequenceDiagram\n    participant User as End User\n    participant Merchant\n    participant Printful as Printful API\n\n    User->>Merchant: Access Merchant Platform\n    Merchant->>User: User Account Linked Successfully\n\n    Merchant->>Printful: Authenticate with API Token\n    Printful->>Merchant: Return Authentication Success\n    Note over Merchant,Printful: Merchant can now design and sell products\n\n    Merchant->>Printful: Retrieve Product Catalog\n    Printful->>Merchant: Return Product Catalog\n\n    Merchant->>Printful: Sync Product Data\n    Printful->>Merchant: Product Synced Successfully\n\n    User->>Merchant: Request sync product catalog\n    Merchant->>Printful: Request sync products\n    Printful->>Merchant: Return sync products\n    Merchant->>User: Display sync product catalog\n\n    User->>Merchant: Place Order\n    User->>Printful: Create Order\n    Printful->>Merchant: Order Created Successfully\n    Merchant->>User: Order Confirmation and Tracking\n
\n\n## Embedded Designer integration\nEmbedded designer is embeddable JavaScript component that allows the shop owner not to build their own product designer, but instead use Printful's product designer. It is used to allow design products by the end customers.\nIt is used in conjunction with Printful's product catalog and order API. The end customer can select a product, design it, and then order it.\nThe following diagram illustrates the flow of the embedded designer integration:\n\n
\ngraph TD\n    subgraph Shop[Shop]\n        style Shop fill:#f9f,stroke:#333,stroke-width:2px\n        A[Displays Printful Product Catalog]\n        subgraph EDM[Embedded Designer]\n            style EDM fill:#ff9,stroke:#333,stroke-width:2px\n            B[Designs Product]\n            C[Saves Design]\n        end\n        D[Orders Product Template]\n    end\n\n    subgraph Printful[Printful API]\n        style Printful fill:#99f,stroke:#333,stroke-width:2px\n        E[Processes Order Request]\n    end\n\n    A --> B\n    B --> C\n    C --> D\n    D --> E\n    EDM -.-> Printful\n
\n\nThe more detailed flow of the embedded designer integration is as follows:\n
\n    graph TD\n    subgraph Shop[Shop]\n        style Shop fill:#f9f,stroke:#333,stroke-width:2px\n        A[Displays Printful Product Catalog]\n        C[Retrieves Nonce Token via API]\n        D[Embeds EDM JavaScript Component]\n        E[Uses Nonce to Establish Single Use Session for EDM]\n        H[Calls Printful API to Order Product Template]\n    end\n\n    subgraph EndCustomer[End Customer]\n        style EndCustomer fill:#9f9,stroke:#333,stroke-width:2px\n        B[Selects Product to Design]\n        F[Designs Product in Embedded Designer]\n        G[Saves Design, Producing a Product Template]\n        I[Orders Product Template]\n    end\n\n    subgraph API[Printful API]\n        style API fill:#99f,stroke:#333,stroke-width:2px\n        J[Handles Nonce Token Request]\n        K[Processes Order Request]\n        L[Marks Nonce as Used]\n        M[Invalidates Token]\n    end\n\n    A --> B\n    B --> C\n    C --> J\n    J --> D\n    D --> E\n    E --> L\n    E --> F\n    F --> G\n    G --> M\n    G --> I\n    I --> H\n    H --> K\n
" }, { "name": "Tutorials", "description": "## Make your first order through the API\n\n### API Flow Overview\n\nHere's a quick visual overview of how your system communicates with Printful's API during the order creation flow:\n\n![Authentication setup](images/tutorial/api-integration/authentication_setup.png)\n![OAuth integration flow](images/tutorial/api-integration/oauth_integration.png)\n![Order creation and fulfillment](images/tutorial/api-integration/order_creation.png)\n![Webhook handling](images/tutorial/api-integration/product_management.png)\n![Product management](images/tutorial/api-integration/webhook_handling.png)\n\n### Entity Relationship Reference\n\nThe following diagram shows key API entities:\n\n![Entity relationship diagram](images/tutorial/entity_relationship_diagram.png)\n\n### Introduction\n\nIn this tutorial, we're going to show you how to start making orders through the Printful API.\nYou will learn to send postcards to friends or customers through the API,\nand select new images or addresses for every order.\n\nYou'll be able to take the lessons learned here and start making orders for any kind of product \nfor your customers.\n\n### Set up\n\nBefore anything else make sure you have created a native or \"manual order platform store\"\nif you haven't already.\n\n- Go to this link: https://www.printful.com/dashboard/store.\n- Click the \"Create\" button under \"Manual order platform/API\"\n- Choose a name and click continue\n\nAs well as this you will need to create an OAuth token for this store.\n\n- Go to the developer portal: https://developers.printful.com/login\n- Sign in with your Printful account\n- Go to this link: https://developers.printful.com/tokens/add-new-token\n- Make sure you have set the access level to \"A single store\" and select your store\n- Make sure you have the following scopes selected for this tutorial:\n - `orders` (\"View and manage orders of the authorized store\")\n- Fill in all other fields as you please\n- Create your token\n- You will receive an access key, you will only see the token once, store it securely\n\n\nTo double-check that your token works, and that you have the right store selected, try running the following command\nreplacing `{your_token}` with the access token created in the developer portal.\n```\ncurl --location --request GET 'https://api.printful.com/stores' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nYou should see your store in the response. If you don't see the right store there, or you get an error,\ndouble-check the token is correct and if necessary create a new token\n\n\n### Making an order\n\nBefore starting let's figure out what we need to make an order through the Printful API.\n\nAccording to [the docs](#operation/createOrder)\nthere are only two fields in the create orders request that are absolutely required,\nthe `recipient` object and the `items` array. So let's focus on those for now.\n\n### The recipient\n\nLet's start with the recipient, this will depend on the location you want to send it to. Mine will\nlook like this:\n\n```\n{\n \"name\": \"recipients name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n}\n```\n\nNot all state and country codes are accepted by Printful, so I double-check to make sure that\nAU and NSW are accepted by running this curl command:\n\n```\ncurl --location --request GET 'https://api.printful.com/countries' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"name\": \"Australia\",\n \"code\": \"AU\",\n \"states\": [\n ...,\n {\n \"code\": \"NSW\",\n \"name\": \"New South Wales\"\n },\n ...\n ]\n }\n ],\n \"extra\": []\n}\n```\n\nSure enough, both codes are there.\n\n**Note**: If your recipient isn't in the US, Australia, or Canada the state code is not necessary.\n[Read more](#tag/CountryState-Code-API).\n\n### The items\n\nWe only want one item, but first, we have to find the `variant_id` of that item.\n\nLet's first see if we can find a category that might have postcards in it, with this command:\n\n```\ncurl --location --request GET 'https://api.printful.com/categories' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nThankfully there's a postcard category.\n\n```\n{\n \"code\": 200,\n \"result\": [\n ...,\n {\n \"id\": 197,\n \"parent_id\": 190,\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/catalog_category/da/da6caac995335b87ace2d79af70eef5f_t?v=1652883254\",\n \"title\": \"Postcards\"\n },\n ...\n ],\n \"extra\": []\n}\n```\n\nNow let's see what options there are in that category\n```\ncurl --location --request GET 'https://api.printful.com/products?category_id=197' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\n```\n{\n \"id\": 433,\n \"main_category_id\": 197,\n \"type\": \"POSTCARD\",\n \"type_name\": \"Standard Postcard\",\n \"title\": \"Standard Postcard\",\n \"brand\": null,\n \"model\": \"Standard Postcard\",\n \"image\": \"https://s3-printful.stage.printful.dev/products/433/product_1602054891.jpg\",\n \"variant_count\": 1,\n \"currency\": \"USD\",\n \"options\": [],\n \"dimensions\": null,\n \"is_discontinued\": false,\n \"avg_fulfillment_time\": null,\n \"techniques\": [\n {\n \"key\": \"DIGITAL\",\n \"display_name\": \"Digital printing\",\n \"is_default\": true\n }\n ],\n \"files\": [\n {\n \"id\": \"default\",\n \"type\": \"default\",\n \"title\": \"Print file\",\n \"additional_price\": null\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null\n }\n ],\n \"description\": \"These postcards are made from thick high-quality matte paper, so they serve as a great addition to a gift or just a thoughtful written note to a friend.\\n• Cardboard paper\\n• Paper weight: 7.67–10.32 oz/yd² (260–350 g/m²)\\n• Size: 4″ × 6″ (101 × 152 mm)\\n• Paper thickness: 0.013″ (0.34 mm)\\n• Coated outer surface\\n• Blank product materials sourced from Sweden, US, Brazil, or China\",\n \"catalog_categories\": {\n \"0\": 197,\n \"1\": 5,\n \"2\": 122,\n \"4\": 213,\n \"5\": 230,\n \"6\": 242\n }\n}\n```\n\nThe standard option looks good so let's get some more information about the product with:\n\n```\ncurl --location --request GET 'https://api.printful.com/products/433' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product\": {\n ...\n },\n \"variants\": [\n {\n \"id\": 11513,\n \"product_id\": 433,\n \"name\": \"Standard Postcards (4″×6″)\",\n \"size\": \"4″×6″\",\n \"color\": null,\n \"color_code\": null,\n \"color_code2\": null,\n \"image\": \"https://s3-printful.stage.printful.dev/products/433/11513_1592384192.jpg\",\n \"price\": \"1.50\",\n \"in_stock\": true,\n \"availability_regions\": {\n \"US\": \"United States\",\n \"EU\": \"Europe\",\n \"EU_LV\": \"Latvia\",\n \"AU\": \"Australia\"\n },\n \"availability_status\": [\n {\n \"region\": \"US\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"EU\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"EU_LV\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"AU\",\n \"status\": \"in_stock\"\n }\n ]\n }\n ]\n },\n \"extra\": []\n}\n```\n\nOur choice here should be easy, there is only one variant, and it's available in the region\nwe need to send it to.\n\nNow we can add this id (`11513`) to an item in our order payload.\n\n````\n{\n ...,\n \"items\": [\n {\n \"variant_id\": 11513\n }\n ]\n}\n````\n\nNext, we need to add a `files` array to the item and decide on the \"`quantity`\" we want to print\n(let's just print 1 for now). This way Printful knows what to print, and how many\nitems should be sent to the recipient.\n\n````\n{\n \"variant_id\": 11513,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_1.jpg\"\n }\n ]\n}\n````\n\n### Putting it all together\n\nNow we can finish our orders payload and create our first order.\nThe final payload should look like this:\n\n````\n{\n \"recipient\": {\n \"name\": \"recipients name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"variant_id\": 11513,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_1.jpg\"\n }\n ]\n }\n ]\n}\n````\n\nWe can now make a `POST` request to `https://api.printful.com/orders` with this payload, and\nwe'll get a draft order using a request like this:\n\n```\ncurl --location --request POST 'https://api.printful.com/orders' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {your_token}' \\\n--data-raw '{\n \"recipient\": {\n \"name\": \"recipients name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"variant_id\": 11513,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_1.jpg\"\n }\n ]\n }\n ]\n}'\n```\n\nNow your order is ready to be made, you will even be able to see the draft already in your\ndashboard here:\n`https://www.printful.com/dashboard/default/orders`\n\n### Confirming an order\n\nTo confirm the order we need the `id` of our new order, it should have been returned by the response to\nthe request above. If you've lost it, you can find it again by making a GET request to\n`https://www.api.printful.com/orders` and find your order in the returned list.\n```\ncurl --location --request GET 'https://api.printful.com/orders' \\\n--header 'Authorization: Bearer {your_token}'\n```\nAssuming you haven't made any other orders it will probably be the first item returned in that list.\n\nOnce you have your order id you can confirm the order and have it sent to fulfillment.\n\n**Note**: If you do want the order to be fulfilled remember to [set up billing](https://www.printful.com/dashboard/billing/how-does-billing-work).\nIf billing is not set up first the order will fail.\n\n**Warning**: Do not run the following command if you do not want to be charged for this order.\n```\ncurl --location --request POST 'https://api.printful.com/orders/{your_order_id}/confirm' \\\n--header 'Authorization: Bearer {your_token}' \\\n```\n\n### Automatically confirming new orders\n\nNow I want to be able to send these postcards in one step, without \nneeding to confirm every time.\n\nTo do that, all I have to do is add `confirm=1` as a query parameter to the `POST` request. \nSo that the request looks like this: `POST https://api.printful.com/orders?confirm=1`\n\nNow, whenever I need to send a postcard with a new image I just change the item file URL in this request:\n\n**Warning**: Do not run the following command if you do not want to be charged for this order. \n```\ncurl --location --request POST 'https://api.printful.com/orders?confirm=1' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {your_token}' \\\n--data-raw '{\n \"recipient\": {\n \"name\": \"recipient name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"variant_id\": 11513,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"{change_this_url}\"\n }\n ]\n }\n ]\n}'\n```\n\nIf I then wanted to send it to someone else all I'd need to do is change the address object.\n\n### Next steps\nTry making some more draft requests like this for different items, and see how they look in the dashboard.\nTry moving the requests into an application you've already created so that your customers can make orders through a UI.\n\nIf you'd like to sell your own products that you've pre-built for your store you\ncan follow our tutorial on [creating products for your store through the API](#tag/Tutorials/Creating-products-for-your-store-through-the-API).\n\n\n## Creating products for your store through the API\n\n### Set up\nTo follow along with this tutorial, you will need to do the following:\n\nMake sure you have created a native or\n\"manual order platform store\" if you haven't already.\n\n- Go to this link: https://www.printful.com/dashboard/store.\n- Click the \"Create\" button under \"Manual order platform/API\"\n- Choose a name and click continue\n\nAs well as this you will need to create an OAuth token for this store.\n\n- Go to the developer portal: https://developers.printful.com/login\n- Sign in with your Printful account\n- Go to this link: https://developers.printful.com/tokens/add-new-token\n- Make sure you have set the access level to \"A single store\" and select your store\n- Make sure you have the following scopes selected:\n - `orders` View and manage orders of the authorized store\n - `sync_products` View and manage store products\n- Fill in all other fields as you please\n- Create your token\n- You will receive an access token, you will only see the token once, store it securely\n\nTo double-check that your token works, and that you have the right store selected, try running the following command\nreplacing `{your_token}` with the access token created in the developer portal.\n```\ncurl --location --request GET 'https://api.printful.com/stores' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nYou should see your store there. If you don't see the right store there, or you get an error,\ndouble-check the token is correct and if necessary create a new token\n\n### Get Sync Products\n\nI've created a new store, \"My Photos Store\", and I want to start selling landscapes.\n\nThe first thing I want to do is see what products I have in my store. To do this I will use the\n[Products API](#tag/Products-API), which lets me create, modify and delete products\nin my Printful store.\n\nSo I make this request with curl.\n\n```\ncurl --location --request GET 'https://api.printful.com/store/products' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nAnd it looks like I have no products in my store yet.\n\n**Note**: If you've already created some products you'll see them here.\n```\n{\n \"code\": 200,\n \"result\": [],\n \"extra\": [],\n \"paging\": {\n \"total\": 0,\n \"offset\": 0,\n \"limit\": 20\n }\n}\n```\n\nTo create a new product for our store we'll need to make a post request to that same endpoint.\n\nAccording to [the docs](#operation/createSyncProduct),\nthere are two required fields, an object `sync_product` and an array `sync_variants`.\n\nThe product only has one required field, `name`, and the variants only require the `id`\nand `files` fields to be present.\n\nSo to make a simple first product, let's try and build an object like this:\n\n```\n{\n \"sync_product\": {\n \"name\": \"string\"\n },\n \"sync_variants\": [\n {\n \"variant_id\": 1,\n \"files\": [\n {\n \"url\": \"string\"\n }\n ]\n }\n ]\n}\n\n```\n\nOur first step is to figure out the `variant_ids` that we need.\n\n### The Printful catalog\n\nMy main goal is to sell landscape photos, so let's check the\n[Get Categories endpoint](#operation/getCategories)\nto see if there's anything suitable for that.\n\n```\ncurl --location --request GET 'https://api.printful.com/categories' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"categories\": [\n ...\n {\n \"id\": 55,\n \"parent_id\": 21,\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/catalog_category/6f/6f2f0c50f2558af01e4f8eebbc09a66d_t?v=1652883254\",\n \"title\": \"Posters\"\n },\n {\n \"id\": 56,\n \"parent_id\": 21,\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/catalog_category/34/347883396e6a71fdb25121f20c85e2b3_t?v=1652883254\",\n \"title\": \"Framed posters\"\n },\n {\n \"id\": 57,\n \"parent_id\": 21,\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/catalog_category/7c/7c2dd885646f3971b7199ac833a0232f_t?v=1652883254\",\n \"title\": \"Canvas prints\"\n },\n ...\n ]\n },\n \"extra\": []\n}\n```\n\nPosters, Framed Posters and Canvas prints all sound suitable.\nThough I'd prefer my photos framed before sending them to customers, so I will look into\nthe category with `id` `56`.\n\nSee if you can find a product that suits your needs best from the list returned from the `/categories` endpoint.\n\nTo see all options for framed posters let's use the `category_id` (`56`)\nwith the [Get Products endpoint](#operation/getProducts).\n\nWe can pass the `id` of the category we're interested in as a query parameter, so I'll pass `56` in as a parameter with a\nrequest:\n\n```\ncurl --location --request GET 'https://api.printful.com/products?category_id=56' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nThis returns 4 products in an array:\n\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"id\": 2,\n \"main_category_id\": 56,\n \"title\": \"Enhanced Matte Paper Framed Poster (in)\",\n ...\n },\n {\n \"id\": 304,\n \"main_category_id\": 56,\n \"title\": \"Enhanced Matte Paper Framed Poster (cm)\",\n ...\n },\n {\n \"id\": 366,\n \"main_category_id\": 56,\n \"title\": \"Framed Poster with Frame Mat (cm)\",\n ...\n },\n {\n \"id\": 172,\n \"main_category_id\": 56,\n \"title\": \"Premium Luster Photo Paper Framed Poster (in)\",\n ...\n }\n ],\n \"extra\": []\n}\n```\n\nThis will give us a lot of information about the products,\nbut all we really need at this point is the `id`.\n\nI'm interested in that \"Premium Luster Photo Paper Framed Poster (in)\" product,\nso to find what variants are available to me, I'll search for it by its `id`\n(`172`) and find the `variant_id`s I'm looking for.\n\n```\ncurl --location --request GET 'https://api.printful.com/products/172' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product\": {\n \"id\": 172,\n \"main_category_id\": 56,\n \"type\": \"FRAMED-POSTER\",\n \"type_name\": \"Premium Luster Photo Paper Framed Poster (in)\",\n \"title\": \"Premium Luster Photo Paper Framed Poster (in)\",\n ...\n },\n \"variants\": [\n ...,\n {\n \"id\": 10760,\n \"product_id\": 172,\n \"name\": \"Premium Luster Photo Paper Framed Poster (White/8″×10″)\",\n \"size\": \"8″×10″\",\n \"color\": \"White\",\n \"color_code\": \"#ffffff\",\n \"color_code2\": null,\n \"image\": \"https://s3-printful.stage.printful.dev/products/172/10760_1565081295.jpg\",\n \"price\": \"23.00\",\n \"in_stock\": true,\n \"availability_regions\": {\n \"US\": \"United States\",\n \"EU\": \"Europe\",\n \"EU_LV\": \"Latvia\",\n \"AU\": \"Australia\",\n \"UK\": \"United Kingdom\"\n },\n \"availability_status\": [\n {\n \"region\": \"US\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"EU\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"EU_LV\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"AU\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"UK\",\n \"status\": \"in_stock\"\n }\n ]\n }\n ]\n },\n \"extra\": []\n}\n```\n\nThe final variant with id `10760` is in stock in all the regions I want to sell in\nand a small 8x10 sounds like a great first product for my store.\n\n### Your first sync product and sync variant\n\nNow we can finish this payload from before:\n\n```\n{\n \"sync_product\": {\n \"name\": \"string\"\n },\n \"sync_variants\": [\n {\n \"variant_id\": 1,\n \"files\": [\n {\n \"url\": \"string\"\n }\n ]\n }\n ]\n}\n```\n\nI'll name my product \"Framed Landscape Poster\" so my object will look like this:\n\n```\n{\n \"sync_product\": {\n \"name\": \"Framed Landscape Poster\"\n },\n \"sync_variants\": [\n {\n \"variant_id\": 10760,\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_1.jpg\"\n }\n ]\n }\n ]\n}\n```\n\nSo let's post that object to the Products endpoint:\n\n```\ncurl --location --request POST 'https://api.printful.com/store/products' \\\n--header 'Authorization: Bearer {your_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"sync_product\": {\n \"name\": \"Framed Landscape Poster\"\n },\n \"sync_variants\": [\n {\n \"variant_id\": 10760,\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_1.jpg\"\n }\n ]\n }\n ]\n}'\n```\n\nAnd now we'll get our product back looking like this:\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 280896090,\n \"external_id\": \"6308d1498007d7\",\n \"name\": \"Framed Landscape Poster\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": null,\n \"is_ignored\": false\n },\n \"extra\": []\n}\n```\n\nAnd when I go back to see the products in my store\n\n```\ncurl --location --request GET 'https://api.printful.com/store/products' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nI see the new product:\n\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"id\": 280896090,\n \"external_id\": \"6308d1498007d7\",\n \"name\": \"Framed Landscape Poster\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": null,\n \"is_ignored\": false\n }\n ],\n \"extra\": [],\n \"paging\": {\n \"total\": 1,\n \"offset\": 0,\n \"limit\": 20\n }\n}\n```\n\nAnd I can see more details about the product with this request now.\n\n**Note**: Replace the `{your_product_id}` at the end with the `id` of your sync product, i.e.\n\n```\ncurl --location --request GET 'https://api.printful.com/store/products/{your_product_id}' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nFor me, the request will look like this, but you will have a different id:\n```\ncurl --location --request GET 'https://api.printful.com/store/products/280896090' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"sync_product\": {\n \"id\": 280896090,\n \"external_id\": \"6308d1498007d7\",\n \"name\": \"Framed Landscape Poster\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": null,\n \"is_ignored\": false\n },\n \"sync_variants\": [\n {\n \"id\": 3374445206,\n \"external_id\": \"6308d14981f197\",\n \"sync_product_id\": 280896090,\n \"name\": \"Framed Landscape Poster - Black / 10″×10″\",\n \"synced\": true,\n \"variant_id\": 6883,\n \"warehouse_product_id\": null,\n \"warehouse_product_variant_id\": null,\n \"retail_price\": null,\n \"sku\": null,\n \"currency\": \"USD\",\n \"product\": {\n \"variant_id\": 6883,\n \"product_id\": 172,\n \"image\": \"https://s3-printful.stage.printful.dev/products/172/6883_1527683114.jpg\",\n \"name\": \"Premium Luster Photo Paper Framed Poster (Black/10″×10″)\"\n },\n \"files\": [\n {\n \"id\": 450621845,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://example.com/files/posters/poster_1.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1661516795,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": [],\n \"is_ignored\": false\n }\n ]\n },\n \"extra\": []\n}\n```\n\n### Ordering the new product\n\nNow that I have the product in my store, I can very easily order\none of my sync variants as an item using only the `sync_variant_id`.\n\nThe payload might look something like this\n\n``` \n{\n \"recipient\": {\n \"name\": \"name\",\n \"address1\": \"address\",\n \"city\": \"city\",\n \"state_code\": \"STATE_CODE\",\n \"country_code\": \"COUNTRY_CODE\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"sync_variant_id\": 3374445206,\n \"quantity\": 1,\n }\n ]\n}\n```\nWe can make a draft order with this command:\n\n**Note**: You will need to swap `{your_sync_variant_id}` out with your own `sync_variant_id`\n```\ncurl --location --request POST 'https://api.printful.com/orders' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {your_token}' \\\n--data-raw '{\n \"recipient\": {\n \"name\": \"name\",\n \"address1\": \"address\",\n \"city\": \"city\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"sync_variant_id\": {your_sync_variant_id},\n \"quantity\": 1\n }\n ]\n}\n'\n```\n\n### Next steps\nTo learn more about making an order see:\n[Make your first order through the API](#tag/Tutorials/Make-your-first-order-through-the-API).\n\n## Ordering a Direct to Garment (DTG) and an Embroidery Product through the API\n\n### Introduction\n\nIn this tutorial, we're going to make an order and design one of Printful's\nmost popular items, the **Unisex Staple T-Shirt | Bella + Canvas 3001**.\nYou will learn how to define file placements and product options when ordering DTG and embroidery products.\n\n### Set up\n\nBefore anything else make sure you have created a native or \"manual order platform store\"\nif you haven't already.\n\n- Go to this link: https://www.printful.com/dashboard/store\n- Click the \"Create\" button under \"Manual order platform/API\"\n- Choose a name and click continue\n\nAs well as this you will need to create an OAuth token for this store.\n\n- Go to the developer portal: https://developers.printful.com/login\n- Sign in with your Printful account\n- Go to this link: https://developers.printful.com/tokens/add-new-token\n- Make sure you have set the access level to \"A single store\" and select your store\n- Make sure you have the following scopes selected for this tutorial:\n - `orders` (\"View and manage orders of the authorized store\")\n- Fill in all other fields as you please\n- Create your token\n- You will receive an access key, you will only see the token once, store it securely\n\n\nTo double-check that your token works and that you have the right store selected, try running the following command\nreplacing `your_token` with the access token created in the developer portal.\n```\ncurl --location --request GET 'https://api.printful.com/stores' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\nYou should see your store in the response. If you don't see the right store there, or you get an error,\ndouble-check the token is correct and if necessary create a new token.\n\n### Making the order\nWe won't go through all the details on how to make an order in this tutorial, instead we will start with the following \nJSON object, which we can use as the basis for constructing an order. \n\n```\n{\n \"recipient\": {\n \"name\": \"recipients name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"variant_id\": 4035,\n \"quantity\": 1\n }\n ]\n}\n```\n\nThe `recipient` object describes where, and to whom, I want to send the order. Inside the `items`\narray I have one object with `variant_id` `4035` which is this T-Shirt:\n\n\"variant_id\n\nDescribed in JSON like this:\n```\n{\n \"id\": 4035,\n \"product_id\": 71,\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (Asphalt / 2XL)\",\n \"size\": \"2XL\",\n \"color\": \"Asphalt\",\n \"color_code\": \"#52514f\",\n \"color_code2\": null,\n \"image\": \"https://s3-printful.stage.printful.dev/products/71/4035_1581408351.jpg\",\n \"price\": \"12.55\",\n \"in_stock\": true,\n \"availability_regions\": {\n \"US\": \"United States\",\n \"EU\": \"Europe\",\n \"EU_LV\": \"Latvia\",\n \"EU_ES\": \"Spain\",\n \"AU\": \"Australia\",\n \"CA\": \"Canada\",\n \"UK\": \"United Kingdom\"\n },\n \"availability_status\": [\n {\n \"region\": \"US\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"EU\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"EU_LV\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"EU_ES\",\n \"status\": \"stocked_on_demand\"\n },\n {\n \"region\": \"AU\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"CA\",\n \"status\": \"in_stock\"\n },\n {\n \"region\": \"UK\",\n \"status\": \"in_stock\"\n }\n ]\n}\n```\nIf you'd like more detail, we have a tutorial to help you\n[make your first order through the API](#tag/Tutorials/Make-your-first-order-through-the-API).\n\n### Adding placements\nWe already know what we want to order. But now we want to add our design to the image. I want to print the following design\non the right sleeve and the back of the T-Shirt.\n\n![Printful logo](https://printful.com/static/images/layout/logo-printful.png)\n\n\nFirst let's make sure that's actually possible, by making a request to the `variants` endpoint.\n```\ncurl --location --request GET 'https://api.printful.com/products/variant/4035' \\\n--header 'Authorization: Bearer {your_token}'\n```\n**Note**: You could also do this with a request to the Products endpoint as this information will be the same for each variant of a product.\n```\ncurl --location --request GET 'https://api.printful.com/products/71' \\\n--header 'Authorization: Bearer {your_token}'\n```\nYou will see what file placements are available under `result.product.files`. As of writing this tutorial the following placements are\navailable:\n```\n...\n\"files\": [\n {\n \"id\": \"embroidery_chest_left\",\n \"type\": \"embroidery_chest_left\",\n \"title\": \"Left chest\",\n \"additional_price\": \"2.60\"\n },\n {\n \"id\": \"embroidery_large_center\",\n \"type\": \"embroidery_large_center\",\n \"title\": \"Large center\",\n \"additional_price\": \"3.25\"\n },\n {\n \"id\": \"embroidery_chest_center\",\n \"type\": \"embroidery_chest_center\",\n \"title\": \"Center chest\",\n \"additional_price\": \"2.60\"\n },\n {\n \"id\": \"embroidery_sleeve_left_top\",\n \"type\": \"embroidery_sleeve_left_top\",\n \"title\": \"Left sleeve top\",\n \"additional_price\": \"2.60\"\n },\n {\n \"id\": \"embroidery_sleeve_right_top\",\n \"type\": \"embroidery_sleeve_right_top\",\n \"title\": \"Right sleeve top\",\n \"additional_price\": \"2.60\"\n },\n {\n \"id\": \"default\",\n \"type\": \"front\",\n \"title\": \"Front print\",\n \"additional_price\": null\n },\n {\n \"id\": \"front_large\",\n \"type\": \"front_large\",\n \"title\": \"Large front print\",\n \"additional_price\": \"5.25\"\n },\n {\n \"id\": \"back\",\n \"type\": \"back\",\n \"title\": \"Back print\",\n \"additional_price\": \"5.25\"\n },\n {\n \"id\": \"label_outside\",\n \"type\": \"label_outside\",\n \"title\": \"Outside label\",\n \"additional_price\": \"2.20\"\n },\n {\n \"id\": \"label_inside\",\n \"type\": \"label_inside\",\n \"title\": \"Inside label\",\n \"additional_price\": \"2.20\"\n },\n {\n \"id\": \"sleeve_left\",\n \"type\": \"sleeve_left\",\n \"title\": \"Left sleeve\",\n \"additional_price\": \"2.20\"\n },\n {\n \"id\": \"sleeve_right\",\n \"type\": \"sleeve_right\",\n \"title\": \"Right sleeve\",\n \"additional_price\": \"2.20\"\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null\n }\n],\n...\n```\n\nThankfully \"Right sleeve\" (`sleeve_right`) and \"Back print\" (`back`) are among the available options for this product.\n\n```\n ...\n {\n \"id\": \"back\",\n \"type\": \"back\",\n \"title\": \"Back print\",\n \"additional_price\": \"5.25\"\n },\n ...\n {\n \"id\": \"sleeve_right\",\n \"type\": \"sleeve_right\",\n \"title\": \"Right sleeve\",\n \"additional_price\": \"2.20\"\n },\n ...\n```\nThe most important thing here is the `type` field, that's what we will use to indicate where we want our files to be placed.\n\n### Adding the image placements to the items\nNow we can add our designs to the item object. To do that we need a `files` array containing the source of our images.\n\nIn our [previous article](#tag/Tutorials/Make-your-first-order-through-the-API) on making orders, we already added a file to an item, \nand it looked like this:\n```\n{\n \"variant_id\": 4035,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n }\n ]\n}\n```\n\nThis won't work for us though, because it doesn't specify the placement. The above payload\nwill use the `default` placement because no other was specified. If we use the default the image\nwill be printed on the `front` for this product.\n\nTo have the placement on the back instead, let's add a `type` field to the `file` object\n```\n{\n \"type\": \"back\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n}\n```\nThen we can add another object to the `files` array doing the same but with `sleeve_right` as the type so that our final item\nlooks like this.\n```\n{\n \"variant_id\": 4035,\n \"quantity\": 1,\n \"files\": [\n { \n \"type\": \"back\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n },\n { \n \"type\": \"sleeve_right\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n }\n ]\n}\n```\n\n### Ordering the product\nWe can already make our order as a draft with this request:\n\n```\ncurl --location --request POST 'https://api.printful.com/orders' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {your_token}' \\\n--data-raw '{\n \"recipient\": {\n \"name\": \"recipients name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"variant_id\": 4035,\n \"quantity\": 1,\n \"files\": [\n { \n \"type\": \"back\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n },\n { \n \"type\": \"sleeve_right\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n }\n ]\n }\n ]\n}'\n```\n\nIn the response, you'll find a link to the order in the dashboard.\n\n```\n...\n\"dashboard_url\": \"https://www.printful.com/dashboard?order_id={your_order_id}\"\n...\n```\nIn the dashboard, you'll be able to view the order and see how your item looks on a mockup. You may have to wait\nfor the mockup to be generated.\n\n**Note**: This can be done programmatically through the API as well, using the Mockup Generator API.\n\n### File position\nThe print file on the `back` placement didn't look how I expected. I wanted the image towards the top and the middle.\nSo, I will update the order and pass a position object along with the item using a `PUT` request to\nthe `orders` endpoint.\n\nThe position object looks like this:\n```\n{\n \"area_width\": 1200,\n \"area_height\": 1600,\n \"width\": 300,\n \"height\": 100,\n \"top\": 100,\n \"left\": 450\n}\n```\nThis object creates an invisible background for your image, which you can use to place your image in a more specific location.\n`area_width` and `area_height` are used to create the area your image will be placed on top of. `width` and `height` can\nbe used to resize your image. `top` and `left` refer to how far away the image should be placed from the top and left\nrespectively.\n\nThese numbers are relative and don't refer to centimeters, inches, or pixels. So the following `placement` object is the same as the previous one:\n```\n{\n \"area_width\": 12,\n \"area_height\": 16,\n \"width\": 3,\n \"height\": 1,\n \"top\": 1,\n \"left\": 4.5\n}\n```\n\nThis is the request I make to update the order:\n```\ncurl --location --request PUT 'https://api.printful.com/orders/{your_order_id}' \\\n--header 'Authorization: Bearer {your_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"items\": [\n {\n \"variant_id\": 4035,\n \"quantity\": 1,\n \"files\": [\n { \n \"type\": \"back\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\",\n \"position\": {\n \"area_width\": 1200,\n \"area_height\": 1600,\n \"width\": 300,\n \"height\": 100,\n \"top\": 100,\n \"left\": 450\n }\n },\n { \n \"type\": \"sleeve_right\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n }\n ]\n }\n ]\n}'\n```\n\n### Adding embroidery\nNow that I have an order with direct to garment prints made, I'd also like to have my design embroidered.\n\nFor the embroidered version of the T-Shirt I'd like the design to be on the chest towards the left,\nwhere a pocket might be on another shirt. Thankfully, we've already seen that top left is an option for this shirt\n\n```\n{\n \"id\": \"embroidery_chest_left\",\n \"type\": \"embroidery_chest_left\",\n \"title\": \"Left chest\",\n \"additional_price\": \"2.60\"\n}\n```\n\nSo let's try and make our previous `POST` request again, but this time with only the `embroidery_chest_left` file type:\n\n```\ncurl --location --request POST 'https://api.printful.com/orders' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {your_token}' \\\n--data-raw '{\n \"recipient\": {\n \"name\": \"recipients name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"variant_id\": 4035,\n \"quantity\": 1,\n \"files\": [\n { \n \"type\": \"embroidery_chest_left\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n }\n ]\n }\n ]\n}'\n```\nUnfortunately, embroidery items work a bit differently, so if we make that request we'll get this error:\n```\n{\n \"code\": 400,\n \"result\": \"Item 0: thread_colors_chest_left option is missing or incorrect! Allowed values: #FFFFFF, #000000, #96A1A8, #A67843, #FFCC00, #E25C27, #CC3366, #CC3333, #660000, #333366, #005397, #3399FF, #6B5294, #01784E, #7BA35A\",\n \"error\": {\n \"reason\": \"BadRequest\",\n \"message\": \"Item 0: thread_colors_chest_left option is missing or incorrect! Allowed values: #FFFFFF, #000000, #96A1A8, #A67843, #FFCC00, #E25C27, #CC3366, #CC3333, #660000, #333366, #005397, #3399FF, #6B5294, #01784E, #7BA35A\"\n }\n}\n```\n\nThere are only so many colors available when using embroidery, so the `thread_colors` need to be set in the request.\nIf you don't want to do that manually you can pass the `auto_thread_color` into the files `options` array.\n\n```\n\"type\": \"embroidery_chest_left\",\n\"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n\"options\": [\n {\n \"id\": \"auto_thread_color\",\n \"value\": true\n }\n]\n\n```\n**Note**: The options are a property of the **file** object not the item\n\nIf that option is passed into the request, Printful will choose the colors closest to those in the file.\n\nHowever, in this case, I'd like more control over the thread colors. I'd like a black and white effect,\nso I need to add the option `thread_colors_chest_left` to the item along with the first two allowed values\nfrom the error message.\n\n```\n{\n \"variant_id\": 4035,\n \"quantity\": 1,\n \"files\": [\n { \n \"type\": \"embroidery_chest_left\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n }\n ],\n \"options\": [\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": [\"#000000\", \"#FFFFFF\"]\n }\n ]\n}\n```\n**Note**: The options are a property of the **item** object not of the file.\n\nNow to make that order we can make a request like this:\n```\ncurl --location --request POST 'https://api.printful.com/orders' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer {your_token}' \\\n--data-raw '{\n \"recipient\": {\n \"name\": \"recipients name\",\n \"address1\": \"12 address avenue, Bankstown\",\n \"city\": \"Sydney\",\n \"state_code\": \"NSW\",\n \"country_code\": \"AU\",\n \"zip\": \"2200\"\n },\n \"items\": [\n {\n \"variant_id\": 4035,\n \"quantity\": 1,\n \"files\": [\n {\n \"type\": \"embroidery_chest_left\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n }\n ],\n \"options\": [\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": [\"#000000\", \"#FFFFFF\"]\n }\n ]\n }\n ]\n}'\n```\n\n### Next steps\nWe've made these orders, but we haven't confirmed them yet, so they are just drafts. For more information on making orders, you can\nlook through the documentation [here](#tag/Orders-API) or follow our other tutorial [Make your first order through the API](#tag/Tutorials/Make-your-first-order-through-the-API).\n\nOr if you would like these items to be more reusable as items in your store you can follow our tutorial on [creating products for your store through the API](#tag/Tutorials/Creating-products-for-your-store-through-the-API).\n\n## Creating Mockups in the API\n### Introduction\nIn our previous tutorials we created products that can be ordered by ourselves or our customers.\nHowever, if we're going to order a product, or offer it to a customer, we'll want to know what\nit looks like first. That's where mockups come in.\n\nIn this tutorial, we're going to create mockups for some of the products we built in previous tutorials.\n\n### Set up\n\nBefore anything else make sure you have created a native or \"manual order platform store\"\nif you haven't already.\n\n- Go to this link: https://www.printful.com/dashboard/store\n- Click the \"Create\" button under \"Manual order platform/API\"\n- Choose a name and click create\n\nAs well as this you will need to create an OAuth token for this store.\n\n- Go to the developer portal: https://developers.printful.com/login\n- Sign in with your Printful account\n- Go to this link: https://developers.printful.com/tokens/add-new-token\n- Make sure you have set access level to \"A single store\" and select your store\n- Make sure you have the following scopes selected for this tutorial:\n - `orders` (\"View and manage orders of the authorized store\")\n- Fill in all other fields as you please\n- Create your token\n- You will receive an access key, you will only see the token once, store it securely\n\n### Deciding which variants to generate\nIn one of our previous tutorials, [Ordering a Direct to Garment (DTG) and an Embroidery Product through the API](#tag/Tutorials/Ordering-a-Direct-to-Garment-(DTG)-and-an-Embroidery-Product-through-the-API).\nLet's make some mockups for that same T-Shirt.\n\nWhen we originally made the T-Shirt, we only had the `Asphalt` color, but I'd also like to\ndisplay a `Black` and `White` variant as well. So, I find the `id` of the T-Shirt product I want,\n`71`, and make a `GET` request to `https://api.printful.com/products/71`.\n\n```\ncurl --location --request GET 'https://api.printful.com/products/71' \\\n--header 'Authorization: Bearer {your_token}'\n```\nThis will provide you with, among other things, a list of variants. Among those variants,\nyou will find the Asphalt variant `4035` we created in the previous tutorial. We will also find\na variant with the color black `4020` and a variant with the color white `4015`.\n\nNow we need to get the files from our previous tutorial and put them into a new files array using the format\nof the [Mockup Generator API](#tag/Mockup-Generator-API).\n\nSo if we had files from an order that looked like this:\n```\n \"files\": [\n { \n \"type\": \"embroidery_chest_left\",\n \"url\": \"https://printful.com/static/images/layout/logo-printful.png\"\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n }\n }\n ]\n```\n\nOur new files array will look like this:\n``` \n \"files\": [\n\t{ \n\t\t\"type\": \"embroidery_chest_left\",\n\t\t\"image_url\": \"https://printful.com/static/images/layout/logo-printful.png\",\n\t\t\"position\": {\n\t\t \"area_width\": 1800,\n\t\t \"area_height\": 2400,\n\t\t \"width\": 1800,\n\t\t \"height\": 1800,\n\t\t \"top\": 300,\n\t\t \"left\": 0\n\t\t}\n\t}\n ]\n```\n\nTo generate the mockups for these variants we can put these files and `variant_id`s in\na single `POST` request to `https://api.printful.com/mockup-generator/create-task/{product_id}`.\n\n``` \ncurl --location --request POST 'https://api.printful.com/mockup-generator/create-task/71' \\\n--header 'Authorization: Bearer {your_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"variant_ids\": [\n 4035,\n 4020,\n 4015\n ],\n \"files\": [\n { \n \"type\": \"embroidery_chest_left\",\n \"image_url\": \"https://printful.com/static/images/layout/logo-printful.png\",\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n }\n }\n ]\n}'\n```\n\nThis will give you a response like this:\n```\n{\n \"code\" : 200,\n \"extra\" : [],\n \"result\" : {\n \"status\" : \"pending\",\n \"task_key\" : \"gt-421699980\"\n }\n}\n```\nYou'll notice that there are no mockups in the response, instead, you receive a `task_key`\nwhich you can use to retrieve the actual mockup:\n\n```\ncurl --location --request GET 'https://api.printful.com/mockup-generator/task?task_key=gt-421699980' \\\n--header 'Authorization: Bearer {your_token}'\n```\n\n```\n{\n \"code\" : 200,\n \"extra\" : [],\n \"result\" : {\n \"mockups\" : [\n {\n \"extra\" : [\n {\n \"option\" : \"Front\",\n \"option_group\" : \"Men's\",\n \"title\" : \"Front\",\n \"url\" : \"https://printful-upload.s3-accelerate.amazonaws.com/tmp/ca321525cfd907188c2266fb6a41cf94/unisex-staple-t-shirt-black-front-634d3ec02e655.png\"\n },\n {\n \"option\" : \"Front\",\n \"option_group\" : \"Flat\",\n \"title\" : \"Front\",\n \"url\" : \"https://printful-upload.s3-accelerate.amazonaws.com/tmp/a3560e3a7558374cfdb2bb6c53ccee18/unisex-staple-t-shirt-black-front-634d3ec02e945.png\"\n }\n ],\n \"mockup_url\" : \"https://printful-upload.s3-accelerate.amazonaws.com/tmp/e2a9e33986914a13096d60847be8a5b0/unisex-staple-t-shirt-black-zoomed-in-634d3ec02dafc.png\",\n \"placement\" : \"embroidery_chest_left\",\n \"variant_ids\" : [\n 4020\n ]\n },\n {\n ...\n \"variant_ids\" : [\n 4035\n ]\n },\n {\n ...\n \"variant_ids\" : [\n 4015\n ]\n }\n ],\n \"printfiles\" : [\n {\n \"placement\" : \"embroidery_chest_left\",\n \"url\" : \"https://printful-upload.s3-accelerate.amazonaws.com/tmp/81aabb08df3df89bf67edbd0540fcbe1/printfile_embroidery_chest_left.png\",\n \"variant_ids\" : [\n 4020,\n 4035,\n 4015\n ]\n }\n ],\n \"status\" : \"completed\",\n \"task_key\" : \"gt-421709941\"\n }\n}\n```\n\nAnd that's it, now we have three mockups for each variant, one is an image of the front of the T-Shirt with no model,\nand the other two are the front of the T-Shirt with a model.\n\nThe only problem is that these default mockups only give me one kind of model or style\nTo change the style of my mockups I'll need to find the `options` and `option_groups` that will help create different mockup styles.\n\n### Options and Option Groups\n#### What are options and option_groups?\nIn the context of mockup generation `options`, generally speaking, refer to the part of the product being displayed.\n`option_groups` refers to the \"style\" of the mockup. For example \"Front\" refers to an `option` but \"Wrinkled\" or \"On Hanger\"\nare `option_groups`.\n\n#### Finding options and option_groups\nTo find what `options` and `option_groups` are available I make a request to `mockup-generator/printfiles/{product_id}`:\n\n```\ncurl --location --request GET 'https://api.printful.com/mockup-generator/printfiles/71' \\\n--header 'Authorization: Bearer {your_token}' \n```\nGiving the following response:\n```\n{\n \"code\" : 200,\n \"extra\" : [],\n \"result\" : {\n \"available_placements\" : {\n\t ...\n },\n \"option_groups\" : [\n \"Couple's\",\n \"Flat\",\n \"Flat 2\",\n \"Flat Lifestyle\",\n \"Folded\",\n \"Halloween\",\n \"Holiday season\",\n \"Men's\",\n \"Men's 2\",\n \"Men's 3\",\n \"Men's 4\",\n \"Men's 5\",\n \"Men's Lifestyle\",\n \"Men's Lifestyle 2\",\n \"Men's Lifestyle 3\",\n \"Men's Lifestyle 4\",\n \"On Hanger\",\n \"Product details\",\n \"Red, white & blue\",\n \"Spring/summer vibes\",\n \"Valentine's Day\",\n \"Women's\",\n \"Women's 2\",\n \"Women's 3\",\n \"Women's 4\",\n \"Women's 5\",\n \"Women's Lifestyle\",\n \"Women's Lifestyle 2\",\n \"Women's Lifestyle 3\",\n \"Wrinkled\"\n ],\n \"options\" : [\n \t ...\n \"Front\",\n\t ...\n ],\n \"printfiles\" : [\n ...\n ],\n \"product_id\" : 71,\n \"variant_printfiles\" : [\n\t...\n ]\n }\n}\n\n```\n\nI'd like to have mockups for both genders, so I've already created \"Men's\" mockups.\nSo, I can make the request again, specifying that I want the \"Women's\" `option_group`\n\n```\ncurl --location --request POST 'https://api.printful.com/mockup-generator/create-task/71' \\\n--header 'Authorization: Bearer {your_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"variant_ids\": [\n 4035,\n 4020,\n 4015\n ],\n \"files\": [\n { \n \"type\": \"embroidery_chest_left\",\n \"image_url\": \"https://upload.wikimedia.org/wikipedia/commons/0/06/Ercole_de%27_roberti%2C_san_michele_arcangelo_louvre_01.jpg\",\n \"position\": {\n\t \"area_width\": 1800,\n\t\t\"area_height\": 2400,\n\t\t\"width\": 1800,\n\t\t\"height\": 1800,\n\t\t\"top\": 300,\n\t\t\"left\": 0\n }\n }\n ],\n \"options\": [\"Front\"],\n \"option_groups\": [\"Women'\\''s\"]\n\n}'\n```\n\nRepeating the steps from before, results in new mockups for each variant, but now with a different model.\n\nIf I also want to receive additional styles (`option_groups`) I just need to add it to the option groups.\nFor example, these option groups will give me mockups for \"Men's 2\", \"Women's\" and \"Couple's\".\n```\n \"option_groups\": [\"Men's 2\", \"Women's\", \"Couple's\"]\n```\n\n#### Mismatched options\nIt is possible to add `options` or `option_groups` that don't produce any mockups.\n\nFor example, if I try and make the previous request with `\"options\": [\"Back\"]` I will\nreceive a `400` error:\n```\n{\n \"code\" : 400,\n \"error\" : {\n \"message\" : \"No variants to generate. Option filters may exclude all variants or variants are not available. Alternatively, make sure that variants belong to given product id.\",\n \"reason\" : \"BadRequest\"\n },\n \"result\" : \"No variants to generate. Option filters may exclude all variants or variants are not available. Alternatively, make sure that variants belong to given product id.\"\n}\n```\nThis is because all the print files are on the front, so Printful can't produce a mockup for the \"Back\".\n\nBut if our request had a print file on the back the request would succeed for. For example:\n```\ncurl --location --request POST 'https://api.printful.com/mockup-generator/create-task/71' \\\n--header 'Authorization: Bearer {your_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"variant_ids\": [\n 4035,\n 4020,\n 4015\n ],\n \"files\": [\n {\n \"type\": \"back\",\n \"image_url\": \"https://upload.wikimedia.org/wikipedia/commons/0/06/Ercole_de%27_roberti%2C_san_michele_arcangelo_louvre_01.jpg\",\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n }\n }\n ],\n \"options\": [\"Back\"],\n \"option_groups\": [\"Women'\\''s\"]\n\n}'\n```\n\n#### Multiple options and option_groups\nIt is also possible to have multiple `options`. For example, assuming we have the right variants and print files,\nthe following combination would produce mockups of the back and front of the product, for \"Men's\" \"Women's\".\n\n```\n \"options\": [\"Front\", \"Back\"],\n \"option_groups\": [\"Men's 2\", \"Women's\"]\n```\nHowever, you should attempt to limit the number of `options` and `option_groups` you provide here as much as possible.\nOtherwise, you may get combinations that don't match resulting in unexpected results that you won't see until after generation.\n\nThe following request will not give `400`, instead, it will produce the `\"Front\"` mockups and ignore the `\"Back\"`\nmockups.\n\n```\ncurl --location --request POST 'https://api.printful.com/mockup-generator/create-task/71' \\\n--header 'Authorization: Bearer {your_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"variant_ids\": [\n ...\n ],\n \"files\": [\n {\n \"type\": \"embroidery_chest_left\",\n ...\n }\n ],\n \"options\": [\"Front\", \"Back\"],\n \"option_groups\": [\"Men'\\''s 2\", \"Women'\\''s\"]\n}'\n```\nWithout the `400` message you may think you are producing mockups that are actually impossible to produce.\nIf these requests are part of a larger system, it could mean that you end up promising mockups\nto your users that are actually impossible.\n\nAdditionally, mockup generation can be slow, each new option group will add new mockups\nmultiplied by the amount of variants and options you have. In a user facing application\ngenerating too many mockups for users might be unacceptably slow.\n\n**It is usually safer to make multiple requests with limited than one large request that attempts to generate a large range of different mockups**\n\n### Next Steps\nNow that you've created a basic mockup try and create some mockups for your products.\nAfter that you can save the results somewhere on your server and use your new mockups however you like.\n\nYou could also update the `thumbnail` of one of your existing store products.\n\n```\ncurl --location --request PUT 'https://api.printful.com/store/products/{sync_product_id}' \\\n--header 'Authorization: Bearer {your_token}' \\\n--data-raw '{\n \"sync_product\": {\n \"thumbnail\": \"{url_of_your_new_mockup}\"\n }\n}'\n```\n\nIf you don't have any products in your store yet, check out our tutorial on that subject,\n[Creating products for your store through the API](#tag/Tutorials/Creating-products-for-your-store-through-the-API).\n[Make your first order through the API](#tag/Tutorials/Make-your-first-order-through-the-API).\n\n## Integrating with ECommerce Platforms through the API\n### Introduction\nIn this tutorial, we will show you how to integrate with your ECommerce Sync Products through the API. \nWe will retrieve our products, update sync variants, and send out notifications.\n\nSuppose we have a new store that is selling a range of products with a design that changes every year, \nit could be for a conference or maybe for a holiday like Christmas. We have a very large range of products and at the moment our designers have to update all the products manually every year. We want to offer our designers a way to update all of these products at once through the API.\n\n\n### Set up\n\nBefore anything else make sure you have created a store using one of our integrations.\nYou can choose a platform here: https://www.printful.com/dashboard/store/connect, and \nfind additional tutorials to help you set it up.\n\nAs well as this you will need to create an OAuth token for this store.\n\n- Go to the developer portal: https://developers.printful.com/login\n- Sign in with your Printful account\n- Go to this link: https://developers.printful.com/tokens/add-new-token\n- Make sure you have set access level to \"A single store\" and select your store\n- Make sure you have the following scopes selected for this tutorial:\n - `webhooks` (\"View and manage store webhooks\")\n - `sync_products` (\"View and manage store products\")\n- Fill in all other fields as you please\n- Create your token\n- You will receive an access key, you will only see the token once, store it securely\n\n### Limitations\nFor the most part, the ECommerce API works just like the Products API, but there are a couple of important limitations. \nThese limitations are explained here: https://developers.printful.com/docs/#tag/Ecommerce-Platform-Sync-API. But, for the \npurposes of this tutorial, the most important thing is that it’s not possible to create new sync products directly through the API.\n\n### Retrieving Products and Variants\nFirst, let's find the products from last year's Christmas sale\n\n```\ncurl --location --request GET 'https://api.printful.com/sync/products' \\\n--header 'Authorization: Bearer {your_token} \\ \n```\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"id\": 290959495,\n \"external_id\": \"christmas_636b6f729a37c7\",\n \"name\": \"Unisex t-shirt | Christmas\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://files.cdn.printful.com/files/thumbnail/christmas.png\",\n \"is_ignored\": false\n },\n ...\n ],\n \"extra\": [],\n \"paging\": {\n \"total\": 143,\n \"offset\": 0,\n \"limit\": 20\n }\n}\n```\n\nNow we will need to loop through these products to find the variants.\n\n```\ncurl --location --request GET 'https://api.printful.com/sync/products/{id} \\\n--header 'Authorization: Bearer {your_token} \\\n```\n\nFor that first product we might get a list of variants that looks like this\n```\n{\n \"code\": 200,\n \"result\": {\n \"sync_product\": {\n \"id\": 290959495,\n \"external_id\": \"636b6f729a37c7\",\n \"name\": \"Unisex t-shirt | Christmas\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://files.cdn.printful.com/files/6bf/6bfceb21e5fa7a854ff915ca66ca3a79_preview.png\",\n \"is_ignored\": false\n },\n \"sync_variants\": [\n {\n \"id\": 3590218032,\n \"external_id\": \"636b6f729a3867\",\n \"sync_product_id\": 290959495,\n \"name\": \"Unisex t-shirt | Christmas\",\n \"synced\": true,\n \"variant_id\": 9575,\n \"main_category_id\": 24,\n \"warehouse_product_id\": 330125,\n \"warehouse_product_variant_id\": 394380,\n \"retail_price\": \"37.25\",\n \"sku\": \"636B6F729A302\",\n \"currency\": \"EUR\",\n \"product\": {\n \"variant_id\": 9575,\n \"product_id\": 71,\n \"image\": \"https://s3-printful.stage.printful.dev/products/71/9575_1581408916.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (Black Heather / XS)\"\n },\n \"files\": [\n {\n \"id\": 490457488,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"https://example.com/file_for_christmas_2022.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1681472128,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true,\n \"is_temporary\": false\n }\n ],\n\n ],\n \"options\": [\n ...\n ],\n \"is_ignored\": false\n }\n ]\n },\n \"extra\": []\n}\n```\n\n### Updating a Sync Variant\nAs you can see from the request above the image is for 2022, https://example.com/file_for_christmas_2022.jpg,\nand we want to update so that we use the new 2023 image. For that all we need to do is send a PUT request to the endpoint\n\n```\ncurl --location --request PUT 'https://api.printful.com/sync/variant/3590218032' \\\n--header 'Authorization: Bearer {your_token} \\\n--data '{\n \"files\": [\n {\n \"type\": \"default\",\n \"url\": \"https://example.com/file_for_christmas_2023.jpg\"\n }\n ]\n}'\n```\n\nThis will replace the original 2022 files with the new 2023 files.\n\nNow, rather than changing each product individually the designers could simply \nsend you the new design, or use your custom UI. You will then be able to loop \nthrough all the relevant variants, replacing the old file for each variant.\n\n**Note** when looping through anything within the API remember to keep within the\n[rate limits](#section/About-the-Printful-API/Rate-Limits)\n\n### Setting Up a Webhook For Newly Synced Products\nWebhooks are another opportunity for the automation of your ECommmerce website through the API. \nSuppose you want to inform your customers everytime your team creates a new Sync Product. This can be automated using webhooks.\n\nFirst, you will need to listen for webhooks coming from Printful. We can’t help with setting up a server to do that,\nbut you can use our [webhook simulator](https://www.printful.com/api/webhook-simulator).\n\nThe webhook you will be listening for is: [**product_synced**](#operation/productSynced).\nTo configure the webhook make the following request\n\n```\ncurl --location -X POST 'https://api.printful.com/webhooks' \\\n--header 'Authorization: Bearer {your_token} \\\n--data '{\n \"url\": \"https://your.site/path/to/webhook-listener\",\n \"types\": [\n \"product_synced\"\n ]\n}'\n```\n\nNow, whenever a new product is synced to Printful, Printful will POST to the new product to that endpoint in this format:\n\n```\n{\n \"type\": \"product_synced\",\n \"created\": 1681473307,\n \"retries\": 1,\n \"store\": {your_store_id},\n \"data\": {\n \"sync_product\": {\n \"id\": 4567234,\n \"external_id\": \"christmas_collection-1234\",\n \"name\": \"Mug | Christmas\",\n \"variants\": 1,\n \"synced\": 1\n }\n }\n}\n```\nNow, whenever you receive the webhook you can send updates to your customers about the new product that was just synced.\n\n### Next steps\nAfter updating your products you may also want to [generate mockups through the Mockup Generator API](#tag/Tutorials/Creating-Mockups-in-the-API).\n\nIf you have a Native Store, you should check [our tutorial on the Store Products API](#tag/Tutorials/Creating-products-for-your-store-through-the-API)." }, { "name": "Errors", "description": "# General errors\n\n|
Code
|
Name
| Explanation |\n|:------------------------------------:|:-------------------------------------|:------------------------------------------------------------------------------------------------------------|\n| 401 | `UNAUTHORIZED` | Indicates that the endpoint requires authentication |\n| 403 | `FORBBIDEN` | Unauthorized requests. The client does not have access rights to the resource |\n| 404 | `NOT FOUND` | The server cannot find the requested resource |\n| 405 | `METHOD NOT ALLOWED` | The request `HTTP` method is known by the server but has been disabled and cannot be used for that resource |\n| 419 | `RATE LIMITED WARNING` | Returned by the API when the client is being rate limited |\n| 429 | `TOO MANY REQUESTS` | The user has sent too many requests in a given amount of time (_rate limiting_) |\n| 430 | `INVALID JSON` | The user has sent an invalid `JSON`. |\n| 431 | `INVALID PARAMETER` | The user has sent a parameter with the wrong `type` |\n\n# API Errors\n\n## Products API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| PR-1 | `MISSING_VARIANT_ID` | The required field `variant_id` must be present |\n| PR-2 | `WAREHOUSE_VARIANT_NOT_AVAILABLE` | The `warehouse_variant_id` provided in the `sync_variant` object is not available at the moment |\n| PR-3 | `WAREHOUSE_VARIANT_NOT_APPROVED` | The warehouse `variant` related to the provided `warehouse_variant_id` wasn't approved |\n| PR-4 | `WAREHOUSE_PRODUCT_NOT_APPROVED` | The warehouse `product` related to the provided `warehouse_variant_id` wasn't approved |\n| PR-5 | `SYNC_PRODUCT_SOFT_DELETED` | The `sync_product` related to the provided `id` doesn't have any `sync_variants` related. Please add at least one `sync_variant` |\n| PR-6 | `INVALID_FILTER_STATUS` | The provided `status` is not a valid filter. Must be one of the following: `all`, `synced`, `unsynced`, `ignored`, `imported`, `discontinued`, `out_of_stock` |\n\n## Orders API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------|:---------------------------------------------------------------------------------------------------------------------|\n| OR-1 | `ORDER_NO_LONGER_EDITABLE` | The `order` is no longer editable. To be editable via API must have one of the following statuses: `DRAFT`, `FAILED` |\n| OR-2 | `STORE_TERMINATED` | The `store` related to the account is terminated |\n| OR-3 | `INCOMPATIBLE_ORDER_OPTIONS` | The `order` cannot be confirmed and saved as a draft at the same time. |\n| OR-4 | `INVALID_SHIPPING_METHOD` | The shipping method selected for the `order` is invalid or not supported |\n| OR-5 | `INVALID_ORDER_ITEM` | The `item` provided is not an array |\n| OR-6 | `RESTRICTED_VARIANT` | The `variant` that you are trying to order is currently restricted |\n| OR-7 | `INCOMPATIBLE_SYNC_VARIANT_ITEM` | Associating Sync Variant with the existing `item` is not allowed |\n| OR-8 | `INCOMPATIBLE_PRODUCT_TEMPLATE` | Associating the Product Template with the existing `item` is not allowed |\n| OR-9 | `LIMITED_SHIPPING_SERVICE` | The `product` related to the provided `product_id` can be only ordered to the US territory |\n| OR-10 | `UNSUPPORTED_FILE_TYPE` | The file `type` provided is not supported via API |\n| OR-11 | `MULTIPLE_LABEL_PRODUCT` | Inside and outside labels can't be combined with each other on the same `product` |\n| OR-12 | `DUPLICATED_FILE_TYPE` | The provided `item` contains multiple files for `placement` |\n| OR-13 | `EXTERNAL_ID_IN_USE` | The `external_id` provided already exists and cannot be used |\n\n## File Library API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------------------------|:----------------------------------------------------------|\n| FL-1 | `INVALID_FILE_FORMAT` | The URL provided returns a `file` with an invalid format |\n| FL-2 | `INVALID_FILE_URL` | The `file` URL provided is invalid |\n| FL-3 | `UNKNOW_FILE_ID` | The `file` ID provided was not found |\n| FL-4 | `FILE_NOT_ACCESIBLE` | The specified `file` does not belong to this `store` |\n| FL-5 | `PRINT_FILE_PREVIEW` | Temporary print file preview `file` cannot be used |\n| FL-6 | `FILE_LICENSED_ASSETS` | Print files with `licensed assets` cannot be used |\n| FL-7 | `INVALID_FILE_DATA` | Posted `file` data doesn't contain valid image data |\n| FL-8 | `MISSING_URL_DATA` | The fields `url` or `data` must be present in the request |\n| FL-9 | `FAILED_FILE_THREAD_COLORS` | The `file` image could not be processed |\n\n\n## Shipping Rates API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------------------------|:----------------------------------------------------------------------|\n| SH-1 | `INVALID_COUNTRY_CODE` | The `country_code` provided is invalid or missing |\n| SH-2 | `SHIPPING_DISABLED` | This happens when the shipping is disabled to the `country` specified |\n| SH-3 | `INVALID_CURRENCY_CODE` | The `currency_code` provided is invalid or not supported |\n\n\n## Ecommerce platform Sync API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| EC-1 | `INVALID_FILTER_STATUS` | The provided `status` is not a valid filter. Must be one of the following: `all`, `synced`, `unsynced`, `ignored`, `imported`, `discontinued`, `out_of_stock` |\n| EC-2 | `INVALID_PARAMETER_LENGTH` | The `search` parameter should be at least 3 characters long |\n| EC-3 | `INVALID_OPTIONS_ELEMENT` | The `options` field is incorrect or invalid |\n| EC-4 | `NON_LABEL_FILES_MISSING` | Non-label `files` must be provided for this `product` |\n| EC-5 | `UNSUPPORTED_INTEGRATION_SYNC` | The integration of this `store` (_store name_) does not support syncing Printful `items`. |\n| EC-6 | `JEWELRY_PRODUCTS_NOT_AVAILABLE` | The jewelry `products` are not available with this endpoint. |\n\n\n## Tax Rate API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------|:---------------------------------------------------------|\n| TR-1 | `MISSING_RECIPIENT` | The `recipient` parameter must be present in the payload |\n| TR-2 | `RECIPIENT_ERRORS` | Related to the collected errors found in the `recipient` |\n\n\n## Store Information API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------|:-------------------------------|\n| SI-1 | `INVALID_PACKING_SLIP` | The `data` provided is invalid |\n\n## Mockup Generator API\n\n|
Code
|
Name
| Explanation |\n|:-----------------------------------:|:-------------------------------------|:------------------------------------------------------------------|\n| MG-1 | `INVALID_ORIENTATION` | Invalid `orientation` given |\n| MG-2 | `INVALID_TECHNIQUE` | Invalid `technique` given |\n| MG-3 | `UNAVAILABLE_GENERATOR_PRODUCT` | The mockup generator is not available for the `product` specified |\n| MG-4 | `GENERATOR_PRODUCT` | Related to general errors in the `payload` |\n| MG-5 | `INVALID_FORMAT` | The specified `format` is invalid |\n| MG-6 | `INVALID_WIDTH` | The specified `width` is invalid |\n| MG-7 | `MISSING_REQUIRED_OPTION` | Either `file` array or `product_template_id` should be present |\n| MG-8 | `DAILY_ALLOWANCE_EXCEEDED` | The daily file count allowance is exceeded |" }, { "name": "Examples", "description": "# Catalog API examples\n\n### API Flow Overview\n\nHere's a quick visual overview of how your system communicates with Printful's API during the order creation flow:\n\n![Authentication setup](images/tutorial/api-integration/authentication_setup.png)\n![OAuth integration flow](images/tutorial/api-integration/oauth_integration.png)\n![Order creation and fulfillment](images/tutorial/api-integration/order_creation.png)\n![Webhook handling](images/tutorial/api-integration/product_management.png)\n![Product management](images/tutorial/api-integration/webhook_handling.png)\n\n### Entity Relationship Reference\n\nThe following diagram shows key API entities:\n\n![Entity relationship diagram](images/tutorial/entity_relationship_diagram.png)\n\n## Filter products by single category ID\n\nThe IDs of the categories may be retrieved using the `GET /categories` endpoint. We're going to list products belonging\nto the \"Samsung cases\" category (ID: 62).\n\nRequest URL: https://api.printful.com/products?category_id=62\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"id\": 267,\n \"type\": \"PHONE-CASE\",\n \"type_name\": \"Samsung Case\",\n \"title\": \"Samsung Case\",\n \"brand\": null,\n \"model\": \"Samsung Case\",\n \"image\": \"https://s3-printful.stage.printful.dev/upload/product-catalog-img/7c/7c7a0c9bba1ab7ead3c03753adc262b6_l\",\n \"variant_count\": 13,\n \"currency\": \"USD\",\n \"options\": [],\n \"dimensions\": null,\n \"is_discontinued\": false,\n \"avg_fulfillment_time\": null,\n \"techniques\": [\n {\n \"key\": \"UV\",\n \"display_name\": \"UV printing\",\n \"is_default\": true\n }\n ],\n \"files\": [\n {\n \"id\": \"default\",\n \"type\": \"default\",\n \"title\": \"Print file\",\n \"additional_price\": null\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null\n }\n ],\n \"description\": \"This sleek Samsung case protects your phone from scratches, dust, oil, and dirt. It has a solid back and flexible sides that make it easy to take on and off, with precisely aligned cuts and holes. \\r\\n\\r\\n• BPA free Hybrid Thermoplastic Polyurethane (TPU) and Polycarbonate (PC) material\\r\\n• Solid polycarbonate back\\r\\n• 0.02″ (0.5 mm) raised bezel\\r\\n• See-through sides\\r\\n• Wireless charging compatible\\r\\n• Easy to take on and off\"\n }\n ],\n \"extra\": []\n}\n```\n\n
\n\n## Filter products by multiple category IDs\n\nThe following request will fetch iPhone cases (ID: 50) and Samsung cases (ID: 62).\n\nRequest URL: https://api.printful.com/products?category_id=50,62\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"id\": 424,\n \"type\": \"PHONE-CASE\",\n \"type_name\": \"Eco iPhone Case\",\n \"title\": \"Biodegradable iPhone Case\",\n \"brand\": null,\n \"model\": \"Eco iPhone Case\",\n \"image\": \"https://s3-printful.stage.printful.dev/upload/product-catalog-img/07/07eabbd80051c972d900332d5523dc5a_l\",\n \"variant_count\": 14,\n \"currency\": \"USD\",\n \"options\": [],\n \"dimensions\": null,\n \"is_discontinued\": false,\n \"avg_fulfillment_time\": null,\n \"techniques\": [\n {\n \"key\": \"UV\",\n \"display_name\": \"UV printing\",\n \"is_default\": true\n }\n ],\n \"files\": [\n {\n \"id\": \"default\",\n \"type\": \"default\",\n \"title\": \"Print file\",\n \"additional_price\": null\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null\n }\n ],\n \"description\": \"Protect your phone and the environment all in one go—this phone case is eco-friendly and 100% biodegradable. Cover your phone with a unique case to protect it from bumps and scratches in style.\\r\\n\\r\\n• 100% biodegradable material\\r\\n• Components: soil (30%), onions (7.5%), carrots (7.5%), pepper (7.5%), sawdust (1.5%), rice (18%), soybeans (18%), wheat (10%)\\r\\n• Anti-shock protection\\r\\n• Thickness over 1.8mm\\r\\n• Decomposes in ~1 year\\r\\n• Packaged in a degradable and protective CPE 07 bag and shipped in a carton box\\r\\n• The SE case fits the 2020 iPhone SE model\\r\\n• Blank product sourced from China \"\n },\n {\n \"id\": 181,\n \"type\": \"PHONE-CASE\",\n \"type_name\": \"iPhone Case\",\n \"title\": \"iPhone Case\",\n \"brand\": null,\n \"model\": \"iPhone Case\",\n \"image\": \"https://s3-printful.stage.printful.dev/products/181/product_1570615955.jpg\",\n \"variant_count\": 17,\n \"currency\": \"USD\",\n \"options\": [],\n \"dimensions\": {\n \"default\": \"2.93x6.1\"\n },\n \"is_discontinued\": false,\n \"avg_fulfillment_time\": null,\n \"techniques\": [\n {\n \"key\": \"UV\",\n \"display_name\": \"UV printing\",\n \"is_default\": true\n }\n ],\n \"files\": [\n {\n \"id\": \"default\",\n \"type\": \"default\",\n \"title\": \"Print file\",\n \"additional_price\": null\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null\n }\n ],\n \"description\": \"This sleek iPhone case protects your phone from scratches, dust, oil, and dirt. It has a solid back and flexible sides that make it easy to take on and off, with precisely aligned port openings. \\r\\n\\r\\n• BPA free Hybrid Thermoplastic Polyurethane (TPU) and Polycarbonate (PC) material\\r\\n• Solid polycarbonate back\\r\\n• Flexible, see-through polyurethane sides\\r\\n• .5 mm raised bezel\\r\\n• Precisely aligned port openings\\r\\n• Easy to take on and off\\r\\n• Wireless charging compatible\\r\\n• The SE case fits the 2020 iPhone SE model\\r\\n• Blank product sourced from China\"\n },\n {\n \"id\": 267,\n \"type\": \"PHONE-CASE\",\n \"type_name\": \"Samsung Case\",\n \"title\": \"Samsung Case\",\n \"brand\": null,\n \"model\": \"Samsung Case\",\n \"image\": \"https://s3-printful.stage.printful.dev/upload/product-catalog-img/7c/7c7a0c9bba1ab7ead3c03753adc262b6_l\",\n \"variant_count\": 13,\n \"currency\": \"USD\",\n \"options\": [],\n \"dimensions\": null,\n \"is_discontinued\": false,\n \"avg_fulfillment_time\": null,\n \"techniques\": [\n {\n \"key\": \"UV\",\n \"display_name\": \"UV printing\",\n \"is_default\": true\n }\n ],\n \"files\": [\n {\n \"id\": \"default\",\n \"type\": \"default\",\n \"title\": \"Print file\",\n \"additional_price\": null\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null\n }\n ],\n \"description\": \"This sleek Samsung case protects your phone from scratches, dust, oil, and dirt. It has a solid back and flexible sides that make it easy to take on and off, with precisely aligned cuts and holes. \\r\\n\\r\\n• BPA free Hybrid Thermoplastic Polyurethane (TPU) and Polycarbonate (PC) material\\r\\n• Solid polycarbonate back\\r\\n• 0.02″ (0.5 mm) raised bezel\\r\\n• See-through sides\\r\\n• Wireless charging compatible\\r\\n• Easy to take on and off\"\n }\n ],\n \"extra\": []\n}\n```\n\n
\n\n## Using size guides\n\nIn this example, we'll fetch the size guides for the\n\"Women's Basic Organic T-Shirt | SOL'S 02077\" product (ID: 561).\n\nWe use the default `en_US` locale and don't provide the `unit` parameter, so the measurement values will be returned in\ninches.\n\nURL: https://api.printful.com/products/561/sizes\n\n
\n Whole response body\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product_id\": 561,\n \"available_sizes\": [\n \"S\",\n \"M\",\n \"L\",\n \"XL\",\n \"2XL\"\n ],\n \"size_tables\": [\n {\n \"type\": \"measure_yourself\",\n \"unit\": \"inches\",\n \"description\": \"

Measurements are provided by suppliers.

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Product measurements may vary by up to 2\\\" (5 cm). 

\",\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/measure-yourself/6a/6a4fe322f592f2b91d5a735d7ff8d1c0_t?v=1652962720\",\n \"image_description\": \"
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Chest
\\n

Measure yourself around the fullest part of your chest. Keep the tape measure horizontal.

\",\n \"measurements\": [\n {\n \"type_label\": \"Length\",\n \"values\": [\n {\n \"size\": \"S\",\n \"value\": \"25.2\"\n },\n {\n \"size\": \"M\",\n \"value\": \"26\"\n },\n {\n \"size\": \"L\",\n \"value\": \"26.7\"\n },\n {\n \"size\": \"XL\",\n \"value\": \"27.6\"\n },\n {\n \"size\": \"2XL\",\n \"value\": \"28.3\"\n }\n ]\n },\n {\n \"type_label\": \"Chest\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"34\",\n \"max_value\": \"37\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"36\",\n \"max_value\": \"39\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"39\",\n \"max_value\": \"42\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"41\",\n \"max_value\": \"44\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"43\",\n \"max_value\": \"46\"\n }\n ]\n }\n ]\n },\n {\n \"type\": \"product_measure\",\n \"unit\": \"inches\",\n \"description\": \"

Measurements are provided by our suppliers. Product measurements may vary by up to 2\\\" (5 cm).

\\n

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Pro tip! Measure one of your products at home and compare with the measurements you see in this guide.

\",\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/product-measure/85/857e7cc8b802da216e7f1a6114075a72_t?v=1652962720\",\n \"image_description\": \"
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Width
\\n

Place the end of the tape at the seam under the sleeve and pull the tape measure across the shirt to the seam under the opposite sleeve.

\",\n \"measurements\": [\n {\n \"type_label\": \"Length\",\n \"values\": [\n {\n \"size\": \"S\",\n \"value\": \"25.2\"\n },\n {\n \"size\": \"M\",\n \"value\": \"26\"\n },\n {\n \"size\": \"L\",\n \"value\": \"26.7\"\n },\n {\n \"size\": \"XL\",\n \"value\": \"27.6\"\n },\n {\n \"size\": \"2XL\",\n \"value\": \"28.3\"\n }\n ]\n },\n {\n \"type_label\": \"Width\",\n \"values\": [\n {\n \"size\": \"S\",\n \"value\": \"16.1\"\n },\n {\n \"size\": \"M\",\n \"value\": \"17.3\"\n },\n {\n \"size\": \"L\",\n \"value\": \"18.5\"\n },\n {\n \"size\": \"XL\",\n \"value\": \"19.7\"\n },\n {\n \"size\": \"2XL\",\n \"value\": \"20.9\"\n }\n ]\n }\n ]\n },\n {\n \"type\": \"international\",\n \"unit\": \"none\",\n \"measurements\": [\n {\n \"type_label\": \"US size\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"6\",\n \"max_value\": \"8\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"10\",\n \"max_value\": \"12\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"14\",\n \"max_value\": \"16\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"18\",\n \"max_value\": \"20\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"22\",\n \"max_value\": \"24\"\n }\n ]\n },\n {\n \"type_label\": \"EU size\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"36\",\n \"max_value\": \"38\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"40\",\n \"max_value\": \"42\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"44\",\n \"max_value\": \"46\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"48\",\n \"max_value\": \"50\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"52\",\n \"max_value\": \"54\"\n }\n ]\n },\n {\n \"type_label\": \"UK size\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"10\",\n \"max_value\": \"12\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"14\",\n \"max_value\": \"16\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"18\",\n \"max_value\": \"20\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"22\",\n \"max_value\": \"24\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"26\",\n \"max_value\": \"28\"\n }\n ]\n }\n ]\n }\n ]\n },\n \"extra\": []\n}\n```\n\n
\n\nNow, we'll take a closer look at the objects related to all three types of size tables.\n\n### Measure yourself size table\n\nThis object provides all measurements for the end customers to be able to measure themselves and see what size they\nshould buy.\n\n
\n The corresponding response fragment\n\n```\n...\n{\n \"type\": \"measure_yourself\",\n \"unit\": \"inches\",\n \"description\": \"

Measurements are provided by suppliers.

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Product measurements may vary by up to 2\\\" (5 cm). 

\",\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/measure-yourself/6a/6a4fe322f592f2b91d5a735d7ff8d1c0_t?v=1652962720\",\n \"image_description\": \"
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Chest
\\n

Measure yourself around the fullest part of your chest. Keep the tape measure horizontal.

\",\n \"measurements\": [\n {\n \"type_label\": \"Length\",\n \"values\": [\n {\n \"size\": \"S\",\n \"value\": \"25.2\"\n },\n {\n \"size\": \"M\",\n \"value\": \"26\"\n },\n {\n \"size\": \"L\",\n \"value\": \"26.7\"\n },\n {\n \"size\": \"XL\",\n \"value\": \"27.6\"\n },\n {\n \"size\": \"2XL\",\n \"value\": \"28.3\"\n }\n ]\n },\n {\n \"type_label\": \"Chest\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"34\",\n \"max_value\": \"37\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"36\",\n \"max_value\": \"39\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"39\",\n \"max_value\": \"42\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"41\",\n \"max_value\": \"44\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"43\",\n \"max_value\": \"46\"\n }\n ]\n }\n ]\n},\n...\n```\n\n
\n\nThe measurement image with the descriptions for the product as seen in the web version of the size guides:\n\n![Image](images/size-guides/my_measurement_image.png)\n\nThe size chart from the web version:\n\n![Image](images/size-guides/my_size_chart.png)\n\n### Product measurements size table\n\nThis object provides all product measurements so the end customer can measure a product they own and see what size they\nshould buy.\n\n
\n The corresponding response fragment\n\n```\n...\n{\n \"type\": \"product_measure\",\n \"unit\": \"inches\",\n \"description\": \"

Measurements are provided by our suppliers. Product measurements may vary by up to 2\\\" (5 cm).

\\n

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Pro tip! Measure one of your products at home and compare with the measurements you see in this guide.

\",\n \"image_url\": \"https://s3-printful.stage.printful.dev/upload/product-measure/85/857e7cc8b802da216e7f1a6114075a72_t?v=1652962720\",\n \"image_description\": \"
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Width
\\n

Place the end of the tape at the seam under the sleeve and pull the tape measure across the shirt to the seam under the opposite sleeve.

\",\n \"measurements\": [\n {\n \"type_label\": \"Length\",\n \"values\": [\n {\n \"size\": \"S\",\n \"value\": \"25.2\"\n },\n {\n \"size\": \"M\",\n \"value\": \"26\"\n },\n {\n \"size\": \"L\",\n \"value\": \"26.7\"\n },\n {\n \"size\": \"XL\",\n \"value\": \"27.6\"\n },\n {\n \"size\": \"2XL\",\n \"value\": \"28.3\"\n }\n ]\n },\n {\n \"type_label\": \"Width\",\n \"values\": [\n {\n \"size\": \"S\",\n \"value\": \"16.1\"\n },\n {\n \"size\": \"M\",\n \"value\": \"17.3\"\n },\n {\n \"size\": \"L\",\n \"value\": \"18.5\"\n },\n {\n \"size\": \"XL\",\n \"value\": \"19.7\"\n },\n {\n \"size\": \"2XL\",\n \"value\": \"20.9\"\n }\n ]\n }\n ]\n},\n...\n```\n\n
\n\nThe measurement image with the descriptions for the product as seen in the web version of the size guides:\n\n![Image](images/size-guides/pm_measurement_image.png)\n\nThe size chart from the web version:\n\n![Image](images/size-guides/pm_size_chart.png)\n\n### International size conversion\n\nThis object provides information what international (US, EU, UK) sizes correspond to the product sizes.\n\n
\n The corresponding response fragment\n\n```\n...\n{\n \"type\": \"international\",\n \"unit\": \"none\",\n \"measurements\": [\n {\n \"type_label\": \"US size\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"6\",\n \"max_value\": \"8\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"10\",\n \"max_value\": \"12\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"14\",\n \"max_value\": \"16\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"18\",\n \"max_value\": \"20\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"22\",\n \"max_value\": \"24\"\n }\n ]\n },\n {\n \"type_label\": \"EU size\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"36\",\n \"max_value\": \"38\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"40\",\n \"max_value\": \"42\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"44\",\n \"max_value\": \"46\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"48\",\n \"max_value\": \"50\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"52\",\n \"max_value\": \"54\"\n }\n ]\n },\n {\n \"type_label\": \"UK size\",\n \"values\": [\n {\n \"size\": \"S\",\n \"min_value\": \"10\",\n \"max_value\": \"12\"\n },\n {\n \"size\": \"M\",\n \"min_value\": \"14\",\n \"max_value\": \"16\"\n },\n {\n \"size\": \"L\",\n \"min_value\": \"18\",\n \"max_value\": \"20\"\n },\n {\n \"size\": \"XL\",\n \"min_value\": \"22\",\n \"max_value\": \"24\"\n },\n {\n \"size\": \"2XL\",\n \"min_value\": \"26\",\n \"max_value\": \"28\"\n }\n ]\n }\n ]\n}\n...\n```\n\n
\n\nThe international size conversion table from the web version:\n\n![Image](images/size-guides/international_sizes.png)\n\n## Product containing Unlimited Color option\n\nThe following request will fetch Bella Canvas 3001 product (ID: 71).\n\nRequest URL: https://api.printful.com/products/71\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product\": {\n \"id\": 71,\n \"main_category_id\": 24,\n \"type\": \"T-SHIRT\",\n \"description\": \"This t-shirt is everything you've dreamed of and more. It feels soft and lightweight, with the right amount of stretch. It's comfortable and flattering for all. \\n\\n• 100% combed and ring-spun cotton (Heather colors contain polyester)\\n• Fabric weight: 4.2 oz/yd² (142 g/m²)\\n• Pre-shrunk fabric\\n• Side-seamed construction\\n• Shoulder-to-shoulder taping\\n• Blank product sourced from Guatemala, Nicaragua, Mexico, Honduras, or the US\",\n \"type_name\": \"T-Shirt\",\n \"title\": \"Unisex Staple T-Shirt | Bella + Canvas 3001\",\n \"brand\": \"Bella + Canvas\",\n \"model\": \"3001 Unisex Short Sleeve Jersey T-Shirt\",\n \"image\": \"https://s3-printful.stage.printful.dev/upload/product-catalog-img/20/2079a3ee4cc472ad952fe16654f274cd_l\",\n \"variant_count\": 378,\n \"currency\": \"EUR\",\n \"options\": [\n ...\n ],\n \"dimensions\": null,\n \"is_discontinued\": false,\n \"avg_fulfillment_time\": null,\n \"techniques\": [\n {\n \"key\": \"EMBROIDERY\",\n \"display_name\": \"Embroidery\",\n \"is_default\": false\n },\n {\n \"key\": \"DTG\",\n \"display_name\": \"DTG printing\",\n \"is_default\": true\n }\n ],\n \"files\": [\n {\n \"id\": \"embroidery_chest_left\",\n \"type\": \"embroidery_chest_left\",\n \"title\": \"Left chest\",\n \"additional_price\": \"2.60\",\n \"options\": [\n {\n \"id\": \"full_color\",\n \"type\": \"bool\",\n \"title\": \"Unlimited color\",\n \"additional_price\": 3.25\n }\n ]\n },\n {\n \"id\": \"embroidery_chest_center\",\n \"type\": \"embroidery_chest_center\",\n \"title\": \"Center chest\",\n \"additional_price\": \"2.60\",\n \"options\": [\n {\n \"id\": \"full_color\",\n \"type\": \"bool\",\n \"title\": \"Unlimited color\",\n \"additional_price\": 3.25\n }\n ]\n },\n {\n \"id\": \"embroidery_sleeve_left_top\",\n \"type\": \"embroidery_sleeve_left_top\",\n \"title\": \"Left sleeve top\",\n \"additional_price\": \"2.60\",\n \"options\": []\n },\n {\n \"id\": \"embroidery_sleeve_right_top\",\n \"type\": \"embroidery_sleeve_right_top\",\n \"title\": \"Right sleeve top\",\n \"additional_price\": \"2.60\",\n \"options\": []\n },\n {\n \"id\": \"default\",\n \"type\": \"front\",\n \"title\": \"Front print\",\n \"additional_price\": null,\n \"options\": []\n },\n {\n \"id\": \"front_large\",\n \"type\": \"front_large\",\n \"title\": \"Large front print\",\n \"additional_price\": \"5.25\",\n \"options\": []\n },\n {\n \"id\": \"back\",\n \"type\": \"back\",\n \"title\": \"Back print\",\n \"additional_price\": \"5.25\",\n \"options\": []\n },\n {\n \"id\": \"label_outside\",\n \"type\": \"label_outside\",\n \"title\": \"Outside label\",\n \"additional_price\": \"2.20\",\n \"options\": []\n },\n {\n \"id\": \"label_inside\",\n \"type\": \"label_inside\",\n \"title\": \"Inside label\",\n \"additional_price\": \"2.20\",\n \"options\": []\n },\n {\n \"id\": \"sleeve_left\",\n \"type\": \"sleeve_left\",\n \"title\": \"Left sleeve\",\n \"additional_price\": \"2.20\",\n \"options\": []\n },\n {\n \"id\": \"sleeve_right\",\n \"type\": \"sleeve_right\",\n \"title\": \"Right sleeve\",\n \"additional_price\": \"2.20\",\n \"options\": []\n },\n {\n \"id\": \"preview\",\n \"type\": \"mockup\",\n \"title\": \"Mockup\",\n \"additional_price\": null,\n \"options\": []\n }\n ],\n \"catalog_categories\": {\n \"0\": 24,\n \"1\": 1,\n \"2\": 2,\n \"3\": 6,\n \"4\": 8,\n \"5\": 32,\n \"6\": 85,\n \"7\": 89,\n \"10\": 155,\n \"11\": 164,\n \"12\": 188,\n \"13\": 213,\n \"14\": 226,\n \"15\": 227,\n \"16\": 233,\n \"17\": 234,\n \"18\": 260\n }\n },\n \"variants\": [\n ...\n ]\n },\n \"extra\": [],\n}\n```\n\n
\n\n# Products API examples\n\n## Create a new Sync Product\n\n### Using multiple placements\n\nRequest body:\n\n```\n{\n \"sync_product\": {\n \"name\": \"API product Bella\",\n \"thumbnail\": \"https://example.com/image.jpg\"\n },\n \"sync_variants\": [\n {\n \"retail_price\": \"21.00\",\n \"variant_id\": 4011,\n \"files\": [\n {\n \"url\": \"https://example.com/image.jpg\"\n },\n {\n \"type\": \"back\",\n \"url\": \"https://example.com/image.jpg\"\n }\n ]\n },\n {\n \"retail_price\": \"21.00\",\n \"variant_id\": 4012,\n \"files\": [\n {\n \"url\": \"https://example.com/image.jpg\"\n },\n {\n \"type\": \"back\",\n \"url\": \"https://example.com/image.jpg\"\n }\n ]\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 79348732,\n \"external_id\": \"5bd9947c709b34\",\n \"name\": \"API product Bella\",\n \"variants\": 2,\n \"synced\": 2\n }\n}\n```\n
\n\n### Using inside label\n\nCreate a new Sync Product with native inside label.\n\nRequest body:\n\n```\n{\n \"sync_product\": {\n \"name\": \"API product custom\"\n },\n \"sync_variants\": [\n {\n \"retail_price\": \"19.00\",\n \"variant_id\": 9575,\n \"files\": [\n {\n \"type\": \"front\",\n \"url\": \"https://picsum.photos/200/300\"\n },\n {\n \"type\": \"label_inside\",\n \"url\": \"https://picsum.photos/200/300\",\n \"options\": [{\n \"id\": \"template_type\",\n \"value\": \"native\"\n }]\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ]\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 166266931,\n \"external_id\": \"5e8db0013cf026\",\n \"name\": \"API product custom\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": null\n }\n}\n```\n
\n\n## Modify a Sync Product\n\nUpdate a Sync Product's Name and Thumbnail.\n\nRequest body:\n\n```\n{\n \"sync_product\": {\n \"name\": \"API product new name\",\n \"thumbnail\": \"https://example.com/image.jpg\"\n }\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 79348721,\n \"external_id\": \"e9460f6c67\",\n \"name\": \"API product new name\",\n \"variants\": 2,\n \"synced\": 2\n }\n}\n```\n
\n\nUpdate a Sync Product and one of its Sync Variants.\n\nRequest body:\n\n```\n{\n \"sync_product\": {\n \"name\": \"API product new name\",\n \"thumbnail\": \"https://example.com/image.jpg\"\n },\n \"sync_variants\": [\n {\n \"id\": 866914574\n },\n {\n \"id\": 866914580,\n \"retail_price\": 21,\n \"files\": [\n {\n \"url\": \"https://example.com/image.jpg\"\n },\n {\n \"type\": \"back\",\n \"url\": \"https://example.com/image.jpg\"\n }\n ]\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 79348721,\n \"external_id\": \"e9460f6c67\",\n \"name\": \"API product\",\n \"variants\": 2,\n \"synced\": 2\n }\n}\n```\n
\n\n## Modify a Sync Variant\n\nUpdate price of an existing Sync Variant.\n\nRequest body:\n\n```\n{\n \"retail_price\": \"29.00\"\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 866914574,\n \"external_id\": \"5bd967595a1174\",\n \"sync_product_id\": 79348721,\n \"name\": \"API product\",\n \"synced\": true,\n \"variant_id\": 4011,\n \"retail_price\": \"29.00\",\n \"currency\": \"\",\n \"product\": {\n \"variant_id\": 4011,\n \"product_id\": 71,\n \"image\": \"https://s3.dev.printful.com/products/71/4012_1517927381.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)\"\n },\n \"files\": [\n {\n \"id\": 76564075,\n \"type\": \"default\",\n \"hash\": \"7d6a2367c1e338750e68dc66b20cba1a\",\n \"url\": \"https://example.com/image.jpg\",\n \"filename\": \"76564075.jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 8245,\n \"width\": 200,\n \"height\": 300,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1539341673,\n \"thumbnail_url\": \"https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png\",\n \"preview_url\": \"https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png\",\n \"visible\": true\n },\n {\n \"id\": 76564075,\n \"type\": \"back\",\n \"hash\": \"7d6a2367c1e338750e68dc66b20cba1a\",\n \"url\": \"https://example.com/image.jpg\",\n \"filename\": \"76564075.jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 8245,\n \"width\": 200,\n \"height\": 300,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1539341673,\n \"thumbnail_url\": \"https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png\",\n \"preview_url\": \"https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png\",\n \"visible\": true\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ]\n }\n}\n```\n\n
\n\nAdd a native inside label to an existing Sync Variant.\n\nRequest body:\n\n```\n{\n \"files\": [\n {\n \"type\": \"label_inside\",\n \"url\": \"https://picsum.photos/200/300\",\n \"options\": [{\n \"id\": \"template_type\",\n \"value\": \"native\"\n }]\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 1817548049,\n \"external_id\": \"5e8dbb006e62d5\",\n \"sync_product_id\": 162979476,\n \"name\": \"lucia - White / XL\",\n \"synced\": true,\n \"variant_id\": 4014,\n \"retail_price\": \"19.00\",\n \"currency\": \"USD\",\n \"product\": {\n \"variant_id\": 4014,\n \"product_id\": 71,\n \"image\": \"https://s3.dev.printful.com/products/71/4014_1581412553.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / XL)\"\n },\n \"files\": [\n {\n \"id\": 185425196,\n \"type\": \"label_inside\",\n \"hash\": null,\n \"url\": \"https://picsum.photos/200/300\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1586351368,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n },\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"text_thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n },\n {\n \"id\": \"text_thread_colors_chest_left\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_center\",\n \"value\": []\n },\n {\n \"id\": \"text_thread_colors_chest_center\",\n \"value\": []\n }\n ]\n }\n}\n```\n\n
\n\nUpdate the variant t-shirt to have only front print instead of both front and back prints.\n\nRequest body:\n\n```\n{\n \"files\": [\n {\n \"type\": \"default\",\n \"url\": \"https://example.com/image.jpg\"\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 866914574,\n \"external_id\": \"5bd967595a1174\",\n \"sync_product_id\": 79348721,\n \"name\": \"API product\",\n \"synced\": true,\n \"variant_id\": 4011,\n \"retail_price\": \"29.00\",\n \"currency\": \"\",\n \"product\": {\n \"variant_id\": 4011,\n \"product_id\": 71,\n \"image\": \"https://s3.dev.printful.com/products/71/4012_1517927381.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)\"\n },\n \"files\": [\n {\n \"id\": 76564159,\n \"type\": \"default\",\n \"hash\": \"ebd559858e5703088de8900ce99c37d3\",\n \"url\": \"https://example.com/image.jpg\",\n \"filename\": \"76564159.jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 11246,\n \"width\": 200,\n \"height\": 300,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1540797879,\n \"thumbnail_url\": \"https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_thumb.png\",\n \"preview_url\": \"https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_preview.png\",\n \"visible\": true\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ]\n }\n}\n```\n\n
\n\n## Create a new Sync Variant\n\nRequest body:\n\n```\n{\n \"external_id\": \"my-external-id\",\n \"retail_price\": \"19.00\",\n \"variant_id\": 4011,\n \"files\": [\n {\n \"type\": \"default\",\n \"url\": \"https://example.com/image.jpg\"\n },\n {\n \"type\": \"back\",\n \"url\": \"https://example.com/image.jpg\"\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 866914592,\n \"external_id\": \"my-external-id\",\n \"sync_product_id\": 79348732,\n \"name\": \"API product Bella\",\n \"synced\": true,\n \"variant_id\": 4011,\n \"retail_price\": \"19.00\",\n \"currency\": \"USD\",\n \"product\": {\n \"variant_id\": 4011,\n \"product_id\": 71,\n \"image\": \"https://s3.dev.printful.com/products/71/4012_1517927381.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)\"\n },\n \"files\": [\n {\n \"id\": 76564159,\n \"type\": \"default\",\n \"hash\": \"ebd559858e5703088de8900ce99c37d3\",\n \"url\": \"https://example.com/image.jpg\",\n \"filename\": \"76564159.jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 11246,\n \"width\": 200,\n \"height\": 300,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1540797879,\n \"thumbnail_url\": \"https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_thumb.png\",\n \"preview_url\": \"https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_preview.png\",\n \"visible\": true\n },\n {\n \"id\": 76564159,\n \"type\": \"back\",\n \"hash\": \"ebd559858e5703088de8900ce99c37d3\",\n \"url\": \"https://example.com/image.jpg\",\n \"filename\": \"76564159.jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 11246,\n \"width\": 200,\n \"height\": 300,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1540797879,\n \"thumbnail_url\": \"https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_thumb.png\",\n \"preview_url\": \"https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_preview.png\",\n \"visible\": true\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ]\n }\n}\n```\n\n
\n\n\nCreate a new Sync Variant with a native inside label.\n\n__Please note that the inside label type must be specified in the file options.__\n\nRequest body:\n\n```\n{\n \"retail_price\": \"19.00\",\n \"variant_id\": 4025,\n \"files\": [\n {\n \"type\": \"default\",\n \"url\": \"https://example.com/image.jpg\"\n },\n {\n \"type\": \"label_inside\",\n \"url\": \"https://example.com/image.jpg\",\n \"options\": [{\n \"id\": \"template_type\",\n \"value\": \"native\"\n }]\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 1817548049,\n \"external_id\": \"5e8dbb006e62d5\",\n \"sync_product_id\": 162979476,\n \"name\": \"lucia - White / XL\",\n \"synced\": true,\n \"variant_id\": 4014,\n \"retail_price\": \"19.00\",\n \"currency\": \"USD\",\n \"product\": {\n \"variant_id\": 4014,\n \"product_id\": 71,\n \"image\": \"https://s3.dev.printful.com/products/71/4014_1581412553.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / XL)\"\n },\n \"files\": [\n {\n \"id\": 185425195,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"https://example.com/image.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1586346752,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n },\n {\n \"id\": 185425195,\n \"type\": \"label_inside\",\n \"hash\": null,\n \"url\": \"https://example.com/image.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1586346752,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"text_thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n },\n {\n \"id\": \"text_thread_colors_chest_left\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_center\",\n \"value\": []\n },\n {\n \"id\": \"text_thread_colors_chest_center\",\n \"value\": []\n }\n ]\n }\n}\n```\n\n
\n\n## Filter products by single category ID\n\nThe IDs of the categories may be retrieved using the GET /categories endpoint. We're going to list products belonging to the \"T-shirts\" category (ID: 24).\n\nRequest URL: https://api.printful.com/store/products?category_id=24\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"id\": 277353234,\n \"external_id\": \"62f35549aeefa2\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353233,\n \"external_id\": \"62f26ed43060d9\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353218,\n \"external_id\": \"62e139cbdf6946\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353216,\n \"external_id\": \"62e0fd3e89b655\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n }\n ],\n \"extra\": [],\n \"paging\": {\n \"total\": 194,\n \"offset\": 0,\n \"limit\": 20\n },\n}\n```\n\n
\n\n## Filter products by multiple category IDs\n\nThe following request will fetch T-shirts cases (ID: 24) and Dad hats (ID: 42).\n\nRequest URL: https://api.printful.com/store/products?category_id=24,42\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": [\n {\n \"id\": 277353234,\n \"external_id\": \"62f35549aeefa2\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353233,\n \"external_id\": \"62f26ed43060d9\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353218,\n \"external_id\": \"62e139cbdf6946\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353216,\n \"external_id\": \"62e0fd3e89b655\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353215,\n \"external_id\": \"62de751d178f83\",\n \"name\": \"API product custom\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353214,\n \"external_id\": \"62de40d6dfc335\",\n \"name\": \"API product custom\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353213,\n \"external_id\": \"62de40c4a73325\",\n \"name\": \"API product custom\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353212,\n \"external_id\": \"62de40b67313e3\",\n \"name\": \"API product custom\",\n \"variants\": 1,\n \"synced\": 1,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353211,\n \"external_id\": \"62de40ac1c6694\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353210,\n \"external_id\": \"62dd5e06eff211\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353209,\n \"external_id\": \"62dd5db6314647\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353208,\n \"external_id\": \"62dd5d6ab15749\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353207,\n \"external_id\": \"62dd5d29d70bd6\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353206,\n \"external_id\": \"62dd5cba7b4dc2\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353205,\n \"external_id\": \"62dd5c2d1df034\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": null,\n \"is_ignored\": false\n },\n {\n \"id\": 277353204,\n \"external_id\": \"62dd5b3ca4f9a8\",\n \"name\": \"API product Bella Test 1\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://picsum.photos/200/300\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353203,\n \"external_id\": \"62dd5ad498ea59\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/\",\n \"is_ignored\": false\n },\n {\n \"id\": 277353202,\n \"external_id\": \"62dd5a839ad745\",\n \"name\": \"API product custom\",\n \"variants\": 2,\n \"synced\": 2,\n \"thumbnail_url\": null,\n \"is_ignored\": false\n }\n ],\n \"extra\": [],\n \"paging\": {\n \"total\": 194,\n \"offset\": 0,\n \"limit\": 20\n },\n}\n```\n\n
\n\n# Product Templates API\n\n## Get Template List\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"items\": [\n {\n \"id\": 24966053,\n \"product_id\": 328,\n \"external_product_id\": null,\n \"title\": \"All-Over Print Men's Athletic T-shirt\",\n \"available_variant_ids\": [\n 9952,\n 9958\n ],\n \"option_data\": [\n {\n \"id\": \"stitch_color\",\n \"value\": \"white\"\n },\n {\n \"id\": \"text_thread_colors_front\",\n \"value\": [\n \"#000000\"\n ]\n }\n ],\n \"colors\": [\n {\n \"color_name\": \"White\",\n \"color_codes\": [\n \"#ffffff\"\n ]\n }\n ],\n \"sizes\": [\n \"XS\",\n \"S\"\n ],\n \"mockup_file\": {\n \"imageURL\": \"https://example.com/upload/product-templates/d1/d1341a6efb49f59cc58172ce1c15eb20_l\",\n \"thumbnailURL\": \"https://example.com/upload/product-templates/d1/d1341a6efb49f59cc58172ce1c15eb20_t\",\n \"imageSVG\": null,\n \"imageDownloadURL\": null,\n \"status\": \"done\",\n \"pusherKey\": null\n },\n \"created_at\": 1644848286,\n \"updated_at\": 1644849302\n }\n ]\n },\n \"extra\": [],\n \"paging\": {\n \"total\": 2558,\n \"offset\": 0,\n \"limit\": 1\n },\n \"debug\": []\n}\n```\n
\n\n## Get Template Details\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 25029900,\n \"product_id\": 19,\n \"external_product_id\": null,\n \"title\": \"White glossy mug\",\n \"available_variant_ids\": [\n 1320\n ],\n \"option_data\": [\n {\n \"id\": \"text_thread_colors_default\",\n \"value\": [\n \"#EAD6BB\",\n \"#EAD6BB\"\n ]\n }\n ],\n \"colors\": [\n {\n \"color_name\": \"White\",\n \"color_codes\": []\n }\n ],\n \"sizes\": [\n \"11oz\"\n ],\n \"mockup_file\": {\n \"imageURL\": \"https://example.com/upload/product-templates/e8/e88de2eb2c0cc4933bcbc8866ef5ad47_l\",\n \"thumbnailURL\": \"https://example.com/upload/product-templates/e8/e88de2eb2c0cc4933bcbc8866ef5ad47_t\",\n \"imageSVG\": null,\n \"imageDownloadURL\": null,\n \"status\": \"done\",\n \"pusherKey\": null\n },\n \"created_at\": 1645021359,\n \"updated_at\": 1645021359\n },\n \"extra\": [],\n \"debug\": []\n}\n```\n
\n\n# Orders API examples\n## Using a catalog variant\nCreate an order containing an item, which shall be constructed on-the-fly and based on a print file and a `variant_id` from [Printful Catalog](https://developers.printful.com/docs#tag/Catalog-API).\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 1,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_1.jpg\"\n }\n ]\n }\n ]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 21510,\n \"external_id\": null,\n \"status\": \"draft\",\n \"shipping\": \"STANDARD\",\n \"created\": 1390825082,\n \"updated\": 1390825082,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"items\": [\n {\n \"id\": 17621,\n \"external_id\": null,\n \"variant_id\": 1,\n \"quantity\": 1,\n \"price\": \"13.00\",\n \"retail_price\": null,\n \"name\": \"Unframed Poster 18×24\",\n \"product\": {\n \"variant_id\": 1,\n \"product_id\": 1,\n \"image\": \"https://www.printful.com/storage/products/poster_18x24.jpg\",\n \"name\": \"Unframed Poster 18×24\"\n },\n \"files\": [\n {\n \"id\": 11818,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://example.com/files/posters/poster_1.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1390823900,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": []\n }\n ],\n \"costs\": {\n \"subtotal\": \"13.00\",\n \"discount\": \"0.00\",\n \"shipping\": \"7.95\",\n \"tax\": \"1.17\",\n \"total\": \"22.12\"\n },\n \"retail_costs\": {\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"total\": null\n },\n \"shipments\": []\n }\n}\n```\n
\n\n## Using a sync variant\nCreate an order containing an item, which is based on a pre-configured sync variant from the authorized Printful store and is referenced by its sync variant ID. Please note, that the existing sync variant must be configured (synced) for this to work.\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"sync_variant_id\": 1,\n \"quantity\": 1\n }\n ]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 11360229,\n \"external_id\": null,\n \"store\": 952434,\n \"status\": \"draft\",\n \"error\": null,\n \"shipping\": \"PRINTFUL_FAST\",\n \"created\": 1539584164,\n \"updated\": 1539584164,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 7253102,\n \"external_id\": null,\n \"variant_id\": 4011,\n \"sync_variant_id\": 866913817,\n \"external_variant_id\": \"5bc04fbe956147\",\n \"quantity\": 1,\n \"price\": \"12.95\",\n \"retail_price\": null,\n \"name\": \"Short-Sleeve Unisex T-Shirt - S\",\n \"product\": {\n \"variant_id\": 4011,\n \"product_id\": 71,\n \"image\": \"https://www.printful.com/products/71/4012_1517927381.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)\"\n },\n \"files\": [\n {\n \"id\": 76564071,\n \"type\": \"default\",\n \"hash\": \"1c43709da13e3480049379d41e473ad9\",\n \"url\": null,\n \"filename\": \"printfile-23aeb205.png\",\n \"mime_type\": \"image/png\",\n \"size\": 18660,\n \"width\": 1800,\n \"height\": 2400,\n \"dpi\": 150,\n \"status\": \"ok\",\n \"created\": 1539329978,\n \"thumbnail_url\": \"https://www.printful.com/files/1c4/1c43709da13e3480049379d41e473ad9_thumb.png\",\n \"preview_url\": \"https://www.printful.com/files/1c4/1c43709da13e3480049379d41e473ad9_preview.png\",\n \"visible\": false\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false\n }\n ],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": true,\n \"costs\": {\n \"currency\": \"USD\",\n \"subtotal\": \"12.95\",\n \"discount\": \"0.00\",\n \"shipping\": \"2.60\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"1.35\",\n \"vat\": \"0.00\",\n \"total\": \"16.90\"\n },\n \"retail_costs\": {\n \"currency\": \"USD\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.com/dashboard?order_id=11360229\"\n },\n \"extra\": []\n}\n```\n
\n\n## Using sync variant with external ID\nCreate an order containing an item, which is based on a pre-configured sync variant from the authorized Printful store and is referenced by its external ID. Please note, that the existing Sync Variant must be configured (synced) for this to work.\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"external_variant_id\": \"5bc04fbe956148\",\n \"quantity\": 1\n }\n ]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 11360229,\n \"external_id\": null,\n \"store\": 952434,\n \"status\": \"draft\",\n \"error\": null,\n \"shipping\": \"PRINTFUL_FAST\",\n \"created\": 1539584164,\n \"updated\": 1539584164,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 7253102,\n \"external_id\": null,\n \"variant_id\": 4011,\n \"sync_variant_id\": 866913817,\n \"external_variant_id\": \"5bc04fbe956147\",\n \"quantity\": 1,\n \"price\": \"12.95\",\n \"retail_price\": null,\n \"name\": \"Short-Sleeve Unisex T-Shirt - S\",\n \"product\": {\n \"variant_id\": 4011,\n \"product_id\": 71,\n \"image\": \"https://www.printful.com/products/71/4012_1517927381.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)\"\n },\n \"files\": [\n {\n \"id\": 76564071,\n \"type\": \"default\",\n \"hash\": \"1c43709da13e3480049379d41e473ad9\",\n \"url\": null,\n \"filename\": \"printfile-23aeb205.png\",\n \"mime_type\": \"image/png\",\n \"size\": 18660,\n \"width\": 1800,\n \"height\": 2400,\n \"dpi\": 150,\n \"status\": \"ok\",\n \"created\": 1539329978,\n \"thumbnail_url\": \"https://www.printful.com/files/1c4/1c43709da13e3480049379d41e473ad9_thumb.png\",\n \"preview_url\": \"https://www.printful.com/files/1c4/1c43709da13e3480049379d41e473ad9_preview.png\",\n \"visible\": false\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_chest_left\",\n \"value\": []\n }\n ],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false\n }\n ],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": true,\n \"costs\": {\n \"currency\": \"USD\",\n \"subtotal\": \"12.95\",\n \"discount\": \"0.00\",\n \"shipping\": \"2.60\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"1.35\",\n \"vat\": \"0.00\",\n \"total\": \"16.90\"\n },\n \"retail_costs\": {\n \"currency\": \"USD\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.com/dashboard?order_id=11360229\"\n }\n}\n```\n\n
\n\n## Using a product template\n\nTo create an order from a template, you need to know the IDs or External Product IDs of the product template(s) you want\nto use. You can find them by calling `GET /product-templates` or in the address bar when viewing the template in\ndashboard.\n\n### Specifying one variant from a product template ID\n\nRequest body:\n\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 11325,\n \"quantity\": 1,\n \"product_template_id\": 123456789\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 83445633,\n \"external_id\": null,\n \"store\": 4485069,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (2-4 business days after fulfillment)\",\n \"created\": 1667914568,\n \"updated\": 1667914568,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"Brīvības iela 1\",\n \"address2\": null,\n \"city\": \"Riga\",\n \"state_code\": null,\n \"state_name\": null,\n \"country_code\": \"LV\",\n \"country_name\": \"Latvia\",\n \"zip\": \"1010\",\n \"phone\": null,\n \"email\": null,\n \"tax_number\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 56514363,\n \"external_id\": null,\n \"variant_id\": 11325,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"19.00\",\n \"retail_price\": null,\n \"name\": \"Men's Curved Hem T-Shirt | Bella + Canvas 3003 (Black / S)\",\n \"product\": {\n \"variant_id\": 11325,\n \"product_id\": 415,\n \"image\": \"https://s3-printful.stage.printful.dev/products/415/11325_1591685336.jpg\",\n \"name\": \"BELLA + CANVAS 3003 Fast Fashion Jersey Curved Hem Tee (Black / S)\"\n },\n \"files\": [\n {\n \"id\": 487204563,\n \"type\": \"default\",\n \"hash\": \"8cc82d028560643ca41df0315db64ec1\",\n \"url\": null,\n \"filename\": \"Motivational_posters_4_Won-with-it-(20)-(1).jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 1727730,\n \"width\": 7201,\n \"height\": 9001,\n \"dpi\": 300,\n \"status\": \"ok\",\n \"created\": 1667907555,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/files/8cc/8cc82d028560643ca41df0315db64ec1_thumb.png\",\n \"preview_url\": \"https://s3-printful.stage.printful.dev/files/8cc/8cc82d028560643ca41df0315db64ec1_preview.png\",\n \"visible\": true,\n \"is_temporary\": false\n },\n {\n \"id\": 487204565,\n \"type\": \"sleeve_right\",\n \"hash\": \"ecf7982f2671ccfd2038a2228fda24dc\",\n \"url\": null,\n \"filename\": \"ed176bfb8272eac737256d6186ce403f.png\",\n \"mime_type\": \"image/png\",\n \"size\": 4012,\n \"width\": 600,\n \"height\": 525,\n \"dpi\": 150,\n \"status\": \"ok\",\n \"created\": 1667907619,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/printfile-preview/487204565/ed176bfb8272eac737256d6186ce403f_thumb.png\",\n \"preview_url\": \"https://s3-printful.stage.printful.dev/printfile-preview/487204565/ed176bfb8272eac737256d6186ce403f_preview.png\",\n \"visible\": false,\n \"is_temporary\": false\n },\n {\n \"id\": 487208045,\n \"type\": \"preview\",\n \"hash\": null,\n \"url\": null,\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1667914568,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": false,\n \"is_temporary\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false,\n \"product_template_id\": 123456789\n }\n ],\n \"branding_items\": [],\n \"incomplete_items\": [],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"GBP\",\n \"subtotal\": \"19.00\",\n \"discount\": \"0.00\",\n \"shipping\": \"3.39\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"4.71\",\n \"total\": \"27.10\"\n },\n \"retail_costs\": {\n \"currency\": \"GBP\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.com/dashboard?order_id=83445633\"\n }\n}\n```\n\n
\n\n### Specifying multiple variants from a product template ID\n\nRequest body:\n\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 6882,\n \"quantity\": 1,\n \"product_template_id\": 111222333\n },\n {\n \"variant_id\": 1350,\n \"quantity\": 2,\n \"product_template_id\": 11235813\n },\n {\n \"variant_id\": 4398,\n \"quantity\": 1,\n \"product_template_id\": 11235813\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 83445637,\n \"external_id\": null,\n \"store\": 4485069,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (2-4 business days after fulfillment)\",\n \"created\": 1667915130,\n \"updated\": 1667915130,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"Brīvības iela 1\",\n \"address2\": null,\n \"city\": \"Riga\",\n \"state_code\": null,\n \"state_name\": null,\n \"country_code\": \"LV\",\n \"country_name\": \"Latvia\",\n \"zip\": \"1010\",\n \"phone\": null,\n \"email\": null,\n \"tax_number\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 56514369,\n \"external_id\": null,\n \"variant_id\": 6882,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"18.75\",\n \"retail_price\": null,\n \"name\": \"Premium Luster Photo Paper Framed Poster (in) (Black / 8″×10″)\",\n \"product\": {\n \"variant_id\": 6882,\n \"product_id\": 172,\n \"image\": \"https://s3-printful.stage.printful.dev/products/172/6882_1527683092.jpg\",\n \"name\": \"Premium Luster Photo Paper Framed Poster (Black/8″×10″)\"\n },\n \"files\": [\n {\n \"id\": 487203842,\n \"type\": \"default\",\n \"hash\": \"8cc82d028560643ca41df0315db64ec1\",\n \"url\": null,\n \"filename\": \"Motivational_posters_4_Won-with-it-(10)-(6)-(19).jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 1727730,\n \"width\": 7201,\n \"height\": 9001,\n \"dpi\": 300,\n \"status\": \"ok\",\n \"created\": 1667906016,\n \"thumbnail_url\": \"https://s3-printful.stage.printful.dev/files/8cc/8cc82d028560643ca41df0315db64ec1_thumb.png\",\n \"preview_url\": \"https://s3-printful.stage.printful.dev/files/8cc/8cc82d028560643ca41df0315db64ec1_preview.png\",\n \"visible\": true,\n \"is_temporary\": false\n },\n {\n \"id\": 487208085,\n \"type\": \"preview\",\n \"hash\": null,\n \"url\": null,\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1667915129,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": false,\n \"is_temporary\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false,\n \"product_template_id\": 111222333\n },\n {\n \"id\": 56514370,\n \"external_id\": null,\n \"variant_id\": 1350,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 2,\n \"price\": \"23.50\",\n \"retail_price\": null,\n \"name\": \"Enhanced Matte Paper Framed Poster (in) (Black / 12″×16″)\",\n \"product\": {\n \"variant_id\": 1350,\n \"product_id\": 2,\n \"image\": \"https://s3-printful.stage.printful.dev/products/2/1350_1527683296.jpg\",\n \"name\": \"Enhanced Matte Paper Framed Poster (Black/12″×16″)\"\n },\n \"files\": [\n {\n \"id\": 487207998,\n \"type\": \"default\",\n \"hash\": \"d4024345dec7d649058a50948935ad05\",\n \"url\": null,\n \"filename\": \"d81aec33ca3a7ebf24c4ada1647e3ed0-(1).png\",\n \"mime_type\": \"image/png\",\n \"size\": 773995,\n \"width\": 1650,\n \"height\": 1650,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1667911881,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_preview.png\",\n \"visible\": true,\n \"is_temporary\": false\n },\n {\n \"id\": 487208083,\n \"type\": \"preview\",\n \"hash\": null,\n \"url\": null,\n \"filename\": \"enhanced-matte-paper-framed-poster-(in)-black-12x16-transparent-636a5d67f10a6.png\",\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1667915109,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": false,\n \"is_temporary\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false,\n \"product_template_id\": 11235813\n },\n {\n \"id\": 56514371,\n \"external_id\": null,\n \"variant_id\": 4398,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"24.75\",\n \"retail_price\": null,\n \"name\": \"Enhanced Matte Paper Framed Poster (in) (Black / 12″×18″)\",\n \"product\": {\n \"variant_id\": 4398,\n \"product_id\": 2,\n \"image\": \"https://s3.staging.printful.com/products/2/4398_1527683145.jpg\",\n \"name\": \"Enhanced Matte Paper Framed Poster (Black/12″×18″)\"\n },\n \"files\": [\n {\n \"id\": 487207998,\n \"type\": \"default\",\n \"hash\": \"d4024345dec7d649058a50948935ad05\",\n \"url\": null,\n \"filename\": \"d81aec33ca3a7ebf24c4ada1647e3ed0-(1).png\",\n \"mime_type\": \"image/png\",\n \"size\": 773995,\n \"width\": 1650,\n \"height\": 1650,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1667911881,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_preview.png\",\n \"visible\": true,\n \"is_temporary\": false\n },\n {\n \"id\": 487208084,\n \"type\": \"preview\",\n \"hash\": null,\n \"url\": null,\n \"filename\": \"enhanced-matte-paper-framed-poster-(in)-black-12x18-transparent-636a5d690c2c8.png\",\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1667915109,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": false,\n \"is_temporary\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false,\n \"product_template_id\": 11235813\n }\n ],\n \"branding_items\": [],\n \"incomplete_items\": [],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"GBP\",\n \"subtotal\": \"90.50\",\n \"discount\": \"0.00\",\n \"shipping\": \"16.54\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"22.49\",\n \"total\": \"129.53\"\n },\n \"retail_costs\": {\n \"currency\": \"GBP\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.com/dashboard?order_id=83445637\"\n }\n}\n```\n\n
\n\n### Using External Product ID\n\nThe Product Template may be specified by the associated External Product ID. You can mix it with Product Template IDs\nfor different items but for one item, only one of the identifier fields must be present.\n\nThe External Product ID is used only to specify the template. The Item will be associated with the template and only its\nID will be present in the response.\n\nRequest body:\n\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 6882,\n \"quantity\": 1,\n \"product_template_id\": 111222333\n },\n {\n \"variant_id\": 1350,\n \"quantity\": 2,\n \"external_product_id\": \"fibonacci\"\n },\n {\n \"variant_id\": 4398,\n \"quantity\": 1,\n \"external_product_id\": \"fibonacci\"\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 83445641,\n \"external_id\": null,\n \"store\": 4485069,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (2-4 business days after fulfillment)\",\n \"created\": 1667916052,\n \"updated\": 1667916052,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"Brīvības iela 1\",\n \"address2\": null,\n \"city\": \"Riga\",\n \"state_code\": null,\n \"state_name\": null,\n \"country_code\": \"LV\",\n \"country_name\": \"Latvia\",\n \"zip\": \"1010\",\n \"phone\": null,\n \"email\": null,\n \"tax_number\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 56514375,\n \"external_id\": null,\n \"variant_id\": 6882,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"18.75\",\n \"retail_price\": null,\n \"name\": \"Premium Luster Photo Paper Framed Poster (in) (Black / 8″×10″)\",\n \"product\": {\n \"variant_id\": 6882,\n \"product_id\": 172,\n \"image\": \"https://s3.staging.printful.com/products/172/6882_1527683092.jpg\",\n \"name\": \"Premium Luster Photo Paper Framed Poster (Black/8″×10″)\"\n },\n \"files\": [\n {\n \"id\": 487203842,\n \"type\": \"default\",\n \"hash\": \"8cc82d028560643ca41df0315db64ec1\",\n \"url\": null,\n \"filename\": \"Motivational_posters_4_Won-with-it-(10)-(6)-(19).jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 1727730,\n \"width\": 7201,\n \"height\": 9001,\n \"dpi\": 300,\n \"status\": \"ok\",\n \"created\": 1667906016,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/8cc/8cc82d028560643ca41df0315db64ec1_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/8cc/8cc82d028560643ca41df0315db64ec1_preview.png\",\n \"visible\": true,\n \"is_temporary\": false\n },\n {\n \"id\": 487208085,\n \"type\": \"preview\",\n \"hash\": \"b0c646ddb59f66d6d043021d0f7c4dd5\",\n \"url\": null,\n \"filename\": \"premium-luster-photo-paper-framed-poster-(in)-black-8x10-transparent-636a5d7e97726.png\",\n \"mime_type\": \"image/png\",\n \"size\": 169640,\n \"width\": 1000,\n \"height\": 1000,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1667915129,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/b0c/b0c646ddb59f66d6d043021d0f7c4dd5_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/b0c/b0c646ddb59f66d6d043021d0f7c4dd5_preview.png\",\n \"visible\": false,\n \"is_temporary\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false,\n \"product_template_id\": 111222333\n },\n {\n \"id\": 56514376,\n \"external_id\": null,\n \"variant_id\": 1350,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 2,\n \"price\": \"23.50\",\n \"retail_price\": null,\n \"name\": \"Enhanced Matte Paper Framed Poster (in) (Black / 12″×16″)\",\n \"product\": {\n \"variant_id\": 1350,\n \"product_id\": 2,\n \"image\": \"https://s3.staging.printful.com/products/2/1350_1527683296.jpg\",\n \"name\": \"Enhanced Matte Paper Framed Poster (Black/12″×16″)\"\n },\n \"files\": [\n {\n \"id\": 487207998,\n \"type\": \"default\",\n \"hash\": \"d4024345dec7d649058a50948935ad05\",\n \"url\": null,\n \"filename\": \"d81aec33ca3a7ebf24c4ada1647e3ed0-(1).png\",\n \"mime_type\": \"image/png\",\n \"size\": 773995,\n \"width\": 1650,\n \"height\": 1650,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1667911881,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_preview.png\",\n \"visible\": true,\n \"is_temporary\": false\n },\n {\n \"id\": 487208083,\n \"type\": \"preview\",\n \"hash\": \"74563a236db28cccc22f3a5554ede2fa\",\n \"url\": null,\n \"filename\": \"enhanced-matte-paper-framed-poster-(in)-black-12x16-transparent-636a5d67f10a6.png\",\n \"mime_type\": \"image/png\",\n \"size\": 274306,\n \"width\": 1000,\n \"height\": 1000,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1667915109,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/745/74563a236db28cccc22f3a5554ede2fa_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/745/74563a236db28cccc22f3a5554ede2fa_preview.png\",\n \"visible\": false,\n \"is_temporary\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false,\n \"product_template_id\": 11235813\n },\n {\n \"id\": 56514377,\n \"external_id\": null,\n \"variant_id\": 4398,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"24.75\",\n \"retail_price\": null,\n \"name\": \"Enhanced Matte Paper Framed Poster (in) (Black / 12″×18″)\",\n \"product\": {\n \"variant_id\": 4398,\n \"product_id\": 2,\n \"image\": \"https://s3.staging.printful.com/products/2/4398_1527683145.jpg\",\n \"name\": \"Enhanced Matte Paper Framed Poster (Black/12″×18″)\"\n },\n \"files\": [\n {\n \"id\": 487207998,\n \"type\": \"default\",\n \"hash\": \"d4024345dec7d649058a50948935ad05\",\n \"url\": null,\n \"filename\": \"d81aec33ca3a7ebf24c4ada1647e3ed0-(1).png\",\n \"mime_type\": \"image/png\",\n \"size\": 773995,\n \"width\": 1650,\n \"height\": 1650,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1667911881,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/d40/d4024345dec7d649058a50948935ad05_preview.png\",\n \"visible\": true,\n \"is_temporary\": false\n },\n {\n \"id\": 487208084,\n \"type\": \"preview\",\n \"hash\": \"d1021840b0e9514038e9440edbfef4ec\",\n \"url\": null,\n \"filename\": \"enhanced-matte-paper-framed-poster-(in)-black-12x18-transparent-636a5d690c2c8.png\",\n \"mime_type\": \"image/png\",\n \"size\": 277513,\n \"width\": 1000,\n \"height\": 1000,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1667915109,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/d10/d1021840b0e9514038e9440edbfef4ec_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/d10/d1021840b0e9514038e9440edbfef4ec_preview.png\",\n \"visible\": false,\n \"is_temporary\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false,\n \"product_template_id\": 11235813\n }\n ],\n \"branding_items\": [],\n \"incomplete_items\": [],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"GBP\",\n \"subtotal\": \"90.50\",\n \"discount\": \"0.00\",\n \"shipping\": \"16.54\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"22.49\",\n \"total\": \"129.53\"\n },\n \"retail_costs\": {\n \"currency\": \"GBP\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.com/dashboard?order_id=83445641\"\n }\n}\n```\n\n
\n\n## Using customized retail prices\n\nCreate an order with external order ID, custom item names, and retail price information. Order with external ID and\ncustomized item names and prices.\n\nRequest body:\n\n```\n{\n \"external_id\": \"9887112\",\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 2,\n \"quantity\": 1,\n \"name\": \"Niagara Falls poster\",\n \"retail_price\": \"19.99\",\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_2.jpg\"\n }\n ]\n },\n {\n \"variant_id\": 1,\n \"quantity\": 3,\n \"name\": \"Grand Canyon poster\",\n \"retail_price\": \"17.99\",\n \"files\": [\n {\n \"url\": \"http://example.com/files/posters/poster_3.jpg\"\n }\n ]\n }\n ],\n \"retail_costs\": {\n \"shipping\": \"24.50\"\n }\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 21509,\n \"external_id\": \"9887112\",\n \"status\": \"draft\",\n \"shipping\": \"STANDARD\",\n \"created\": 1390825006,\n \"updated\": 1390825006,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"items\": [\n {\n \"id\": 17619,\n \"external_id\": null,\n \"variant_id\": 2,\n \"quantity\": 1,\n \"price\": \"18.00\",\n \"retail_price\": \"19.99\",\n \"name\": \"Niagara Falls poster\",\n \"product\": {\n \"variant_id\": 2,\n \"product_id\": 1,\n \"image\": \"https://www.printful.com/storage/products/poster_24x36.jpg\",\n \"name\": \"Unframed Poster 24×36\"\n },\n \"files\": [\n {\n \"id\": 11819,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://example.com/files/posters/poster_2.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1390824712,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": []\n },\n {\n \"id\": 17620,\n \"external_id\": null,\n \"variant_id\": 1,\n \"quantity\": 3,\n \"price\": \"13.00\",\n \"retail_price\": \"17.99\",\n \"name\": \"Grand Canyon poster\",\n \"product\": {\n \"variant_id\": 1,\n \"product_id\": 1,\n \"image\": \"https://www.printful.com/storage/products/poster_18x24.jpg\",\n \"name\": \"Unframed Poster 18×24\"\n },\n \"files\": [\n {\n \"id\": 11820,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://example.com/files/posters/poster_3.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1390824712,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": []\n }\n ],\n \"costs\": {\n \"subtotal\": \"57.00\",\n \"discount\": \"0.00\",\n \"shipping\": \"9.95\",\n \"tax\": \"5.13\",\n \"total\": \"72.08\"\n },\n \"retail_costs\": {\n \"subtotal\": \"73.96\",\n \"discount\": \"0.00\",\n \"shipping\": \"24.50\",\n \"tax\": \"0.00\",\n \"total\": \"98.46\"\n },\n \"shipments\": []\n }\n}\n```\n
\n\n## Using multiple print placements\nCreate an order from a catalog variant that uses both front and back print files specified.\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 1118,\n \"quantity\": 1,\n \"files\": [\n {\n \"type\": \"front\",\n \"url\": \"http://example.com/files/tshirts/shirt_front.png\"\n },\n {\n \"type\": \"back\",\n \"url\": \"http://example.com/files/tshirts/shirt_back.png\"\n }\n ],\n \"options\": []\n }\n ]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 21516,\n \"external_id\": null,\n \"status\": \"draft\",\n \"shipping\": \"STANDARD\",\n \"created\": 1390825437,\n \"updated\": 1390825437,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"items\": [\n {\n \"id\": 17627,\n \"external_id\": null,\n \"variant_id\": 1118,\n \"quantity\": 1,\n \"price\": \"20.50\",\n \"retail_price\": null,\n \"name\": \"Alternative 1070 Short Sleeve Men T-Shirt (Black / M)\",\n \"product\": {\n \"variant_id\": 1118,\n \"product_id\": 14,\n \"image\": \"https://www.printful.com/storage/products/14/1095.jpg\",\n \"name\": \"Alternative 1070 Short Sleeve Men T-Shirt (Black / M)\"\n },\n \"files\": [\n {\n \"id\": 11822,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://example.com/files/tshirts/shirt_front.png\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1390825349,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n },\n {\n \"id\": 11823,\n \"type\": \"back\",\n \"hash\": null,\n \"url\": \"http://example.com/files/tshirts/shirt_back.png\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1390825349,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": []\n }\n ],\n \"costs\": {\n \"subtotal\": \"20.50\",\n \"discount\": \"0.00\",\n \"shipping\": \"5.50\",\n \"tax\": \"1.85\",\n \"total\": \"27.85\"\n },\n \"retail_costs\": {\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"total\": null\n },\n \"shipments\": []\n }\n}\n```\n
\n\n## Using all-over products\nCreate an order containing a pair of leggings with the \"Stitch color\" option specified.\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [{\n \"variant_id\": 7983,\n \"quantity\": 1,\n \"name\": \"Leggings\",\n \"retail_price\": \"19.99\",\n \"files\": [{\n \"url\": \"https://example.com/id/858/2000/2009.jpg\"\n },\n {\n \"url\": \"https://example.com/id/858/2000/2009.jpg\",\n \"type\": \"label_inside\"\n }\n ],\n \"options\": [{\"id\":\"stitch_color\", \"value\": \"white\"}]\n }]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 22481169,\n \"external_id\": null,\n \"store\": 1633247,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (3-4 business days after fulfillment)\",\n \"created\": 1575645857,\n \"updated\": 1575645857,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 13516941,\n \"external_id\": null,\n \"variant_id\": 9144,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"26.99\",\n \"retail_price\": null,\n \"name\": \"All-Over Print Men's Leggings (XS)\",\n \"product\": {\n \"variant_id\": 9144,\n \"product_id\": 288,\n \"image\": \"https://www.printful.com/products/288/9144_1532344185.jpg\",\n \"name\": \"All-Over Print Men's Leggings (XS)\"\n },\n \"files\": [\n {\n \"id\": 138304686,\n \"type\": \"default\",\n \"hash\": \"c27a71ab4008c83eba9b554775aa12ca\",\n \"url\": \"http://example.com/files/leggings/leggings_mockup.jpg\",\n \"filename\": \"QmTQo4cxDZ5MoszQAK93JyhFedeMuj7j4x5P7tQnvRi4A5.png\",\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1575645853,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": [\n {\n \"id\": \"stitch_color\",\n \"value\": \"black\"\n }\n ],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock_eu\": false,\n \"out_of_stock\": false\n }\n ],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"EUR\",\n \"subtotal\": \"26.99\",\n \"discount\": \"0.00\",\n \"shipping\": \"3.65\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"2.82\",\n \"vat\": \"0.00\",\n \"total\": \"33.46\"\n },\n \"retail_costs\": {\n \"currency\": \"EUR\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.com/dashboard/default/orders?order_id=22481169\"\n },\n \"extra\": []\n}\n```\n
\n\n## Using embroidery products\nCreate an order containing a hat with the embroidery type and thread colors specified.\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 8746,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"http://example.com/files/hats/hats_mockup.jpg\"\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": [\"#FFFFFF\", \"#A67843\"]\n }\n ]\n }\n ]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 22481172,\n \"external_id\": null,\n \"store\": 1387102,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (3-4 business days after fulfillment)\",\n \"created\": 1575647137,\n \"updated\": 1575647137,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 13516944,\n \"external_id\": null,\n \"variant_id\": 8746,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"12.57\",\n \"retail_price\": null,\n \"name\": \"Yupoong 6606 Retro Trucker Cap (White)\",\n \"product\": {\n \"variant_id\": 8746,\n \"product_id\": 252,\n \"image\": \"https://www.printful.com/products/252/8746_1543592826.jpg\",\n \"name\": \"Yupoong 6606 Retro Trucker Cap (White)\"\n },\n \"files\": [\n {\n \"id\": 138304687,\n \"type\": \"default\",\n \"hash\": \"c27a71ab4008c83eba9b554775aa12ca\",\n \"url\": \"http://example.com/files/hats/hats_mockup.jpg\",\n \"filename\": \"QmTQo4cxDZ5MoszQAK93JyhFedeMuj7j4x5P7tQnvRi4A5.png\",\n \"mime_type\": \"image/png\",\n \"size\": 37257,\n \"width\": 2480,\n \"height\": 2480,\n \"dpi\": 300,\n \"status\": \"ok\",\n \"created\": 1575646661,\n \"thumbnail_url\": \"https://www.printful.com/files/c27/c27a71ab4008c83eba9b554775aa12ca_thumb.png\",\n \"preview_url\": \"https://www.printful.com/files/c27/c27a71ab4008c83eba9b554775aa12ca_preview.png\",\n \"visible\": true\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": [\n \"#FFFFFF\",\n \"#A67843\"\n ]\n },\n {\n \"id\": \"text_thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n }\n ],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock_eu\": false,\n \"out_of_stock\": false\n }\n ],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"EUR\",\n \"subtotal\": \"12.57\",\n \"discount\": \"0.00\",\n \"shipping\": \"3.65\",\n \"digitization\": \"5.75\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"1.91\",\n \"vat\": \"0.00\",\n \"total\": \"23.88\"\n },\n \"retail_costs\": {\n \"currency\": \"EUR\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.com/dashboard/default/orders?order_id=22481172\"\n },\n \"extra\": []\n}\n```\n
\n\n## Using full color option\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 8746,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"http://example.com/files/hats/hats_mockup.jpg\",\n \"type\": \"embroidery_front\",\n \"options\": [\n {\n \"id\": \"full_color\",\n \"value\": true\n }\n ]\n }\n ]\n }\n ]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 77329346,\n \"external_id\": null,\n \"store\": 7158238,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (3-4 business days after fulfillment)\",\n \"created\": 1657290197,\n \"updated\": 1657290197,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null,\n \"tax_number\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 51123823,\n \"external_id\": null,\n \"variant_id\": 8746,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"18.50\",\n \"retail_price\": null,\n \"name\": \"Retro Trucker Hat | Yupoong 6606 (White)\",\n \"product\": {\n \"variant_id\": 8746,\n \"product_id\": 252,\n \"image\": \"https://s3.staging.printful.com/products/252/8746_1585041861.jpg\",\n \"name\": \"Yupoong 6606 Retro Trucker Cap (White)\"\n },\n \"files\": [\n {\n \"id\": 438932922,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://example.com/files/hats/hats_mockup.jpg\",\n \"filename\": \"hats_mockup.jpg\",\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"failed\",\n \"created\": 1657290187,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": false\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock_eu\": false,\n \"out_of_stock\": false\n }\n ],\n \"branding_items\": [],\n \"incomplete_items\": [],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"CAD\",\n \"subtotal\": \"18.50\",\n \"discount\": \"0.00\",\n \"shipping\": \"4.99\",\n \"digitization\": \"9.60\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"2.93\",\n \"vat\": \"0.00\",\n \"total\": \"36.02\"\n },\n \"retail_costs\": {\n \"currency\": \"CAD\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.test/dashboard?order_id=77329346\"\n },\n}\n```\n
\n\n## T-shirt with an inside label\nCreate an order containing a t-shirt with a native inside label. Please note that the inside label type must be specified in the file options.\n\nRequest body:\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"id\": 16303890,\n \"variant_id\": 6950,\n \"quantity\": 1,\n \"files\": [\n {\n \"type\": \"front\",\n \"url\": \"http://www.example.com/media/prints/38/large.jpg\"\n },\n {\n \"type\": \"label_inside\",\n \"url\": \"http://www.example.com/media/image_123.jpg\",\n \"options\": [\n {\n \"id\": \"template_type\",\n \"value\": \"native\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 30931362,\n \"external_id\": null,\n \"store\": 493,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (3-4 business days after fulfillment)\",\n \"created\": 1586183759,\n \"updated\": 1586183759,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 17915289,\n \"external_id\": null,\n \"variant_id\": 6950,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"20.51\",\n \"retail_price\": null,\n \"name\": \"Unisex Premium T-Shirt | Bella + Canvas 3001 (Athletic Heather / L)\",\n \"product\": {\n \"variant_id\": 6950,\n \"product_id\": 71,\n \"image\": \"https://s3.dev.printful.com/products/71/6950_1581408454.jpg\",\n \"name\": \"Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (Athletic Heather / L)\"\n },\n \"files\": [\n {\n \"id\": 183409147,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://www.example.com/media/prints/38/large.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1586183758,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n },\n {\n \"id\": 183409148,\n \"type\": \"label_inside\",\n \"hash\": null,\n \"url\": \"http://www.example.com/media/image_123.jpg\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1586183758,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": [],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock_eu\": false,\n \"out_of_stock\": false\n }\n ],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"CAD\",\n \"subtotal\": \"20.51\",\n \"discount\": \"0.00\",\n \"shipping\": \"5.70\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"2.15\",\n \"vat\": \"0.00\",\n \"total\": \"28.36\"\n },\n \"retail_costs\": {\n \"currency\": \"CAD\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.test/dashboard?order_id=30931362\"\n },\n \"extra\": [],\n}\n```\n
\n\n## Embroidery patch\nCreate an order containing the embroidery patch.\n\nRequest body:\n\n```\n{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 12983,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"https://pbs.twimg.com/profile_images/1073247505381552129/53OmqmtE_400x400.jpg\",\n \"type\": \"embroidery_patch_front\"\n }\n ],\n \"options\": [\n {\n \"id\": \"thread_colors_outline\",\n \"value\": [\n \"#A67843\"\n ]\n },\n {\n \"id\": \"thread_colors_patch_front\",\n \"value\": [\n \"#96A1A8\",\n \"#3399FF\",\n \"#E25C27\",\n \"#CC3333\",\n \"#333366\",\n \"#000000\"\n ]\n }\n ]\n }\n ]\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 77329716,\n \"external_id\": null,\n \"store\": 7158238,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (3-4 business days after fulfillment)\",\n \"created\": 1658333148,\n \"updated\": 1658333148,\n \"recipient\": {\n \"name\": \"John Doe\",\n \"company\": null,\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null,\n \"tax_number\": null\n },\n \"notes\": null,\n \"items\": [\n {\n \"id\": 51124091,\n \"external_id\": null,\n \"variant_id\": 12983,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": \"11.50\",\n \"retail_price\": null,\n \"name\": \"Embroidered Patches (White / Circular ⌀3 in)\",\n \"product\": {\n \"variant_id\": 12983,\n \"product_id\": 516,\n \"image\": \"https://s3.staging.printful.com/products/516/12983_1631709382.jpg\",\n \"name\": \"Embroidered Patches (White / Circular ⌀3 in)\"\n },\n \"files\": [\n {\n \"id\": 438932260,\n \"type\": \"embroidery_patch_front\",\n \"hash\": \"9740034e67529e49e4db9329c733b0ea\",\n \"url\": \"https://pbs.twimg.com/profile_images/1073247505381552129/53OmqmtE_400x400.jpg\",\n \"filename\": \"53OmqmtE_400x400.jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 10045,\n \"width\": 400,\n \"height\": 400,\n \"dpi\": null,\n \"status\": \"ok\",\n \"created\": 1655901818,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/974/9740034e67529e49e4db9329c733b0ea_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/974/9740034e67529e49e4db9329c733b0ea_preview.png\",\n \"visible\": true\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n },\n {\n \"id\": \"thread_colors\",\n \"value\": [\n \"#96A1A8\",\n \"#3399FF\",\n \"#E25C27\",\n \"#CC3333\",\n \"#333366\",\n \"#000000\"\n ]\n },\n {\n \"id\": \"text_thread_colors\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_3d\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_patch_front\",\n \"value\": []\n },\n {\n \"id\": \"text_thread_colors_patch_front\",\n \"value\": []\n },\n {\n \"id\": \"thread_colors_outline\",\n \"value\": [\n \"#A67843\"\n ]\n }\n ],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock_eu\": false,\n \"out_of_stock\": false\n }\n ],\n \"branding_items\": [],\n \"incomplete_items\": [],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"CAD\",\n \"subtotal\": \"11.50\",\n \"discount\": \"0.00\",\n \"shipping\": \"5.09\",\n \"digitization\": \"9.60\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"tax\": \"2.20\",\n \"vat\": \"0.00\",\n \"total\": \"28.39\"\n },\n \"retail_costs\": {\n \"currency\": \"CAD\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"shipments\": [],\n \"gift\": null,\n \"packing_slip\": null,\n \"dashboard_url\": \"https://www.printful.test/dashboard?order_id=77329716\"\n },\n}\n```\n\n
\n\n## Using Knitwear Product\n\nIn v1 of the API the `color_reduction_mode` is not available to be specified\nand it will always default to `solid`.\n\nCreate an order with an order for a knitwear product.\n```\n{\n \"recipient\": {\n \"name\": \"john smith\",\n \"company\": \"john smith inc\",\n \"address1\": \"19749 dearborn st\",\n \"city\": \"chatsworth\",\n \"state_code\": \"ca\",\n \"country_code\": \"us\",\n \"country_name\": \"united states\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 19633,\n \"quantity\": 1,\n \"files\": [\n {\n \"type\": \"front\",\n \"url\": \"https://picsum.photos/200\"\n }\n ],\n \"options\": [\n {\n \"id\": \"yarn_colors\",\n \"value\": [\n \"#090909\",\n \"#48542e\"\n ]\n },\n {\n \"id\": \"trim_color\",\n \"value\": \"#dcd3cc\"\n },\n {\n \"id\": \"base_color\",\n \"value\": \"#dda032\"\n }\n ]\n }\n ]\n}\n```\n\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 108346939,\n \"external_id\": null,\n \"store\": 2036805,\n \"status\": \"draft\",\n \"error\": null,\n \"errorCode\": 0,\n \"shipping\": \"STANDARD\",\n \"shipping_service_name\": \"Flat Rate (3-4 business days after fulfillment)\",\n \"created\": 1722332904,\n \"updated\": 1722332904,\n \"recipient\": {\n \"name\": \"John Smith\",\n \"company\": \"John Smith Inc\",\n \"address1\": \"19749 Dearborn St\",\n \"address2\": null,\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\",\n \"phone\": null,\n \"email\": null,\n \"tax_number\": null\n },\n \"notes\": null,\n \"incomplete_items\": [],\n \"is_sample\": false,\n \"needs_approval\": false,\n \"not_synced\": false,\n \"has_discontinued_items\": false,\n \"can_change_hold\": false,\n \"costs\": {\n \"currency\": \"AUD\",\n \"subtotal\": 65.5,\n \"discount\": 0,\n \"shipping\": 0,\n \"digitization\": 0,\n \"additional_fee\": 0,\n \"fulfillment_fee\": 0,\n \"retail_delivery_fee\": \"0.00\",\n \"tax\": \"6.84\",\n \"vat\": 0,\n \"total\": 72.34\n },\n \"dashboard_url\": \"https://www.printful.test/dashboard?order_id=108346939\",\n \"items\": [\n {\n \"id\": 85614675,\n \"external_id\": null,\n \"variant_id\": 19633,\n \"sync_variant_id\": null,\n \"external_variant_id\": null,\n \"quantity\": 1,\n \"price\": 65.5,\n \"retail_price\": null,\n \"name\": \"Classic Fit Knitted Crew Neck Sweater (Custom / 3XS)\",\n \"product\": {\n \"variant_id\": 19633,\n \"product_id\": 769,\n \"image\": \"https://s3.staging.printful.com/products/769/19633_1716883244.jpg\",\n \"name\": \"Classic Fit Knitted Crew Neck Sweater (Custom / 3XS)\"\n },\n \"files\": [\n {\n \"id\": 165809524,\n \"type\": \"default\",\n \"hash\": \"2cfa55e156067d0ef050343f80f81e1d\",\n \"url\": \"https://picsum.photos/200\",\n \"filename\": \"165809524.jpg\",\n \"mime_type\": \"image/jpeg\",\n \"size\": 9289,\n \"width\": 200,\n \"height\": 200,\n \"dpi\": 72,\n \"status\": \"ok\",\n \"created\": 1579677111,\n \"thumbnail_url\": \"https://s3.staging.printful.com/files/2cf/2cfa55e156067d0ef050343f80f81e1d_thumb.png\",\n \"preview_url\": \"https://s3.staging.printful.com/files/2cf/2cfa55e156067d0ef050343f80f81e1d_preview.png\",\n \"visible\": true,\n \"is_temporary\": false,\n \"message\": \"\"\n }\n ],\n \"options\": [\n {\n \"id\": \"base_color\",\n \"value\": \"#dda032\"\n },\n {\n \"id\": \"yarn_colors\",\n \"value\": [ \"#090909\", \"#48542e\" ]\n },\n {\n \"id\": \"trim_color\",\n \"value\": \"#dcd3cc\"\n }\n ],\n \"sku\": null,\n \"discontinued\": false,\n \"out_of_stock\": false\n }\n ],\n \"branding_items\": [],\n \"shipments\": [],\n \"packing_slip\": null,\n \"retail_costs\": {\n \"currency\": \"AUD\",\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"gift\": null\n },\n \"extra\": [],\n \"debug\": []\n}\n```\n\n
\n\nThe resulting mockup should look as follows:\n
\n![Image](images/mockups/knitwear_example.png)\n\n# File Library API examples\n\n## Add a new file\n\nAdd file to the print file library, file name will be detected from URL. After creation file is not processed instantly.\n\nRequest body:\n\n```\n{\n \"url\": \"http://www.example.com/files/tshirts/example.png\"\n}\n```\n\nResponse data:\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"id\": 11816,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://www.example.com/files/tshirts/example.png\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1390819101,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n}\n```\n\nAdd file to the mockup library, and specify file name manually\n\nRequest body:\n\n```\n{\n \"type\": \"preview\",\n \"url\": \"http://www.example.com/files/tshirts/example.png\",\n \"filename\": \"shirt1.png\"\n}\n```\n\nAdd file to the library, but not show up in the web interface.\n\nRequest body:\n\n``` \n{\n \"url\": \"http://www.example.com/files/tshirts/example.png\",\n \"visible\": 0\n}\n```\n\n## Suggest thread colors\n\nGet suggested thread colors for provided image URL\n\nRequest body:\n\n```\n{\n \"file_url\": \"http://www.example.com/files/tshirts/example.png\"\n}\n```\n\nResponse data:\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"thread_colors\": [\n \"#FFFFFF\",\n \"#000000\",\n \"#96A1A8\",\n \"#CC3333\",\n \"#E25C27\"\n ]\n },\n}\n```\n\n# Ecommerce Platform Sync API examples\n\n## Modify a Sync Variant\n\nLinks Sync Variant with T-shirt with front and back images.\n\nRequest body:\n\n```\n{\n \"variant_id\": 1118,\n \"files\": [\n {\n \"url\": \"http://example.com/files/tshirts/shirt_front.png\"\n },\n {\n \"type\": \"back\",\n \"url\": \"http://example.com/files/tshirts/shirt_back.png\"\n }\n ],\n \"options\": []\n}\n```\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"sync_variant\": {\n \"id\": 4699529,\n \"external_id\": \"1117068664\",\n \"sync_product_id\": 1055835,\n \"name\": \"Michael Jackson T-Shirt - Medium\",\n \"synced\": true,\n \"variant_id\": 1118,\n \"product\": {\n \"variant_id\": 1118,\n \"product_id\": 14,\n \"image\": \"https://files.cdn.printful.com/products/14/1095.jpg\",\n \"name\": \"Alternative 1070 Short Sleeve Men T-Shirt (Black / M)\"\n },\n \"files\": [\n {\n \"id\": 304995,\n \"type\": \"default\",\n \"hash\": null,\n \"url\": \"http://example.com/files/tshirts/shirt_front.png\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1426839420,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n },\n {\n \"id\": 304996,\n \"type\": \"back\",\n \"hash\": null,\n \"url\": \"http://example.com/files/tshirts/shirt_back.png\",\n \"filename\": null,\n \"mime_type\": null,\n \"size\": 0,\n \"width\": null,\n \"height\": null,\n \"dpi\": null,\n \"status\": \"waiting\",\n \"created\": 1426839420,\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true\n }\n ],\n \"options\": []\n },\n \"sync_product\": {\n \"id\": 1055835,\n \"external_id\": \"409040684\",\n \"name\": \"Michael Jackson T-Shirt\",\n \"variants\": 1,\n \"synced\": 1\n }\n }\n}\n```\n\n
\n\n# Mockup Generator API examples\n\n## Retrieve product variant print files with default technique\n\nURI: `GET /mockup-generator/printfiles/162`\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product_id\": 162,\n \"available_placements\": {\n \"front\": \"Front print\",\n \"back\": \"Back print\",\n \"label_outside\": \"Outside label\",\n \"label_inside\": \"Inside label\",\n \"sleeve_left\": \"Left sleeve\",\n \"sleeve_right\": \"Right sleeve\"\n },\n \"printfiles\": [\n {\n \"printfile_id\": 1,\n \"width\": 1800,\n \"height\": 2400,\n \"dpi\": 150,\n \"fill_mode\": \"fit\",\n \"can_rotate\": false\n },\n ...\n ],\n \"variant_printfiles\": [\n {\n \"variant_id\": 6584,\n \"placements\": {\n \"front\": 1,\n \"back\": 1,\n \"label_outside\": 90,\n \"label_inside\": 71,\n \"sleeve_left\": 130,\n \"sleeve_right\": 130\n }\n },\n ...\n ],\n \"option_groups\": [\n \"Couple's\",\n \"Flat\",\n \"Flat 2\",\n \"Flat 3\",\n \"Flat Lifestyle\",\n \"Holiday season\",\n \"Labels\",\n \"Men's\",\n \"Men's 2\",\n \"Men's 3\",\n \"Men's 4\",\n \"On Hanger\",\n \"Spring/summer vibes\",\n \"Women's\",\n \"Women's 2\",\n \"Women's 3\",\n \"Women's 4\"\n ],\n \"options\": [\n \"Back\",\n \"Back 2\",\n \"Front\",\n \"Front 2\",\n \"Inside label\",\n \"Left\",\n \"Left Front\",\n \"Outside label\",\n \"Right\",\n \"Right Back\",\n \"Right Front\"\n ]\n }\n}\n```\n\n
\n\n## Retrieve product variant printfiles with specified technique\n\nURI: `GET /mockup-generator/printfiles/162?technique=EMBROIDERY`\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"product_id\": 162,\n \"available_placements\": {\n \"embroidery_chest_center\": \"Center chest\",\n \"embroidery_chest_left\": \"Left chest\"\n },\n \"printfiles\": [\n {\n \"printfile_id\": 136,\n \"width\": 1200,\n \"height\": 1200,\n \"dpi\": 300,\n \"fill_mode\": \"fit\",\n \"can_rotate\": false\n }\n ],\n \"variant_printfiles\": [\n {\n \"variant_id\": 6584,\n \"placements\": {\n \"embroidery_chest_center\": 136,\n \"embroidery_chest_left\": 136\n }\n },\n ...\n ],\n \"option_groups\": [\n \"Couple's\",\n \"Flat\",\n \"Flat 2\",\n \"Flat 3\",\n \"Flat Lifestyle\",\n \"Holiday season\",\n \"Men's\",\n \"Men's 2\",\n \"Men's 3\",\n \"Men's 4\",\n \"On Hanger\",\n \"Spring/summer vibes\",\n \"Women's\",\n \"Women's 2\",\n \"Women's 3\",\n \"Women's 4\"\n ],\n \"options\": [\n \"Front\",\n \"Front 2\",\n \"Zoomed-in\",\n \"Zoomed-in 2\"\n ]\n }\n}\n```\n\n
\n\n## Get layout templates with default technique\n\nURI: `GET /mockup-generator/templates/162`\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"version\": 100,\n \"variant_mapping\": [\n {\n \"variant_id\": 6584,\n \"templates\": [\n {\n \"placement\": \"front\",\n \"template_id\": 7597\n },\n {\n \"placement\": \"back\",\n \"template_id\": 7617\n },\n {\n \"placement\": \"label_outside\",\n \"template_id\": 3521\n },\n {\n \"placement\": \"label_inside\",\n \"template_id\": 47233\n },\n {\n \"placement\": \"sleeve_left\",\n \"template_id\": 7684\n },\n {\n \"placement\": \"sleeve_right\",\n \"template_id\": 7685\n }\n ]\n },\n ...\n ],\n \"templates\": [\n {\n \"template_id\": 7597,\n \"image_url\": \"https://printful-mockups-dev.s3.amazonaws.com/56-bella-canvas-3413/medium/onman/front/03_bc3413_onman_front_shadows_whitebg.png?v=1646372077\",\n \"background_url\": \"https://printful-mockups-dev.s3.amazonaws.com/56-bella-canvas-3413/medium/onman/front/01_bc3413_onman_front_solidblack.png?v=1646372077\",\n \"background_color\": null,\n \"printfile_id\": 1,\n \"template_width\": 1000,\n \"template_height\": 1000,\n \"print_area_width\": 299,\n \"print_area_height\": 399,\n \"print_area_top\": 228,\n \"print_area_left\": 350,\n \"is_template_on_front\": true,\n \"orientation\": \"any\"\n },\n ...\n ],\n \"min_dpi\": 75,\n \"conflicting_placements\": [\n {\n \"placement\": \"back\",\n \"conflicts\": [\n \"label_outside\"\n ]\n },\n {\n \"placement\": \"label_outside\",\n \"conflicts\": [\n \"back\",\n \"label_inside\"\n ]\n },\n {\n \"placement\": \"label_inside\",\n \"conflicts\": [\n \"label_outside\"\n ]\n }\n ]\n }\n}\n```\n\n
\n\n## Get layout templates with specified technique\n\nURI: `GET /mockup-generator/templates/162?technique=EMBROIDERY`\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"version\": 100,\n \"variant_mapping\": [\n {\n \"variant_id\": 6584,\n \"templates\": [\n {\n \"placement\": \"embroidery_chest_center\",\n \"template_id\": 53432\n },\n {\n \"placement\": \"embroidery_chest_left\",\n \"template_id\": 12221\n }\n ]\n },\n ...\n ],\n \"templates\": [\n {\n \"template_id\": 53432,\n \"image_url\": \"https://printful-mockups-dev.s3.amazonaws.com/56-bella-canvas-3413/medium/onman/embroidery_chest_left/zoomed/04_bc3413_onman_front_zoomed_shadows.png?v=1646372077\",\n \"background_url\": \"https://printful-mockups-dev.s3.amazonaws.com/56-bella-canvas-3413/medium/onman/embroidery_chest_left/zoomed/01_bc3413_onman_front_zoomed_solidblack.png?v=1646372077\",\n \"background_color\": null,\n \"printfile_id\": 136,\n \"template_width\": 1000,\n \"template_height\": 1000,\n \"print_area_width\": 173,\n \"print_area_height\": 173,\n \"print_area_top\": 464,\n \"print_area_left\": 425,\n \"is_template_on_front\": true,\n \"orientation\": \"any\"\n },\n ...\n ],\n \"min_dpi\": 150,\n \"conflicting_placements\": [\n {\n \"placement\": \"embroidery_chest_center\",\n \"conflicts\": [\n \"embroidery_chest_left\",\n \"embroidery_large_center\"\n ]\n },\n {\n \"placement\": \"embroidery_chest_left\",\n \"conflicts\": [\n \"embroidery_chest_center\",\n \"embroidery_large_center\"\n ]\n }\n ]\n }\n}\n```\n\n
" } ], "paths": { "/products": { "get": { "tags": [ "Catalog API" ], "summary": "Get Products", "description": "Returns list of Products available in the Printful", "operationId": "getProducts", "parameters": [ { "$ref": "#/components/parameters/ProductCategoryId" } ], "responses": { "200": { "$ref": "#/components/responses/GetProducts" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/products'" } ] } }, "/products/variant/{id}": { "get": { "summary": "Get Variant", "description": "Returns information about a specific Variant and its Product", "operationId": "getVariantById", "tags": [ "Catalog API" ], "parameters": [ { "$ref": "#/components/parameters/VariantId" } ], "responses": { "200": { "$ref": "#/components/responses/GetVariantById" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/products/variant/4018'" } ] } }, "/products/{id}": { "get": { "summary": "Get Product", "description": "Returns information about a specific product and a list of variants for this product.", "operationId": "getProductById", "tags": [ "Catalog API" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductById" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/products/71'" } ] } }, "/products/{id}/sizes": { "get": { "summary": "Get Product Size Guide", "description": "Returns information about the size guide for a specific product.", "operationId": "getProductSizeGuideById", "tags": [ "Catalog API" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/MeasurementUnit" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductSizeGuideById" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/products/71/sizes'" } ] } }, "/categories": { "get": { "tags": [ "Catalog API" ], "summary": "Get Categories", "description": "Returns list of Catalog Categories available in the Printful", "operationId": "getCategories", "responses": { "200": { "$ref": "#/components/responses/GetCategories" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/categories'" } ] } }, "/categories/{id}": { "get": { "summary": "Get Category", "description": "Returns information about a specific category.", "operationId": "getCategoryById", "tags": [ "Catalog API" ], "parameters": [ { "$ref": "#/components/parameters/CategoryId" } ], "responses": { "200": { "$ref": "#/components/responses/GetCategoryById" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/categories/24'" } ] } }, "/store/products": { "get": { "summary": "Get Sync Products", "description": "Returns a list of Sync Product objects from your custom Printful store.", "operationId": "getSyncProducts", "security": [ { "OAuth": [ "sync_products/read" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/SyncStatus" }, { "$ref": "#/components/parameters/ProductCategoryId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncProducts" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/store/products' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "post": { "summary": "Create a new Sync Product", "description": "Creates a new Sync Product together with its Sync Variants ([See examples](#tag/Products-API/operation/createSyncProduct)).", "operationId": "createSyncProduct", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/SyncProductCreate" }, "responses": { "200": { "$ref": "#/components/responses/SyncProduct" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/store/products' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"sync_product\": {\n \"name\": \"T-Shirt\",\n \"thumbnail\": \"https://picsum.photos/200/300\"\n },\n \"sync_variants\": [\n {\n \"retail_price\": 21.00,\n \"variant_id\": 4011,\n \"files\": [\n {\n \"url\": \"https://picsum.photos/200/300?image=1\"\n },\n {\n \"type\": \"back\",\n \"url\": \"https://picsum.photos/200/300?image=1\"\n }\n ]\n },\n {\n \"retail_price\": 21.00,\n \"variant_id\": 4012,\n \"files\": [\n {\n \"url\": \"https://picsum.photos/200/300?image=1\"\n },\n {\n \"type\": \"back\",\n \"url\": \"https://picsum.photos/200/300?image=1\"\n }\n ]\n }\n ]\n}'" } ] } }, "/store/products/{id}": { "get": { "summary": "Get a Sync Product", "description": "Get information about a single Sync Product and its Sync Variants.", "operationId": "getSyncProductById", "security": [ { "OAuth": [ "sync_products/read" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/SyncProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncProductInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/store/products/{sync_product_id}' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "delete": { "summary": "Delete a Sync Product", "description": "Deletes a Sync Product with all of its Sync Variants", "operationId": "deleteSyncProduct", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/SyncProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncProductInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/store/products/161636638' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "put": { "summary": "Modify a Sync Product", "description": "Modifies an existing Sync Product with its Sync Variants.\n\nPlease note that in the request body you only need to specify the fields that need to be changed. Furthermore, if you want to update existing sync variants, \nthen in the sync variants array you must specify the IDs of all existing sync variants. All omitted existing sync variants will be deleted. All new sync \nvariants without an ID will be created. See examples for more insights.\n\n**Rate limiting:** Up to 10 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.\n\n[See examples](#tag/Examples/Products-API-examples/Modify-a-Sync-Product)\n", "operationId": "updateSyncProduct", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/SyncProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/SyncProductUpdate" }, "responses": { "200": { "$ref": "#/components/responses/SyncProduct" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/store/variants/{id}": { "get": { "summary": "Get a Sync Variant", "description": "Get information about a single Sync Variant.", "operationId": "getSyncVariantById", "security": [ { "OAuth": [ "sync_products/read" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/SyncVariantId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncVariant" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a Sync Variant", "description": "Deletes a single Sync Variant.", "operationId": "deleteSyncVariant", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/SyncVariantId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncVariantDeleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/store/variants/1781126754' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "put": { "summary": "Modify a Sync Variant", "description": "Modifies an existing Sync Variant.\n\nPlease note that in the request body you only need to specify the fields that need to be changed. See examples for more insights.\n\n[See examples](#tag/Examples/Products-API-examples/Modify-a-Sync-Variant)\n", "operationId": "updateSyncVariant", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/SyncVariantId" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/SyncVariantUpdate" }, "responses": { "200": { "$ref": "#/components/responses/SyncVariant" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request PUT 'https://api.printful.com/store/variants/161636640' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n {\n \"retail_price\": 25.00,\n \"variant_id\": 4011\n }\n}'" } ] } }, "/store/products/{id}/variants": { "post": { "summary": "Create a new Sync Variant", "description": "Creates a new Sync Variant for an existing Sync Product ([See examples](#tag/Examples/Products-API-examples/Create-a-new-Sync-Variant)).", "operationId": "createSyncVariant", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Products API" ], "parameters": [ { "$ref": "#/components/parameters/SyncProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/SyncVariantCreate" }, "responses": { "200": { "$ref": "#/components/responses/SyncVariant" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/store/products/161636640/variants' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"retail_price\": 19.00,\n \"variant_id\": 4011,\n \"files\": [\n {\n \"type\": \"back\",\n \"url\": \"https://picsum.photos/200/300?image=2\"\n }\n ],\n \"options\": [\n {\n \"id\": \"embroidery_type\",\n \"value\": \"flat\"\n }\n ]\n}'" } ] } }, "/product-templates": { "get": { "summary": "Get product template list", "description": "Returns a list of templates.", "operationId": "getProductTemplates", "security": [ { "OAuth": [ "product_templates/read" ] } ], "tags": [ "Product Templates API" ], "parameters": [ { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/ProductTemplates" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/product-templates' \\\n--header 'Authorization: Bearer {oauth_token}'\n" } ] } }, "/product-templates/{id}": { "get": { "summary": "Get product template", "description": "Get information about a single product template", "operationId": "getProductTemplateById", "security": [ { "OAuth": [ "product_templates/read" ] } ], "tags": [ "Product Templates API" ], "parameters": [ { "$ref": "#/components/parameters/TemplateById" } ], "responses": { "200": { "$ref": "#/components/responses/TemplateById" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/product-templates/{template_id}' \\\n--header 'Authorization: Bearer {oauth_token}'\n" } ] }, "delete": { "summary": "Delete product template", "description": "Delete product template by ID or External Product ID", "operationId": "deleteProductTemplate", "security": [ { "OAuth": [ "product_templates" ] } ], "tags": [ "Product Templates API" ], "parameters": [ { "$ref": "#/components/parameters/TemplateById" } ], "responses": { "200": { "$ref": "#/components/responses/DeleteTemplate" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/product-templates/{template_id}' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/orders": { "get": { "summary": "Get list of orders", "description": "Returns list of order objects from your store", "operationId": "getOrders", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders API" ], "parameters": [ { "$ref": "#/components/parameters/Status" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "$ref": "#/components/responses/Orders" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/orders' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "post": { "summary": "Create a new order", "description": "Creates a new order and optionally submits it for fulfillment ([See examples](#tag/Examples/Orders-API-examples))", "operationId": "createOrder", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders API" ], "parameters": [ { "$ref": "#/components/parameters/Confirm" }, { "$ref": "#/components/parameters/UpdateExisting" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/OrderInput" }, "responses": { "200": { "$ref": "#/components/responses/Order" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/orders/{id}": { "get": { "summary": "Get order data", "description": "Returns order data by ID or External ID.", "operationId": "getOrderById", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders API" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/Order" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/orders/{order_id}' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "delete": { "summary": "Cancel an order", "description": "Cancels pending order or draft. Charged amount is returned to the store owner's credit card.", "operationId": "cancelOrderById", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders API" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/Order" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/orders/{order_id}' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "put": { "summary": "Update order data", "description": " Updates unsubmitted order and optionally submits it for the fulfillment.\n\n Note that you need to post only the fields that need to be changed, not all required fields.\n\n If items array is given in the update data, the items will be:\n\n a) updated, if the update data contains the item id or external_id parameter that alreay exists\n\n b) deleted, if the request doesn't contain the item with previously existing id\n\n c) created as new if the id is not given or does not already exist ", "operationId": "updateOrderById", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders API" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/Confirm" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/OrderInput" }, "responses": { "200": { "$ref": "#/components/responses/Order" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orders/{id}/confirm": { "post": { "summary": "Confirm draft for fulfillment", "description": "Approves for fulfillment an order that was saved as a draft. Store owner's credit card is charged when the order is submitted for fulfillment.", "operationId": "confirmOrderById", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders API" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/Order" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/orders/{order_id}/confirm' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/orders/estimate-costs": { "post": { "summary": "Estimate order costs", "description": "Calculates the estimated order costs including item costs, print costs (back prints, inside labels etc.), shipping and taxes", "operationId": "estimateOrderCosts", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/OrderInput" }, "responses": { "200": { "$ref": "#/components/responses/EstimateOrderCosts" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/orders/estimate-costs' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"recipient\": {\n \"name\": \"John Doe\",\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"variant_id\": 8630,\n \"quantity\": 1,\n \"files\": [\n {\n \"url\": \"https://picsum.photos/200\"\n }\n ]\n }\n ]\n}'" } ] } }, "/files": { "post": { "summary": "Add a new file", "description": "Adds a new File to the library by providing URL of the file.\n\nIf a file with identical URL already exists, then the original file is returned. If a file does not exist, a new file is created.\n\n[See examples](#tag/Examples/File-Library-API-examples/Add-a-new-file)\n", "operationId": "addFile", "security": [ { "OAuth": [ "file_library" ] } ], "tags": [ "File Library API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/AddFile" }, "responses": { "200": { "$ref": "#/components/responses/AddFile" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/files' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"url\": \"http://www.example.com/files/tshirts/example.png\"\n}'" } ] } }, "/files/{id}": { "get": { "summary": "Get file", "description": "Returns information about the given file.", "operationId": "getFile", "security": [ { "OAuth": [ "file_library/read" ] } ], "tags": [ "File Library API" ], "parameters": [ { "$ref": "#/components/parameters/FileId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetFile" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/files/{123}' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/files/thread-colors": { "post": { "summary": "Return available thread colors from provided image URL", "description": "Returns colors in hexadecimal format.\n\nReturned thread colors are matched as closely as possible to provided image colors.\n\n[See examples](#tag/Examples/File-Library-API-examples/Suggest-thread-colors)\n", "operationId": "threadColors", "tags": [ "File Library API" ], "requestBody": { "$ref": "#/components/requestBodies/ThreadColors" }, "responses": { "200": { "$ref": "#/components/responses/ThreadColors" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/files' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"url\": \"http://www.example.com/files/tshirts/example.png\"\n}'" } ] } }, "/sync/products": { "get": { "summary": "Get list of Sync Products", "description": "Returns list of Sync Product objects from your store.", "operationId": "getStoreSyncProducts", "security": [ { "OAuth": [ "sync_products/read" ] } ], "tags": [ "Ecommerce Platform Sync API" ], "parameters": [ { "$ref": "#/components/parameters/Search" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/SyncStatus" } ], "responses": { "200": { "$ref": "#/components/responses/SyncProducts" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/sync/products' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/sync/products/{id}": { "get": { "summary": "Get a Sync Product", "description": "Get information about a single Sync Product and its Sync Variants", "operationId": "getStoreSyncProductById", "security": [ { "OAuth": [ "sync_products/read" ] } ], "tags": [ "Ecommerce Platform Sync API" ], "parameters": [ { "$ref": "#/components/parameters/SyncProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncProductInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/sync/products/161636640' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "delete": { "summary": "Delete a Sync Product", "description": "Deletes a Sync Product with all of its Sync Variants", "operationId": "deleteStoreSyncProduct", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Ecommerce Platform Sync API" ], "parameters": [ { "$ref": "#/components/parameters/SyncProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncProductInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/sync/products/161636640' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/sync/variant/{id}": { "get": { "summary": "Get a Sync Variant", "description": "Get information about a single Sync Variant", "operationId": "getStoreSyncVariantById", "security": [ { "OAuth": [ "sync_products/read" ] } ], "tags": [ "Ecommerce Platform Sync API" ], "parameters": [ { "$ref": "#/components/parameters/SyncVariantId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncVariantInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/sync/variant/1781126748' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "put": { "summary": "Modify a Sync Variant", "description": "Modifies an existing Sync Variant.\n\nPlease note that in the request body you only need to specify the fields that need to be changed. See examples for more insights.\n\n **Rate limiting:** Up to 10 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.\n\n[See examples](#tag/Examples/Ecommerce-Platform-Sync-API-examples/Modify-a-Sync-Variant)\n", "operationId": "updateStoreSyncVariant", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Ecommerce Platform Sync API" ], "parameters": [ { "$ref": "#/components/parameters/SyncVariantId" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/EcommerceSyncVariantUpdate" }, "responses": { "200": { "$ref": "#/components/responses/SyncVariantInfo" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request PUT 'https://api.printful.com/sync/variant/1781126748' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"id\": 1781126748,\n \"files\": [\n {\n \"url\": \"picsum.photos/200\"\n }\n ]\n}'" } ] }, "delete": { "summary": "Delete a Sync Variant", "description": "Deletes configuraton information (`variant_id`, print files and options) and disables automatic order importing for this Sync Variant.", "operationId": "deleteStoreSyncVariant", "security": [ { "OAuth": [ "sync_products" ] } ], "tags": [ "Ecommerce Platform Sync API" ], "parameters": [ { "$ref": "#/components/parameters/SyncVariantId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/SyncVariantInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/sync/variant/1781126748' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/shipping/rates": { "post": { "summary": "Calculate shipping rates", "description": "Returns available shipping options and rates for the given list of products.\n\n**Recipient Address Requirements:**\n- Only `country_code` is required in the recipient object\n- `state_code` is only required for United States (US), Australia (AU), and Canada (CA)\n- All other recipient fields are optional\n\n**Note:** Providing more address information may produce more precise results and more shipping options. While only the country code is required, including additional details like city, postal code, and state/province can help return more accurate shipping rates and additional delivery options.\n\n**Important:** Shipping rates returned by this endpoint may differ from those returned by `/orders/estimate-costs` if your store has [store shipping settings](https://www.printful.com/dashboard/settings/store-shipping) configured. \n\nThe `/orders/estimate-costs` endpoint automatically applies your store's shipping settings (including shipping markup), while this endpoint applies them **only if the store shipping settings are enabled**. To ensure consistent results between both endpoints, make sure your store shipping settings are enabled and properly configured in your Printful Dashboard.\n", "operationId": "calculateShippingRates", "security": [ { "OAuth": [] } ], "tags": [ "Shipping Rate API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/CalculateShippingRates" }, "responses": { "200": { "$ref": "#/components/responses/ShippingRates" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/shipping/rates' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"recipient\": {\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"country_code\": \"US\",\n \"state_code\": \"CA\",\n \"zip\": 91311\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"variant_id\": 2\n },\n {\n \"quantity\": 5,\n \"variant_id\": 202\n }\n ]\n }'" } ] } }, "/countries": { "get": { "summary": "Retrieve country list", "description": "Returns list of countries and states that are accepted by the Printful.", "operationId": "getCountries", "tags": [ "Country/State Code API" ], "responses": { "200": { "$ref": "#/components/responses/GetCountries" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/countries'" } ] } }, "/tax/countries": { "get": { "summary": "Get a list of countries for tax calculation", "description": "Retrieve state list that requires sales tax calculation", "operationId": "getTaxCountries", "tags": [ "Tax Rate API" ], "responses": { "200": { "$ref": "#/components/responses/TaxCountries" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/tax/countries'" } ] } }, "/tax/rates": { "post": { "summary": "Calculate tax rate", "description": "Calculates sales tax rate for given address if required.\n\n
\n ⚠️ Important – /tax/rates endpoint sunset\n

Since May 2023, the POST /tax/rates endpoint is no longer maintained and may return inaccurate results.

\n

On July 29, 2025, we started the sunset process. The rate limit is being reduced by 10 RPM each week (starting with 60) until it reaches 0 on September 8, 2025, at which point the endpoint will be removed entirely.

\n

There is no replacement endpoint in the Printful API for retrieving standalone tax rates. For accurate tax information, please use official government sources or external tax calculation providers.

\n

If you require the total order cost including taxes, use the order creation or estimation endpoints.

\n
\n", "operationId": "calculateTaxRates", "deprecated": true, "tags": [ "Tax Rate API" ], "requestBody": { "$ref": "#/components/requestBodies/CalculateTaxRates" }, "responses": { "200": { "$ref": "#/components/responses/TaxRates" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/tax/rates' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"recipient\": {\n \"country_code\": \"US\",\n \"state_code\": \"CA\",\n \"city\": \"Chatsworth\",\n \"zip\": \"91311\"\n }\n }'" } ] } }, "/store/packing-slip": { "post": { "summary": "Change packing slip", "description": "Modifies packing slip information of the currently authorized Printful store.", "operationId": "changePackingSlip", "security": [ { "OAuth": [ "stores_list" ] } ], "tags": [ "Store Information API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/ChangePackingSlip" }, "responses": { "200": { "$ref": "#/components/responses/PackingSlip" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/store/packing-slip' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"email\": \"email@example.com\",\n \"phone\": \"+1 1 11111111\",\n \"message\": \"Custom message\",\n}'" } ] } }, "/stores": { "get": { "summary": "Get basic information about stores", "description": "Get basic information about stores depending on the token access level", "operationId": "getStores", "security": [ { "OAuth": [ "stores_list" ] } ], "tags": [ "Store Information API" ], "responses": { "200": { "$ref": "#/components/responses/Stores" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/stores/{id}": { "get": { "summary": "Get basic information about a store", "description": "Get basic information about a store based on provided ID", "operationId": "getStore", "security": [ { "OAuth": [ "stores_list" ] } ], "tags": [ "Store Information API" ], "parameters": [ { "$ref": "#/components/parameters/StoreInformationId" } ], "responses": { "200": { "$ref": "#/components/responses/Store" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/mockup-generator/create-task/{id}": { "post": { "summary": "Create a mockup generation task", "description": "Creates an asynchronous mockup generation task.\nGeneration result can be retrieved using mockup generation task retrieval endpoint.
\n**Rate limiting**: Up to 10 requests per 60 seconds for established stores;\n2 requests per 60 seconds for new stores. Currently available rate is returned in response headers.\nA 60 seconds lockout is applied if request count is exceeded. We also limit the number of files that may\nbe generated to 20,000 files per account in a 24-hour period.\n", "operationId": "createGeneratorTask", "security": [ { "OAuth": [] } ], "tags": [ "Mockup Generator API" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateGenerationTask" }, "responses": { "200": { "$ref": "#/components/responses/GenerationTask" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/mockup-generator/create-task/71' \\\n--header 'Authorization: Bearer {oauth_token}' \\\n--data-raw '{\n \"variant_ids\" : [4012, 4013, 4014, 4017, 4018, 4019],\n \"format\": \"jpg\",\n \"files\" : [\n {\n \"placement\": \"front\",\n \"image_url\": \"http://your-site/path-to-front-printfile.jpg\",\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n }\n },\n {\n \"placement\": \"back\",\n \"image_url\": \"http://your-site/path-to-back-printfile.jpg\",\n \"position\": {\n \"area_width\": 1800,\n \"area_height\": 2400,\n \"width\": 1800,\n \"height\": 1800,\n \"top\": 300,\n \"left\": 0\n }\n }\n ]\n }'" } ] } }, "/mockup-generator/printfiles/{id}": { "get": { "summary": "Retrieve product variant printfiles", "description": "List of printfiles available for products variants. Printfile indicates what file resolution should be used to create a mockup or submit an order.\n\n
\nThis endpoint uses DTG as a default printing technique for products\nwith more than one technique available. For products with DTG and more\ntechniques available please specify the correct technique in query by using\nthe `technique` parameter. For more information read the examples.\n
\n", "operationId": "getPrintfiles", "security": [ { "OAuth": [] } ], "tags": [ "Mockup Generator API" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/Orientation" }, { "$ref": "#/components/parameters/Technique" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/Printfiles" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/mockup-generator/printfiles/1' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/mockup-generator/task": { "get": { "summary": "Mockup generation task result", "description": "Returns asynchronous mockup generation task result. If generation task is completed, it will contain a list of generated mockups.", "operationId": "getTask", "security": [ { "OAuth": [] } ], "tags": [ "Mockup Generator API" ], "parameters": [ { "$ref": "#/components/parameters/TaskKey" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GenerationTask" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/mockup-generator/task?task_key=3123' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/mockup-generator/templates/{id}": { "get": { "summary": "Layout templates", "description": "Retrieve list of templates that can be used for client-side positioning.\n\n
\nThis endpoint uses DTG as a default printing technique for product layouts\nwith more than one technique available. For products with DTG and more\ntechniques available please specify the correct technique in query by using\nthe `technique` parameter. For more information read the examples.\n
\n", "operationId": "getTemplates", "security": [ { "OAuth": [] } ], "tags": [ "Mockup Generator API" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/Orientation" }, { "$ref": "#/components/parameters/Technique" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/Templates" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/mockup-generator/templates/71' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/warehouse/products": { "get": { "summary": "Get a list of your warehouse products", "description": "Returns a list of warehouse products from your store\n\n
\n The response for this endpoint was documented as paginated, although it was not paginated. The behavior will be \n fixed and the paginated result will be set as the default. Currently to get paginated results please send\n trueor 1 in X-PF-Force-Pagination header. \n
\n", "operationId": "getWarehouseProducts", "security": [ { "OAuth": [] } ], "tags": [ "Warehouse Products API" ], "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/ForcePagination" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/WarehouseProducts" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/warehouse/products?query=some?offset=0&limit=100' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/warehouse/products/{id}": { "get": { "summary": "Get warehouse product data", "description": "Returns warehouse product data by ID", "operationId": "getWarehouseProduct", "security": [ { "OAuth": [] } ], "tags": [ "Warehouse Products API" ], "parameters": [ { "in": "path", "name": "id", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "required": true, "description": "Product ID" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/WarehouseProduct" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/warehouse/products/12' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } }, "/approval-sheets": { "get": { "summary": "Retrieve a list of approval sheets", "description": "Retrieve a list of approval sheets confirming suggested changes to files of on hold orders.", "operationId": "getApprovalSheets", "tags": [ "Approval Sheets API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/ApprovalSheetsResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "summary": "Approve a design", "description": "Uses the confirm hash of an approval sheet to approve a design and remove the hold on an order", "operationId": "approveDesign", "tags": [ "Approval Sheets API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/ConfirmHash" } ], "requestBody": { "$ref": "#/components/requestBodies/ConfirmApprovalSheet" }, "responses": { "200": { "$ref": "#/components/responses/ApprovalSheetsPostResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/approval-sheets/changes": { "post": { "summary": "Submit changes to an approval sheet", "description": "Use this to submit alternative changes to a design that has an approval sheet", "operationId": "submitApprovalSheetChanges", "tags": [ "Approval Sheets API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/ConfirmHash" } ], "requestBody": { "$ref": "#/components/requestBodies/ApprovalSheetsChangeDesign" }, "responses": { "200": { "$ref": "#/components/responses/ApprovalSheetResponse" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/webhooks": { "get": { "summary": "Get webhook configuration", "description": "Returns configured webhook URL and list of webhook event types enabled for the store", "operationId": "getWebhooks", "security": [ { "OAuth": [ "webhooks" ] } ], "tags": [ "Webhook API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/webhooks' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "post": { "summary": "Set up webhook configuration", "description": "Use this endpoint to enable a webhook URL for a store and select webhook event types that will be sent to this URL.\n\n Note that only one webhook URL can be active for a store, so calling this method disables all existing webhook configuration.\n\n Setting up the [Stock updated](#operation/stockUpdated) webhook requires passing IDs for products that need to be monitored for changes. Stock update webhook will only include information for specified products. These product IDs need to be set up using the params property.", "operationId": "createWebhook", "security": [ { "OAuth": [ "webhooks" ] } ], "tags": [ "Webhook API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateWebhook" }, "responses": { "200": { "$ref": "#/components/responses/WebhookInfo" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/webhooks' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"url\": \"http://www.example.com/printful/webhook\",\n \"types\": [\n \"package_shipped\",\n \"stock_updated\"\n ],\n \"params\": {\n \"stock_updated\": {\n \"product_ids\": [5, 12]\n }\n }\n }'" } ] }, "delete": { "summary": "Disable webhook support", "description": "Removes the webhook URL and all event types from the store.", "operationId": "disableWebhook", "security": [ { "OAuth": [ "webhooks" ] } ], "tags": [ "Webhook API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/webhooks' \\\n--header 'Content-Type: application/json'" } ] } }, "/oauth/scopes": { "get": { "summary": "Get scopes for token", "description": "Returns a list of scopes associated with the token", "operationId": "getScopes", "security": [ { "OAuth": [] } ], "tags": [ "OAuth API" ], "responses": { "200": { "$ref": "#/components/responses/Scopes" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/oauth/scopes' --header 'Authorization: Bearer {oauth_token}'" } ] } }, "/reports/statistics": { "get": { "summary": "Get statistics", "description": "Returns statistics for specified report types.\n\nYou need to specify the report types you want to retrieve in the `report_types` query parameter as a comma-separated list,\ne.g. `report_types=sales_and_costs,profit`.\n\n**Note**: You cannot get statistics for a period longer than 6 months.\n\n#### Example\n\nTo get statistics in the default currency of a store for `sales_and_costs` and `profit` reports for August 2022, you can use the\nfollowing\nURL: https://api.printful.com/reports/statistics?report_types=sales_and_costs,profit&date_from=2022-08-01&date_to=2022-08-31.\n\n### Report types\n\nCurrently, the following report types are available:\n\n| Report type | Description |\n|----------------------------|----------------------------------------------------------|\n| `sales_and_costs` | Detailed information on sales and costs grouped by date. |\n| `sales_and_costs_summary` | Short information on sales and costs grouped by date. |\n| `printful_costs` | Amount paid to Printful for fulfillment and shipping. |\n| `profit` | Profit in the specified period. |\n| `total_paid_orders` | The number of paid orders in the specified period. |\n| `costs_by_amount` | Information on costs by amount grouped by date. |\n| `costs_by_product` | Information on costs grouped by product. |\n| `costs_by_variant` | Information on costs grouped by variant. |\n| `average_fulfillment_time` | Average time it took Printful to fulfill your orders. |\n\nThe response structure for the specific reports is documented in the response schema (`result.store_statistics.[reportName]`).\n", "operationId": "getStatistics", "security": [ { "OAuth": [] } ], "tags": [ "Reports API" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/DateFrom" }, { "$ref": "#/components/parameters/DateTo" }, { "$ref": "#/components/parameters/Currency" }, { "$ref": "#/components/parameters/ReportTypes" } ], "responses": { "200": { "$ref": "#/components/responses/Statistics" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/reports/statistics?report_types=sales_and_costs,profit&date_from=2022-08-01&date_to=2022-08-31¤cy=PLN' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] } } }, "x-webhooks": { "package_shipped": { "post": { "summary": "Package shipped", "operationId": "packageShipped", "description": "Is called when a shipment with all or part of the ordered items is shipped.\n\n If the order is shipped in multiple shipments, this event will be called for every shipment sent.\n\n If some items are reshipped, a shipping notification will be sent again for the same items.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/PackageShipped" }, "responses": { "2xx": { "description": "Data received" } } } }, "package_returned": { "post": { "summary": "Package returned", "operationId": "packageReturned", "description": " Is called when a shipment is processed as returned to the fulfillment facility. To learn more about the reasons why a shipment might be returned, take a look at [Printful's Return Policy](https://www.printful.com/policies/returns) ", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/PackageReturned" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_created": { "post": { "summary": "Order created", "operationId": "orderCreated", "description": "Is called when the order is first created.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderCreated" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_updated": { "post": { "summary": "Order updated", "operationId": "orderUpdated", "description": "Is called when an existing order gets updated for any reason - including things that are covered with other webhooks like `order_canceled`.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderUpdated" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_failed": { "post": { "summary": "Order failed", "operationId": "orderFailed", "description": "Is called when a confirmed order changes its status to `failed`.\n\n It can happen, for example, if printfiles can not be downloaded, are not valid image files or when there is a payment failure.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderFailed" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_canceled": { "post": { "summary": "Order canceled", "operationId": "orderCanceled", "description": "Is called when a confirmed order changes its status to `canceled`.\n\n It can happen when a submitted order is canceled from the dashboard or through the API or when the order is canceled by the Printful staff.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderCanceled" }, "responses": { "2xx": { "description": "Data received" } } } }, "product_synced": { "post": { "summary": "Product synced", "operationId": "productSynced", "description": "Is called when a new product or variant is imported from the store's ecommerce integration.\n\n See [Ecommerce Platform Sync API](#tag/Ecommerce-Platform-Sync-API)", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/ProductSynced" }, "responses": { "2xx": { "description": "Data received" } } } }, "product_updated": { "post": { "summary": "Product updated", "operationId": "productUpdated", "description": "Is called when a new product or variant is created or updated in any way.\n\n See [Ecommerce Platform Sync API](#tag/Ecommerce-Platform-Sync-API)", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/ProductUpdated" }, "responses": { "2xx": { "description": "Data received" } } } }, "product_deleted": { "post": { "summary": "Product deleted", "operationId": "productDeleted", "description": "Is called when a new product or variant is deleted.\n\n See [Ecommerce Platform Sync API](#tag/Ecommerce-Platform-Sync-API)", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/ProductDeleted" }, "responses": { "2xx": { "description": "Data received" } } } }, "stock_updated": { "post": { "summary": "Stock updated", "operationId": "stockUpdated", "description": "Is called when stock is updated for some of a product's variants.\n\n Contains product id and ids of it's discontinued variants and variants that are out of stock. Variant ids that are not present should be considered as active and in stock.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/StockUpdated" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_put_hold": { "post": { "summary": "Order put hold", "operationId": "orderPutHold", "description": "Is called when order is put on hold.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderPutHold" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_put_hold_approval": { "post": { "summary": "Order put hold approval", "operationId": "orderPutHoldApproval", "description": "Is called when order is put on hold and there are changes that must be approved by the customer before fulfillment. Will contain a confirm hash that can be used to approve changes with the Approval Sheets Api.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderHoldApproval" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_remove_hold": { "post": { "summary": "Order remove hold", "operationId": "orderRemoveHold", "description": "Is called when order is removed from hold.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderRemoveHold" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_refunded": { "post": { "summary": "Order refunded", "operationId": "orderRefunded", "description": "Is called when a confirmed order has been refunded.", "tags": [ "Webhook API" ], "requestBody": { "$ref": "#/components/requestBodies/OrderRefunded" }, "responses": { "2xx": { "description": "Data received" } } } } }, "components": { "securitySchemes": { "OAuth": { "type": "oauth2", "description": "### Making authorized API calls\n\nTo make OAuth requests to the Printful API, `access_token` and `token_type` must be included in the request `Authorization` header.\n\n```\n # Authorized CURL request example with OAuth\n curl -X GET 'https://api.printful.com/store/products' \\\n -H 'Authorization: Bearer smk_GN0I1Os3OdfqzjJnTOWn1wlbqqq2Y2Pc10TS'\n```", "flows": { "authorizationCode": { "authorizationUrl": "https://www.printful.com/oauth/token", "tokenUrl": "https://www.printful.com/oauth/token", "refreshUrl": "https://www.printful.com/oauth/token", "scopes": { "orders": "Read and Write access to Orders", "orders/read": "Read access to Orders", "stores_list": "Read and Write access to Stores", "stores_list/read": "Read access to Stores", "sync_products": "Read and Write access to SyncProducts", "sync_products/read": "Read access to SyncProducts", "file_library": "Read and Write access to File library", "file_library/read": "Read access to File library", "webhooks": "Read and Write access to Webhooks", "webhooks/read": "Read access to Webhooks" } } } } }, "parameters": { "ProductCategoryId": { "in": "query", "name": "category_id", "schema": { "type": "string" }, "required": false, "description": "A comma-separated list of Category IDs of the Products that are to be returned" }, "VariantId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "Variant id" }, "ProductId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "Product ID." }, "MeasurementUnit": { "in": "query", "name": "unit", "schema": { "type": "string", "example": "inches,cm" }, "required": false, "description": "A comma-separated list of measurement unit in which size tables are to be returned (`inches` or `cm`).\nThe default value is determined based on the locale country. The inches are used for United States, Liberia\nand Myanmar, for other countries the unit defaults to centimeters.\n" }, "CategoryId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "Category ID" }, "StoreId": { "in": "header", "name": "X-PF-Store-Id", "description": "Use this to specify which store you want to use (required only for account level token).\n\nThe store IDs can be retrieved with the [Get basic information about stores](#tag/Store-Information-API/operation/getStores) endpoint.\n", "schema": { "type": "string" }, "required": false }, "SyncStatus": { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "all", "synced", "unsynced", "ignored", "imported", "discontinued", "out_of_stock" ] }, "description": "Parameter used to filter results by status/group of Sync Products" }, "SyncProductId": { "in": "path", "name": "id", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "required": true, "description": "Sync Product ID (integer) or External ID (if prefixed with @)" }, "SyncVariantId": { "in": "path", "name": "id", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "required": true, "description": "Sync Variant ID (integer) or External ID (if prefixed with @)" }, "Offset": { "in": "query", "name": "offset", "schema": { "type": "integer" }, "required": false, "description": "Result set offset" }, "Limit": { "in": "query", "name": "limit", "schema": { "type": "integer" }, "required": false, "description": "Number of items per page (max 100)" }, "TemplateById": { "in": "path", "name": "id", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "required": true, "description": "Template ID (integer) or External Product ID (if prefixed with @)" }, "Status": { "in": "query", "name": "status", "schema": { "type": "string" }, "required": false, "description": "Filter by order status" }, "Confirm": { "in": "query", "name": "confirm", "schema": { "type": "boolean" }, "required": false, "description": "Automatically submit the newly created order for fulfillment (skip the Draft phase)" }, "UpdateExisting": { "in": "query", "name": "update_existing", "schema": { "type": "boolean" }, "required": false, "description": "Try to update existing order if an order with the specified external_id already exists" }, "OrderId": { "in": "path", "name": "id", "schema": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "required": true, "description": "Order ID (integer) or External ID (if prefixed with @)" }, "FileId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "File ID." }, "Search": { "name": "search", "in": "query", "required": false, "description": "Product search needle", "schema": { "type": "string" } }, "StoreInformationId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "Store ID" }, "Orientation": { "in": "query", "name": "orientation", "schema": { "type": "string", "description": "Optional orientation for wall art product printfiles. Allowed values: horizontal, vertical", "enum": [ "horizontal", "vertical" ] } }, "Technique": { "in": "query", "name": "technique", "schema": { "type": "string", "description": "Optional technique for product. This can be used in cases where product supports multiple techniques like DTG and embroidery" } }, "TaskKey": { "in": "query", "name": "task_key", "schema": { "type": "string" }, "required": true, "description": "Task key retrieved when creating the generation task." }, "Query": { "in": "query", "name": "query", "schema": { "type": "string" }, "required": false, "description": "Filter by partial or full product name" }, "ForcePagination": { "in": "header", "name": "X-PF-Force-Pagination", "schema": { "oneOf": [ { "type": "boolean" }, { "type": "integer" } ] }, "required": false, "description": "Whether the pagination behavior should be forced. The response will be paginated if the value is `true` or `1`." }, "ConfirmHash": { "in": "query", "name": "confirm_hash", "schema": { "type": "string" }, "required": true, "description": "The confirm hash for the approval sheet you would like to approve.", "example": "a14e51714be01f98487fcf5131727d31" }, "DateFrom": { "in": "query", "name": "date_from", "description": "The beginning of the period to get the statistics from (date in `Y-m-d` format).", "schema": { "type": "string", "format": "date", "example": "2022-08-01" }, "required": true }, "DateTo": { "in": "query", "name": "date_to", "description": "The end of the period to get the statistics from (date in `Y-m-d` format).", "schema": { "type": "string", "format": "date", "example": "2022-08-31" }, "required": true }, "Currency": { "in": "query", "name": "currency", "description": "The currency (3-letter code) to return the statistics in. You can also specify `display_currency` as the value to get the statistics in the account's display currency. The store currency will be used by default.", "schema": { "type": "string", "example": "USD" }, "required": false }, "ReportTypes": { "in": "query", "name": "report_types", "description": "A comma-separated list of report types to be retrieved.", "schema": { "type": "string", "example": "sales_and_costs,profit" }, "required": true } }, "schemas": { "Response200": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 } } }, "CatalogFileOption": { "type": "object", "title": "CatalogFileOption", "properties": { "id": { "type": "string", "description": "File option identifier. Use this to specify which option you are adding to your file in a request.", "example": "full_color" }, "type": { "type": "string", "example": "bool", "description": "The type of the value property when using this option in a request." }, "title": { "type": "string", "example": "Unlimited color" }, "additional_price": { "type": "number", "description": "Additional cost this will add to the item.", "example": 3.25 } } }, "FileType": { "type": "object", "title": "FileType", "properties": { "id": { "description": "Deprecated file type identifier. Please use type field instead!", "deprecated": true, "type": "string", "example": "default" }, "type": { "description": "File type identifier - use this to specify a file's purpose when creating an order", "type": "string", "example": "front" }, "title": { "description": "Display name", "type": "string", "example": "Front print" }, "additional_price": { "description": "Additional price when this print file type is used", "type": "string", "example": "2.22" }, "options": { "description": "Additional options available to product files", "type": "array", "items": { "$ref": "#/components/schemas/CatalogFileOption" } } } }, "OptionType": { "type": "object", "title": "OptionType", "properties": { "id": { "description": "Option identifier - use this to specify the option when creating an order", "type": "string", "example": "embroidery_type" }, "title": { "description": "Display name", "type": "string", "example": "Embroidery type" }, "type": { "description": "Data type of this option (currently only 'bool' is supported)", "type": "string", "example": "radio" }, "values": { "description": "Possible option values - [key, value] map", "type": "object", "additionalProperties": true, "example": { "flat": "Flat Embroidery", "3d": "3D Puff", "both": "Partial 3D Puff" } }, "additional_price": { "description": "Additional price when this option is used", "type": "string" }, "additional_price_breakdown": { "description": "Additional price breakdown by type - [key, value] map", "type": "object", "additionalProperties": true, "example": { "flat": "0.00", "3d": "0.00", "both": "0.00" } } } }, "AvailableTechnique": { "type": "object", "title": "AvailableTechnique", "properties": { "key": { "description": "The technique key to be used in the API", "type": "string", "example": "DTG" }, "display_name": { "description": "The human-readable technique name", "type": "string", "example": "DTG printing" }, "is_default": { "description": "Whether the technique is the default one", "type": "boolean" } } }, "Product": { "type": "object", "title": "Product", "description": "Information about the Product that the Variant belongs to", "properties": { "id": { "description": "Product ID", "type": "integer", "example": 13 }, "main_category_id": { "description": "Main category of product", "type": "integer", "example": 24 }, "type": { "description": "Product type identifier", "type": "string", "example": "T-SHIRT" }, "type_name": { "description": "Product type name", "type": "string", "example": "T-Shirt" }, "title": { "description": "Product title", "type": "string", "example": "Unisex Staple T-Shirt | Bella + Canvas 3001" }, "brand": { "description": "Brand name", "type": "string", "example": "Gildan" }, "model": { "description": "Model name", "type": "string", "example": "2200 Ultra Cotton Tank Top" }, "image": { "description": "URL of a sample image for this product", "type": "string", "example": "https://files.cdn.printful.com/products/12/product_1550594502.jpg" }, "variant_count": { "description": "Number of available variants for this product", "type": "integer", "example": 30 }, "currency": { "description": "Currency in which prices are returned", "type": "string", "example": "EUR" }, "files": { "description": "Definitions of Print/Mockup file categories that can be attached to this product", "type": "array", "items": { "$ref": "#/components/schemas/FileType" } }, "options": { "description": "Definitions of additional options that are available for this product [See examples](#tag/Common/Options)", "type": "array", "items": { "$ref": "#/components/schemas/OptionType" } }, "is_discontinued": { "description": "If product is disabled in push", "type": "boolean", "example": false }, "avg_fulfillment_time": { "description": "Average number of days for order to be fulfilled", "type": "number", "example": 4.3 }, "description": { "description": "Product description", "type": "string" }, "techniques": { "description": "Available techniques", "type": "array", "items": { "$ref": "#/components/schemas/AvailableTechnique" } }, "origin_country": { "description": "The origin country for inside label", "type": "string", "nullable": true, "example": "Nicaragua" } } }, "AvailabilityStatus": { "type": "object", "title": "AvailabilityStatus", "properties": { "region": { "description": "Region code", "type": "string", "example": "US" }, "status": { "description": "Stock status. Possible values include: 'in_stock' - available for fulfillment, 'stocked_on_demand' - available for fulfillment, 'discontinued' - permanently unavailable, 'out_of_stock' - temporarily unavailable", "type": "string", "example": "in_stock" } } }, "Material": { "type": "object", "title": "Material", "properties": { "name": { "type": "string", "description": "Material name", "example": "cotton" }, "percentage": { "type": "number", "description": "Percentage of the material in the product", "example": 100 } } }, "Variant": { "type": "object", "title": "Variant", "properties": { "id": { "description": "Variant ID, use this to specify the product when creating orders", "type": "integer", "example": 100 }, "product_id": { "description": "ID of the product that this variant belongs to", "type": "integer", "example": 12 }, "name": { "description": "Display name", "type": "string", "example": "Gildan 64000 Unisex Softstyle T-Shirt with Tear Away (Black / 2XL)" }, "size": { "description": "Item size", "type": "string", "example": "2XL" }, "color": { "description": "Item color", "type": "string", "example": "Black" }, "color_code": { "description": "Hexadecimal RGB color code. May not exactly reflect the real-world color", "type": "string", "example": "#14191e" }, "color_code2": { "description": "Secondary hexadecimal RGB color code. May not exactly reflect the real-world color", "type": "string" }, "image": { "description": "URL of a preview image for this variant", "type": "string", "example": "https://files.cdn.printful.com/products/12/629_1517916489.jpg" }, "price": { "description": "Variant's price (can change depending on print files and optional settings)", "type": "string", "example": "9.85" }, "in_stock": { "description": "Stock availability of this variant", "type": "boolean", "example": true }, "availability_regions": { "description": "Map of [region code, region name] of regions where the variant is available for fulfillment", "type": "object", "additionalProperties": true, "example": { "US": "USA", "EU": "Europe" } }, "availability_status": { "description": "Detailed stock status per region", "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityStatus" } }, "material": { "description": "A list of materials this Variant is composed of", "type": "array", "items": { "$ref": "#/components/schemas/Material" } } } }, "ProductInfo": { "type": "object", "title": "ProductInfo", "properties": { "product": { "$ref": "#/components/schemas/Product" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } } } }, "MeasurementValue": { "type": "object", "title": "MeasurementValue", "description": "The measurement value for a specific size", "required": [ "size" ], "properties": { "size": { "description": "The size with which the value is associated", "type": "string", "example": "S" }, "value": { "description": "The single value associated with a size (whether this or `min_value` and `max_value` will be present)", "type": "string", "example": "23.5" }, "min_value": { "description": "The lower boundary of the value range (whether this and `max_value` or `value` will be present)", "type": "string", "example": "20" }, "max_value": { "description": "The upper boundary of the value range (whether this and `min_value` or `value` will be present)", "type": "string", "example": "20" } } }, "Measurement": { "type": "object", "title": "Measurement", "description": "The information about a single size table measurement", "required": [ "type", "values" ], "properties": { "type_label": { "description": "Measurement type", "type": "string", "example": "Length" }, "unit": { "description": "The measurement unit if it's not defined on the size table level or is different", "type": "string", "example": "none" }, "values": { "description": "The measurement values for each size", "type": "array", "items": { "$ref": "#/components/schemas/MeasurementValue" } } } }, "SizeTable": { "type": "object", "title": "SizeTable", "description": "Size table for the Product", "required": [ "type", "measurements" ], "properties": { "type": { "description": "Size table type", "type": "string", "enum": [ "measure_yourself", "product_measure", "international" ] }, "unit": { "description": "The unit the size table values are in", "type": "string", "enum": [ "inches", "cm" ] }, "description": { "description": "The size table description (HTML)", "type": "string" }, "image_url": { "description": "The URL of an image showing the measurements", "type": "string" }, "image_description": { "description": "The description of the measurement image (HTML)", "type": "string" }, "measurements": { "description": "The size table measurements", "type": "array", "items": { "$ref": "#/components/schemas/Measurement" } } } }, "ProductSizeGuide": { "type": "object", "title": "ProductSizeGuide", "description": "Size Guide information for the Product", "required": [ "product_id", "available_sizes", "size_tables" ], "properties": { "product_id": { "description": "Product ID", "type": "integer", "example": 13 }, "available_sizes": { "description": "The sizes available for the Product", "type": "array", "items": { "type": "string" }, "example": [ "S", "M", "L" ] }, "size_tables": { "description": "Size tables for the product", "type": "array", "items": { "$ref": "#/components/schemas/SizeTable" }, "example": [ { "type": "measure_yourself", "unit": "inches", "description": "

Measurements are provided by suppliers.

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Product measurements may vary by up to 2\\\" (5 cm). 

", "image_url": "https://s3.staging.printful.com/upload/measure-yourself/6a/6a4fe322f592f2b91d5a735d7ff8d1c0_t?v=1652962720", "image_description": "
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Chest
\\n

Measure yourself around the fullest part of your chest. Keep the tape measure horizontal.

", "measurements": [ { "type_label": "Length", "values": [ { "size": "S", "value": "24" }, { "size": "M", "value": "26" }, { "size": "L", "value": "28" } ] }, { "type_label": "Chest", "values": [ { "size": "S", "min_value": "14", "max_value": "16" }, { "size": "M", "min_value": "18", "max_value": "20" }, { "size": "L", "min_value": "22", "max_value": "24" } ] } ] }, { "type": "product_measure", "unit": "inches", "description": "

Measurements are provided by our suppliers. Product measurements may vary by up to 2\\\" (5 cm).

\\n

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Pro tip! Measure one of your products at home and compare with the measurements you see in this guide.

", "image_url": "https://s3.staging.printful.com/upload/product-measure/85/857e7cc8b802da216e7f1a6114075a72_t?v=1652962720", "image_description": "
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Width
\\n

Place the end of the tape at the seam under the sleeve and pull the tape measure across the shirt to the seam under the opposite sleeve.

", "measurements": [ { "type_label": "Length", "values": [ { "size": "S", "value": "24" }, { "size": "M", "value": "26" }, { "size": "L", "value": "28" } ] }, { "type_label": "Width", "values": [ { "size": "S", "min_value": "14", "max_value": "16" }, { "size": "M", "min_value": "18", "max_value": "20" }, { "size": "L", "min_value": "22", "max_value": "24" } ] } ] }, { "type": "measure_yourself", "unit": "cm", "description": "

Measurements are provided by suppliers.

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Product measurements may vary by up to 2\\\" (5 cm). 

", "image_url": "https://s3.staging.printful.com/upload/measure-yourself/6a/6a4fe322f592f2b91d5a735d7ff8d1c0_t?v=1652962720", "image_description": "
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Chest
\\n

Measure yourself around the fullest part of your chest. Keep the tape measure horizontal.

", "measurements": [ { "type_label": "Length", "values": [ { "size": "S", "value": "60.96" }, { "size": "M", "value": "66.04" }, { "size": "L", "value": "71.12" } ] }, { "type_label": "Chest", "values": [ { "size": "S", "min_value": "35.56", "max_value": "40.64" }, { "size": "M", "min_value": "45.72", "max_value": "50.80" }, { "size": "L", "min_value": "55.88", "max_value": "60.96" } ] } ] }, { "type": "product_measure", "unit": "cm", "description": "

Measurements are provided by our suppliers. Product measurements may vary by up to 2\\\" (5 cm).

\\n

US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.

\\n

Pro tip! Measure one of your products at home and compare with the measurements you see in this guide.

", "image_url": "https://s3.staging.printful.com/upload/product-measure/85/857e7cc8b802da216e7f1a6114075a72_t?v=1652962720", "image_description": "
A Length
\\n

Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure to the bottom of the shirt.

\\n
B Width
\\n

Place the end of the tape at the seam under the sleeve and pull the tape measure across the shirt to the seam under the opposite sleeve.

", "measurements": [ { "type_label": "Length", "values": [ { "size": "S", "value": "60.96" }, { "size": "M", "value": "66.04" }, { "size": "L", "value": "71.12" } ] }, { "type_label": "Width", "values": [ { "size": "S", "min_value": "35.56", "max_value": "40.64" }, { "size": "M", "min_value": "45.72", "max_value": "50.80" }, { "size": "L", "min_value": "55.88", "max_value": "60.96" } ] } ] }, { "type": "international", "unit": "none", "measurements": [ { "type_label": "US size", "values": [ { "size": "S", "min_value": "8", "max_value": "10" }, { "size": "M", "min_value": "12", "max_value": "14" }, { "size": "L", "min_value": "16", "max_value": "18" } ] }, { "type_label": "EU size", "values": [ { "size": "S", "min_value": "38", "max_value": "39" }, { "size": "M", "min_value": "40", "max_value": "41" }, { "size": "L", "min_value": "42", "max_value": "43" } ] }, { "type_label": "UK size", "values": [ { "size": "S", "min_value": "4", "max_value": "6" }, { "size": "M", "min_value": "8", "max_value": "10" }, { "size": "L", "min_value": "12", "max_value": "14" } ] } ] } ] } } }, "Category": { "type": "object", "title": "Category", "description": "Information about the Category", "properties": { "id": { "description": "Category ID", "type": "integer", "example": 24 }, "parent_id": { "description": "ID of the parent Category. If there is no parent Category, 0 is returned.", "type": "integer", "example": 6 }, "image_url": { "description": "The URL of the Category image", "type": "string", "example": "https://s3.staging.printful.com/upload/catalog_category/b1/b1513c82696405fcc316fc611c57f132_t?v=1646395980" }, "size": { "description": "The size of the category image", "type": "string", "enum": [ "small", "medium", "large" ] }, "title": { "description": "Category title", "type": "string", "example": "T-Shirts" } } }, "Paging": { "type": "object", "title": "Paging", "description": "Paging information", "required": [ "total", "offset", "limit" ], "properties": { "total": { "type": "integer", "example": 100, "description": "Total number of items available" }, "offset": { "type": "integer", "example": 10, "description": "Current result set page offset" }, "limit": { "type": "integer", "description": "Max number of items per page", "example": 100 } } }, "Response200Paginated": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "paging": { "$ref": "#/components/schemas/Paging" } } } ] }, "SyncProduct": { "type": "object", "title": "SyncProduct", "description": "Information about the SyncProduct", "required": [ "name" ], "properties": { "id": { "description": "SyncProduct ID", "type": "integer", "example": 13, "readOnly": true }, "external_id": { "description": "Product ID from the Ecommerce platform", "type": "string", "example": "4235234213" }, "name": { "description": "Product name", "type": "string", "example": "T-shirt" }, "variants": { "description": "Total number of Sync Variants belonging to this product", "type": "integer", "example": 10, "readOnly": true }, "synced": { "description": "Number of synced Sync Variants belonging to this product", "type": "integer", "example": 10, "readOnly": true }, "thumbnail": { "type": "string", "description": "Thumbnail image URL. Although we do not limit thumbnail image size, we recommend to keep it reasonably small.", "maxLength": 250, "example": "​http://your-domain.com/path/to/thumbnail.png", "writeOnly": true }, "thumbnail_url": { "description": "Thumbnail image for the product", "type": "string", "example": "​https://your-domain.com/path/to/image.png", "readOnly": true }, "is_ignored": { "description": "Indicates if this Sync Product is ignored", "type": "boolean" } } }, "ProductVariant": { "type": "object", "title": "ProductVariant", "description": "Short information about the Printful Product and Variant", "properties": { "variant_id": { "type": "integer", "description": "Variant ID", "example": 3001 }, "product_id": { "type": "integer", "description": "Product ID of this variant", "example": 301 }, "image": { "type": "string", "description": "URL of a sample image for this variant", "example": "https://files.cdn.printful.com/products/71/5309_1581412541.jpg" }, "name": { "type": "string", "description": "Display name of this variant", "example": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)" } } }, "FileOption": { "type": "object", "title": "FileOption", "description": "File option", "required": [ "id", "value" ], "properties": { "id": { "type": "string", "description": "Option id", "example": "template_type" }, "value": { "type": "string", "description": "Option value", "example": "native" } } }, "File": { "type": "object", "title": "File", "description": "Information about the File", "required": [ "url" ], "properties": { "type": { "type": "string", "description": "Role of the file", "example": "default" }, "id": { "type": "integer", "description": "File ID", "example": 10, "readOnly": true }, "url": { "type": "string", "description": "Source URL where the file is downloaded from. The use of .ai .psd and .tiff files have been depreciated, if your application uses these file types or accepts these types from users you will need to add validation.", "example": "​https://www.example.com/files/tshirts/example.png" }, "options": { "type": "array", "description": "Array of additional options for this file [See examples](#tag/Common/Options)", "items": { "$ref": "#/components/schemas/FileOption" } }, "hash": { "type": "string", "description": "MD5 checksum of the file", "example": "ea44330b887dfec278dbc4626a759547", "readOnly": true }, "filename": { "type": "string", "description": "File name", "example": "shirt1.png" }, "mime_type": { "type": "string", "description": "MIME type of the file", "example": "image/png", "readOnly": true }, "size": { "type": "integer", "description": "Size in bytes", "example": 45582633, "readOnly": true }, "width": { "type": "integer", "description": "Width in pixels", "example": 1000, "readOnly": true }, "height": { "type": "integer", "description": "Height in pixels", "example": 1000, "readOnly": true }, "dpi": { "type": "integer", "description": "Resolution DPI.
**Note:** for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.", "example": 300, "readOnly": true }, "status": { "type": "string", "description": "File processing status:
**ok** - file was processed successfuly
**waiting** - file is being processed
**failed** - file failed to be processed", "example": "ok", "readOnly": true }, "created": { "type": "integer", "description": "File creation timestamp", "example": 1590051937, "readOnly": true }, "thumbnail_url": { "type": "string", "description": "Small thumbnail URL", "example": "https://files.cdn.printful.com/files/ea4/ea44330b887dfec278dbc4626a759547_thumb.png", "readOnly": true }, "preview_url": { "type": "string", "description": "Medium preview image URL", "example": "https://files.cdn.printful.com/files/ea4/ea44330b887dfec278dbc4626a759547_thumb.png", "readOnly": true }, "visible": { "type": "boolean", "description": "Show file in the Printfile Library (default true)", "example": true }, "is_temporary": { "type": "boolean", "readOnly": true, "description": "Whether it is a temporary printfile.", "example": false } } }, "SyncVariantFile": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "properties": { "stitch_count_tier": { "type": "string", "description": "Stitch count tier see https://help.printful.com/hc/en-us/articles/4909652626204-What-s-the-new-large-embroidery-pricing-", "nullable": true, "readOnly": true, "example": "stitch_tier_1" } } } ] }, "ItemOption": { "type": "object", "title": "SyncVariantOption", "description": "Additional options for the configured product/variant", "required": [ "id", "value" ], "properties": { "id": { "type": "string", "description": "Option id", "example": "embroidery_type" }, "value": { "type": "string", "description": "Option value", "example": "flat" } } }, "SyncVariant": { "type": "object", "title": "SyncVariant", "description": "Information about the SyncVariant", "properties": { "id": { "type": "integer", "description": "Sync Variant ID", "example": 10, "readOnly": true }, "external_id": { "type": "string", "description": "Variant ID from the Ecommerce platform", "example": "12312414" }, "sync_product_id": { "type": "integer", "description": "Sync Product ID that this variant belongs to", "example": 71, "readOnly": true }, "name": { "type": "string", "description": "Sync Variant name", "example": "Red T-Shirt", "readOnly": true }, "synced": { "type": "boolean", "description": "Indicates if this Sync Variant is properly linked with Printful product", "example": true, "readOnly": true }, "variant_id": { "type": "integer", "description": "Printful Variant ID that this Sync Variant is synced to", "example": 3001 }, "retail_price": { "type": "string", "description": "Retail price that this item is sold for", "example": "29.99" }, "currency": { "type": "string", "description": "Currency in which prices are returned", "example": "USD", "readOnly": true }, "is_ignored": { "type": "boolean", "description": "Indicates if this Sync Variant is ignored", "example": true }, "sku": { "type": "string", "description": "SKU of this Sync Variant", "example": "SKU1234", "nullable": true }, "product": { "allOf": [ { "$ref": "#/components/schemas/ProductVariant" }, { "readOnly": true } ] }, "files": { "type": "array", "description": "Array of attached printfiles / preview images", "items": { "$ref": "#/components/schemas/SyncVariantFile" } }, "options": { "type": "array", "description": "Array of additional options for the configured product/variant [See examples](#tag/Common/Options)", "items": { "$ref": "#/components/schemas/ItemOption" } }, "main_category_id": { "type": "integer", "description": "Printful Variant catalog category ID", "example": 24, "readOnly": true, "nullable": true }, "warehouse_product_id": { "type": "integer", "description": "Warehousing product ID. If the sync variant is connected with a warehousing item, this is the ID of corresponding warehouse product.", "example": 3002, "readOnly": true, "nullable": true }, "warehouse_product_variant_id": { "type": "integer", "description": "Warehousing variant ID. If the sync variant is connected with a warehousing item, this is its ID.", "example": 3002, "readOnly": true, "nullable": true }, "size": { "type": "string", "description": "The size of the associated Catalog Variant", "example": "XS", "readOnly": true, "nullable": true }, "color": { "type": "string", "description": "The color of the associated Catalog Variant", "example": "White", "readOnly": true, "nullable": true }, "availability_status": { "description": "Indicates the status of the Sync Variant.", "type": "string", "enum": [ "active", "discontinued", "out_of_stock", "temporary_out_of_stock" ] } } }, "TemplateById": { "type": "object", "title": "Product template", "description": "Information about the template", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "external_product_id": { "type": "string" }, "title": { "type": "string" }, "available_variant_ids": { "type": "array", "items": { "type": "integer" } }, "option_data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "type": "array", "items": { "type": "string" } } } } }, "colors": { "type": "array", "items": { "type": "object", "properties": { "color_name": { "type": "string" }, "color_codes": { "type": "array" } } } }, "sizes": { "type": "array", "items": { "type": "string" } }, "mockup_file_url": { "type": "string" }, "placements": { "type": "array", "items": { "type": "object", "properties": { "placement": { "type": "string" }, "display_name": { "type": "string" }, "technique_key": { "type": "string", "example": "SUBLIMATION" }, "technique_display_name": { "type": "string", "example": "Sublimation" } } } }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "placement_option_data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "embroidery_chest_left" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "full_color" }, "value": { "example": true } } } } } } } } }, "Templates": { "type": "object", "title": "Product template", "description": "Information about the template", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateById" } } } }, "Address": { "type": "object", "title": "Address", "description": "Information about the address", "properties": { "name": { "description": "Full name", "type": "string", "example": "John Smith" }, "company": { "description": "Company name", "type": "string", "example": "John Smith Inc" }, "address1": { "description": "Address line 1", "type": "string", "example": "19749 Dearborn St" }, "address2": { "description": "Address line 2", "type": "string" }, "city": { "description": "City", "type": "string", "example": "Chatsworth" }, "state_code": { "description": "State code", "type": "string", "example": "CA" }, "state_name": { "description": "State name", "type": "string", "example": "California" }, "country_code": { "description": "Country code", "type": "string", "example": "US" }, "country_name": { "description": "Country name", "type": "string", "example": "United States" }, "zip": { "description": "ZIP/Postal code", "type": "string", "example": "91311" }, "phone": { "description": "Phone number", "example": "2312322334", "type": "string" }, "email": { "description": "Email address", "example": "firstname.secondname@domain.com", "type": "string" }, "tax_number": { "description": "TAX number (`optional`, but in case of Brazil country this field becomes `required` and will be used as CPF/CNPJ number)
CPF format is 000.000.000-00 (14 characters);
CNPJ format is 00.000.000/0000-00 (18 characters).", "type": "string", "example": "123.456.789-10" } } }, "GenerationTaskFilePosition": { "type": "object", "title": "GenerationTaskFilePosition", "description": "Position", "properties": { "area_width": { "type": "integer", "description": "Positioning area width on print area in pixels", "example": 1800, "nullable": true }, "area_height": { "type": "integer", "description": "Positioning area height on print area in pixels", "example": 2400, "nullable": true }, "width": { "type": "integer", "description": "Width of the image in given area in pixels", "example": 1800, "readOnly": false }, "height": { "type": "integer", "description": "Height of the image in given area in pixels", "example": 1800, "readOnly": false }, "top": { "type": "integer", "description": "Image top offset in given area in pixels", "example": 300 }, "left": { "type": "integer", "description": "Image left offset in given area in pixels", "example": 0 } } }, "Option": { "type": "object", "title": "ItemOption", "description": "Additional option for order item", "properties": { "id": { "type": "string", "description": "Option ID", "example": "OptionKey" }, "value": { "type": "string", "description": "Option value", "example": "OptionValue" } } }, "Item": { "type": "object", "title": "Item", "description": "Information about an item in the order", "properties": { "id": { "description": "Line item ID", "type": "integer", "example": 1 }, "external_id": { "description": "Line item ID from the external system", "type": "string", "example": "item-1" }, "variant_id": { "description": "Variant ID of the item ordered. See [Catalog API](#tag/Catalog-API)", "type": "integer", "example": 1 }, "sync_variant_id": { "description": "Sync variant ID of the item ordered. [Example](#tag/Examples/Orders-API-examples/Using-a-sync-variant).", "type": "integer", "example": 1 }, "external_variant_id": { "description": "External variant ID of the item ordered. [Example](#tag/Examples/Orders-API-examples/Using-sync-variant-with-external-ID).", "type": "string", "example": "variant-1" }, "warehouse_product_variant_id": { "description": "Warehousing product variant ID of the item ordered. See Warehouse Products API", "type": "integer", "example": 1 }, "product_template_id": { "description": "The ID of a Product Template to generate the printfiles from. The `variant_id` field must be passed as well.\nCan't be combined with following fields: `sync_variant_id`, `external_variant_id`, `warehouse_product_variant_id`,\n`files`, `options`, `external_product_id`. [Examples](#tag/Examples/Orders-API-examples/Using-a-product-template).\n", "type": "integer", "example": 1 }, "external_product_id": { "description": "The External Product ID associated with a Product Template to generate the printfiles from.\nThe `variant_id` field must be passed as well. Can't be combined with following fields: `sync_variant_id`,\n`external_variant_id`, `warehouse_product_variant_id`, `files`, `options`, `product_template_id`. [Examples](#tag/Examples/Orders-API-examples/Using-a-product-template).\n", "type": "string", "example": "template-123", "writeOnly": true }, "quantity": { "description": "Number of items ordered (Limited to 1000 for one item)", "type": "integer", "example": 1 }, "price": { "description": "Printful price of the item", "type": "string", "example": "13.00" }, "retail_price": { "description": "Original retail price of the item to be displayed on the packing slip", "type": "string", "example": "13.00" }, "name": { "description": "Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip", "type": "string", "example": "Enhanced Matte Paper Poster 18×24" }, "product": { "$ref": "#/components/schemas/ProductVariant" }, "files": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/File" }, { "type": "object", "properties": { "position": { "writeOnly": true, "allOf": [ { "$ref": "#/components/schemas/GenerationTaskFilePosition" }, { "type": "object", "properties": { "limit_to_print_area": { "type": "boolean", "default": true, "description": "Should limit printfile to print area" } } } ] } } } ] }, "description": "Array of attached printfiles / preview images" }, "options": { "type": "array", "description": "Array of additional options for this product [See examples](#tag/Common/Options)", "items": { "$ref": "#/components/schemas/Option" } }, "sku": { "description": "Product identifier (SKU) from the external system", "type": "string", "example": null }, "discontinued": { "description": "Whether the item belongs to discontinued product i.e. it's permanently unavailable", "type": "boolean", "example": true }, "out_of_stock": { "description": "Whether the item is out of stock i.e. temporarily unavailable", "type": "boolean", "example": true } }, "anyOf": [ { "required": [ "variant_id" ] }, { "required": [ "sync_variant_id" ] }, { "required": [ "external_variant_id" ] }, { "required": [ "warehouse_product_variant_id" ] }, { "required": [ "variant_id", "product_template_id" ] }, { "required": [ "variant_id", "external_product_id" ] } ], "not": { "anyOf": [ { "required": [ "product_template_id", "sync_variant_id" ] }, { "required": [ "product_template_id", "external_variant_id" ] }, { "required": [ "product_template_id", "warehouse_product_variant_id" ] }, { "required": [ "product_template_id", "files" ] }, { "required": [ "product_template_id", "options" ] }, { "required": [ "product_template_id", "external_product_id" ] }, { "required": [ "external_product_id", "sync_variant_id" ] }, { "required": [ "external_product_id", "external_variant_id" ] }, { "required": [ "external_product_id", "warehouse_product_variant_id" ] }, { "required": [ "external_product_id", "files" ] }, { "required": [ "external_product_id", "options" ] }, { "required": [ "external_product_id", "product_template_id" ] } ] } }, "IncompleteItem": { "type": "object", "title": "IncompleteItem", "description": "Information about an incomplete item in the order", "properties": { "name": { "type": "string", "description": "Incomplete item name", "example": "Red T-Shirt" }, "quantity": { "description": "Incompleted item quantity", "type": "integer", "example": 1 }, "sync_variant_id": { "description": "Sync variant ID of the incompleted item.", "type": "integer", "example": 70 }, "external_variant_id": { "description": "External variant ID of the incompleted item.", "type": "string", "example": "external-id" }, "external_line_item_id": { "description": "External order line item id.", "type": "string", "example": "external-line-item-id" } } }, "Costs": { "type": "object", "title": "OrderCosts", "description": "Order costs (Printful prices)", "properties": { "currency": { "type": "string", "description": "3 letter currency code", "example": "USD" }, "subtotal": { "type": "string", "description": "Total cost of all items", "example": "10.00" }, "discount": { "type": "string", "description": "Discount sum", "example": "0.00" }, "shipping": { "type": "string", "description": "Shipping costs", "example": "5.00" }, "digitization": { "type": "string", "description": "Digitization costs", "example": "0.00" }, "additional_fee": { "type": "string", "description": "Additional fee for custom product", "example": "0.00" }, "fulfillment_fee": { "type": "string", "description": "Custom product fulfillment fee", "example": "0.00" }, "retail_delivery_fee": { "type": "string", "description": "Retail delivery fee", "example": "0.00" }, "tax": { "type": "string", "description": "Sum of taxes (not included in the item price)", "example": "0.00" }, "vat": { "type": "string", "description": "Sum of vat (not included in the item price)", "example": "0.00" }, "total": { "type": "string", "description": "Grand Total (subtotal-discount+tax+vat+shipping)", "example": "15.00" } } }, "RetailCosts": { "type": "object", "title": "OrderRetailCosts", "description": "Retail costs that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the `retail_price` attribute.", "properties": { "currency": { "type": "string", "description": "3 letter currency code", "example": "USD" }, "subtotal": { "type": "string", "nullable": true, "description": "Total cost of all items", "example": "10.00" }, "discount": { "type": "string", "nullable": true, "description": "Discount sum", "example": "0.00" }, "shipping": { "type": "string", "nullable": true, "description": "Shipping costs", "example": "5.00" }, "tax": { "type": "string", "nullable": true, "description": "Sum of taxes (not included in the item price)", "example": "0.00" }, "vat": { "type": "string", "nullable": true, "readOnly": true, "description": "Sum of VAT (not included in the item price)", "example": "0.00" }, "total": { "type": "string", "nullable": true, "readOnly": true, "description": "Grand Total (subtotal-discount+tax+vat+shipping)", "example": "15.00" } } }, "PricingBreakdown": { "type": "object", "title": "PricingBreakdown", "description": "Difference between order price and retail costs. Will be shown only if order is completed.", "properties": { "customer_pays": { "type": "string", "description": "Amount customer paid", "example": "3.75" }, "printful_price": { "type": "string", "description": "Printful price", "example": "6" }, "profit": { "type": "string", "description": "Profit", "example": "-2.25" }, "currency_symbol": { "type": "string", "description": "Shipment tracking number", "example": "USD" } } }, "OrderShipmentItem": { "type": "object", "title": "OrderShipmentItem", "description": "Information about item in an order shipment", "properties": { "item_id": { "type": "integer", "description": "Line item ID", "example": 1 }, "quantity": { "type": "integer", "description": "Quantity of items in this shipment", "example": 1 }, "picked": { "type": "integer", "enum": [ 0, 1 ], "description": "A boolean indicating that the pickup stage of this item's fulfillment has been completed", "example": 1 }, "printed": { "type": "integer", "enum": [ 0, 1 ], "description": "A boolean indicting that the item has been printed, sublimated or sewed.", "example": 1 } } }, "Shipment": { "type": "object", "title": "OrderShipment", "description": "Information about order shipment", "properties": { "id": { "type": "integer", "description": "Shipment ID", "example": 10 }, "carrier": { "type": "string", "description": "Carrier name", "example": "FEDEX" }, "service": { "type": "string", "description": "Delivery service name", "example": "FedEx SmartPost" }, "tracking_number": { "type": "string", "description": "Shipment tracking number", "example": 0 }, "tracking_url": { "type": "string", "description": "Shipment tracking URL", "example": "https://www.fedex.com/fedextrack/?tracknumbers=0000000000" }, "created": { "type": "integer", "description": "Shipping time", "example": 1588716060 }, "ship_date": { "type": "string", "description": "Ship date", "example": "2020-05-05" }, "shipped_at": { "type": "string", "description": "Ship time in unix timestamp", "example": 1588716060 }, "reshipment": { "type": "boolean", "description": "Whether this is a reshipment", "example": false }, "items": { "type": "array", "description": "Array of items in this shipment", "items": { "$ref": "#/components/schemas/OrderShipmentItem" } } } }, "Gift": { "type": "object", "title": "OrderGift", "description": "Optional gift message for the packing slip", "properties": { "subject": { "type": "string", "maxLength": 200, "description": "Gift message title", "example": "To John" }, "message": { "type": "string", "maxLength": 200, "description": "Gift message text", "example": "Have a nice day" } } }, "PackingSlip": { "type": "object", "title": "OrderPackingSlip", "description": "Custom packing slip for this order. Example of a packing slip with explained fields can be found [here](#packing-slip).", "anyOf": [ { "required": [ "email" ] }, { "required": [ "phone" ] }, { "required": [ "message" ] }, { "required": [ "custom_order_id" ] } ], "properties": { "email": { "type": "string", "description": "Customer service email", "example": "your-name@your-domain.com" }, "phone": { "type": "string", "description": "Customer service phone", "example": "+371 28888888" }, "message": { "type": "string", "description": "Custom packing slip message", "example": "Message on packing slip" }, "logo_url": { "type": "string", "description": "URL address to a sticker we will put on a package. The provided image is converted to grayscale/1-bit monochrome image.", "example": "​http://www.your-domain.com/packing-logo.png" }, "store_name": { "type": "string", "description": "Store name override for the return address", "example": "Your store name" }, "custom_order_id": { "type": "string", "description": "Your own Order ID that will be printed instead of Printful's Order ID", "example": "kkk2344lm" } } }, "Order": { "type": "object", "title": "Order", "description": "Information about the Order", "required": [ "recipient", "items" ], "properties": { "id": { "description": "Order ID", "type": "integer", "example": 13, "readOnly": true }, "external_id": { "description": "Order ID from the external system", "type": "string", "nullable": true, "example": "4235234213" }, "store": { "description": "Store ID", "type": "integer", "example": 10, "readOnly": true }, "status": { "description": " Order status:
**draft** - order is not submitted for fulfillment
**failed** - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
**inreview** - order is being reviewed
**pending** - order has been submitted for fulfillment
**canceled** - order is canceled
**onhold** - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service **inprocess** - order is being fulfilled and is no longer cancellable
**partial** - order is partially fulfilled (some items are shipped already, the rest will follow)
**fulfilled** - all items are shipped
", "type": "string", "example": "draft", "readOnly": true }, "shipping": { "description": "Shipping method. Defaults to 'STANDARD'", "type": "string", "example": "STANDARD" }, "shipping_service_name": { "description": "Human readable shipping method name.", "type": "string", "example": "Flat Rate (3-4 business days after fulfillment)", "readOnly": true }, "created": { "description": "Time when the order was created", "type": "integer", "example": 1602607640, "readOnly": true }, "updated": { "description": "Time when the order was updated", "type": "integer", "example": 1602607640, "readOnly": true }, "recipient": { "$ref": "#/components/schemas/Address" }, "items": { "type": "array", "description": "Array of items in the order", "items": { "$ref": "#/components/schemas/Item" } }, "branding_items": { "type": "array", "description": "Array of branding items in the order", "readOnly": true, "items": { "$ref": "#/components/schemas/Item" } }, "incomplete_items": { "type": "array", "description": "Array of incomplete items in the order", "readOnly": true, "items": { "$ref": "#/components/schemas/IncompleteItem" } }, "costs": { "allOf": [ { "$ref": "#/components/schemas/Costs" }, { "readOnly": true } ] }, "retail_costs": { "$ref": "#/components/schemas/RetailCosts" }, "pricing_breakdown": { "type": "array", "description": "Difference between order price and retail costs. Will be shown only if order is completed.", "readOnly": true, "items": { "$ref": "#/components/schemas/PricingBreakdown" } }, "shipments": { "type": "array", "description": "Array of shipments already shipped for this order", "readOnly": true, "items": { "$ref": "#/components/schemas/Shipment" } }, "gift": { "$ref": "#/components/schemas/Gift" }, "packing_slip": { "$ref": "#/components/schemas/PackingSlip" } } }, "OrderEstimateCosts": { "type": "object", "title": "OrderEstimateCosts", "description": "Order costs (Printful prices)", "properties": { "currency": { "type": "string", "description": "3 letter currency code", "example": "USD" }, "subtotal": { "type": "number", "description": "Total cost of all items", "example": 10 }, "discount": { "type": "number", "description": "Discount sum", "example": 0 }, "shipping": { "type": "number", "description": "Shipping costs", "example": 5 }, "digitization": { "type": "string", "description": "Digitization costs", "example": 0 }, "additional_fee": { "type": "number", "description": "Additional fee for custom product", "example": 0 }, "fulfillment_fee": { "type": "number", "description": "Custom product fulfillment fee", "example": 0 }, "tax": { "type": "number", "description": "Sum of taxes (not included in the item price)", "example": 0 }, "vat": { "type": "number", "description": "Sum of vat (not included in the item price)", "example": 0 }, "total": { "type": "number", "description": "Grand Total (subtotal-discount+tax+vat+shipping)", "example": 15 } } }, "OrderEstimateRetailCosts": { "type": "object", "title": "OrderEstimateRetailCosts", "description": "Retail costs that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the `retail_price` attribute.", "properties": { "currency": { "type": "string", "description": "3 letter currency code", "example": "USD" }, "subtotal": { "type": "number", "nullable": true, "description": "Total cost of all items", "example": 10 }, "discount": { "type": "number", "nullable": true, "description": "Discount sum", "example": 0 }, "shipping": { "type": "number", "nullable": true, "description": "Shipping costs", "example": 5 }, "tax": { "type": "number", "nullable": true, "description": "Sum of taxes (not included in the item price)", "example": 0 }, "vat": { "type": "number", "nullable": true, "readOnly": true, "description": "Sum of VAT (not included in the item price)", "example": 0 }, "total": { "type": "number", "nullable": true, "readOnly": true, "description": "Grand Total (subtotal-discount+tax+vat+shipping)", "example": 15 } } }, "ShippingRatesAddress": { "type": "object", "title": "ShippingRatesAddress", "description": "Recipient address information for shipping rate calculation.\n\n**Required fields:**\n- `country_code`: Always required\n\n**Conditionally required fields:**\n- `state_code`: Required for United States (US), Australia (AU), and Canada (CA)\n\n**Optional fields:**\n- All other fields are optional but providing more information may produce more precise results and more shipping options.\n", "required": [ "country_code" ], "properties": { "address1": { "description": "Address line 1", "type": "string", "example": "19749 Dearborn St" }, "address2": { "description": "Address line 2", "type": "string", "nullable": true, "example": "Apt 2B" }, "city": { "description": "City", "type": "string", "example": "Chatsworth" }, "state_code": { "description": "State/province code. Required for United States (US), Australia (AU), and Canada (CA).\nFor other countries, this field is optional.\n", "type": "string", "example": "CA", "nullable": true }, "country_code": { "description": "Two-letter country code (ISO 3166-1 alpha-2)", "type": "string", "example": "US" }, "zip": { "description": "ZIP or postal code", "type": "string", "example": "91311", "nullable": true }, "phone": { "description": "Phone number", "type": "string", "example": "+1234567890", "nullable": true } } }, "ItemInfo": { "type": "object", "title": "ItemInfo", "description": "Order item information", "required": [ "quantity" ], "properties": { "variant_id": { "type": "string", "description": "Catalog Variant ID of the item ordered. See [Catalog API](#tag/Catalog-API) *Required if no other IDs given", "example": "202" }, "external_variant_id": { "type": "string", "description": "External Variant ID of the item ordered. See [Ecommerce Platform Sync API](#tag/Ecommerce-Platform-Sync-API). *Required if no other IDs given", "example": "1001" }, "warehouse_product_variant_id": { "type": "string", "description": "Warehouse product variant ID of the item ordered. See [Warehouse Products API](#tag/Warehouse-Products-API). *Required if no other IDs given", "example": "2" }, "quantity": { "type": "integer", "description": "Number of items ordered", "example": 10 }, "value": { "type": "string", "description": "Item retail value - optional but can help to properly calculate", "example": "2.99" } } }, "ShippingInfo": { "type": "object", "title": "ShippingInfo", "description": "Shipping information", "properties": { "id": { "type": "string", "description": "Shipping method ID", "example": "STANDARD" }, "name": { "type": "string", "description": "Shipping method name", "example": "Flat Rate (Estimated delivery: May 19–24) " }, "rate": { "type": "string", "description": "Shipping rate", "example": "13.60" }, "currency": { "type": "string", "description": "Currency code in which the rate is returned", "example": "EUR" }, "minDeliveryDays": { "type": "integer", "description": "Estimated minimum delivery days. Warning! This value may not be present in response.", "example": 4 }, "maxDeliveryDays": { "type": "integer", "description": "Estimated maximum delivery days. Warning! This value may not be present in response.", "example": 7 }, "minDeliveryDate": { "type": "integer", "description": "Estimated minimum delivery date. Warning! This value may not be present in response.", "example": "2022-10-17" }, "maxDeliveryDate": { "type": "integer", "description": "Estimated maximum delivery date. Warning! This value may not be present in response.", "example": "2022-10-20" } } }, "State": { "type": "object", "title": "State", "properties": { "code": { "type": "string", "description": "State code", "example": "ACT" }, "name": { "type": "string", "description": "State name", "example": "Australian Capital Territory" } } }, "Country": { "type": "object", "title": "Country", "properties": { "code": { "type": "string", "description": "Country code", "example": "Australia" }, "name": { "type": "string", "description": "Country name", "example": "AU" }, "states": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/State" } }, "region": { "type": "string", "example": "oceania" } } }, "TaxAddressInfo": { "type": "object", "title": "TaxAddressInfo", "description": "Recipient address information", "required": [ "country_code", "state_code", "city", "zip" ], "properties": { "country_code": { "type": "string", "description": "Country code", "example": "US" }, "state_code": { "type": "string", "description": "State code", "example": "CA" }, "city": { "type": "string", "description": "City", "example": "Chatsworth" }, "zip": { "type": "string", "description": "ZIP or postal code", "example": "91311" } } }, "TaxInfo": { "type": "object", "title": "TaxInfo", "description": "Tax address information", "properties": { "required": { "type": "boolean", "example": true, "description": "Whether sales tax is required for the given address" }, "rate": { "type": "number", "example": 0.095, "description": "Tax rate" }, "shipping_taxable": { "description": "Whether shipping is taxable", "type": "boolean", "example": false } } }, "Store": { "type": "object", "description": "Information about the Store", "properties": { "id": { "description": "Store ID", "type": "integer", "example": 10 }, "type": { "description": "Store type", "type": "string", "example": "native" }, "name": { "description": "Store name", "type": "string", "example": "My Store" } } }, "StoreSummary": { "allOf": [ { "$ref": "#/components/schemas/Store" }, { "type": "object" } ] }, "StoreDetails": { "allOf": [ { "$ref": "#/components/schemas/Store" }, { "type": "object" } ] }, "GenerationTaskFile": { "type": "object", "title": "GenerationTaskFile", "description": "Placement and file mapping to be generated.", "properties": { "placement": { "type": "string", "description": "Placement identifier (front, back, etc.).", "example": "front" }, "image_url": { "type": "string", "description": "Public URL where your file is stored.", "example": "​http://your-site/path-to-front-printfile.jpg" }, "position": { "$ref": "#/components/schemas/GenerationTaskFilePosition" }, "options": { "type": "array", "description": "Array of additional options for this file [See examples](#tag/Common/Options)", "items": { "$ref": "#/components/schemas/FileOption" } } } }, "GenerationTaskExtraMockup": { "type": "object", "title": "GenerationTaskExtraMockup", "description": "Generation task extra mockup", "properties": { "title": { "type": "string", "description": "Display name of the extra mockup." }, "url": { "type": "string", "description": "Temporary URL of the mockup.", "example": "​https://url-to/extra-mockup.png" }, "option": { "type": "string", "description": "Style option name" }, "option_group": { "type": "string", "description": "Style option group name" } } }, "GenerationTaskMockup": { "type": "object", "title": "GenerationTaskMockup", "description": "Generation task mockup.", "properties": { "placement": { "type": "string", "description": "Placement identifier.", "example": "front" }, "display_name": { "type": "string", "description": "This is a name that can be displayed to end customers.", "example": "Front Print" }, "variant_ids": { "type": "array", "description": "List of variant ids this mockup is used for. One mockup can be used for multiple variants.", "items": { "type": "integer" }, "example": [ 4011, 4012, 4013 ] }, "extra": { "type": "array", "description": "Optional extra mockups.", "items": { "$ref": "#/components/schemas/GenerationTaskExtraMockup" } } } }, "GenerationTaskTemplateFile": { "type": "object", "title": "GenerationTaskTemplateFile", "description": "Generated File placements and URLs.", "properties": { "variant_ids": { "type": "array", "description": "List of variant IDs associated with printfiles.", "items": { "type": "integer" }, "example": [ 4012, 4013, 4014, 4017, 4018, 4019 ] }, "placement": { "type": "string", "description": "Placement identifier (front, back, etc.).", "example": "front" }, "url": { "type": "string", "description": "Public URL where your file is stored.", "example": "​https://url-to/printfile.png" } } }, "GenerationTask": { "type": "object", "title": "GenerationTask", "description": "GenerationTask", "properties": { "task_key": { "type": "string", "description": "Task identifier you will use to retrieve generated mockups.", "example": "123456" }, "status": { "type": "string", "description": "Status of the generation task.", "enum": [ "pending", "completed", "failed" ], "example": "completed" }, "error": { "type": "string", "description": "If task has failed, reason will be provided here." }, "mockups": { "type": "array", "description": "If task is completed, list of mockups will be provided here.", "items": { "$ref": "#/components/schemas/GenerationTaskMockup" } }, "printfiles": { "type": "array", "description": "If task is completed, list of printfiles will be provided here.", "items": { "$ref": "#/components/schemas/GenerationTaskTemplateFile" } } } }, "Printfile": { "type": "object", "title": "Printfile", "description": "Printfile", "properties": { "printfile_id": { "type": "integer", "description": "Unique printfile identifier.", "example": 1 }, "width": { "type": "integer", "description": "Width in pixels.", "example": 1800 }, "height": { "type": "integer", "description": "Height in pixels.", "example": 2400 }, "dpi": { "type": "integer", "description": "Resulting DPI for given width and height.", "example": 150 }, "fill_mode": { "type": "string", "description": "Indicates if printfile will be used in cover or fit mode. Cover mode can produce cropping if side ratio does not match printfile.", "enum": [ "cover", "fit" ], "example": "fit" }, "can_rotate": { "type": "boolean", "description": "Indicates if printfile can be rotated horizontally (e.g. for posters).", "example": false } } }, "VariantPrintfile": { "type": "object", "title": "VariantPrintfile", "properties": { "variant_id": { "type": "integer", "example": 4012 }, "placements": { "type": "object", "description": "A key-value object mapping placement identifiers to printfile IDs.", "example": { "front": 1, "back": 1, "label_outside": 1 } } } }, "PrintfileInfo": { "type": "object", "title": "PrintfileInfo", "description": "Printfile info", "properties": { "product_id": { "type": "integer", "description": "Requested product id.", "example": 71 }, "available_placements": { "type": "object", "description": "List of available placements. Key is placement identifier, value is display name. (e.g. {embroidery_front: Front, ..}).", "example": { "front": "Front print", "back": "Back print", "label_outside": "Outside label" } }, "printfiles": { "type": "array", "items": { "$ref": "#/components/schemas/Printfile" } }, "variant_printfiles": { "type": "array", "items": { "$ref": "#/components/schemas/VariantPrintfile" } }, "option_groups": { "type": "array", "items": { "type": "string" } }, "options": { "type": "array", "items": { "type": "string" } } } }, "TemplateVariantMappingItem": { "type": "object", "title": "TemplateVariantMappingItem", "description": "Template variant mapping item", "properties": { "placement": { "type": "string", "description": "Placement ID.", "example": "front" }, "template_id": { "type": "integer", "description": "Corresponding template id which should be used for this variant and placement combination.", "example": 1 } } }, "TemplateVariantMapping": { "type": "object", "title": "TemplateVariantMapping", "description": "Template variant mapping", "properties": { "variant_id": { "type": "integer", "description": "Product variant ID.", "example": 1 }, "templates": { "type": "array", "description": "Array of Template Variant Mapping items", "items": { "$ref": "#/components/schemas/TemplateVariantMappingItem" } } } }, "Template": { "type": "object", "title": "Template", "description": "Template variant mapping", "properties": { "template_id": { "type": "integer", "description": "Template ID.", "example": 919 }, "image_url": { "type": "string", "description": "Main template image URL.", "example": "https://www.printful.com/files/generator/40/11oz_template.png" }, "background_url": { "type": "string", "description": "Background image URL (optional).", "nullable": true, "example": null }, "background_color": { "type": "integer", "description": "HEX color code that should be used as a background color.", "nullable": true, "example": null }, "printfile_id": { "type": "integer", "description": "Printfile ID that should be generated for this template. See [printfile API endpoint](#operation/getPrintfiles) for list of Printfiles.", "example": 43 }, "template_width": { "type": "integer", "description": "Width of the whole template in pixels.", "example": 560 }, "template_height": { "type": "integer", "description": "Height of the whole template in pixels.", "example": 295 }, "print_area_width": { "type": "integer", "description": "Print area width (image is positioned in this area).", "example": 520 }, "print_area_height": { "type": "integer", "description": "Print area height (image is positioned in this area).", "example": 202 }, "print_area_top": { "type": "integer", "description": "Print area top offset (offset in template).", "example": 18 }, "print_area_left": { "type": "integer", "description": "Print area left offset (offset in template).", "example": 20 }, "is_template_on_front": { "type": "boolean", "description": "Should the main template image (image_url) be used as an overlay or as a background.", "example": true }, "orientation": { "type": "string", "description": "Wall art product orientation. Possible values: horizontal, vertical, any", "enum": [ "horizontal", "vertical", "any" ], "example": "any" } } }, "TemplatePlacementConflict": { "type": "object", "title": "TemplatePlacementConflict", "description": "Template placement conflict", "properties": { "placement": { "type": "string", "description": "Placement ID", "example": "label_outside" }, "conflicts": { "type": "array", "description": "List Placement IDs that are conflicting with given placement", "items": { "type": "string" }, "example": [ "back", "label_inside" ] } } }, "ProductTemplate": { "type": "object", "title": "ProductTemplate", "description": "Product Template", "properties": { "version": { "type": "integer", "description": "Resource version. If this changes, resources (positions, images, etc.) should be re-cached.", "example": 1 }, "min_dpi": { "type": "integer", "description": "Recommended minimum DPI for given product.", "example": 300 }, "variant_mapping": { "type": "array", "description": "List of product variants mapped to templates. From this information you can determine which template should be used for a variant.", "items": { "$ref": "#/components/schemas/TemplateVariantMapping" } }, "templates": { "type": "array", "description": "List of templates. Use variant_mapping to determine which template corresponds to which product variant.", "items": { "$ref": "#/components/schemas/Template" } }, "conflicting_placements": { "type": "array", "description": "List of conflicting placements. Used to determine which placements can be used together.", "items": { "$ref": "#/components/schemas/TemplatePlacementConflict" } } } }, "WarehouseStockLocation": { "type": "object", "title": "WarehouseStockLocation", "properties": { "facility": { "description": "Name of the warehouse facility", "type": "string", "example": "Charlotte Steele Point, United States" }, "stocked": { "description": "Total quantity of product variant in our stock", "type": "integer", "example": 10 }, "available": { "description": "Available quantity of product variant in our stock", "type": "integer", "example": 10 } } }, "WarehouseProductVariant": { "type": "object", "title": "WarehouseProductVariant", "description": "Warehouse product variant data", "properties": { "id": { "type": "integer", "description": "Product variant ID", "example": 12 }, "name": { "type": "string", "description": "Name of product variant", "example": "SomeName" }, "sku": { "type": "string", "description": "SKU of product variant", "example": "some-sku-12" }, "image_url": { "type": "string", "description": "Image URL of product variant", "example": "url.to/image/variant.png" }, "retail_price": { "type": "number", "description": "Retail price of product variant", "format": "float", "example": 1.1 }, "quantity": { "type": "integer", "description": "Total available quantity of product variant in our stock", "example": 10 }, "length": { "type": "number", "description": "Length of product variant", "format": "float", "example": 3.21 }, "width": { "type": "number", "description": "Width of product variant", "format": "float", "example": 2.13 }, "height": { "type": "number", "description": "Height of product variant", "format": "float", "example": 3.11 }, "weight": { "type": "number", "description": "Weight of product variant", "format": "float", "example": 1.11 }, "stock_locations": { "description": "Product variant quantities in the warehouse stock", "type": "array", "items": { "$ref": "#/components/schemas/WarehouseStockLocation" } } } }, "WarehouseProduct": { "type": "object", "title": "WarehouseProduct", "description": "Warehouse product data", "properties": { "id": { "type": "integer", "description": "Product ID", "example": 12 }, "name": { "type": "string", "description": "Product name", "example": "Some product name" }, "status": { "type": "string", "description": "Product status:\n\n **created** - product request created,\n\n **active** - product request approved\n\n **suspended** - product suspended\n\n **declined** - product request declined\n\n **draft** - product created as a draft", "enum": [ "created", "active", "suspended", "declined", "draft" ], "example": "draft" }, "currency": { "type": "string", "description": "Currency", "example": "USD" }, "image_url": { "type": "string", "description": "Image URL of product", "example": "url.to/your/image/location.png" }, "retail_price": { "type": "number", "description": "Retail price of product", "example": 12.99 }, "variants": { "type": "array", "description": "Array of product variants", "items": { "$ref": "#/components/schemas/WarehouseProductVariant" } } } }, "ApprovalSheet": { "type": "object", "title": "ApprovalSheet", "description": "Approval sheet", "properties": { "id": { "type": "integer", "example": 2 }, "status": { "type": "string", "enum": [ "waiting_for_action", "approved" ], "example": "waiting_for_action" }, "confirm_hash": { "type": "string", "example": "a14e51714be01f98487fcf5131727d31" }, "submitted_design": { "type": "string", "example": "https://s3.staging.printful.com/upload/approval-design/ae/ae7b3d3e965c238b3e5c1a4e15696f07_l" }, "recommended_design": { "type": "string", "example": "https://s3.staging.printful.com/upload/approval-design/aa/aaf9e1c6b32cb7a2c04d2746108d4124_l" }, "approval_sheet": { "type": "string", "example": "https://www.printful.test/dashboard/order/download-approval-sheet-pdf?confirmationHash=13aa35854bfc67a85b7ce231aef2ae8" } } }, "WebhookInfo": { "title": "WebhookInfo", "properties": { "url": { "type": "string", "description": "Webhook URL that will receive store's event notifications", "example": "​https://www.example.com/printful/webhook" }, "types": { "type": "array", "description": "Array of enabled webhook event types", "items": { "type": "string" }, "example": [ "package_shipped", "stock_updated" ] }, "params": { "type": "object", "additionalProperties": true, "example": { "stock_updated": { "product_ids": [ 5, 12 ] } } } } }, "SalesAndCosts": { "type": "array", "title": "SalesAndCostsValue", "description": "Sales and costs report", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date of the value: day in `Y-m-d` format, month in `Y-m` format or \"Total\" for the first element of the list which shows the total values for the whole requested period" }, "sales": { "type": "number", "description": "Order retail price data. Available only if retail price fields are properly set up on the integration's side" }, "fulfillment": { "type": "number", "description": "Product fulfillment, digitization, branding, shipping costs and taxes that are charged by Printful" }, "profit": { "type": "number", "description": "The difference between Sales and Fulfillment. If retail price data is not available, profit might be negative" }, "sales_discount": { "type": "number", "description": "Any retail price discounts set up on the integration's side" }, "fulfillment_discount": { "type": "number", "description": "Any fulfillment discounts (such as the monthly discount) set up on Printful's side" }, "sales_shipping": { "type": "number", "description": "The retail shipping price that was paid by the buyer" }, "fulfillment_shipping": { "type": "number", "description": "Shipping costs that were charged by Printful" } } } }, "SalesAndCostsSummary": { "type": "array", "title": "SalesAndCostsSummaryValue", "description": "Sales and costs summary report", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date of the value: day in `Y-m-d` format, month in `Y-m` format or \"Total\" for the first element of the list which shows the total values for the whole requested period" }, "order_count": { "type": "number", "description": "The order count in the aggregation period" }, "costs": { "type": "number", "description": "Product fulfillment, digitization, branding, shipping costs and taxes that are charged by Printful" }, "profit": { "type": "number", "description": "The difference between Sales and Fulfillment. If retail price data is not available, profit might be negative" } } } }, "PrintfulCosts": { "type": "object", "title": "PrintfulCosts", "description": "Printful costs report", "properties": { "value": { "type": "number", "description": "Amount paid to Printful for fulfillment and shipping." }, "relative_difference": { "type": "number", "description": "Relative difference from the value from the previous period. -1 means 100% decrease, 1 means 100% increase. 0 is returned if there is no change or the previous value was 0." } } }, "Profit": { "type": "object", "title": "Profit", "description": "Profit report", "properties": { "value": { "type": "number", "description": "The difference between Sales and Fulfillment. If retail price data is not available, profit might be negative" }, "relative_difference": { "type": "number", "description": "Relative difference from the value from the previous period. -1 means 100% decrease, 1 means 100% increase. 0 is returned if there is no change or the previous value was 0." } } }, "TotalPaidOrders": { "type": "object", "title": "TotalPaidOrders", "description": "Total paid orders report", "properties": { "value": { "type": "number", "description": "Number of unique orders for period" }, "relative_difference": { "type": "number", "description": "Relative difference from the value from the previous period. -1 means 100% decrease, 1 means 100% increase. 0 is returned if there is no change or the previous value was 0." } } }, "CostsByAmount": { "type": "array", "title": "CostsByAmountValue", "description": "Costs by amount report", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date of the value: day in `Y-m-d` format, month in `Y-m` format or \"Total\" for the first element of the list which shows the total values for the whole requested period" }, "product_amount": { "type": "number", "description": "Product & fulfillment costs" }, "digitization": { "type": "number", "description": "Embroidery digitization costs" }, "branding": { "type": "number", "description": "Pack-in costs" }, "vat": { "type": "number", "description": "Tax amounts. If not applicable, it will be 0." }, "sales_tax": { "type": "number", "description": "Tax amounts. If not applicable, it will be 0." }, "shipping": { "type": "number", "description": "Shipping costs that were charged by Printful" }, "discount": { "type": "number", "description": "Any fulfillment discounts (such as the monthly discount) set up on Printful's side" }, "total": { "type": "number", "description": "Summary of all costs" } } } }, "CostsByProduct": { "type": "array", "title": "CostsByProductValue", "description": "Costs by product report", "items": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "Product ID. See [Catalog API](#tag/Catalog-API)." }, "product_name": { "type": "string", "description": "Product name." }, "fulfillment": { "type": "number", "description": "All fulfillment costs that are charged by Printful, excluding shipping." }, "sales": { "type": "number", "description": "Order retail price data. Available only if retail price fields are properly set up on the integration's side." }, "quantity": { "type": "integer", "description": "Total quantity of items ordered from this product in the selected period." } } } }, "CostsByVariant": { "type": "array", "title": "CostsByVariantValue", "description": "Costs by variant report", "items": { "type": "object", "properties": { "variant_id": { "type": "integer", "description": "Variant ID. See [Catalog API](#tag/Catalog-API)." }, "variant_name": { "type": "string", "description": "Variant name." }, "product_id": { "type": "integer", "description": "Product ID. See [Catalog API](#tag/Catalog-API)." }, "fulfillment": { "type": "number", "description": "All fulfillment costs that are charged by Printful, excluding shipping." }, "sales": { "type": "number", "description": "Order retail price data. Available only if retail price fields are properly set up on the integration's side." }, "quantity": { "type": "integer", "description": "Total quantity of items ordered from this product in the selected period." } } } }, "AverageFulfillmentTime": { "type": "object", "title": "AverageFulfillmentTime", "description": "Average fulfillment time report", "properties": { "value": { "type": "number", "description": "Average time it took Printful to fulfill your orders." }, "relative_difference": { "type": "number", "description": "Relative difference from the value from the previous period. -1 means 100% decrease, 1 means 100% increase. 0 is returned if there is no change or the previous value was 0." } } }, "StoreStatistics": { "type": "object", "title": "StoreStatistics", "description": "Statistics for a single store", "properties": { "store_id": { "type": "integer", "description": "The ID of the store for which the statistics are returned" }, "currency": { "type": "string", "description": "The code of the currency in which the statistics are returned", "example": "USD" }, "sales_and_costs": { "$ref": "#/components/schemas/SalesAndCosts" }, "sales_and_costs_summary": { "$ref": "#/components/schemas/SalesAndCostsSummary" }, "printful_costs": { "$ref": "#/components/schemas/PrintfulCosts" }, "profit": { "$ref": "#/components/schemas/Profit" }, "total_paid_orders": { "$ref": "#/components/schemas/TotalPaidOrders" }, "costs_by_amount": { "$ref": "#/components/schemas/CostsByAmount" }, "costs_by_product": { "$ref": "#/components/schemas/CostsByProduct" }, "costs_by_variant": { "$ref": "#/components/schemas/CostsByVariant" }, "average_fulfillment_time": { "$ref": "#/components/schemas/AverageFulfillmentTime" } } }, "Statistics": { "type": "object", "title": "Statistics", "description": "Statistics", "properties": { "store_statistics": { "type": "array", "description": "The statistics for each store (currently only a single store is supported).", "items": { "$ref": "#/components/schemas/StoreStatistics" } } } }, "Webhook": { "properties": { "type": { "type": "string", "description": "Event type" }, "created": { "type": "integer", "description": "Event time", "example": 1622456737 }, "retries": { "type": "integer", "description": "Number of previous attempts to deliver this webhook event", "example": 2 }, "store": { "type": "integer", "description": "ID of the store that the event occured to", "example": 12 } } }, "OrderEvent": { "type": "object", "title": "Order", "allOf": [ { "properties": { "id": { "readOnly": false }, "external_id": {}, "store": { "readOnly": false }, "status": { "readOnly": false }, "shipping": {}, "shipping_service_name": { "readOnly": false }, "created": { "readOnly": false }, "updated": { "readOnly": false }, "recipient": {}, "items": {}, "branding_items": { "readOnly": false }, "incomplete_items": { "readOnly": false }, "costs": { "readOnly": false }, "retail_costs": {}, "pricing_breakdown": { "readOnly": false }, "shipments": { "readOnly": false }, "gift": {}, "packing_slip": {} } }, { "$ref": "#/components/schemas/Order" } ] }, "SyncProductEvent": { "type": "object", "title": "SyncProduct", "description": "Information about the SyncProduct", "required": [ "name" ], "properties": { "id": { "description": "SyncProduct ID", "type": "integer", "example": 13 }, "external_id": { "description": "Product ID from the Ecommerce platform", "type": "string", "example": "4235234213" }, "name": { "description": "Product name", "type": "string", "example": "T-shirt" }, "variants": { "description": "Total number of Sync Variants belonging to this product", "type": "integer", "example": 10, "readOnly": true }, "synced": { "description": "Number of synced Sync Variants belonging to this product", "type": "integer", "example": 10, "readOnly": true }, "thumbnail": { "type": "string", "description": "Thumbnail image URL. Although we do not limit thumbnail image size, we recommend to keep it reasonably small.", "example": "​http://your-domain.com/path/to/thumbnail.png", "writeOnly": true }, "thumbnail_url": { "description": "Thumbnail image for the product", "type": "string", "example": "​https://your-domain.com/path/to/image.png", "readOnly": true }, "is_ignored": { "description": "Indicates if this Sync Product is ignored", "type": "boolean" } } }, "SyncProductDeleted": { "type": "object", "title": "SyncProductDeleted", "description": "Information about the SyncProductDeleted", "required": [ "id", "external_id", "name" ], "properties": { "id": { "description": "SyncProduct ID", "type": "integer", "example": 13 }, "external_id": { "description": "Product ID from the Ecommerce platform", "type": "string", "example": "42352342133" }, "name": { "description": "Product name", "type": "string", "example": "T-shirt" } } }, "ApprovalSheetWebhookFile": { "type": "object", "title": "ApprovalSheetWebhookFile", "properties": { "confirm_hash": { "type": "string", "example": "a14e51714be01f98487fcf5131727d31" }, "submitted_design": { "type": "string", "example": "https://s3.staging.printful.com/upload/approval-design/ae/ae7b3d3e965c238b3e5c1a4e15696f07_l" }, "recommended_design": { "type": "string", "example": "https://s3.staging.printful.com/upload/approval-design/aa/aaf9e1c6b32cb7a2c04d2746108d4124_l" }, "approval_sheet": { "type": "string", "example": "https://www.printful.test/dashboard/order/download-approval-sheet-pdf?confirmationHash=13aa35854bfc67a85b7ce231aef2ae8" } } } }, "responses": { "GetProducts": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } ] } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `401`", "example": 401 }, "result": { "type": "string", "description": "Actual error message", "example": "Malformed Authorization header." }, "error": { "type": "object", "properties": { "reason": { "type": "string", "example": "BadRequest" }, "message": { "type": "string", "example": "Malformed Authorization header." } } } } } } } }, "GetVariantById": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "object", "title": "VariantInfo", "properties": { "variant": { "$ref": "#/components/schemas/Variant" }, "product": { "$ref": "#/components/schemas/Product" } } } } } ] } } } }, "GetProductById": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/ProductInfo" } } } ] } } } }, "GetProductSizeGuideById": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/ProductSizeGuide" } } } ] } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `404`", "example": 404 }, "result": { "type": "string", "description": "Actual error message", "example": "Not found" }, "error": { "type": "object", "properties": { "reason": { "type": "string", "example": "NotFound" }, "message": { "type": "string", "example": "Not found" } } } } } } } }, "GetCategories": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } ] } } } }, "GetCategoryById": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/Category" } } } ] } } } }, "SyncProducts": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200Paginated" }, { "properties": { "result": { "type": "array", "description": "Array of SyncProduct", "items": { "$ref": "#/components/schemas/SyncProduct" } } } } ] } } } }, "SyncProduct": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/SyncProduct" } } } ] } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `400`", "example": 400 }, "result": { "type": "string", "description": "Actual error message", "example": "Missing required parameters" }, "error": { "type": "object", "properties": { "reason": { "type": "string", "example": "BadRequest" }, "message": { "type": "string", "example": "Missing required parameters" } } } } } } } }, "SyncProductInfo": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "title": "SyncProductInfo", "properties": { "sync_product": { "$ref": "#/components/schemas/SyncProduct" }, "sync_variants": { "type": "array", "description": "Array of Sync Variants available for the selected product", "items": { "$ref": "#/components/schemas/SyncVariant" } } } } } } ] } } } }, "SyncVariant": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 }, "result": { "$ref": "#/components/schemas/SyncVariant" } } } } } }, "SyncVariantDeleted": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 }, "result": { "type": "array", "maxItems": 0, "minItems": 0 } } } } } }, "ProductTemplates": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/Templates" }, "paging": { "$ref": "#/components/schemas/Paging" } } } ] } } } }, "TemplateById": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/TemplateById" } } } ] } } } }, "DeleteTemplate": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the deletion was successful" } } } } } ] } } } }, "Orders": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200Paginated" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } } ] } } } }, "Order": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/Order" } } } ] } } } }, "EstimateOrderCosts": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "properties": { "costs": { "$ref": "#/components/schemas/OrderEstimateCosts" }, "retail_costs": { "$ref": "#/components/schemas/OrderEstimateRetailCosts" } } } } } ] } } } }, "AddFile": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/File" } } } ] } } } }, "GetFile": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/File" } } } ] } } } }, "ThreadColors": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "thread_colors": { "type": "array", "items": { "type": "string", "example": "#FFFFFF", "description": "Suggested available thread colors" } } } } ] } } } }, "SyncVariantInfo": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "title": "SyncVariantInfo", "properties": { "sync_variant": { "$ref": "#/components/schemas/SyncVariant" }, "sync_product": { "$ref": "#/components/schemas/SyncProduct" } } } } } ] } } } }, "ShippingRates": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingInfo" } } } } } } }, "GetCountries": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } ] } } } }, "TaxCountries": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 }, "result": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Country" }, { "type": "object", "properties": { "states": { "type": "array", "items": { "type": "object", "properties": { "shipping_taxable": { "description": "Whether shipping is taxable in this state", "type": "boolean", "example": true } } } } } } ] } } } } } } }, "TaxRates": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 }, "result": { "$ref": "#/components/schemas/TaxInfo" } } } } } }, "PackingSlip": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 }, "result": { "type": "object", "properties": { "packing_slip": { "$ref": "#/components/schemas/PackingSlip" } } } } } } } }, "Stores": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200Paginated" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/StoreSummary" } } } } ] } } } }, "Forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `403`", "example": 403 }, "result": { "type": "string", "description": "Actual error message", "example": "This endpoint requires Oauth authentication!." }, "error": { "type": "object", "properties": { "reason": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "This endpoint requires Oauth authentication!." } } } } } } } }, "Store": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/StoreDetails" } } } ] } } } }, "GenerationTask": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/GenerationTask" } } } ] } } } }, "Printfiles": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/PrintfileInfo" } } } ] } } } }, "Templates": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ProductTemplate" } } } ] } } } }, "WarehouseProducts": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "result": { "type": "array", "description": "Array of WarehouseProducts", "items": { "$ref": "#/components/schemas/WarehouseProduct" } }, "paging": { "$ref": "#/components/schemas/Paging" } } } ] } } } }, "WarehouseProduct": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WarehouseProduct" } } } ] } } } }, "ApprovalSheetsResponse": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalSheet" } } } } ] } } } }, "ApprovalSheetsPostResponse": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "object", "properties": { "message": { "type": "string", "example": "Design approval submitted successfully" } } } } } ] } } } }, "ApprovalSheetResponse": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/ApprovalSheet" } } } ] } } } }, "WebhookInfo": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/WebhookInfo" } } } ] } } } }, "Scopes": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "example": "orders/read" }, "display_name": { "type": "string", "example": "View all orders" } } } } } } } } ] } } } }, "Statistics": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 }, "result": { "$ref": "#/components/schemas/Statistics" } } } } } } }, "requestBodies": { "SyncProductCreate": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Product", "description": "Information about the Sync Product", "required": [ "sync_product", "sync_variants" ], "properties": { "sync_product": { "$ref": "#/components/schemas/SyncProduct" }, "sync_variants": { "type": "array", "description": "Information about the Sync Variants", "items": { "allOf": [ { "required": [ "files", "variant_id" ] }, { "$ref": "#/components/schemas/SyncVariant" } ] } } } } } } }, "SyncProductUpdate": { "description": "PUT request body", "required": true, "content": { "application/json": { "schema": { "properties": { "sync_product": { "$ref": "#/components/schemas/SyncProduct" }, "sync_variants": { "type": "array", "description": "Information about the Sync Variants", "items": { "allOf": [ { "type": "object" }, { "anyOf": [ { "required": [ "files", "variant_id" ] }, { "required": [ "id" ] } ], "properties": { "id": { "type": "integer", "description": "Sync Variant ID. Please specify the IDs of all Sync Variants you wish to keep.", "example": 10, "readOnly": false } } }, { "$ref": "#/components/schemas/SyncVariant" } ] } } } } } } }, "SyncVariantUpdate": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "id": { "type": "integer", "description": "Sync Variant ID. Please specify the IDs of all Sync Variants you wish to keep.", "example": 10, "readOnly": false } } }, { "$ref": "#/components/schemas/SyncVariant" } ] } } } }, "SyncVariantCreate": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "required": [ "files", "variant_id" ] }, { "$ref": "#/components/schemas/SyncVariant" } ] } } } }, "OrderInput": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "AddFile": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "ThreadColors": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_url": { "type": "string", "description": "URL to file", "example": "https://example.com/image.jpg" } } } } } }, "EcommerceSyncVariantUpdate": { "description": "PUT request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_id": { "type": "integer", "description": "Printful Variant ID that this Sync Variant is synced to", "example": 3001 }, "retail_price": { "type": "string", "description": "Retail price that this item is sold for", "example": "29.99" }, "sku": { "type": "string", "description": "SKU of this Sync Variant", "example": "SKU1234", "nullable": true }, "is_ignored": { "type": "boolean", "description": "If is set to true, indicates the Sync Variant has been marked as ignored by Printful for order imports. This also means that Printful will not handle the stock for Shopify stores that have marked this Sync Variant as ignored.", "example": false }, "files": { "type": "array", "description": "Array of attached printfiles/preview images", "items": { "$ref": "#/components/schemas/File" } }, "options": { "type": "array", "description": "Array of additional options for the configured product/variant [See examples](#tag/Common/Options)", "items": { "$ref": "#/components/schemas/ItemOption" } }, "warehouse_product_variant_id": { "type": "integer", "description": "Warehousing variant ID. If the sync variant is connected with a warehousing item, this is its ID.", "example": 3002, "readOnly": true, "nullable": true } } } } } }, "CalculateShippingRates": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "CalculateShippingRates", "description": "Order information", "required": [ "recipient", "items" ], "properties": { "recipient": { "$ref": "#/components/schemas/ShippingRatesAddress" }, "items": { "type": "array", "description": "Array of order items", "items": { "$ref": "#/components/schemas/ItemInfo" } }, "currency": { "type": "string", "description": "3 letter currency code (optional), required if the rates need to be converted to another currency instead of store default currency", "example": "USD" }, "locale": { "type": "string", "description": "Locale in which shipping rate names will be returned. Available options: `en_US` (default), `es_ES`", "example": "en_US" } } } } } }, "CalculateTaxRates": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "TaxRequest", "description": "Tax address information", "required": [ "recipient" ], "properties": { "recipient": { "$ref": "#/components/schemas/TaxAddressInfo" } } } } } }, "ChangePackingSlip": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackingSlip" } } } }, "CreateGenerationTask": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "CreateGenerationTask", "description": "Mockup generation data.", "properties": { "variant_ids": { "type": "array", "description": "List of variant ids you want to generate.", "items": { "type": "integer" }, "example": [ 4012, 4013, 4014, 4017, 4018, 4019 ] }, "format": { "type": "string", "description": "Generated file format. PNG will have a transparent background, JPG will have a smaller file size.", "enum": [ "jpg", "png" ], "example": "jpg" }, "width": { "type": "integer", "description": "Width of the resulting mockup images (min 50, max 2000, default is 1000)" }, "product_options": { "description": "Key-value list of product options (embroidery thread, stitch colors). Product options can be found in Catalog API endpoint. [See examples](#tag/Common/Options)", "type": "object", "additionalProperties": true }, "option_groups": { "type": "array", "additionalProperties": true, "description": "List of option group names you want to generate. Product's option groups can be found in printfile API request.", "items": { "type": "string" } }, "options": { "type": "array", "description": "List of option names you want to generate. Product's options can be found in printfile API request.", "items": { "type": "string" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationTaskFile" } }, "product_template_id": { "type": "integer", "description": "Product template ID. Use instead of files parameter.", "example": 123 } } } } } }, "ConfirmApprovalSheet": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Approval Sheet", "description": "Change the status of the approval sheet", "required": [ "status" ], "properties": { "status": { "type": "string", "example": "approved", "enum": [ "approved" ] } } } } } }, "ApprovalSheetsChangeDesign": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Approval Sheet Changes", "description": "Changes to a design in an Approval sheet", "required": [ "message", "files" ], "properties": { "message": { "type": "string", "description": "A message to send to Printful designers. Customers should use this to describe the changes they want.", "example": "The design needs to be aligned to the left" }, "files": { "type": "array", "description": "An array of images to help describe the requested changes. Consider using the mockup generator to generate these images. The array is required but can be empty if you do not want to email any images.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "A url to an image, consider using the mockup generator to generate this image.", "example": "example.com" } } } } } } } } }, "CreateWebhook": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookInfo" }, { "required": [ "url", "types" ] } ] } } } }, "PackageShipped": { "description": "Package shipped.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `package_shipped`", "example": "package_shipped" }, "data": { "description": "Shipment and order data", "title": "ShipmentInfo", "properties": { "shipment": { "$ref": "#/components/schemas/Shipment" }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "PackageReturned": { "description": "Package returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `package_returned`", "example": "package_returned" }, "data": { "description": "Shipment and order data", "title": "ReturnInfo", "properties": { "reason": { "type": "string", "description": "Reason why the shipment was returned." }, "shipment": { "$ref": "#/components/schemas/Shipment" }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "OrderCreated": { "description": "Order created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_created`", "example": "order_created" }, "data": { "description": "Created order data", "title": "CreateInfo", "properties": { "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "OrderUpdated": { "description": "Order updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_updated`", "example": "order_updated" }, "data": { "description": "Updated order data", "title": "UpdateInfo", "properties": { "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "OrderFailed": { "description": "Order failed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_failed`", "example": "order_failed" }, "data": { "description": "Failure reason and order data", "title": "FailureInfo", "properties": { "reason": { "type": "string", "description": "Reason why the order has failed." }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "OrderCanceled": { "description": "Order canceled.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_canceled`", "example": "order_canceled" }, "data": { "description": "Cancel reason and order data", "title": "CancelInfo", "properties": { "reason": { "type": "string", "description": "Reason why the order has been canceled." }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "ProductSynced": { "description": "Product synced.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `product_synced`", "example": "product_synced" }, "data": { "title": "SyncInfo", "properties": { "sync_product": { "$ref": "#/components/schemas/SyncProductEvent" } } } } } ] } } } }, "ProductUpdated": { "description": "Product updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `product_updated`", "example": "product_updated" }, "data": { "title": "SyncInfo", "properties": { "sync_product": { "$ref": "#/components/schemas/SyncProductEvent" } } } } } ] } } } }, "ProductDeleted": { "description": "Product deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `product_deleted`", "example": "product_deleted" }, "data": { "title": "SyncInfo", "properties": { "sync_product": { "$ref": "#/components/schemas/SyncProductDeleted" } } } } } ] } } } }, "StockUpdated": { "description": "Stock updated.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `stock_updated`", "example": "stock_updated" }, "data": { "title": "ProductStock", "properties": { "product_id": { "type": "integer", "description": "Product ID", "example": 9001 }, "variant_stock": { "title": "VariantStock", "description": "Variant stock for this product", "properties": { "out": { "type": "array", "description": "Variant IDs that are out of stock", "items": { "type": "integer" } }, "discontinued": { "type": "array", "description": "Variant IDs that are discontinued", "items": { "type": "integer" } } } } } } } } ] } } } }, "OrderPutHold": { "description": "Order put on hold.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_put_hold`", "example": "order_put_hold" }, "data": { "title": "OrderStatusChange", "properties": { "reason": { "type": "string", "description": "Reason why the order status was changed." }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "OrderHoldApproval": { "description": "Order put on hold because it needs customer approval. You will receive an approval sheet with suggested changes and a confirmation hash so you can approve the changes if you agree with them.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_put_hold_approval`", "example": "order_put_hold_approval" }, "data": { "title": "OrderRequiresApproval", "properties": { "reason": { "type": "string", "description": "Reason why the order was put on hold and requires approval." }, "approval_files": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalSheetWebhookFile" } }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "OrderRemoveHold": { "description": "Order removed from on hold.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_remove_hold`", "example": "order_remove_hold" }, "data": { "title": "OrderStatusChange", "properties": { "reason": { "type": "string", "description": "Reason why the order status was changed." }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } }, "OrderRefunded": { "description": "Order refunded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_refunded`", "example": "order_refunded" }, "data": { "description": "Refunded amount and order data", "title": "RefundInfo", "properties": { "amount": { "type": "string", "example": "13.50", "description": "Refunded amount." }, "order": { "$ref": "#/components/schemas/OrderEvent" } } } } } ] } } } } } } }