{ "openapi": "3.0.0", "info": { "version": "2.0.0-beta", "title": "API Documentation v2 | Printful", "description": "# About the Printful API\n\n
\n

Welcome to API v2 BETA

\n \n
\n
\n\n* **How to use new endpoints?**\n Create or use an already created private token for authorization.\n Unless it's stated otherwise, the v2 version of Printful API may be used like the v1 version.\n All v2 endpoints use **/v2** prefix and the specifics of each endpoint are explained in a dedicated section.\n\n* **Test and provide feedback:** Explore the new features, experiment with the enhancements, and share your feedback through our dedicated [feedback form](https://forms.gle/Yq4t1poQQR8Mwoyt5).\n\n### What is new in the V2s\n\n- The flexibility of order creation with itemized order building [(read more)](#tag/Orders-v2).\n- Simplifying embroidery orders: auto thread color detection as default, simplified thread colors definition on the layer level.\n- New, powerful design creation with multiple design layers support and positioning for order\n items [(read more)](#tag/Orders-v2).\n- New, more secure Webhooks by enforcing HTTPS, added expiration date, and request signing.\n- More flexibility in webhook per event configuration.\n- New webhook events – a new event for catalog price change, and the stock update event is now real-time with a refresh rate every 5 minutes (previously every 24h).\n- More information in the Catalog about the products (images, discounted pricing, placement information).\n- More flexibility in the catalog (extensive filtering and sorting options, DSR support, pagination).\n- More information on the order shipment level – more precise EDT, departure country, and shipment tracking events.\n- Standardization of returned time in API – standardized format according to ISO 8601, UTC time zone.\n- Standardization of returned price formats in API. Prices are displayed as a string with up to 2 decimal points.\n- Uniform pagination parameters across all endpoints.\n- Performance improvements for all endpoints.\n\n## Postman Collection\n\nYou can explore the API using the Postman collection:\n\nDownload Postman Collection\n\n# Migration Guide\n\n## How to switch from V1 to V2 endpoints\n\n- **Update the Base URL:** Ensure your requests use the updated V2 base path. For V2, endpoints include the prefix /v2 (\n e.g., https://api.printful.com/v2/orders).\n- **Authentication:** Both V1 and V2 use private tokens for authorization. Confirm your token is still valid and configured\n for your store. No major changes are required here.\n- **Leverage New Features:** V2 introduces several enhancements, including:\n - Improved order creation flexibility, allowing itemized order building.\n - Simplified embroidery orders with features like auto thread color detection.\n - New webhooks for real-time updates on events like stock changes.\n - Standardized returned time (ISO 8601) and price formats.\n- **Handle Pagination and Rate Limiting:** V2 implements uniform pagination parameters and adopts a leaky bucket algorithm\n for rate limiting. The X-Ratelimit-* headers indicate usage and reset times. Adjust your application to handle these\n changes effectively.\n- **Test the Endpoints:** Create a separate store to test scenarios in production cautiously. Provide feedback on any\n anomalies using Printful’s feedback form linked in their documentation.\n- **Explore Documentation for Changes:** Thoroughly review the updated API reference to understand the specifics of V2\n endpoints, parameters, and expected responses. Adjust your code for endpoints where behavior or parameters have\n changed compared to V1.\n\n# Errors\n\nThe errors in the API are formatted following the [RFC 9457: Problem Details for HTTP APIs][1]. The content type of\nerror\nresponses is `application/problem+json` and the response is a JSON object with the members:\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
typestringA URL that identifies the type of error. The URL can be followed to get more information about the error in our documentation.
statusintegerThe status code of the response that returned the error.
titlestringA short human-readable summary of the problem.
detailstringA human-readable explanation of the problem.
instancestringA unique identifier of a specific instance of the error. You can send it when you \n contact our support team so that it's easier for us to find the \n logs for your specific request.\n

This member may not be present for all error types.

\n
\n\nSome error types may include some other additional information. For example, validation errors will contain the problem\nthat was detected and a pointer to the invalid data.\n\nAn example of a response would be:\n\n```\n{\n \"type\": \"https://developers.printful.com/docs/v2-beta/#errors/not-found\",\n \"status\" : 404,\n \"title\" : \"Not Found\",\n \"detail\" : \"The resource that you tried to access does not exist.\"\n}\n```\n\n
\n

We introduced this format after we started working on V2, so it's not yet supported by all endpoints. These are the\n operations that are not supporting this format yet:

\n
\n List of operations not supporting these error format\n \n
\n
\n\n[1]: https://www.rfc-editor.org/rfc/rfc9457.html\n\n## General Errors\n\n

Internal Server Error

\n\nThis error is returned when the server encounters an unexpected problem to complete the requested operation. Since this\nis usually an error on our end, resending the request will probably result in getting the error again.\n\nYou don't need to do any action to solve this since we are notified when this error happens. However, if you want, you\ncan contact us through our support channels. If you decide to contact us, providing the returned instance will help\nus to identify the problem.\n\n## Validation Errors\n\nThis error is returned when the server encounters an unexpected or incorrect value provided by the user.\nUsually the request can be corrected by providing the correct values specified in `valid_values` property on an error.\n\n## Retired Resources\n\n### Sync endpoints and Product templates endpoints\n\nProduct management, with sync products or product templates, is not available in version 2 of the API yet.\n\n## FAQ\n\n### How can I access the new API?\n\nTo access the new API (V2), update your endpoint URLs to include the /v2 prefix (\ne.g., https://api.printful.com/v2/orders). You’ll also\nneed a valid private token for authorization. The V2 API supports the same authentication method as V1, so you can\ncontinue using your\nexisting token unless it has expired. Ensure that your applications are updated to use the V2 endpoints, as these\ninclude several new\nfeatures and enhancements.\n\n### What happens if I don't migrate?\n\nWhile the V1 API will continue to function for now, it is essential to migrate to V2 to take advantage of new features\nand optimizations.\nV2 includes enhancements like real-time webhook updates, better performance, standardized formats, and improved\nfunctionalities. Staying on\nV1 means missing out on these improvements and could lead to challenges as support for V1 may be phased out in the\nfuture. It’s strongly\nrecommended to migrate to ensure compatibility and optimal performance.\n\n### How can I get help with my migration?\n\nFor migration assistance, you can:\n\n- Refer to the V2 API documentation, which provides detailed information about endpoints, parameters, and response\n formats.\n- Contact Printful Customer Support at [https://www.printful.com/contacts](https://www.printful.com/contacts) for\n specific questions or troubleshooting help.\n\n### Are there any changes to API Rate Limits?\n\nYes, there are changes to the rate-limiting mechanism in V2. Unlike the simple limit-reset system in V1, V2 implements a\nleaky bucket\nalgorithm:\n\n- The headers X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Reset, and X-Ratelimit-Policy provide detailed\n rate-limit information.\n- V2 allows smoother traffic bursts by gradually refilling the bucket over time, improving performance and reducing the\n impact of hitting the limit.\n- Default limits remain similar (120 requests per minute), but the reset mechanism is now more dynamic, reflecting the\n real-time refill process.\n- These changes aim to provide more predictable behavior and better utilization of API resources. Adjust your\n application to handle the revised rate-limiting system effectively.\n\n# Use Cases\n\n## Order Management\n\nThis section outlines practical use cases to help you estimate, create, update, and track orders effectively.\nWhether you're calculating shipment costs, determining potential custom fees, or leveraging webhooks for real-time\nupdates,\nthese use cases are designed to streamline your order workflows.\n\nKey topics include:\n\n- **Estimating Shipments:** Learn how to estimate shipment costs, types, and determine whether custom fees will apply.\n- **Order Estimation:** Understand how to calculate the costs and details of an order before placing it.\n- **Creating Orders from Catalog Source:** Discover how to create new orders using items directly from the catalog.\n- **Order Modifications:** Includes deleting individual order items and updating existing orders.\n- **Order Confirmation:** How to confirm yout orders and initiate fulfillment.\n- **Order Updates and Tracking:** Access tools for receiving updates via webhook events, retrieving detailed order\n information through the API,\n and tracking shipments with precise shipping details.\n\nThese use cases are tailored to provide actionable insights for efficiently managing your Printful orders, ensuring a\nsmooth integration\nexperience.\n\n### Estimating orders\n\nThe cost of the order can be estimated before even placing the order by using the order\n[estimation endpoint](#tag/Orders-v2/operation/createOrderEstimationTask). The estimation is an asynchronous process so\nthe response won’t\ncontain the estimation data right away, but instead the task ID will be returned.\n\n```\n{\n \"data\": {\n \"id\": \"fc959efb-b3a0-4c12-9cc6-f54d3158291d\",\n \"status\": \"pending\",\n \"costs\": null,\n \"retail_costs\": null,\n \"failure_reasons\": []\n }\n}\n```\n\nThe task ID `fc959efb-b3a0-4c12-9cc6-f54d3158291d` can be then used\nto [retrieve the result](#tag/Orders-v2/operation/getOrderEstimationTask)\nof the estimation with `https://api.printful.com/v2/order-estimation-tasks?id=fc959efb-b3a0-4c12-9cc6-f54d3158291d`.\n\nThe estimation task has 3 different statuses:\n\n- `pending`\n- `failed`\n- `completed`\n\nIf the estimation fails the task status will be set to the failed and the reason will be included in the\n`failure_reasons`\n\n### Estimating Shipments\n\nShipping rates can be estimated by using\nthe [Estimating orders endpoint](#tag/Orders-v2/operation/createOrderEstimationTask) as it also returns the shipping\ncost.\n\n```\n{\n \"data\": {\n \"id\": \"fc959efb-b3a0-4c12-9cc6-f54d3158291d\",\n \"status\": \"completed\",\n \"costs\": {\n ...\n \"shipping\": \"4.79\",\n ...\n }\n }\n}\n```\n\nThat shipping cost however is always calculated for the standard shipping method.\n\n#### How to estimate the shipment cost and type\n\nTo display the different shipping methods\nthe [shipping rates endpoint](#tag/Shipping-Rates-v2/operation/calculateShppingRates) needs to be used. Three main\nthings are required to correctly\ncalculate the shipping costs:\n\n- Recipient data\n- Product variant + quantity\n- Currency\n\nThe response will contain all the available shipment methods:\n\n```\n{\n \"data\": [\n {\n \"shipping\": \"STANDARD\",\n \"shipping_method_name\": \"Flat Rate (Estimated delivery: May 19–24) \",\n \"rate\": \"13.60\",\n \"currency\": \"EUR\",\n \"min_delivery_days\": 4,\n \"max_delivery_days\": 7,\n \"min_delivery_date\": \"2022-10-17\",\n \"max_delivery_date\": \"2022-10-20\",\n \"shipments\": [\n {\n \"departure_country\": \"US\",\n \"shipment_items\": [\n {\n \"catalog_variant_id\": 4011,\n \"quantity\": 3\n }\n ],\n \"customs_fees_possible\": true\n }\n ]\n }\n ]\n}\n```\n\n#### How to determine if the custom fees will be applied\n\nDepending on where the shipment is shipped from and where it will be shipped the additional taxes and duties might\napply.\nTo check if the custom fees might apply the `customs_fees_possible` parameter from the shipping rates endpoint can be\nused to determine that.\n\n```\n{\n \"data\": [\n {\n ...\n \"shipments\": [\n {\n ...\n \"customs_fees_possible\": true\n }\n ]\n }\n ]\n}\n```\n\n#### Creating order from catalog source\n\nTo [create the order](#tag/Orders-v2/operation/createOrder) the recipient address and the catalog product with the\ndesigns needs to be specified. Order will be created with the\ndraft status and the pending costs calculations.\n\nOrders with the draft status won’t be charged, and they won’t be picked up by our fulfillment facilities. In order to\nmark the order as\nready for fulfillment the order confirmation endpoint needs to be used.\n\nOrders can be also created without specifying any items at first. In that case just the recipient address can be\nprovided:\n\n```\n{\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}\n```\n\nThe [item creation endpoint](#tag/Orders-v2/operation/createItemByOrderId) can be then used in such order to add\ndifferent products that should be included in the order.\nThis functionality might be useful when implementing a user cart.\n\n#### Deleting an order item\n\nIndividual items can be removed from the order by using the\ndelete [order item endpoint](#tag/Orders-v2/operation/deleteItemById)\nbut only if the order is in either draft or failed state.\n\n#### Updating an order\n\nOrder can be updated only in the draft and failed\nstate. [An entire order can be updated](#tag/Orders-v2/operation/updateOrder)\nor [just a specific item](#tag/Orders-v2/operation/updateItem).\n\nThe updates in the V2 of the API use the PATCH method protocol. This means that only the values provided in the request\nwill be updated.\nFor example, sending a request with an empty body will not perform any changes to the order.\n\nExample of updating a recipient name:\n`PATCH https://api.printful.com/v2/orders/{order_id}`\n\n```\n{\n \"recipient\": {\n \"name\": \"John Smith\"\n }\n}\n```\n\nSome values can’t be updated separately, attempting to update an array's values requires sending a whole array. For\nexample updating just the item design placement is not possible and will result in an error.\n\n```\n{\n \"items\": [\n {\n \"placements\": [\n {\n \"placement\": \"front\"\n }\n ]\n }\n ]\n}\n```\n\nIn such case a whole valid design data needs to be provided:\n\n```\n{\n \"items\": [\n {\n \"quantity\": 1,\n \"catalog_variant_id\": 4011,\n \"source\": \"catalog\",\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"{{image_url}}\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n#### Order Confirmation\n\nIn V2 API the orders cannot be created immediately in a confirmed state. In order to confirm an order it first needs to\nbe\n[created in the draft state](#creating-order-from-catalog-source). Or if the order failed e.g. due to payment method\nmissing it can be confirmed again.\n\nIf the order cost calculations are still calculating or they have failed to calculate then the order won’t be possible\nto be confirmed.\n\nExample of order cost still calculating:\n\n```\n...\n\"costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": null,\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"digitization\": null,\n \"additional_fee\": null,\n \"fulfillment_fee\": null,\n \"retail_delivery_fee\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n...\n```\n\n#### Webhook events\n\nTo get the notifications about the order status, the [webhook events endpoint](#tag/Webhook-v2) can be used to subscribe\nto various webhook events e.g.:\n\n- Order created\n- Order updated\n- Order failed\n- Order cancelled\n- Order put on hold\n- Order put on hold approved\n- Order removed from hold\n- Order refunded\n\n#### Get endpoints\n\nThe order list can be retrieved using the retrieve a [list of orders endpoint](#tag/Orders-v2/operation/getOrders).\nThere is also an endpoint for [retrieving the single order](#tag/Orders-v2/operation/getOrder)\nand the endpoint to [retrieve a specific order item](#tag/Orders-v2/operation/getItemById).\n\n#### Shipping information\n\nAfter an order is made it is split into shipments, meaning that a single order can have multiple shipments. You can\nretrieve the status of these shipments\nusing the [shipments endpoint](#tag/Orders-v2/operation/getShipments).\n\nThe main use case of this endpoint is in providing tracking details about each shipment. Providing information about the\nstatus of the shipment and what\nevents have occurred so far.\n\n```\n{\n ...\n \"shipment_status\": \"canceled\",\n \"shipped_at\": \"2023-06-15T16:35:35Z\",\n \"delivery_status\": \"unknown\",\n \"delivered_at\": \"2023-06-15T16:35:35Z\",\n \"departure_address\": {\n \"country_name\": \"United States\",\n \"country_code\": \"US\",\n \"state_code\": \"CA\"\n },\n \"tracking_url\": \"​https://myorders.com/tracking/39925631\",\n \"tracking_events\": [\n {\n \"triggered_at\": \"2023-06-15T19:15:05Z\",\n \"description\": \"Arrived At Destination\"\n }\n ],\n...\n```\n\nAnother important usage of this endpoint is in providing delivery time estimates:\n\n```\n{\n ...\n \"estimated_delivery\": {\n \"from_date\": \"2023-06-15\",\n \"to_date\": \"2023-06-15\",\n \"calculated_at\": \"2023-06-15T16:35:35Z\"\n },\n ...\n}\n```\n\nGiven that not all orders can fit in a single shipment it may be necessary to indicate which shipment will contain which\nitem.\nThe shipments endpoint can be used to link ordered items back to physical items.\n\n```\n{\n ...\n \"shipment_items\": [\n {\n \"id\": 10,\n \"order_item_id\": 20,\n \"order_item_external_id\": \"item-external-id\",\n \"order_item_name\": \"Item name\",\n \"quantity\": 1,\n \"_links\": {\n \"order_item\": {\n \"href\": \"​https://api.printful.com/v2/orders/2/order-items/20\"\n }\n }\n }\n ],\n ...\n}\n```\n\n## Building a product catalog\n\n### Product options, placements and techniques\n\nIn order to create order items and other designs it's important to know the specification of the product. The\n[catalog products endpoints](#tag/Catalog-v2) offers a way to expose these options so that designs can be created\ndynamically from\nblank Printful products.\n\n#### Displaying the product\n\nA request to `https://api.printful.com/v2/catalog-products` will provide a paged list of products along with\ndescriptions and images\nof products to help users identify the product they would like.\n\n```\n[\n {\n \"id\": 294,\n \"type\": \"T-SHIRT\",\n \"main_category_id\": 7,\n \"name\": \"Unisex Pullover Hoodie | Bella + Canvas 3719\",\n \"brand\": \"Bella + Canvas\",\n \"model\": \"3719\",\n \"image\": \"https://s3-printful.stage.printful.dev/upload/product-catalog-img/35/352d4f3cc9fbac9ee9173467bc7f200e_l\",\n \"variant_count\": 20,\n \"is_discontinued\": false,\n \"description\": \"A soft and comfy unisex hoodie that fits all your hoodie needs. The fleece fabric makes it a great partner all year round, be it a summer evening on the beach, or a Christmas dinner in a mountain cabin.\\n\\n• 52% airlume combed ring-spun cotton, 48% poly fleece\\n• Heather colors are 60% airlume combed ring-spun cotton, 40% poly fleece\\n• Fabric weight: 6.5 oz/yd² (220.4 g/m²)\\n• Regular fit\\n• Side-seamed construction\\n• Blank product sourced from Honduras, Nicaragua or the US\"\n },\n {\n \"id\": 262,\n \"type\": \"CUT-SEW\",\n \"main_category_id\": 49,\n \"name\": \"All-Over Print Drawstring Bag\",\n \"brand\": null,\n \"model\": null,\n \"image\": \"https://s3-printful.stage.printful.dev/upload/product-catalog-img/0f/0f04d73474287ef01d6f5541c3a63de2_l\",\n \"variant_count\": 1,\n \"is_discontinued\": false,\n \"description\": \"Combine your love for vibrant prints and a sporty style with a cool drawstring bag. It's a must-have gym essential that can be worn as a backpack with drawstring closure at top, and narrow, contrasting shoulder straps. \\n\\n• 100% polyester\\n• One size: 15″ × 17″ (38.1 cm × 43.2 cm)\\n• Fabric weight (may vary by 5%): 6.64 oz/yd² (225 g/m²)\\\"\\n• Maximum weight limit: 33 lbs (15 kg)\\n• Twin cotton handles\\n• Drawstring closure\\n• Blank product components sourced from Israel\",\n }\n]\n```\n\n#### Selecting the product and creating a design\n\nOnce the product is selected additional information is needed in order to create a design with the blank product. The\nfollowing is a\nvalid item\n\n```\n{\n \"quantity\": 1,\n \"catalog_variant_id\": 4011,\n \"source\": \"catalog\",\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"{{image_url}}\"\n }\n ]\n }\n ]\n}\n```\n\nA lot of the information in the above request depend on information taken from the catalog.\n\n`https://api.printful.com/v2/catalog-products/294`\n\n```\n{\n \"id\": 294,\n \"techniques\": [\n {\n \"key\": \"dtg\",\n \"display_name\": \"DTG printing\",\n \"is_default\": true\n },\n {\n \"key\": \"embroidery\",\n \"display_name\": \"Embroidery\",\n \"is_default\": false\n }\n ],\n \"placements\": [\n {\n \"placement\": \"embroidery_chest_left\",\n \"technique\": \"embroidery\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"layer_options\": [\n {\n \"name\": \"thread_colors\",\n \"techniques\": [\n \"embroidery\"\n ],\n \"type\": \"array\",\n \"values\": {\n \"#FFFFFF\": \"1801 White\",\n \"#000000\": \"1800 Black\",\n \"#96A1A8\": \"1718 Grey\",\n \"#A67843\": \"1672 Old Gold\",\n \"#FFCC00\": \"1951 Gold\",\n \"#E25C27\": \"1987 Orange\",\n \"#CC3366\": \"1910 Flamingo\",\n \"#CC3333\": \"1839 Red\",\n \"#660000\": \"1784 Maroon\",\n \"#333366\": \"1966 Navy\",\n \"#005397\": \"1842 Royal\",\n \"#3399FF\": \"1695 Aqua/Teal\",\n \"#6B5294\": \"1832 Purple\",\n \"#01784E\": \"1751 Kelly Green\",\n \"#7BA35A\": \"1848 Kiwi Green\"\n }\n }\n ]\n }\n ],\n \"placement_options\": []\n },\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"layer_options\": []\n }\n ],\n \"placement_options\": []\n },\n ...\n ],\n ...\n}\n```\n\nThe example above gives us most of the information necessary to design the item, it provides the `techiques`,\n`placements` and `layers`\navailable for the product.\n\nMapped onto an item these values would look like this:\n\n```\n{\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"{{image_url}}\"\n }\n ]\n }\n ]\n}\n```\n\nIt also offers alternative options, for example the same product could use embroidery thread colors if embroidery\nplacements are selected.\n\n```\n{\n \"placements\": [\n {\n \"placement\": \"embroidery_chest_left\",\n \"technique\": \"embroidery\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"layer_options\": [\n {\n \"name\": \"thread_colors\",\n \"value\": [\n \"#FFFFFF\",\n \"#000000\"\n ]\n }\n ],\n \"url\": \"{{image_url}}\"\n }\n ]\n }\n ]\n}\n```\n\nWhat's missing from this is the `catalog_variant_id`, the variant can be found using\n`https://api.printful.com/v2/catalog-products/294/catalog-variants`.\nEach variant is different in color and size and the user can view an image of each to help select their variant.\n\n```\n[\n {\n \"id\": 9224,\n \"catalog_product_id\": 294,\n \"name\": \"Bella + Canvas 3719 Unisex Fleece Pullover Hoodie (White / XL)\",\n \"size\": \"XL\",\n \"color\": \"White\",\n \"color_code\": \"#ffffff\",\n \"color_code2\": null,\n \"image\": \"https://s3-printful.stage.printful.dev/products/294/9220_1526986863.jpg\",\n ...\n },\n ...\n]\n```\n\nWith the catalog variant selected the design can be finished, and creating an item is just a matter of selecting the\nquantity and\nsource of the design.\n\n```\n{\n \"quantity\": 1,\n \"catalog_variant_id\": 9224,\n \"source\": \"catalog\",\n \"placements\": [\n {\n \"placement\": \"embroidery_chest_left\",\n \"technique\": \"embroidery\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"layer_options\": [\n {\n \"name\": \"thread_colors\",\n \"value\": [\n \"#FFFFFF\",\n \"#000000\"\n ]\n }\n ],\n \"url\": \"{{image_url}}\"\n }\n ]\n }\n ]\n}\n```\n\n### Getting the pricing information\n\nThe catalog API can also be used to indicate to the end customer what the price of the product will be.\n\n`https://api.printful.com/v2/catalog-variants/9224/prices`\n\n```\n{\n \"data\": {\n \"currency\": \"EUR\",\n \"product\": {\n \"id\": 294,\n \"placements\": [\n {\n \"id\": \"embroidery_chest_left\",\n \"title\": \"Left chest\",\n \"type\": \"Embroidery\",\n \"technique_key\": \"embroidery\",\n \"placement_options\": [],\n \"price\": \"2.95\",\n \"discounted_price\": \"2.95\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"additional_price\": \"0.00\",\n \"layer_options\": []\n }\n ]\n },\n {\n \"id\": \"front\",\n \"title\": \"Front print\",\n \"type\": \"DTG printing\",\n \"technique_key\": \"dtg\",\n \"placement_options\": [],\n \"price\": \"5.75\",\n \"discounted_price\": \"5.75\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"additional_price\": \"0.00\",\n \"layer_options\": []\n }\n ]\n }\n ]\n },\n \"variant\": {\n \"id\": 9224,\n \"techniques\": [\n {\n \"technique_key\": \"dtg\",\n \"technique_display_name\": \"DTG printing\",\n \"price\": \"28.95\",\n \"discounted_price\": \"28.95\"\n },\n {\n \"technique_key\": \"embroidery\",\n \"technique_display_name\": \"Embroidery\",\n \"price\": \"30.75\",\n \"discounted_price\": \"30.75\"\n }\n ]\n },\n \"discount_tiers\": [\n {\n \"quantity\": 25,\n \"bulk_discount_percentage\": 0.08\n },\n ...\n ]\n },\n}\n```\n\nThe price of the product will depend upon the technique, the variant, the placement and the quantity of the product\nordered.\nFurthermore, the first placement will be discounted by the `discounted_price`.\n\nFor more information on pricing please follow this link: https://www.printful.com/pricing\n\n#### Price changed webhook\n\nIt may also be useful that a system can react to changes in product pricing, the\n[Catalog Price Changed](#tag/Webhook-v2/operation/catalogStockUpdated) (`catalog_price_changed`) webhook can\nbe used to handle this use case.\n\n### Getting the images for the products\n\nThe images provided in the catalog [products](#tag/Catalog-v2/operation/getProductById)\nand [variants](#tag/Catalog-v2/operation/getVariantById) are only very simple. For more complex use cases where\na larger variety of mockups of a single product may need to be displayed, the\ncatalog [product images](#tag/Catalog-v2/operation/getProductImagesById)\nand [variant images](#tag/Catalog-v2/operation/getVariantImagesById) endpoints can help. Note however, that these\nrequire additional work, Printful doesn't provide images for every color so most images on those endpoints are\ntransparent and require\nthe developer\nto [overlay them on top of the color defined on the resource](#tag/Catalog-v2/operation/getProductImagesById).\n\n### Getting the availability of products (stock information)\n\nStock of products changes daily at Printful so it's important to make sure to display this availability to the end\ncustomers.\n\nOne way to make sure end customers only see the products available in their region is to\n[filter by selling region](https://developers.printful.com/docs/v2-beta/#tag/Catalog-v2/operation/getProducts)\n`https://api.printful.com/v2/catalog-products?selling_region_name=brazil`.\n\nIf more detailed availability information is needed it can be taken from\nthe [variant](#tag/Catalog-v2/operation/getProductStockAvailabilityById)\nand [product](#tag/Catalog-v2/operation/getProductStockAvailabilityById) availability endpoints.\n\n`https://api.printful.com/v2/catalog-products/294/availability`\n\n```\n{\n \"data\": [\n {\n \"catalog_variant_id\": 9231,\n \"techniques\": [\n {\n \"technique\": \"dtg\",\n \"selling_regions\": [\n {\n \"name\": \"usa\",\n \"availability\": \"in stock\",\n \"placement_option_availability\": []\n }\n ]\n },\n {\n \"technique\": \"embroidery\",\n \"selling_regions\": [\n {\n \"name\": \"usa\",\n \"availability\": \"in stock\",\n \"placement_option_availability\": []\n }\n ]\n }\n ...\n ]\n```\n\nThis may be important in cases where the stock availability of specific techniques is important.\n\n#### Stock updated webhook\n\nIt may also be useful that a system can react to changes in product availability, the\n[catalog stock updated](#tag/Webhook-v2/operation/catalogStockUpdated) (`catalog_stock_updated`) webhook can\nbe used to handle this use case.~~\n\n## How to create mockups\n\n### Defining mockup styles\n\nWhen creating a [mockup a style](#tag/Catalog-v2/operation/retrieveMockupStylesByProductId) first needs to be selected\nfor the given product.\n\n`https://api.printful.com/v2/catalog-products/294/mockup-styles`\n\n```\n{\n \"data\": [\n {\n \"placement\": \"front\",\n \"display_name\": \"Front print\",\n \"technique\": \"dtg\",\n \"print_area_width\": 12.0,\n \"print_area_height\": 12.0,\n \"print_area_type\": \"simple\",\n \"dpi\": 150,\n \"mockup_styles\": [\n {\n \"id\": 16652,\n \"category_name\": \"Flat\",\n \"view_name\": \"Front\",\n \"restricted_to_variants\": null\n },\n ...\n```\n\nThese styles contain a view and category and are limited by placement to help select the correct style.\n\n### Creating mockups\n\nOnce the style is retrieved [creating a mockup](#tag/Mockup-Generator-v2/operation/createMockupGeneratorTasks)\nis very similar to creating an order item. All of this data from the order item created above can be reused to\ncreate a mockup\n\n```\n{\n \"source\": \"catalog\",\n \"placements\": [\n {\n \"placement\": \"embroidery_chest_left\",\n \"technique\": \"embroidery\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"layer_options\": [\n {\n \"name\": \"thread_colors\",\n \"value\": [\n \"#FFFFFF\",\n \"#000000\"\n ]\n }\n ],\n \"url\": \"{{image_url}}\"\n }\n ]\n }\n ]\n}\n```\n\nThe placements are all that is needed to create a design. A mockup also needs these properties\n\n```\n{\n \"mockup_style_ids\": [\n 16652 # The style selected before\n ],\n \"catalog_product_id\": 1, # The catalog product\n \"catalog_variant_ids\": [ # A list of catalog variants\n 16365\n ],\n ...\n}\n```\n\nThe mockup generator can then take a list of products in order to create multiple mockups at a time.\n\n```\n{\n \"format\": \"jpg\",\n \"products\": [\n {\n \"source\": \"catalog\",\n \"mockup_style_ids\": [\n 16652\n ],\n \"catalog_product_id\": 294,\n \"catalog_variant_ids\": [\n 9231\n ],\n \"placements\": [\n {\n \"placement\": \"embroidery_chest_left\",\n \"technique\": \"embroidery\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"layer_options\": [\n {\n \"name\": \"thread_colors\",\n \"value\": [\n \"#FFFFFF\",\n \"#000000\"\n ]\n }\n ],\n \"url\": \"{{image_url}}\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n#### Fetching the mockup task\n\nThe response of the above request will look something like this:\n\n```\n{\n \"id\": 752213059,\n \"status\": \"pending\",\n \"catalog_variant_mockups\": [],\n \"failure_reasons\": [],\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.com/v2/mockup-tasks?id=752213059\"\n }\n }\n}\n```\n\nMockups are generated asynchronously so they will not be present right after making the request.\n\n##### Webhook events\nWhen the mockup is finished processing a webhook will be triggered which can be listened to using the\n[Mockup task finished](#tag/Webhook-v2/operation/mockupTaskFinished) webhook (`mockup_task_finished`).\n\n##### GET endpoint\nIt may not be possible to set up webhooks in some systems, or it may simply be too complicated for the\nscope of a given project. If this is the case the mockup can also be retrieved by polling the endpoint to\n[retrieve mockup tasks](#tag/Mockup-Generator-v2/operation/getMockupGeneratorTasks), e.g.\n`https://api.printful.com/v2/mockup-tasks?id=752213059`.\n\nEven if a system uses webhook events, the GET endpoint should still be used as a backup in case the message\nis never received from the webhook. Setting a server up to automatically check the process of mockup tasks can\nimprove the reliability of an integration.\n", "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": "Rate Limiting", "description": "Printful implements rate limiting to ensure the stability of the API while\nkeeping it fair for all users. Rate limiting is handled differently depending\non the version and endpoint being used.\n\n### Header values\n\nPrintful uses the following header values to communicate rate limits:\n\n```\nX-Ratelimit-Limit\nX-Ratelimit-Remaining\nX-Ratelimit-Reset\nX-Ratelimit-Policy\n```\n\nHowever, the meaning of these values changes depending on the algorithm used.\n\n### V1 Rate limitting\n\nV1 used a very simple rate limiting mechanism, you had a limit of 120, every\nrequest would reduce that limit by 1, if it hits 0 you would receive a 429 error,\nevery minute the limit of 120 would be restored. See: [V1 Rate Limits](#tag/Rate-Limiting).\n\nThis system is good, because it's easy to understand for most users. However,\nwe found it had a number of disadvantages both for users and for Printful.\n\n- A burst in traffic could lead to 120 requests in the first second. This is\n harmful for Printful and will lead to a bad user experience as all end users\n wait for the rate limit to be reset.\n- Some users will have close to 120 requests a minute, but most sites don't have\n such uniform traffic.\n\n### V2 Rate Limiting\n\n#### Leaky Bucket\n\nIn V2 of the API Printful implements a [Leaky Bucket](https://en.wikipedia.org/wiki/Leaky_bucket)\nrate limiting algorithm.\n\n**Note:** The algorithm does not implement any queuing mechanisms in its\ncurrent form so it can also be described as a [Token Bucket](https://en.wikipedia.org/wiki/Token_bucket)\nalgorithm.\n\nLike with the old rate limiting algorithm, when you make a request to the API,\nthe `X-Ratelimit-Remaining` header value will go down by one. However, the `X-Ratelimit-Reset`\ndoes not work the same, it states how long it will take to \"refill the bucket\".\nThe bucket will be refilled one drop at a time instead of all at once, so the\n`X-Ratelimit-Reset` will be much smaller after the first request.\n\nBy default, after the first request the headers will look like this:\n\n```\nX-Ratelimit-Policy: 120;w=60;\nX-Ratelimit-Limit: 120\nX-Ratelimit-Remaining: 119\nX-Ratelimit-Reset: 0.5\n```\n\nThis means 120 requests can be made in a single burst, one request has already\nbeen made and `X-Ratelimit-Remaining` will reach 120 again in 0.5 seconds. The\n`X-Ratelimit-Policy` header indicates that in a window of 60 seconds 120 tokens\n(or \"quota units\") will be added to the bucket.\n\nThe headers are inspired by the format in [RateLimit header fields for HTTP](https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-07.html) Internet-Draft.\n\n##### What is rate-limited in V2\n\nAll endpoints are rate-limited with the leaky bucket rate limiter and the defaults.\nHowever, it is planned for future endpoints to have higher or lower limits depending\non usage and the capacity of the API.\n\n##### Using the leaky bucket effectively\n\nThere are a number of strategies you can use to take advantage of rate limiting.\n\n- When receiving a 429 you can use the `retry-after` header to check when the next\n request can be made, then schedule a request to trigger at that time.\n- You can implement a queue that only sends out requests at the rate indicated\n in the policy. You can calculate the rate of requests using the\n `X-Ratelimit-Policy` 120 ÷ 60 = 0.5, so the queue should send requests out at a \n rate of once every 500 milliseconds. \n- Some combination of the two, for example, allow requests to trigger at any rate,\n start queuing after the first 429, then turn off the queue after no new requests\n are sent and the `X-Ratelimit-Reset` time has been met.\n\n" }, { "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": "OAuth Scopes v2", "description": "OAuth API allows receiving data for token" }, { "name": "Catalog v2", "description": "## What is a catalog product?\nA catalog product refers to a blank product and its variants. Each variant can be used as the base for custom designs. Catalog product consists of multiple catalog variants each of which might be a combination of size and color or it might be a variation with e.g. tear away label. The entire hierarchy is shown in the diagram below:\n\n[\"Catalog](images/catalog/catalog_product_diagram.png)\n\n## What is a catalog variant?\nCatalog variant might be a combination of size and color associated with the catalog product or additional variation of a product with certain features like tear away label. It can be thought of as an actual physical blank product. For example T-shirt Bella Canvas 3001 in White color and size M is considered to be a single variant. Catalog variants can have different availability as different regions could have different stock of some product colors and sizes.\n\n[\"Catalog](images/catalog/catalog_variant_diagram.png)\n\nPrintful 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\nmanaging 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**Important**: Jewelry products are not supported via API.\n\n**Rate limiting**: Up to 120 requests per 60 seconds. A 60 seconds lockout is applied if\nrequest count is exceeded.\n\n## Catalog general information\n### General introduction\n\nThis resource contains the list of all the products that are available in Printful for purchase and fulfillment. Apart from basic product data and availability it also contains the information about:\n* [Product Prices](#operation/getProductPricesById)\n* [Product Size Guides](#operation/getProductSizeGuideById)\n* [Product Images](#operation/getProductImagesById)\n\n[\"Catalog](images/catalog/catalog_diagram.png)\n\n### Filtering options\n\nFilters can be used to search for particular set of products based on the provided values. Multiple filters can be used at the same time.\n\n| Filtering option name | Description | Where to find |\n|-----------------------|----------------------------------------------------------------|----------------------------------------------------------------------------|\n| colors | Filters products by variants containing specified colors | `data[].color` [Catalog variants](#operation/getProductVariantsById) |\n| new | Filters products that are new | - |\n| placements | Filters products by available placements specified in the list | `data[].placements[].placement` [Catalog products](#operation/getProducts) |\n| category_ids | Filters products by specified product categories | `data[].id` [Catalog categories](#operation/getCategories) |\n| techniques | Filters products by specified techniques | `data[].techniques[].key` [Catalog products](#operation/getProducts) |\n| types | Filters products by specified types of product e.g. T-Shirt. | `data[].type` [Catalog products](#operation/getProducts) |\n| bestseller | Filters products that are bestsellers | - |\n\n### Sorting\n\nRequires providing two parameters in the URL: `sort_type`\nAnd `sort_direction`. Sort type determines a type of sorting that will be used e.g. sort by price and the sort direction determines if the result should be sorted ascending or descending.\nOnly one sort type can be used at a time.\n\n| Sorting option name | Description |\n|---------------------|------------------------------------------------------------|\n| new | Sorts resulting catalog products starting with new ones |\n| rating | Sorts resulting catalog products by their user-rating |\n| price | Sorts resulting catalog products by their base price |\n| bestseller | Sorts resulting catalog products starting with bestsellers |\n\n### DSR\n\n* **What is DSR?** – DSR (Default Selling Region) is an option that lets you limit the results of a product catalog to products that could be shipped within a specified region. When choosing Worldwide, we'll display the entire Product Catalog. Delivery times depend on end-customer location and selected product.\n* **Where DSR can be set and how it affects response?** – DSR can be currently set in [Catalog products](#operation/getProducts) and [Product Prices](#operation/getProductPricesById).\n* **Available DSRs**\n\n| Region name | Region name value |\n|--------------------------|----------------------------|\n| Worldwide | `worldwide` |\n| North America | `north_america` |\n| Canada | `canada` |\n| Europe | `europe` |\n| Spain | `spain` |\n| Latvia | `latvia` |\n| United Kingdom | `uk` |\n| France | `france` |\n| Germany | `germany` |\n| Australia | `australia` |\n| Japan | `japan` |\n| New Zealand | `new_zealand` |\n| Italy | `italy` |\n| Brazil | `brazil` |\n| Southeast Asia | `southeast_asia` |\n| Republic of Korea | `republic_of_korea` |\n\n### Size guides\n\n[\"Size](images/catalog/size_guides_diagram.png)\n\n[Get Product Size Guide](#operation/getProductSizeGuideById) endpoint will return size guides for the specified product.\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[See examples](#tag/Examples/Catalog-API-examples/Using-size-guides)\n\n## Categories\n\nCatalog categories are used to group products with similar characteristics such as t-shirts, hats etc.\n\nCategories have purely informational purposes and cannot be edited by the customers. Categories can be nested e.g.\n* Men’s clothing\n * All shirts\n * T-Shirts\n * Polo shirts\n * Jackets & vests\n\nApart from display purposes they can be also used for filtering the products in the API [see Filtering options](#filtering-options)\n" }, { "name": "Orders v2", "description": "## Order Building\n\nYou can create a draft order without order items but you won’t be able to confirm it until at least one order item are added to that order.\nWith this approach, you can create a draft order with all necessary recipient data and add items to it as you go (similar to a shopping cart)\nby using [Create Order Item](#operation/createItemByOrderId). After every order item addition, the order cost will be re-calculated.\n\nA minimal DRAFT order can be created with just the address:\n\n```\nPOST https://api.printful.com/v2/orders\nAuthorization: Bearer {{bearer_token}}\n{\n \"recipient\": {\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\"\n }\n}\n```\n\nAfter the order is created the order items can be added one by one.\n\n```\nPOST https://api.printful.com/v2/orders/{{order_id}}/order-items\nAuthorization: Bearer {{bearer_token}}\n{\n \"catalog_variant_id\": 4011,\n \"source\": \"catalog\",\n \"quantity\": 1,\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n }\n ]\n}\n```\n\nIt is also possible to create an order with all order items in a single request.\n\n```\nPOST https://api.printful.com/v2/orders\nAuthorization: Bearer {{bearer_token}}\n{\n \"recipient\": {\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\"\n },\n \"order_items\": [\n {\n \"catalog_variant_id\": 4011,\n \"source\": \"catalog\",\n \"quantity\": 1,\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n## Order life cycle and statuses\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
draftAt this stage, the order has been created but has not yet been submitted for fulfillment. It can be freely edited, changed, or deleted at this stage. The order will not charged or fulfilled until it has been confirmed.
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 and it will be charged in this stage, but is not yet accepted for fulfillment. The order can be cancelled at this stage so long as it has not been charged yet.
failedOrder was submitted for fulfillment but it had some errors preventing it from being fulfilled (problem with the address, missing printfiles, failed to charge the wallet, etc.).
canceledThe order has been canceled and can no longer be processed. If the order was already charged then the cost of the order will be returned to your store.
inprocessThe order is being fulfilled and can no longer be canceled 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.
\n\nYou are only charged for orders when they have been confirmed with the “Confirm Order” operation and have the status “pending” [Confirm Order](#operation/confirmOrder).\nIf the order encounters a problem after it has been confirmed, then it is moved to the failed state so that the problem can be fixed and the order can be resubmitted.\n\nFor order status updates please subscribe to one of the webhook events following\nwebhook events:\n- [Order created](#tag/Webhook-v2/operation/orderCreated)\n- [Order updated](#tag/Webhook-v2/operation/orderUpdated)\n- [Order failed](#tag/Webhook-v2/operation/orderFailed)\n- [Order canceled](#tag/Webhook-v2/operation/orderCanceled)\n\n## Order items\n\nOrder items are representations of the actual products that will come with an order.\n\nIn the sections below we explain each order item source and provide examples of how a simple request might look like for each source.\n\n### Catalog Source\n\n[Catalog products](https://developers.printful.com/docs/v2-beta/#tag/Catalog-v2/What-is-a-catalog-product) are blank products available in Printful. Since they are blank you’ll need to specify design data during the order creation.\nThis flow is intended if you allow your customers to specify their own designs which means that every order is unique.\n\nThe following example request shows how an item structure might look in JSON.\n\n```\nPOST https://api.printful.com/v2/orders/{{order_id}}/order-items\nAuthorization: Bearer {{bearer_token}}\n{\n \"catalog_variant_id\": 4012,\n \"source\": \"catalog\",\n \"quantity\": 1,\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n }\n ]\n}\n```\n\"Example\n\n## Design specification\nDesign data is the information used to customize the product. A design consists\nof placements, layers and unique product options. Placements refer to where a \ndesign will be printed, for example, a T-Shirt might have the placements `front` \nand `left_sleeve`. Placements can also constrict what techniques can be used in \nthat area of the product, for example a product might have both `front` and \n`embroidery_front` and embroidery can only be used in the second placement.\nA layer is constrained to the print area of the placement that you’ve chosen. \nA design that is outside of the print area won’t be visible.\n\nDepending on the product, placement, and technique different layers might \nbe available. \n\nYou can check which layers are available using the [Retrieve a single catalog product](#tag/Catalog-v2/operation/getProductById)\noperation.\n\nThe design data structure is the same regardless of the flow (making orders,\ngenerating mockups etc.). So the solution can be re-used in the different\nendpoints.\n\n[\"Design](images/design-data/design-data.png)\n\n### Placements\nThe product placement is the part of the product where design layers will be \nprinted, different placements will also offer different options and techniques, \nthey will also have different limitations. The available placement list will \nvary depending on the product. To get the available placements of a product use \nthe [Retrieve a single catalog product](#tag/Catalog-v2/operation/getProductById) \nendpoint with the product ID that you want to check.\n\n
\n
Front placement:
\n \"Front\n
\n
\n
Left sleeve placement:
\n \"Left\n
\n\n
\n Note depending on the type and quantity of the placement additional fees might apply.\n
\n\n### Layers\nLayers are what is printed in each placement, and there can be up to 5 of them \nper one placement. The layers are printed on top of each other with the 0th \nlayer being the furthest back and the 4th element being on top of all other layers.\n\nAPI supports only one layer type - `file`.\n\n[\"Layer](images/design-data/layers/layer_diagram.png)\n\nLayers are defined as an array per placement:\n```\n...\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://picsum.photos/200\",\n \"layer_options\": [\n {\n \"name\": \"thread_colors\",\n \"value\": [\n \"#FFFFFF\"\n ]\n }\n ],\n \"position\": {\n \"width\": 640,\n \"height\": 640,\n \"left\": 0,\n \"top\": 0\n }\n }\n ]\n...\n```\n\n#### Layer Positioning\nYou can specify the image position inside the print area by providing a position object.\n\nEach print area has specific dimensions, by default our system will assume that your file \nhas to fit into those limitations and not exceed them. The (0,0) point is always \nlocated in the top left corner of the print area.\n\n
\n Note all values are in inches.\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 }\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}\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}\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}\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}\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}\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}\n```\n\n
\n\n### Options\nApart from placement and layers you can also specify options.\n```\n# Example of option data.\n{\n \"name\": \"unlimited_color\",\n \"value\": true\n}\n```\nOption always consist of the name of the option and the value. Value of the \noption can be different depending on the option type but they are always \npredefined for the specified product. You can always check what options and \nwhat values are available for a specific product by checking\n[Retrieve a single catalog product](#tag/Catalog-v2/operation/getProductById)\n\nOptions can be specified on three levels:\n- Product options - Those options specify additional design options for an \nentire product. E.g. `inside_pocket` allows you to define if a product should be \nfulfilled with an additional inside pocket. Or `stitch_color` lets you choose the \nstitch colors that will be used to stitch back All-Over print products.\n- Placement options - They specify options for an entire placement. E.g. `unlimited_color` \nif specified causes the placement to be fulfilled using [Unlimited Color embroidery](https://www.printful.com/unlimited-color-embroidery). \nFor the inside label placement, use `inside_label_type` to control how the label is composed (see [Inside label](#inside-label)).\n- Layer options - Specify additional parameters for a single layer. E.g. `3d_puff` \noption if set to true causes that particular layer to use [3D puff embroidery](https://www.printful.com/glossary/3d-puff-embroidery).\n\n## Order Customization\n### Packing Slip Customization\n\nThe packing slip information can be customized according to the store’s specific\nrequirements. Some of the options are: a custom logo, the name of the store,\ncustomer service email/phone, and more.\n\nThe packing slip fields can be configured at the store level (in the Dashboard \nat Settings > Stores > Branding > Packing slip section.) and overridden for a \nspecific order.\n\nTo override the packing slip settings for the order, you can use `packing_slip` \nfields for each order.\n\n```\nPOST https://api.printful.com/v2/orders\nAuthorization: Bearer {{bearer_token}}\n{\n \"recipient\": {\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"customization\": {\n \"packing_slip\": {\n \"email\": \"test@example.com\",\n \"phone\": \"+48000000000\",\n \"message\": \"this is a message\",\n \"logo_url\": \"https://example.com/image.jpg\",\n \"store_name\": \"a store\"\n }\n }\n}\n```\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### Gift\nThe order gift option is part of the order customization and contains two properties:\nsubject and message. This option allows users to add a custom note that will be seen \nby the final customer who receives the product.\n\n```\nPOST https://api.printful.com/v2/orders\nAuthorization: Bearer {{bearer_token}}\n{\n \"recipient\": {\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"customization\": {\n \"gift\": {\n \"subject\": \"To John\",\n \"message\": \"Happy birthday!\"\n }\n }\n}\n```\n\n## Notes for Beta\n\nThe Orders endpoints for the V2 Beta are incomplete. Some V1 endpoints will\nstill need to be used to achieve certain functionality.\n\n- To cancel an order use `DELETE https://api.printful.com/orders/{order_id}`\n https://developers.printful.com/docs/#operation/cancelOrderById\n- Incomplete, or unsynced, items that were created via an integration store but\n haven't been synced with printful yet will not be visible via the V2 orders\n endpoints, if you need this functionality you will need to use V1\n https://developers.printful.com/docs/#tag/Orders-API\n- To update an existing order, use `PUT https://api.printful.com/orders/{order_id}`\n https://developers.printful.com/docs/#operation/updateOrderById\n\n## Order Cost Calculations\n\n**Order costs are calculated asynchronously**. This means when you create or \nupdate an order you are likely to see a response from the API with `costs` and \n`retail_costs` fields set to null and `\"calculation_status\": \"calculating\"`.\n\n```\n\"costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": null,\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"digitization\": null,\n \"additional_fee\": null,\n \"fulfillment_fee\": null,\n \"retail_delivery_fee\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n},\n\"retail_costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": \"USD\",\n \"subtotal\": \"0.00\",\n \"discount\": \"1.00\",\n \"shipping\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"0.00\",\n \"total\": null\n},\n```\n\nOnce the costs and retail costs are calculated the \"calculation_status\" will \nchange the status to \"done\"\n\n```\n\"costs\": {\n \"calculation_status\": \"done\",\n \"currency\": \"USD\",\n \"subtotal\": \"107.50\",\n \"discount\": \"0.00\",\n \"shipping\": \"14.84\",\n \"digitization\": \"0.00\",\n \"additional_fee\": \"0.00\",\n \"fulfillment_fee\": \"0.00\",\n \"retail_delivery_fee\": \"0.00\",\n \"tax\": \"11.20\",\n \"vat\": \"0.00\",\n \"total\": \"133.54\"\n},\n\"retail_costs\": {\n \"calculation_status\": \"done\",\n \"currency\": \"USD\",\n \"subtotal\": \"0.00\",\n \"discount\": \"1.00\",\n \"shipping\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"0.00\",\n \"total\": \"134.54\"\n},\n```\n\nIf you are subscribed to the `order_updated` [webhook event](#tag/Webhook-v2/operation/orderUpdated), \nyou will receive an event when the calculation is finished. \n\n## Inside label\n\nFor products that support the inside label placement, you can control how the label is composed by passing the `inside_label_type` option in `placement_options`. This option accepts three values, each affecting how the material and product origin information is combined with your design and how the final inside label looks.\n\nThe entire inside label print area is then placed above the material and origin information, so inside the print area it is not necessary to place the design on top.\n\nThe **native** inside label is the default option. It works well with square and rectangular images and fits them to a rectangular print area at the top of the label.\n\nExample request with placement options for the inside label:\n\n```\n\"placements\": [\n {\n \"placement\": \"inside_label\",\n \"technique\": \"dtg\",\n \"placement_options\": [\n {\n \"name\": \"inside_label_type\",\n \"value\": \"native\"\n }\n ],\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://example.com/your-design.png\"\n }\n ]\n }\n]\n```\n\n### `inside_label_type` values\n\n| Value | Description | Effect on the inside label |\n|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `native` | **Default.** Material and product origin information are added automatically by Printful. Your design is placed above that information. Works well with square and rectangular images. | The design is scaled to fit a **rectangular** print area at the top of the label. |\n| `custom` | Material and origin information are **not** added automatically. You are responsible for including them in your design file. | **Not globally available.** If you use `custom` but your design file does not include the required material and origin information, the order will be marked as **invalid**. |\n\n
\n custom availability The custom inside label type is not available for all accounts. When using it, ensure your design file contains the required material and product origin information; otherwise the order will be invalid.\n
\n" }, { "name": "Files v2", "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": "Countries v2", "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": "Shipping Rates v2", "description": "
\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.\n\n### Recipient in shipping rates estimates\n\nWhen making a shipping rates estimate the only data that is necessary is the country code, and state code in the case\nof the case of the United States, Canada, and Australia. This allows for an estimate to be retrieved for a\ncustomer before their address is known, however the more information provided the more accurate the estimate will be.\n" }, { "name": "Warehouse Products v2", "description": "Warehouse Products v2" }, { "name": "Mockup Generator v2", "description": "This resource is used to visualize how the designed products will look like. Since this is a resource-heavy operation we process the requests asynchronously. That means that you won't get the results\nimmediately, and instead you will get task ID which you could use to retrieve the mockups once they are done\nusing _[Retrieve mockup generator tasks](#operation/getMockupGeneratorTasks)_.\nYou can also subscribe to a webhook _[Mockup generator task finished event](#operation/mockupTaskFinished)_ to be\nnotified once the tasks finish processing.\n\nTo create a mockup you need to specify:\n* catalog product ID – _[Retrieve a list of catalog products](#operation/getProducts)_\n* catalog variant IDs – _[Retrieve information about catalog product variants](#operation/getProductVariantsById)_\n* design data – Data used to specify how the design should look like on the catalog product\n* mockup styles – _[Retrieve catalog product mockup styles](#operation/retrieveMockupStylesByProductId)_\n\nWhile `placements` specifies how the catalog product should look like, the `mockup_style_ids` define\nhow the mockups themselves should look like. You can find available mockup styles for a product by requesting\n_[Retrieve catalog product mockup styles](#operation/retrieveMockupStylesByProductId)_.\n\nTo give a little bit more context on how to use product mockup styles see the table below:\n\nThe example product is Bella Canvas 3001 with ID 71.\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
Mockup styles Mockups
\n\n```\n {\n \"style_id\": 1115,\n \"style_name\": \"Men's\",\n \"view_name\": \"Front\"\n }\n```\n\n \"Men's
\n\n```\n {\n \"style_id\": 1103,\n \"style_name\": \"Men's\",\n \"view_name\": \"Left sleeve\"\n }\n```\n\n \"Men's
\n\n```\n {\n \"style_id\": 1117,\n \"style_name\": \"Women's\",\n \"view_name\": \"Front\"\n }\n```\n\n \"Women's
\n\n```\n {\n \"style_id\": 1107,\n \"style_name\": \"Women's\",\n \"view_name\": \"Left sleeve\"\n }\n```\n\n \"Women's
\n\n```\n {\n \"style_id\": 768,\n \"style_name\": \"Women's Lifestyle\",\n \"view_name\": \"Front\"\n }\n```\n\n \"Women's
\n\n```\n {\n \"style_id\": 770,\n \"style_name\": \"Women's Lifestyle\",\n \"view_name\": \"Left\"\n }\n```\n\n \"Women's
\n\n```\n {\n \"style_id\": 849,\n \"style_name\": \"Flat\",\n \"view_name\": \"Front\"\n }\n```\n\n \"Flat
\n\n```\n {\n \"style_id\": 931,\n \"style_name\": \"On hanger\",\n \"view_name\": \"Front\"\n }\n```\n\n \"On
\n\n## Mockups from the product templates\n\nInstead of creating a mockups from catalog variants data you can generate them from a product template.\nIn that case all you need is:\n* product template ID\n* catalog variant IDs – _[Retrieve information about catalog product variants](#operation/getProductVariantsById)_\n* mockup styles – _[Retrieve catalog product mockup styles](#operation/retrieveMockupStylesByProductId)_\n\n**Important**: All the catalog variants specified in the request must also be defined in the product template,\notherwise an error will be returned.\n\n## Throttling and daily file limit\n\nAn account is allowed to make a number of mockup generation requests per minute. The limit is:\n\n* 2 requests per minute for new stores;\n* 10 requests per minute for stores with at least $10.00 worth of fulfilled orders.\n\nAdditionally, there is a limit of 20,000 files that can be generated daily by each environment.\n\n## Number of generated files\n\nThere will be one mockup file returned for each valid combination of Catalog Variant, mockup style and placement within\none product object.\n\nIf the same file would be generated for two or more combinations (for example, for different sizes of a T-Shirt in the\nsame color),\nit will only be generated once and the same URL will be returned for each of these combinations. If only one file is generated it will count\nas one file toward the daily limit." }, { "name": "Webhook v2", "description": "Webhooks are an API feature that allows your system to receive notifications about certain events.\n\nWhen an event occurs, for example one of the products you use comes back in stock, the Printful server\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
occurred_attimestampEvent time
retriesintegerNumber of previous attempts to deliver this webhook event
store_idintegerID of the store that the event occurred to
dataObjectAdditional data, depending on the event type
\n\nCurrently, our [Webhook Simulator](https://www.printful.com/api/webhook-simulator) doesn't support the v2 webhooks.\n\n### Event signing\n\nSince the webhook URL used to accept the events needs to be publicly availably, it's important to be able to\nverify if the event originates from our servers or was sent by someone else who knows the URL.\n\nThat's why we introduced event signing in Webhook v2.\n\nWebhook settings are associated with a public and a secret key. The public key is used to identify the specific\nsettings (you may use the same URL for different configurations) and the secret key is used to generate\nand verify the event signature.\n\nWe're using HMAC-SHA256 hash to create the signature. For tests, you may find an online or offline tool\nand check if you get the same hash for the event data you receive and the configuration's secret key.\n\nPlease note that in the `secret_key` field we return the hexadecimal representation of the secret key. It means that you\nneed to decode it before passing it to the tool or method that calculates the signature, unless it supports keys in\nhexadecimal format.\n\nFor actual usage, we strongly recommend to incorporate the signature verification in the event handling process.\n\nIf you find that you receive an event with invalid or missing signature, you should ignore the event.\n\nYou may investigate the situation, starting with verifying if your configuration is correct.\nIt's possible you used wrong secret key to generate the signature on your side or generated it for the formatted\nevent content instead of the raw content etc.\n\nIf you didn't find an explanation, you may contact us with the event details (content, your URL, event time)\nso we can check if we sent such an event and find out why the signature is invalid.\n\n### Expiration time\n\nIt's possible to specify the expiration time of the configuration. If you decide to use this option,\nyou will be forced to resubscribe which will generate a new key pair. You may simply send the GET request\nwhen the configuration is still valid and use the returned data to create the new configuration.\n\nIf the configuration is already expired and you don't have the data saved somewhere, a regular GET request\nwill result in a 404 Not Found response with a message explaining what needs to be done:\n\"The settings are expired. To view them, please use query param show_expired with value true.\"\n\nYou may then use `show_expired` param with value `true` to retrieve the configuration and use it to resubscribe.\n\nPlease note that once the new configuration is saved, the new secret key will be used to sign the events.\nIt needs to be updated in your code as soon as possible to avoid invalid signature warnings.\n" }, { "name": "Stores v2", "description": "Stores v2" }, { "name": "Approval Sheets v2", "description": "Get information about approval sheets." }, { "name": "Basic use cases", "description": "# Using the Printful v2 API for a Basic Use Case: Customer-Designed Products\n\nThis guide explains how to use the Printful v2 API for a basic use case where a merchant allows customers to design and order products through their shop. The integration involves fetching catalog products, enabling customers to design them, and creating orders for fulfillment.\n\n---\n\n## Overview of the Flow\n\n1. **Authenticate**: Obtain your private API key from the Printful dashboard.\n2. **Retrieve Catalog Products**: Fetch available catalog products to display to customers.\n3. **Customize Products**: Allow customers to design products using your shop interface.\n4. **Create Orders**: Send the customized product details and order data to Printful.\n5. **Track Orders**: Use the API to track the status of orders and shipments.\n\n---\n\n## Sequence Diagram\n\nThe following diagram illustrates the interaction between the customer, the shop, and the Printful API:\n\n
\nsequenceDiagram\n    participant Customer as End Customer\n    participant Shop as Merchant's Shop\n    participant Printful as Printful API\n\n    Customer->>Shop: Browse Catalog Products\n    Shop->>Printful: GET /v2/catalog/products\n    Printful->>Shop: Return Product List\n    Shop->>Customer: Display Product Catalog\n\n    Customer->>Shop: Design Product\n    Shop->>Printful: POST /v2/orders (Draft Order)\n    Printful->>Shop: Return Draft Order ID\n\n    Customer->>Shop: Confirm Order\n    Shop->>Printful: POST /v2/orders/{order_id}/confirm\n    Printful->>Shop: Return Order Confirmation\n\n    Shop->>Customer: Provide Order Confirmation and Tracking\n
" }, { "name": "Examples", "description": "# Catalog API examples\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/v2/catalog-products/561/sizes\n\n
\n Whole response body\n\n```javascript\n{\n \"data\": {\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 \"image_url\": \"https://s3-printful.stage.printful.dev/upload/product-measure/85/857e7cc8b802da216e7f1a6114075a72_t?v=1652962720\",\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 \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/catalog-products/561/sizes\"\n },\n \"product\": {\n \"href\": \"https://api.printful.test/v2/catalog-products/561\"\n }\n }\n },\n \"extra\": [],\n \"debug\": []\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```javascript\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```javascript\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```javascript\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# File Library API examples\n\n## Add a new file\n\nAdd file to the print file library, filename 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 \"data\": {\n \"id\": 11816,\n \"url\": \"http://www.example.com/files/tshirts/example.png\",\n \"hash\": 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\": \"2024-06-10T15:31:49Z\",\n \"thumbnail_url\": null,\n \"preview_url\": null,\n \"visible\": true,\n \"is_temporary\": false,\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.com/v2/files/11816\"\n }\n }\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\": false\n}\n```\n\n# Shipping Rates API examples\n\n## Shipment information\n\nFor each entry in the response array, in addition to the basic information about the shipping rate (name, rate,\nestimated delivery time),\nan expected shipment split will be provided. Each shipment object will contain the following data:\n\n* departure country (2-letter code) – currently, this may be null for some branches. We plan to fix this in the\n foreseeable future;\n* shipment items included in the shipment (Catalog Variant ID and item quantity);\n* whether customs fees may be required for the shipment (`customs_fees_possible`).\n\nIt's possible the fees won't apply even if the value of the `customs_fees_possible` field is `true`, depending on the\ncharacteristics of the products and agreements between the countries. The value of `false` means the customs fees\nwon't be required for the shipment (e.g. shipment within the EU or the same country).\n\n### Example: Same-country shipment\n\nIn this example two shipping options are available. All items can be fulfilled in the US and they are split into two shipments because of large quantities. No customs fees will be charged.\n\n
\n Request body\n\n```\n{\n \"recipient\": {\n \"address1\": \"19749 Dearborn St\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"country_code\": \"US\",\n \"zip\": \"91311\"\n },\n \"order_items\": [\n {\n \"source\": \"catalog\",\n \"quantity\": 20,\n \"catalog_variant_id\": 408\n },\n {\n \"source\": \"catalog\",\n \"quantity\": 20,\n \"catalog_variant_id\": 4011\n },\n {\n \"source\": \"catalog\",\n \"quantity\": 30,\n \"catalog_variant_id\": 4016\n },\n {\n \"source\": \"catalog\",\n \"quantity\": 40,\n \"catalog_variant_id\": 4020\n }\n ],\n \"currency\": \"USD\"\n}\n```\n\n
\n\n
\n Response data\n\n```\n{\n \"data\": [\n {\n \"shipping\": \"STANDARD\",\n \"shipping_method_name\": \"Flat Rate (Estimated delivery: Jan 20⁠–27) \",\n \"rate\": \"60.74\",\n \"currency\": \"USD\",\n \"min_delivery_days\": 5,\n \"max_delivery_days\": 8,\n \"min_delivery_date\": \"2025-01-20\",\n \"max_delivery_date\": \"2025-01-27\",\n \"shipments\": [\n {\n \"departure_country\": \"US\",\n \"shipment_items\": [\n {\n \"catalog_variant_id\": 408,\n \"quantity\": 20\n },\n {\n \"catalog_variant_id\": 4011,\n \"quantity\": 20\n },\n {\n \"catalog_variant_id\": 4016,\n \"quantity\": 20\n }\n ],\n \"customs_fees_possible\": false\n },\n {\n \"departure_country\": \"US\",\n \"shipment_items\": [\n {\n \"catalog_variant_id\": 4016,\n \"quantity\": 10\n },\n {\n \"catalog_variant_id\": 4020,\n \"quantity\": 40\n }\n ],\n \"customs_fees_possible\": false\n }\n ]\n },\n {\n \"shipping\": \"STANDARD_CARBON_OFFSET\",\n \"shipping_method_name\": \"Standard rate with CO2 offsetting (Estimated delivery: Jan 20⁠–27) \",\n \"rate\": \"70.64\",\n \"currency\": \"USD\",\n \"min_delivery_days\": 5,\n \"max_delivery_days\": 8,\n \"min_delivery_date\": \"2025-01-20\",\n \"max_delivery_date\": \"2025-01-27\",\n \"shipments\": [\n {\n \"departure_country\": \"US\",\n \"shipment_items\": [\n {\n \"catalog_variant_id\": 408,\n \"quantity\": 20\n },\n {\n \"catalog_variant_id\": 4011,\n \"quantity\": 20\n },\n {\n \"catalog_variant_id\": 4016,\n \"quantity\": 20\n }\n ],\n \"customs_fees_possible\": false\n },\n {\n \"departure_country\": \"US\",\n \"shipment_items\": [\n {\n \"catalog_variant_id\": 4016,\n \"quantity\": 10\n },\n {\n \"catalog_variant_id\": 4020,\n \"quantity\": 40\n }\n ],\n \"customs_fees_possible\": false\n }\n ]\n }\n ],\n \"extra\": []\n}\n```\n\n
\n\n### Example: shipments from different countries\n\nIn this example only one shipping option is available. One item can't be shipped from Europe, so it will be shipped from the US instead,\nprobably incurring customs fees.\n\n
\n Request body\n\n```\n{\n \"recipient\": {\n \"address1\": \"Warszawska 1\",\n \"city\": \"Gdańsk\",\n \"country_code\": \"PL\"\n },\n \"order_items\": [\n {\n \"source\": \"catalog\",\n \"quantity\": 1,\n \"catalog_variant_id\": 408\n },\n {\n \"source\": \"catalog\",\n \"quantity\": 1,\n \"catalog_variant_id\": 4011\n }\n ]\n}\n```\n\n
\n\n
\n Response data\n\n```\n{\n \"data\": [\n {\n \"shipping\": \"STANDARD\",\n \"shipping_method_name\": \"Flat Rate (Estimated delivery: Jan 21⁠–28) \",\n \"rate\": \"5.54\",\n \"currency\": \"EUR\",\n \"min_delivery_days\": 8,\n \"max_delivery_days\": 14,\n \"min_delivery_date\": \"2025-01-21\",\n \"max_delivery_date\": \"2025-01-28\",\n \"shipments\": [\n {\n \"departure_country\": \"US\",\n \"shipment_items\": [\n {\n \"catalog_variant_id\": 408,\n \"quantity\": 1\n }\n ],\n \"customs_fees_possible\": true\n },\n {\n \"departure_country\": \"LV\",\n \"shipment_items\": [\n {\n \"catalog_variant_id\": 4011,\n \"quantity\": 1\n }\n ],\n \"customs_fees_possible\": false\n }\n ]\n }\n ],\n \"extra\": []\n}\n```\n\n
\n\n# Webhook API examples\n\n## Configuring webhooks\n\n### Enabling webhook support\n\nWe will use an endpoint allowing us to enable webhook support for a store specifying multiple events in one request.\n\nWe want to enable support for `order_put_hold`, `shipment_sent`, `shipment_returned`,\nand `catalog_stock_updated` events.\n\nWe want to receive the event at https://example.org/webhook/store for most events\nbut for `shipment_returned` we want to use https://example.org/webhook/catalog.\n\nYou may replace the URLs with your own. If you don't have a server software that will accept the events,\nyou may use a site like https://webhook.site/.\n\nWe don't want the configuration to expire.\n\nWe want to be notified of stock updates for the following product IDs: 1, 71.\n\nEndpoint: `POST https://api.printful.com/v2/webhooks`\n\nThe request needs to be authorized with a store-level token\nor an account-level token with the store ID specified in `X-PF-Store-ID` header.\n\n
\n Request body\n\n```\n{\n \"default_url\": \"https://example.org/webhook/store\",\n \"events\": [\n {\n \"type\": \"order_put_hold\"\n },\n {\n \"type\": \"shipment_sent\"\n },\n {\n \"type\": \"shipment_returned\",\n \"url\": \"https://example.org/webhook/catalog\"\n },\n {\n \"type\": \"catalog_stock_updated\",\n \"params\": [\n {\n \"name\": \"products\",\n \"value\": [\n {\n \"id\": 1\n },\n {\n \"id\": 71\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n
\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"default_url\": \"https://example.org/webhook/store\",\n \"expires_at\": null,\n \"events\": [\n {\n \"type\": \"order_put_hold\",\n \"url\": null,\n \"params\": []\n },\n {\n \"type\": \"shipment_sent\",\n \"url\": null,\n \"params\": []\n },\n {\n \"type\": \"shipment_returned\",\n \"url\": \"https://example.org/webhook/catalog\",\n \"params\": []\n },\n {\n \"type\": \"catalog_stock_updated\",\n \"url\": null,\n \"params\": [\n {\n \"name\": \"products\",\n \"value\": [\n {\n \"id\": 1\n },\n {\n \"id\": 71\n }\n ]\n }\n ]\n }\n ],\n \"public_key\": \"somePublicKey\",\n \"secret_key\": \"0123456789abcdef...\"\n },\n \"extra\": []\n}\n```\n\n
\n\nThe public key will be used to distinguish between events coming from different configurations.\n\nFor example, if you use the same URL for different stores or create multiple configurations for the same store\nwith different tokens for the same URL, you may use the public key to know which configuration was used.\n\nThe secret key will be used to verify the signature of the received event.\n\n### Updating or adding event configuration\n\nIf you have the general settings created for the store, you may modify or update the settings for specific events.\n\nWe will now show how to add support for another event: `order_created`.\n\nEndpoint: `POST https://api.printful.com/v2/webhooks/{eventType}`\n\nIf you don't need to specify additional fields like URL, you may send the request without body.\nWe will send such a request in this example.\n\nRequest URL: https://api.printful.com/v2/webhooks/order_created\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"type\": \"order_created\",\n \"url\": null,\n \"params\": []\n },\n \"extra\": []\n}\n```\n\n
\n\nThe endpoint may be used to replace existing event settings. It may be used for an already configured\nevent or a new one.\n\nRequest URL: https://api.printful.com/v2/webhooks/shipment_returned\n\nIf we omit the request body, we will replace the existing configuration with a custom URL\nwith a default one, using the store's `default_url`.\n\nHowever, we want to update the URL with another one.\n\n
\n Request body\n\n```\n{\n \"url\": \"https://example.org/webhook/another\"\n}\n```\n\n
\n\n
\n Response data\n\n```\n{\n \"code\": 200,\n \"result\": {\n \"type\": \"shipment_returned\",\n \"url\": \"https://example.org/webhook/another\",\n \"params\": []\n },\n \"extra\": []\n}\n```\n\n
\n\nNote it's not possible to omit the request body for an event requiring a parameter.\n\nSending a request without body to https://api.printful.com/v2/webhooks/catalog_stock_updated will result in an error.\n\n## Event example\n\nThis is an example of an `order_created` event sent to the specified URL:\n\n\n
\n Event content\n\n```\n{\n \"type\": \"order_created\",\n \"occurred_at\": \"2023-04-04T12:36:42Z\",\n \"retries\": 0,\n \"store_id\": 123456,\n \"data\": {\n \"order\": {\n \"id\": 11111,\n \"external_id\": null,\n \"status\": \"pending\",\n \"created\": 1680611801,\n \"updated\": 1680611802,\n \"dashboard_url\": \"https://www.printful.test/dashboard?order_id=90630659\",\n }\n }\n}\n```\n\n
\n\nIn headers, you will also receive:\n\n* The base64-encoded public key associated with the configuration used to trigger the event in `x-pf-webhook-public-key`\n header\n* The hexadecimal representation of the signature in `x-pf-webhook-signature` header.\n\nYou may use the secret key associated with the settings to calculate the HMAC-SHA256 hash for the event data\nand compare it to the value from header. You may create a script or use an online or offline tool to do this.\n\nPlease note that in the `secret_key` field we return the hexadecimal representation of the secret key. It means that you\nneed to decode it before passing it to the tool or method that calculates the signature, unless it supports keys in\nhexadecimal format.\n\n# PATCH Partial Updates\n\nSee [RFC 7386](https://datatracker.ietf.org/doc/html/rfc7386).\n\nPATCH updates allows you to change only the fields that you've specified in the request.\n\nIf you'd like to update the value that is an array please keep in mind that in case of arrays the entire\narray is replaced with the value provided in the request. For example:\n\nCurrent array value:\n```\n{\n \"items\": [\n {\n \"catalog_variant_id\": 4011,\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n }\n ]\n },\n {\n \"catalog_variant_id\": 4012,\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n },\n {\n \"placement\": \"back\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\nPATCH request:\n```\n{\n \"items\": [\n {\n \"catalog_variant_id\": 4013,\n \"placements\": [\n {\n \"placement\": \"left_sleeve\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\nResults in:\n```\n{\n \"items\": [\n {\n \"catalog_variant_id\": 4013,\n \"placements\": [\n {\n \"placement\": \"left_sleeve\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\nNotice that all of the previous items were discarded and were replaced with items provided in the request.\nIt's also not possible to override properties in nested arrays. So whenever you are changing the array\nvalue you need to provide full object.\n\n## Example of order update\n\n
\n Order that is being updated\n\n```\n{\n \"data\": {\n \"id\": 94188292,\n \"external_id\": null,\n \"store_id\": 11229252,\n \"shipping\": \"STANDARD\",\n \"status\": \"draft\",\n \"created_at\": \"2023-10-18T12:35:07Z\",\n \"updated_at\": \"2023-10-18T12:35:07Z\",\n \"recipient\": {\n \"name\": \"John Smith\",\n \"company\": \"John Smith Inc\",\n \"address1\": \"19749 Dearborn St\",\n \"address2\": \"string\",\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\": \"string\",\n \"email\": \"dev@printful.com\",\n \"tax_number\": \"123.456.789-10\"\n },\n \"costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": null,\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"digitization\": null,\n \"additional_fee\": null,\n \"fulfillment_fee\": null,\n \"retail_delivery_fee\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"retail_costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": \"USD\",\n \"subtotal\": null,\n \"discount\": \"0.00\",\n \"shipping\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"0.00\",\n \"total\": null\n },\n \"order_items\": [\n {\n \"id\": 66655730,\n \"external_id\": \"some_external_id\",\n \"type\": \"order_item\",\n \"source\": \"catalog\",\n \"catalog_variant_id\": 4012,\n \"quantity\": 1,\n \"name\": \"my_custom_name\",\n \"price\": \"10.50\",\n \"retail_price\": null,\n \"currency\": \"EUR\",\n \"retail_currency\": \"USD\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items/66655730\"\n }\n }\n }\n ],\n \"customization\": null,\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292\"\n },\n \"order_confirmation\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/confirmation\"\n },\n \"order_items\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items\"\n },\n \"shipments\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/shipments\"\n }\n }\n },\n \"extra\": [],\n}\n```\n\n
\n\n### Changing specified fields in recipient object\n\nEndpoint `PATCH https://api.printful.com/v2/orders/{order_id}`\n
\n Request body\n\n```\n{\n \"recipient\": {\n \"address1\": \"new address\",\n \"name\": \"new name\"\n }\n}\n```\n\n
\n\nEndpoint `GET https://api.printful.com/v2/orders/{order_id}`\n
\n Response body\n\n```\n{\n \"data\": {\n \"id\": 94188292,\n \"external_id\": null,\n \"store_id\": 11229252,\n \"shipping\": \"STANDARD\",\n \"status\": \"draft\",\n \"created_at\": \"2023-10-18T12:35:07Z\",\n \"updated_at\": \"2023-10-18T12:35:07Z\",\n \"recipient\": {\n \"name\": \"new name\", <--------Changed field\n \"company\": \"John Smith Inc\",\n \"address1\": \"new address\", <--------Changed field\n \"address2\": \"string\",\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\": \"string\",\n \"email\": \"dev@printful.com\",\n \"tax_number\": \"123.456.789-10\"\n },\n \"costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": null,\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"digitization\": null,\n \"additional_fee\": null,\n \"fulfillment_fee\": null,\n \"retail_delivery_fee\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"retail_costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": \"USD\",\n \"subtotal\": null,\n \"discount\": \"0.00\",\n \"shipping\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"0.00\",\n \"total\": null\n },\n \"order_items\": [\n {\n \"id\": 66655730,\n \"external_id\": \"some_external_id\",\n \"type\": \"order_item\",\n \"source\": \"catalog\",\n \"catalog_variant_id\": 4012,\n \"quantity\": 1,\n \"name\": \"my_custom_name\",\n \"price\": \"10.50\",\n \"retail_price\": null,\n \"currency\": \"EUR\",\n \"retail_currency\": \"USD\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items/66655730\"\n }\n }\n }\n ],\n \"customization\": null,\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292\"\n },\n \"order_confirmation\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/confirmation\"\n },\n \"order_items\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items\"\n },\n \"shipments\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/shipments\"\n }\n }\n },\n \"extra\": [],\n}\n```\n\n
\n\n### Changing `external_id` property\n\nEndpoint `PATCH https://api.printful.com/v2/orders/{order_id}`\n
\n Request body\n\n```\n{\n \"external_id\": \"1234_abc\"\n}\n```\n\n
\n\nEndpoint `GET https://api.printful.com/v2/orders/{order_id}`\n
\n Response body\n\n```\n{\n \"data\": {\n \"id\": 94188292,\n \"external_id\": \"1234_abc\", <--------Changed field\n \"store_id\": 11229252,\n \"shipping\": \"STANDARD\",\n \"status\": \"draft\",\n \"created_at\": \"2023-10-18T12:35:07Z\",\n \"updated_at\": \"2023-10-18T12:35:07Z\",\n \"recipient\": {\n \"name\": \"John Smith\",\n \"company\": \"John Smith Inc\",\n \"address1\": \"19749 Dearborn St\",\n \"address2\": \"string\",\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\": \"string\",\n \"email\": \"dev@printful.com\",\n \"tax_number\": \"123.456.789-10\"\n },\n \"costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": null,\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"digitization\": null,\n \"additional_fee\": null,\n \"fulfillment_fee\": null,\n \"retail_delivery_fee\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"retail_costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": \"USD\",\n \"subtotal\": null,\n \"discount\": \"0.00\",\n \"shipping\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"0.00\",\n \"total\": null\n },\n \"order_items\": [\n {\n \"id\": 66655730,\n \"external_id\": \"some_external_id\",\n \"type\": \"order_item\",\n \"source\": \"catalog\",\n \"catalog_variant_id\": 4012,\n \"quantity\": 1,\n \"name\": \"my_custom_name\",\n \"price\": \"10.50\",\n \"retail_price\": null,\n \"currency\": \"EUR\",\n \"retail_currency\": \"USD\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items/66655730\"\n }\n }\n }\n ],\n \"customization\": null,\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292\"\n },\n \"order_confirmation\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/confirmation\"\n },\n \"order_items\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items\"\n },\n \"shipments\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/shipments\"\n }\n }\n },\n \"extra\": [],\n}\n```\n\n
\n\n### Replacing ordered item with another one\n\nEndpoint `PATCH https://api.printful.com/v2/orders/{order_id}`\n
\n Request body\n\n```\n{\n \"items\": [\n {\n \"source\": \"catalog\",\n \"catalog_variant_id\": 4011,\n \"quantity\": 1,\n \"placements\": [\n {\n \"placement\": \"front\",\n \"technique\": \"dtg\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\",\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n
\n\nEndpoint `GET https://api.printful.com/v2/orders/{order_id}`\n
\n Response body\n\n```\n{\n \"data\": {\n \"id\": 94188292,\n \"external_id\": null,\n \"store_id\": 11229252,\n \"shipping\": \"STANDARD\",\n \"status\": \"draft\",\n \"created_at\": \"2023-10-18T12:35:07Z\",\n \"updated_at\": \"2023-10-18T12:35:07Z\",\n \"recipient\": {\n \"name\": \"John Smith\",\n \"company\": \"John Smith Inc\",\n \"address1\": \"19749 Dearborn St\",\n \"address2\": \"string\",\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\": \"string\",\n \"email\": \"dev@printful.com\",\n \"tax_number\": \"123.456.789-10\"\n },\n \"costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": null,\n \"subtotal\": null,\n \"discount\": null,\n \"shipping\": null,\n \"digitization\": null,\n \"additional_fee\": null,\n \"fulfillment_fee\": null,\n \"retail_delivery_fee\": null,\n \"tax\": null,\n \"vat\": null,\n \"total\": null\n },\n \"retail_costs\": {\n \"calculation_status\": \"calculating\",\n \"currency\": \"USD\",\n \"subtotal\": null,\n \"discount\": \"0.00\",\n \"shipping\": \"0.00\",\n \"tax\": \"0.00\",\n \"vat\": \"0.00\",\n \"total\": null\n },\n \"order_items\": [ <--------Changed field\n {\n \"id\": 66655731,\n \"external_id\": null,\n \"type\": \"order_item\",\n \"source\": \"catalog\",\n \"catalog_variant_id\": 4011,\n \"quantity\": 1,\n \"name\": null,\n \"price\": \"10.50\",\n \"retail_price\": null,\n \"currency\": \"EUR\",\n \"retail_currency\": \"USD\",\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items/66655730\"\n }\n }\n }\n ],\n \"customization\": null,\n \"_links\": {\n \"self\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292\"\n },\n \"order_confirmation\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/confirmation\"\n },\n \"order_items\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/order-items\"\n },\n \"shipments\": {\n \"href\": \"https://api.printful.test/v2/orders/94188292/shipments\"\n }\n }\n },\n \"extra\": [],\n}\n```\n\n
\n\n# Utilising options\n\nOptions are the special properties which are used to customise the products. Depending on the product and the technique different options might be available.\nYou can check the available options for a product in [Retrieve a single catalog product](#tag/Catalog-v2/operation/getProductById). Currently, there are 3 types of options each referencing a different ascpect of the design:\n* `product_options` - options which affect the entire product e.g. if the product should contain inside pocket or not.\n* `placement_options` - options which are affecting the specific placement\n* `layer_options` - options which are affecting the specific layer e.g. thread colors\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 `product_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/v2/orders`\n
\n Request body\n\n```\n{\n \"recipient\": {\n \"name\": \"John Smith\",\n \"company\": \"John Smith Inc\",\n \"address1\": \"19749 Dearborn St\",\n \"address2\": \"string\",\n \"city\": \"Chatsworth\",\n \"state_code\": \"CA\",\n \"state_name\": \"California\",\n \"country_code\": \"US\",\n \"country_name\": \"United States\",\n \"zip\": \"91311\"\n },\n \"items\": [\n {\n \"quantity\": 1,\n \"variant_id\": 10163,\n \"source\": \"catalog\",\n \"placements\": [\n {\n \"placement\": \"default\",\n \"technique\": \"digital\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://www.printful.com/static/images/layout/printful-logo.png\",\n \"position\": {\n \"width\": 3,\n \"height\": 3,\n \"top\": 0,\n \"left\": 0\n }\n }\n ]\n }\n ],\n \"product_options\": [\n {\n \"name\": \"custom_border_color\",\n \"value\": \"#FFFF00\"\n }\n ]\n }\n ]\n}\n```\n\n
\n\n# Creating Orders for Knitwear Products \n\nKnitwear products can be configured with some unique options that affect the color of the final knitted product.\n\nThese options are `trim_color`, `color_reduction_mode`, `base_color`, they only apply to\nknitwear and function differently to other similar options.\n\nNote that `yarn_colors` can be applied on each layer of a product.\n\n\nEndpoint `POST https://api.printful.com/v2/orders`\n
\n Request body\n\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 \"order_items\": [\n {\n \"source\": \"catalog\",\n \"quantity\": 1,\n \"catalog_variant_id\": 19634,\n \"placements\": [\n {\n \"placement\": \"sleeve_right\",\n \"technique\": \"knitting\",\n \"layers\": [\n {\n \"type\": \"file\",\n \"url\": \"https://picsum.photos/200\",\n \"layer_options\": [\n {\n \"name\": \"yarn_colors\",\n \"value\": [\n \"#090909\",\n \"#48542e\"\n ]\n }\n ]\n }\n ]\n }\n ],\n \"product_options\": [\n {\n \"name\": \"trim_color\",\n \"value\": \"#dcd3cc\"\n },\n {\n \"name\": \"color_reduction_mode\",\n \"value\": \"pixelated\"\n },\n {\n \"name\": \"base_color\",\n \"value\": \"#dda032\"\n }\n ]\n }\n ]\n}\n```\n\n
\n" } ], "paths": { "/v2/oauth-scopes": { "get": { "summary": "Retrieve OAuth scopes", "description": "This endpoint will retrieve all OAuth scopes associated with the used token", "operationId": "getOAuthScopes", "security": [ { "OAuth": [] } ], "tags": [ "OAuth Scopes v2" ], "responses": { "200": { "$ref": "#/components/responses/GetOAuthScopes" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products": { "get": { "summary": "Retrieve a list of catalog products", "description": "This endpoint retrieves a list of the products available in Printful's catalog. The list is paginated and can be filtered using various filters. The information returned includes details on how each product can be designed, such as the available placements, techniques, and additional options.\nFor a visual representation of the design data, please see the following diagram:\n[\"Design](images/catalog/design_data_diagram.png)\n", "operationId": "getProducts", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductCategoryIds" }, { "$ref": "#/components/parameters/ColorsFilter" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/NewFilter" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/PlacementsFilter" }, { "$ref": "#/components/parameters/SellingRegion" }, { "$ref": "#/components/parameters/SortDirection" }, { "$ref": "#/components/parameters/SortType" }, { "$ref": "#/components/parameters/TechniquesFilter" }, { "$ref": "#/components/parameters/DestinationCountry" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetProducts" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}": { "get": { "summary": "Retrieve a single catalog product", "description": "Returns information about a single specified catalog product. [See catalog product](#tag/Catalog-v2/What-is-a-catalog-product)\n", "operationId": "getProductById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/SellingRegion" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-variants/{id}": { "get": { "summary": "Retrieve information about specific catalog variant", "description": "Returns information about single specified catalog variant. [See catalog variant](#tag/Catalog-v2/What-is-a-catalog-variant)\n", "operationId": "getVariantById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/VariantId" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetVariantById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/catalog-variants": { "get": { "summary": "Retrieve information about catalog product variants", "description": "Returns information about all catalog variants associated with the specified\ncatalog product. [See catalog variant](#tag/Catalog-v2/What-is-a-catalog-variant)\n", "operationId": "getProductVariantsById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductVariantsById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-categories": { "get": { "tags": [ "Catalog v2" ], "summary": "Retrieve a list of catalog categories", "description": "Returns list of all categories that are present in the catalog. The categories specify the type of the product that is associated with it. For example, the category \"Men’s T-shirts\" indicates that the product is a subgroup of T-shirts specifically targeted at Men.\nCategories can be used to filter the product list by specific tags [See categories_ids](#operation/getProducts)\n", "operationId": "getCategories", "security": [ { "OAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/GetCategories" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-categories/{id}": { "get": { "summary": "Retrieve information about specific category", "description": "Returns information about a specific catalog category. The categories specify the type of the product that is associated with it. For example, the category \"Men’s T-shirts\" indicates that the product is a subgroup of T-shirts specifically targeted at Men.\nCategories can be used to filter the product list by specific tags [See categories_ids](#operation/getProducts)\n", "operationId": "getCategoryById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/CategoryId" } ], "responses": { "200": { "$ref": "#/components/responses/GetCategoryById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/catalog-categories": { "get": { "summary": "Retrieve a list of catalog product categories", "description": "To retrieve information about a particular products categories, use this feature. It returns details about the catalog categories associated with the catalog product. Categories help identify the type of product associated with them. For instance, the category \"Men's T-shirts\" denotes that the product is a subgroup of T-shirts intended for men.\n", "operationId": "getCategoriesByProductId", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/SellingRegion" } ], "responses": { "200": { "$ref": "#/components/responses/GetCategoriesByProductId" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/sizes": { "get": { "summary": "Retrieve size guide for a catalog product", "description": "Returns information about the size guide for a specific product.", "operationId": "getProductSizeGuideById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/MeasurementUnit" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductSizeGuideById" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/prices": { "get": { "summary": "Retrieve catalog product prices", "description": "\nCalculates prices for specific catalog product based on selling region and specified currency. Calculations also include Store discounts. Selling region is used to specify product production currency, that is the price that the product is natively manufactured in. Different selling regions might affect the overall price amount. Currency parameter is used only to define the currency that the prices will be displayed in.\n\nFor more information on product pricing please refer to the information provided at https://www.printful.com/pricing\n
\n

\n When developing against either API be sure to inform your customers that a placement will be included in the price of the product. If one placement is provided that placement will be included in the price, if multiple are provided the included placement will generally be the placement that comes earliest in the list of placements at `/v2/catalog-products/71` (though the discount will generally be up to the price of the first placement in that list). Certain placements come with additional service fees, such as large embroidery, this additional price will never be included even if the only placement is large embroidery.\n

\n

\n There is a minor difference in the handling of prices for placements between V1 and V2.\n In V1 the price of the first placement is always null, this is because there\n is always a placement included in the price of each product. In V2 the price of placements\n is always displayed even if it is included in the price of the product because any\n placement can be included.\n

\n
\n\nThe product pricing process begins with determining the base product price, which depends on the technique used, such as DTG, Embroidery, or DTF. The first placement is typically included in the base price unless it involves special placements like large embroidery or inside labels, which are priced separately. If additional placements are added, their prices are included in the summary cost. Furthermore, additional options, such as 3D puff embroidery or unlimited thread colors, also increase the total cost. The final price is calculated by summing up the base price, additional placement costs, and any extra option costs.\n\n
\n    flowchart TD\n    B{Technique Used} -->|DTG| C[Base Price: DTG]\n    B -->|Embroidery| D[Base Price: Embroidery]\n    B -->|DTF| E[Base Price: DTF]\n    C --> A\n    D --> A\n    E --> A\n    A[Base Product Price] --> F[First Placement Included?]\n\n\n    F -->|Yes| G[Base Price Includes First Placement]\n    F -->|No e.g., Large Embroidery, Inside Label| H[Special Placement Priced Separately]\n\n    G --> I[Additional Placements?]\n    I -->|Yes| J[Add Placement Price to Summary Cost]\n    I -->|No| K[Summary Cost = Base Price]\n\n    H --> J\n    J --> L[Additional Options?]\n    L -->|Yes, such as 3d puff or unlimited color| M[Add Option Price to Summary Cost]\n    L -->|No| K\n\n    M --> K\n
\n", "operationId": "getProductPricesById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/SellingRegionPrice" }, { "$ref": "#/components/parameters/Currency" }, { "$ref": "#/components/parameters/ProductionCurrency" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductPricesById" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-variants/{id}/prices": { "get": { "summary": "Retrieve pricing information for the catalog variant", "description": "Return pricing information from a single variant and the parent product", "operationId": "getVariantPricesById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/VariantId" }, { "$ref": "#/components/parameters/SellingRegionPrice" }, { "$ref": "#/components/parameters/Currency" }, { "$ref": "#/components/parameters/ProductionCurrency" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetVariantPricesById" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/images": { "get": { "summary": "Retrieve blank images for a catalog product", "description": "This feature helps to fetch blank images for a catalog product. These blank images are always white and semi-transparent and can be colored by the user on the client-side as per the specified color in the `data.images.background_color` field. For some mockups the `data.images.background_image` could apply. The endpoint allows filtering of the result based on the type of the mockup, the placement, and the color of the product.\n", "operationId": "getProductImagesById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/MockupStyleIds" }, { "$ref": "#/components/parameters/VariantColor" }, { "$ref": "#/components/parameters/Placement" }, { "$ref": "#/components/parameters/Locale" }, { "$ref": "#/components/parameters/LimitTwenty" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductImagesById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/shipping-countries": { "get": { "summary": "Retrieve the shipping countries for a Product", "description": "Retrieve the list of countries the Catalog Product can be shipped to.", "operationId": "getProductShippingCountriesById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetShippingCountries" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-variants/{id}/images": { "get": { "summary": "Retrieve blank images for a catalog variant", "description": "Returns images for a specified Variant.", "operationId": "getVariantImagesById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/VariantId" }, { "$ref": "#/components/parameters/MockupStyleIds" }, { "$ref": "#/components/parameters/Placement" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetVariantImagesById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/mockup-styles": { "get": { "summary": "Retrieve catalog product mockup styles", "description": "Returns information about available mockup styles for specified catalog product.\n", "operationId": "retrieveMockupStylesByProductId", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/MockupPlacementsFilter" }, { "$ref": "#/components/parameters/DefaultMockupStylesFilter" }, { "$ref": "#/components/parameters/SellingRegion" }, { "$ref": "#/components/parameters/Offset-2" }, { "$ref": "#/components/parameters/Limit-2" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetCatalogProductMockupsStyles" }, "401": { "$ref": "#/components/responses/Unauthorized-2" }, "404": { "$ref": "#/components/responses/NotFound-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/mockup-templates": { "get": { "summary": "Retrieve catalog product mockup templates", "description": "Returns positional data for specified catalog product mockups. The data from this endpoint could be used\nto generate your own mockups without the need to use Printful's mockup generator.\n![Mockup template](images/mockups/mockup_template.png)\n", "operationId": "getMockupTemplatesByProductId", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/PlacementsFilter" }, { "$ref": "#/components/parameters/SellingRegion" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetCatalogProductMockupsTemplates" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-products/{id}/availability": { "get": { "summary": "Retrieve catalog product stock availability", "description": "Provides information about the catalog product stock status. Stock availability is grouped by variants → techniques → selling regions.\n", "operationId": "getProductStockAvailabilityById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/ProductId" }, { "$ref": "#/components/parameters/TechniquesFilter" }, { "$ref": "#/components/parameters/SellingRegionAll" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetProductStockAvailabilityById" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/catalog-variants/{id}/availability": { "get": { "summary": "Retrieve catalog variant stock availability", "description": "Provides information about the catalog variant stock status. Stock availability is grouped by variants → techniques → selling regions.\n", "operationId": "getVariantStockAvailabilityById", "security": [ { "OAuth": [] } ], "tags": [ "Catalog v2" ], "parameters": [ { "$ref": "#/components/parameters/VariantId" }, { "$ref": "#/components/parameters/TechniquesFilter" }, { "$ref": "#/components/parameters/SellingRegion" }, { "$ref": "#/components/parameters/Locale" } ], "responses": { "200": { "$ref": "#/components/responses/GetVariantStockAvailabilityById" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/orders": { "get": { "summary": "Retrieve a list of orders", "description": "Retrieve a list of orders from a specific store. The order list will be paginated with twenty items per page by default.", "operationId": "getOrders", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetOrders" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create a new order", "description": "This endpoint allows the creation of a new order in which the default status will be `draft`.", "operationId": "createOrder", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/OrderInput" }, "responses": { "200": { "$ref": "#/components/responses/GetOrderById" }, "400": { "$ref": "#/components/responses/BadRequest" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/orders/{order_id}": { "get": { "summary": "Retrieve a single order", "description": "Retrieve a single order from the specified store. The result object will contain links to the same resource, order items, and shipments.", "operationId": "getOrder", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetOrderById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete an order", "description": "
\n Warning: The DELETE HTTP method in version 2 of order in the \n API will delete the order if the order can be deleted. This is distinct from \n version 1 where the DELETE method will actually cancel the order rather than \n delete it. Please, keep this in mind if you are migrating to version 2 from \n version 1\n
\n\nDelete the order if it can be deleted. An order can be deleted if it's status is\n`draft`, `failed` or `cancelled`. The order must also have not been charged yet\nand there must be no payments pending.\n", "operationId": "deleteOrder", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/OrderId" } ], "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Update an order", "description": "Make a partial update of an order.", "operationId": "updateOrder", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/OrderId" } ], "requestBody": { "$ref": "#/components/requestBodies/OrderPatchInput" }, "responses": { "200": { "$ref": "#/components/responses/GetOrderById" }, "400": { "$ref": "#/components/responses/BadRequest" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/orders/{order_id}/confirmation": { "post": { "summary": "Confirm an order", "description": "This endpoint allows customers to confirm the order and start the fulfillment in the production facility.", "operationId": "confirmOrder", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/OrderId" } ], "responses": { "200": { "$ref": "#/components/responses/ConfirmOrderById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/orders/{order_id}/order-items": { "get": { "summary": "Retrieve a list of order items", "description": "This endpoint retrieves the list of items that belong to the order.", "operationId": "getItemsByOrderId", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/Type" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetOrderItemsById" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create a new order item", "description": "This endpoint allows the creation of a new item that will be added to an existing order.", "operationId": "createItemByOrderId", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/ItemInput" }, "responses": { "200": { "$ref": "#/components/responses/GetOrderItemsById" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/orders/{order_id}/order-items/{order_item_id}": { "get": { "summary": "Retrieve a single order item", "description": "This endpoint will retrieve a single order item specified in the request.", "operationId": "getItemById", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/ItemId" }, { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetItemById" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "summary": "Update an order item", "description": "Make a partial update of an order item. NOTE that the source of the order item can't be changed via a PATCH request, to create an order item from another source you must delete the current one and add a new one.", "operationId": "updateItem", "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/ItemId" }, { "$ref": "#/components/parameters/OrderId" } ], "requestBody": { "$ref": "#/components/requestBodies/ItemPatchInput" }, "responses": { "200": { "$ref": "#/components/responses/GetOrderItemsById" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "summary": "Delete Order Item", "description": "Remove a single item from the order.", "operationId": "deleteItemById", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/ItemId" }, { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/orders/{order_id}/shipments": { "get": { "summary": "Retrieve a list of shipments", "description": "Shipments contain information about how and when your orders items will be delivered and fulfilled.", "operationId": "getShipments", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/GetShipments" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/orders/{order_id}/invoices": { "get": { "summary": "Retrieve an invoice", "description": "Returns the invoice for an order as a base64 encoded document. Decoding the base64 content can be different depending on the client, for most browsers this format will alow you to view and display the invoice `data:application/pdf;base64,{the_base_64_content_string}`.", "operationId": "getInvoiceByOrderId", "security": [ { "OAuth": [ "orders/read" ] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/OrderId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetInvoiceByOrderId" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/order-estimation-tasks": { "get": { "summary": "Retrieve an order estimation task", "description": "Retrieve an order cost estimation task from a specific store.\nEstimation results are only available for one hour after cost estimation task is done.\n", "operationId": "getOrderEstimationTask", "security": [ { "OAuth": [] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/OrderEstimationTaskId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetOrderEstimationTask" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/OrderEstimationTaskNotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "post": { "summary": "Create a new order estimation task", "description": "Use this endpoint to estimate orders with items.", "operationId": "createOrderEstimationTask", "security": [ { "OAuth": [] } ], "tags": [ "Orders v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateOrderEstimationTaskInput" }, "responses": { "200": { "$ref": "#/components/responses/CreateOrderEstimationTask" }, "400": { "$ref": "#/components/responses/BadRequest" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/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", "tags": [ "Files v2" ], "security": [ { "OAuth": [ "file-library" ] } ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/AddFile" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/File" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/files/{id}": { "get": { "summary": "Retrieve a single file from the file library", "description": "Get basic information about the file stored in the file library", "operationId": "getFileById", "tags": [ "Files v2" ], "security": [ { "OAuth": [ "file-library/read" ] } ], "parameters": [ { "$ref": "#/components/parameters/FileId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/File" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/countries": { "get": { "summary": "Retrieve a list of countries", "description": "Get information about all countries where Printful is available", "operationId": "getCountries", "tags": [ "Countries v2" ], "security": [ { "OAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Offset" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 20 }, "required": false, "description": "The number of results to return per page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/countries?limit=10&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/countries?limit=10&offset=30" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/countries?limit=10&limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/countries?limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/countries?limit=10&offset=90" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/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", "operationId": "calculateShppingRates", "security": [ { "OAuth": [ "orders" ] } ], "tags": [ "Shipping Rates v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/Locale" } ], "requestBody": { "$ref": "#/components/requestBodies/ShippingRatesInput" }, "responses": { "200": { "$ref": "#/components/responses/ShippingRatesResponse" }, "400": { "$ref": "#/components/responses/BadRequest-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/warehouse-products": { "get": { "summary": "Retrieve a list of warehouse products", "description": "This endpoint returns paginated results containing detailed information about warehouse products, including their variants, stock levels, and dimensions.", "operationId": "getWarehouseProducts", "security": [ { "OAuth": [] } ], "tags": [ "Warehouse Products v2" ], "parameters": [ { "$ref": "#/components/parameters/NameFilter" }, { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/GetWarehouseProducts" }, "401": { "$ref": "#/components/responses/Unauthorized-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/warehouse-products/{warehouse_product_id}": { "get": { "summary": "Retrieve a single warehouse product", "description": "Get information about a single warehouse product with it's stock location.", "operationId": "getWarehouseProductById", "security": [ { "OAuth": [] } ], "tags": [ "Warehouse Products v2" ], "parameters": [ { "$ref": "#/components/parameters/WarehouseProductId" }, { "$ref": "#/components/parameters/StoreId" } ], "responses": { "200": { "$ref": "#/components/responses/GetWarehouseProduct" }, "401": { "$ref": "#/components/responses/Unauthorized-2" }, "404": { "$ref": "#/components/responses/NotFound-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/mockup-tasks": { "post": { "summary": "Create Mockup Generator tasks", "description": "Create Mockup Generator tasks", "operationId": "createMockupGeneratorTasks", "security": [ { "OAuth": [] } ], "tags": [ "Mockup Generator v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateMockupGeneratorTasks" }, "responses": { "200": { "$ref": "#/components/responses/CreateMockupGeneratorTasks" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } }, "get": { "summary": "Retrieve Mockup Generator tasks", "description": "Returns result of Mockup Generator tasks", "operationId": "getMockupGeneratorTasks", "security": [ { "OAuth": [] } ], "tags": [ "Mockup Generator v2" ], "parameters": [ { "$ref": "#/components/parameters/MockupGeneratorIds" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "$ref": "#/components/responses/GetMockupGeneratorTasks" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/webhooks": { "get": { "summary": "Get webhook configuration", "description": "Returns a configured webhook URL and a list of webhook event types enabled for the store", "operationId": "getWebhooks", "security": [ { "OAuth": [ "webhooks/read" ] } ], "tags": [ "Webhook v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/ShowExpired" } ], "responses": { "200": { "$ref": "#/components/responses/WebhookInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/v2/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\nNote that only one webhook configuration can be active for each private OAuth token or app, calling this method will disable the previous webhook configuration.\n\nSetting up the [Catalog stock updated](#operation/catalogStockUpdated) webhook requires passing products (currently only IDs are taken into account).\n\nStock update webhook (`catalog_stock_updated`) will only include information for the products specified in the `products` param.\n\nConfiguring all other events require the same set of fields with no parameters.\n", "operationId": "createWebhook", "security": [ { "OAuth": [ "webhooks" ] } ], "tags": [ "Webhook v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateWebhook" }, "responses": { "200": { "$ref": "#/components/responses/WebhookCreated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/v2/webhooks' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"default_url\": \"http://www.example.com/printful/webhook\",\n \"expires_at\": \"1700000000\",\n \"events\": [\n {\n \"type\": \"shipment_sent\"\n \"url\": \"http://www.example.com/printful/webhook/shipment_sent\"\n },\n {\n \"type\": \"catalog_stock_updated\"\n \"params\": [\n {\n \"name\": \"products\",\n \"value\": [\n {\n \"id\": 5\n },\n {\n \"id\": 12\n }\n ]\n }\n ]\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 v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" } ], "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/v2/webhooks' \\\n--header 'Content-Type: application/json'" } ] } }, "/v2/webhooks/{eventType}": { "get": { "summary": "Get event configuration", "description": "Returns event configuration for store", "operationId": "getWebhookEventConfiguration", "security": [ { "OAuth": [ "webhooks/read" ] } ], "tags": [ "Webhook v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/EventType" }, { "$ref": "#/components/parameters/ShowExpired" } ], "responses": { "200": { "$ref": "#/components/responses/EventInfo" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request GET 'https://api.printful.com/v2/webhooks/shipment_sent' \\\n--header 'Authorization: Bearer {oauth_token}'" } ] }, "post": { "summary": "Set up event configuration", "description": "Use this endpoint to create or replace specific event configuration for a store.\n\nSetting up the [Catalog stock updated](#operation/catalogStockUpdated) webhook requires passing products (currently only IDs are taken into account).\n\nStock update webhook will only include information for the products specified in the `products` param.\n", "operationId": "createWebhookEventConfiguration", "security": [ { "OAuth": [ "webhooks" ] } ], "tags": [ "Webhook v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/EventType" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateWebhookEvent" }, "responses": { "200": { "$ref": "#/components/responses/EventInfo" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request POST 'https://api.printful.com/v2/webhooks/shipment_sent' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"type\": \"shipment_sent\"\n \"url\": \"http://www.example.com/printful/webhook/shipment_sent\"\n }'" } ] }, "delete": { "summary": "Disable support for event", "description": "Disables the event for a store and clears its configuration, leaving other webhooks intact.\n", "operationId": "disableWebhookEvent", "security": [ { "OAuth": [ "webhooks" ] } ], "tags": [ "Webhook v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/EventType" } ], "responses": { "204": { "$ref": "#/components/responses/NoContent" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "x-codeSamples": [ { "lang": "Curl", "source": "curl --location --request DELETE 'https://api.printful.com/v2/webhooks/shipment_sent' \\\n--header 'Content-Type: application/json'" } ] } }, "/v2/stores/{store_id}": { "get": { "summary": "Retrieve a single store", "description": "Get information about a single store.", "operationId": "getStoreById", "security": [ { "OAuth": [] } ], "tags": [ "Stores v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId-2" }, { "$ref": "#/components/parameters/StoreIdNotRequired" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StoreSchema" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized-2" }, "404": { "$ref": "#/components/responses/NotFound-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/stores": { "get": { "summary": "Retrieves a list of stores", "description": "Retrieves a list of all stores available to the token. If the token is a store level token it will return only the one store, if it is an account level token it will return all stores available to the account.", "operationId": "getStores", "security": [ { "OAuth": [] } ], "tags": [ "Stores v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreIdNotRequired" } ], "responses": { "200": { "$ref": "#/components/responses/RetrieveStoresList" }, "401": { "$ref": "#/components/responses/Unauthorized-2" }, "404": { "$ref": "#/components/responses/NotFound-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/stores/{store_id}/statistics": { "get": { "summary": "Retrieve statistics for a single store", "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/v2/stores/{id}/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": "getReports", "security": [ { "OAuth": [] } ], "tags": [ "Stores v2" ], "parameters": [ { "$ref": "#/components/parameters/PathStoreId" }, { "$ref": "#/components/parameters/DateFrom" }, { "$ref": "#/components/parameters/DateTo" }, { "$ref": "#/components/parameters/Currency-2" }, { "$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" } } } }, "/v2/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", "security": [ { "OAuth": [ "files" ] } ], "tags": [ "Approval Sheets v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/OrderId-2" }, { "$ref": "#/components/parameters/GroupHash" } ], "responses": { "200": { "$ref": "#/components/responses/GetApprovalSheets" }, "401": { "$ref": "#/components/responses/Unauthorized-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } }, "/v2/approval-sheets/{confirm_hash}/download": { "get": { "summary": "Download approval sheet PDF", "description": "This endpoint allows to programmatically download approval sheet PDF.", "operationId": "downloadApprovalSheet", "security": [ { "OAuth": [ "files" ] } ], "tags": [ "Approval Sheets v2" ], "parameters": [ { "$ref": "#/components/parameters/StoreId" }, { "$ref": "#/components/parameters/ConfirmHash" } ], "responses": { "200": { "$ref": "#/components/responses/DownloadApprovalSheetPdf" }, "401": { "$ref": "#/components/responses/Unauthorized-2" }, "5XX": { "$ref": "#/components/responses/ServerError" } } } } }, "x-webhooks": { "shipment_sent": { "post": { "summary": "Shipment sent", "operationId": "shipmentSent", "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 v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentSent" }, "responses": { "2xx": { "description": "Data received" } } } }, "shipment_delivered": { "post": { "summary": "Shipment delivered", "operationId": "shipmentDelivered", "description": "Is called when a shipment is marked as delivered.\n\nThis event is triggered when the tracking information indicates that the shipment has been successfully delivered to the recipient.\n", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentDelivered" }, "responses": { "2xx": { "description": "Data received" } } } }, "shipment_returned": { "post": { "summary": "Shipment returned", "operationId": "shipmentReturned", "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 v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentReturned" }, "responses": { "2xx": { "description": "Data received" } } } }, "shipment_out_of_stock": { "post": { "summary": "Shipment out of stock", "operationId": "shipmentOutOfStock", "security": [ { "OAuth": [] } ], "description": "Is called when a shipment goes out of stock (`is_out_of_stock = true`) or comes back in stock (`is_out_of_stock = false`).\n", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentOutOfStock" }, "responses": { "2xx": { "description": "Data received" } } } }, "shipment_canceled": { "post": { "summary": "Shipment canceled", "operationId": "shipmentCanceled", "description": "Is called when a shipment 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 or shipment is canceled by the Printful staff.", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentCanceled" }, "responses": { "2xx": { "description": "Data received" } } } }, "order_created": { "post": { "summary": "Order created", "operationId": "orderCreated", "description": "Is called when the order is first created.", "tags": [ "Webhook v2" ], "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 v2" ], "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 v2" ], "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 v2" ], "requestBody": { "$ref": "#/components/requestBodies/OrderCanceled" }, "responses": { "2xx": { "description": "Data received" } } } }, "catalog_stock_updated": { "post": { "summary": "Catalog stock updated", "operationId": "catalogStockUpdated", "description": "Is called when stock is updated for some of a product's variants.\n\n Contains information about the availability of product variants that have changed.", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/CatalogStockUpdated" }, "responses": { "2xx": { "description": "Data received" } } } }, "catalog_price_changed": { "post": { "summary": "Catalog price changed", "operationId": "catalogPriceChanged", "description": "Is called when a catalog product price has changed.\n\n This webhook is related to the pricing endpoint.", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/CatalogPriceChanged" }, "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 v2" ], "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 v2" ], "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 v2" ], "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 v2" ], "requestBody": { "$ref": "#/components/requestBodies/OrderRefunded" }, "responses": { "2xx": { "description": "Data received" } } } }, "mockup_task_finished": { "post": { "summary": "Mockup task finished", "operationId": "mockupTaskFinished", "description": "Is called when a Mockup task is finished.\n\n This doesn't necessarily mean that the task has successfully finished\n\n it could also mean that the task has failed to generate.", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/MockupTaskFinished" }, "responses": { "2xx": { "description": "Data received" } } } }, "shipment_put_hold": { "post": { "summary": "Shipment put hold", "operationId": "shipmentPutHold", "security": [], "description": "Is called when a shipment is put on hold", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentPutHold" }, "responses": { "2xx": { "description": "Data received" } } } }, "shipment_put_hold_approval": { "post": { "summary": "Shipment put hold approval", "operationId": "shipmentPutHoldApproval", "security": [], "description": "Is called when shipment is put on hold and there are changes that must be approved by the customer before fulfillment.", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentHoldApproval" }, "responses": { "2xx": { "description": "Data received" } } } }, "shipment_remove_hold": { "post": { "summary": "Shipment remove hold", "operationId": "shipmentRemoveHold", "security": [], "description": "Is called when shipment is removed from hold.", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/ShipmentRemoveHold" }, "responses": { "2xx": { "description": "Data received" } } } }, "approval_sheet_status_changed": { "post": { "summary": "Approval sheet status changed", "operationId": "approvalSheetStatusChanged", "security": [], "description": "Is called when the status of an approval sheet changes, for example when the approval sheet is approved or changes to the design are requested.", "tags": [ "Webhook v2" ], "requestBody": { "$ref": "#/components/requestBodies/ApprovalSheetStatusChanged" }, "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\ncurl -X GET 'https://api.printful.com/v2/orders' \\\n-H 'Authorization: Bearer smk_GN0I1Os3OdfqzjJnTOWn1wlbqqq2Y2Pc10TS'\n```\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", "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" } } } } }, "schemas": { "OAuthScope": { "type": "object", "title": "OAuthScope", "description": "Information about the OAuth scope", "required": [ "name", "value" ], "properties": { "name": { "description": "Display name of the scope", "type": "string", "example": "View all orders", "enum": [ "View orders of the authorized store", "View and manage orders of the authorized store", "View store products", "View and manage store products", "View store files", "View and manage store files", "View store webhooks", "View and manage store webhooks" ] }, "value": { "description": "The scope value", "type": "string", "example": "orders/read", "enum": [ "orders/read", "orders", "sync_products/read", "sync_products", "file_library/read", "file_library", "webhooks/read", "webhooks/read" ] } } }, "HateoasLink": { "type": "object", "title": "HateoasLink", "readOnly": true, "required": [ "href" ], "properties": { "href": { "description": "The HREF of the linked resource.", "type": "string" } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "format": "URL", "description": "A URL that can be followed to get to our [documentation](#section/Errors) for the problem type." }, "status": { "type": "integer", "description": "The HTTP status code." }, "title": { "type": "string", "description": "A human-readable summary of the problem type." }, "details": { "type": "string", "description": "A human-readable explanation specific to the occurrence of the problem." }, "instance": { "type": "string", "format": "URI", "description": "Optional. A URI that uniquely identifies the specific occurence of the problem" } } }, "ServerErrorDetails": { "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "type": "object", "properties": { "status": { "type": "integer", "minimum": 500, "maximum": 599 } } } ] }, "TechniqueEnum": { "type": "string", "enum": [ "dtg", "digital", "cut-sew", "uv", "embroidery", "sublimation", "dtfilm" ] }, "Techniques": { "type": "object", "title": "Technique", "description": "Information about the available Product's technique", "required": [ "key", "display_name", "is_default" ], "properties": { "key": { "description": "Technique key", "type": "string", "example": "embroidery" }, "display_name": { "description": "Technique display name", "type": "string", "example": "Embroidery" }, "is_default": { "description": "This is the default product technique", "type": "boolean", "example": true } } }, "CatalogOption": { "type": "object", "title": "CatalogOption", "description": "Catalog option definition", "required": [ "name", "techniques", "type", "values" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "3d_puff" }, "techniques": { "description": "Available techniques for option", "type": "array", "items": { "type": "string", "example": "embroidery" } }, "type": { "description": "Type of accepted value", "type": "string", "example": "boolean" }, "values": { "description": "List of available option values.", "type": "array", "example": [ true, false ] } } }, "FileLayer": { "type": "object", "required": [ "type" ], "properties": { "type": { "description": "File type layer", "type": "string", "example": "file" }, "layer_options": { "description": "Possible layer options", "type": "array", "items": { "$ref": "#/components/schemas/CatalogOption" }, "example": [ { "name": "3d_puff", "techniques": [ "embroidery" ], "type": "boolean", "values": [ true, false ] } ] } } }, "DesignPlacement": { "type": "object", "title": "DesignPlacement", "description": "Information about the product placements that can be used to specify the design placement", "required": [ "placement", "technique", "layers" ], "properties": { "placement": { "description": "Name of placement that can be used to place design in a correct spot on a product", "type": "string", "example": "back" }, "technique": { "description": "Indicates technique for which the placements are available", "type": "string", "example": "embroidery" }, "layers": { "description": "Available layers for that product", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FileLayer" } ] } }, "placement_options": { "description": "Possible placement options", "type": "array", "items": { "$ref": "#/components/schemas/CatalogOption" }, "example": [ { "name": "unlimited_color", "techniques": [ "embroidery" ], "type": "boolean", "values": [ true, false ] } ] } } }, "Product": { "type": "object", "title": "Product", "required": [ "id", "main_category_id", "type", "name", "brand", "model", "image", "variant_count", "is_discontinued", "description", "sizes", "colors", "techniques", "placements", "product_options", "_links" ], "description": "Information about the Product", "properties": { "id": { "description": "Product ID", "type": "integer", "example": 362 }, "main_category_id": { "description": "Main category of product", "type": "integer", "example": 24 }, "type": { "description": "Product type", "type": "string", "example": "T-Shirt" }, "name": { "description": "Product name", "type": "string", "example": "Unisex Organic T-Shirt | Econscious EC1000" }, "brand": { "description": "Brand name", "type": "string", "nullable": true, "example": "Econscious" }, "model": { "description": "Model name", "type": "string", "nullable": true, "example": "Unisex Organic T-Shirt" }, "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": 10 }, "is_discontinued": { "description": "Product is discontinued and can no longer be ordered", "type": "boolean", "example": false }, "description": { "description": "Product description", "type": "string" }, "sizes": { "description": "Product sizes", "type": "array", "items": { "type": "string", "example": "M" } }, "colors": { "description": "Product colors", "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Name of the color", "example": "Athletic Heather" }, "value": { "type": "string", "description": "Value of the color in HEX", "example": "#cbcbcb" } } } }, "techniques": { "description": "Product's techniques", "type": "array", "items": { "$ref": "#/components/schemas/Techniques" } }, "placements": { "description": "Product's design placements", "type": "array", "items": { "allOf": [ { "required": [ "print_area_width", "print_area_height", "placement_options", "conflicting_placements" ] }, { "$ref": "#/components/schemas/DesignPlacement" }, { "properties": { "conflicting_placements": { "description": "List of conflicting placements. Used to determine which placements can be used together.", "type": "array", "example": [ "back", "label_inside" ], "items": { "type": "string" } } } } ] } }, "product_options": { "description": "Possible product options", "type": "array", "items": { "$ref": "#/components/schemas/CatalogOption" }, "example": [ { "name": "stitch_color", "techniques": [ "cut-sew" ], "type": "string", "values": [ "White", "Black" ] } ] } } }, "ProductLinks": { "type": "object", "title": "Product links", "description": "HATEOAS links", "required": [ "self", "variants", "categories", "product_prices", "product_sizes", "product_images", "availability" ], "properties": { "self": { "description": "Link to same resource", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "variants": { "description": "Link to product variants", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "categories": { "description": "Link to product categories", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/categories" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_prices": { "description": "Link to product prices", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/prices" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_sizes": { "description": "Link product size guides", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/sizes" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_images": { "description": "Link product images", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/images" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "availability": { "description": "Link to product stock availability endpoint", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/availability" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } }, "ProductInfo": { "type": "object", "title": "Product", "description": "Information about the Catalog Product", "allOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "_links": { "$ref": "#/components/schemas/ProductLinks" } } } ] }, "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 } } }, "ProductsLinks": { "type": "object", "title": "Product links", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "type": "object", "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "type": "object", "description": "Link to next resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products?offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "type": "object", "description": "Link to first resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "type": "object", "description": "Link to the last resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products?offset=280" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } }, "Variant": { "type": "object", "title": "Variant", "required": [ "id", "catalog_product_id", "name", "size", "color", "color_code", "color_code2", "image", "_links" ], "properties": { "id": { "description": "Variant ID, use this to specify the product when creating orders", "type": "integer", "example": 100 }, "catalog_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", "nullable": true, "example": "Black" }, "color_code": { "description": "Hexadecimal RGB color code. May not exactly reflect the real-world color", "type": "string", "nullable": true, "example": "#14191e" }, "color_code2": { "description": "Secondary hexadecimal RGB color code. May not exactly reflect the real-world color", "type": "string", "nullable": true }, "placement_dimensions": { "description": "A list of placement configuration objects, each specifying the layout details for a particular placement.", "items": { "type": "object", "properties": { "placement": { "type": "string", "description": "The name or type of the placement (e.g., \"default\").", "example": "front" }, "height": { "type": "number", "description": "The height dimension for the placement (in inches).", "example": 33.11 }, "width": { "type": "number", "description": "The width dimension for the placement (in inches).", "example": 23.39 }, "orientation": { "type": "string", "description": "The orientation of the placement, such as \"vertical\", \"horizontal\" or \"any\".", "example": "any" } } } }, "image": { "description": "URL of a preview image for this variant", "type": "string", "example": "https://files.cdn.printful.com/products/12/629_1517916489.jpg" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "product_details", "product_variants", "variant_prices", "variant_images", "variant_availability" ], "properties": { "self": { "type": "object", "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_details": { "type": "object", "description": "Link to details about the product", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_variants": { "type": "object", "description": "Link to a list of all catalog variants that are siblings of this catalog variant, relating to the same catalog product", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "variant_prices": { "type": "object", "description": "Link to pricing information about this catalog variant", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/100/prices" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "variant_images": { "type": "object", "description": "Link to images related to this variant and details about those images", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/100/images" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "variant_availability": { "type": "object", "description": "Link to information about the availability of this variant", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/100/availability" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } }, "Category": { "type": "object", "title": "Category", "description": "Information about the Category", "required": [ "id", "parent_id", "image_url", "title", "_links" ], "properties": { "id": { "description": "Category ID", "type": "integer", "example": 24 }, "parent_id": { "description": "ID of the parent Category. If there is no parent Category, null is returned.", "type": "integer", "nullable": true, "example": 6 }, "image_url": { "description": "The URL of the Category image", "type": "string", "example": "https://s3-printful.stage.printful.dev/upload/catalog_category/b1/b1513c82696405fcc316fc611c57f132_t?v=1646395980" }, "title": { "description": "Category title", "type": "string", "example": "T-Shirts" }, "_links": { "description": "HATEOAS links", "type": "object", "properties": { "self": { "type": "object", "description": "Link to single category", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories/1" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } }, "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_label", "unit", "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", "unit", "description", "image_url", "image_description", "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": [ "catalog_product_id", "available_sizes", "size_tables" ], "properties": { "catalog_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-printful.stage.printful.dev/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-printful.stage.printful.dev/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-printful.stage.printful.dev/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-printful.stage.printful.dev/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" } ] } ] } ] } } }, "FileOptionPrices": { "type": "object", "title": "FileOptionPrice", "description": "Info about additional product file option prices", "required": [ "name", "type", "values", "description", "price", "retail_price" ], "properties": { "name": { "description": "Option name", "type": "string", "example": "unlimited_color" }, "type": { "description": "Option value type", "type": "string", "example": "array" }, "values": { "description": "Possible option values", "type": "array", "example": [ true, false ] }, "description": { "description": "Option description", "type": "string", "example": "Unlimited color" }, "price": { "description": "Additional price expressed in the region currency", "type": "object", "additionalProperties": { "type": "string" }, "example": { "false": "0.00", "true": "3.50" } } } }, "LayerOptionPrices": { "type": "object", "title": "ItemOptionPrice", "description": "Info about additional product item option prices", "required": [ "name", "type", "values", "description", "price", "retail_price" ], "properties": { "name": { "description": "Option name", "type": "string", "example": "3d_puff" }, "type": { "description": "Option value type", "type": "string", "example": "array" }, "values": { "description": "Possible option values", "type": "array", "example": [ true, false ] }, "description": { "description": "Option description", "type": "string", "example": "3D puff" }, "price": { "description": "Additional price expressed in the region currency", "type": "object", "additionalProperties": { "type": "string" }, "example": { "false": "0.00", "true": "1.50" } } } }, "Layers": { "type": "object", "title": "Layer", "description": "Information about the layer prices", "required": [ "type", "additional_price", "retail_additional_price", "layer_options" ], "properties": { "type": { "description": "Type of layer", "type": "string", "example": "file" }, "additional_price": { "description": "Additional price for layer", "type": "string", "example": "0.00" }, "layer_options": { "description": "Layer options prices", "type": "array", "items": { "$ref": "#/components/schemas/LayerOptionPrices" } } } }, "AdditionalPlacements": { "type": "object", "title": "AdditionalPlacement", "description": "Info about additional product placements prices.", "required": [ "id", "title", "type", "technique_key", "price", "discounted_price", "retail_price", "retail_discounted_price", "placement_options", "layers" ], "properties": { "id": { "description": "ID or key of placement", "type": "string", "example": "default" }, "title": { "description": "Title of the placement related", "type": "string", "example": "Print file" }, "type": { "description": "Placement type", "type": "string", "example": "Digital printing" }, "technique_key": { "description": "Key associated to the available technique", "type": "string", "example": "digital" }, "price": { "description": "Price converted to the region currency", "type": "string", "example": "19.75" }, "discounted_price": { "description": "Discounted price per region", "type": "string", "example": "18.75" }, "placement_options": { "description": "Array containing the pricing information about the file options used", "type": "array", "items": { "$ref": "#/components/schemas/FileOptionPrices" } }, "layers": { "description": "Array containing the pricing information about the layers.", "type": "array", "items": { "$ref": "#/components/schemas/Layers" } } } }, "VariantTechniquePrice": { "type": "object", "title": "VariantTechniquePrice", "description": "Product prices information", "required": [ "technique_key", "technique_display_name", "price", "discounted_price", "retail_price", "retail_discounted_price" ], "properties": { "technique_key": { "description": "Key associated to the technique", "type": "string", "example": "digital" }, "technique_display_name": { "description": "Full technique name", "type": "string", "example": "Digital printing" }, "price": { "description": "Price converted to the region currency", "type": "string", "example": "9.50" }, "discounted_price": { "description": "Discounted price per region", "type": "string", "example": "8.50" } } }, "VariantsPriceData": { "type": "object", "title": "VariantPriceData", "description": "Variant with the pricing information", "required": [ "id", "techniques" ], "properties": { "id": { "description": "Variant id", "type": "integer", "example": 1 }, "techniques": { "description": "Array containing pricing information about available techniques per variant", "type": "array", "items": { "$ref": "#/components/schemas/VariantTechniquePrice" } } } }, "ProductPrices": { "type": "object", "title": "ProductPrice", "description": "Product prices information", "required": [ "currency", "product", "variants" ], "properties": { "currency": { "description": "Abbreviation from the store currency or currency specified", "type": "string", "example": "EUR" }, "product": { "description": "Product related with the pricing information", "type": "object", "required": [ "id", "placements" ], "properties": { "id": { "description": "Product Identifier", "type": "integer", "example": 1 }, "placements": { "description": "Array containing the pricing information about the placement prices. The product price includes one print, pricing here only applies to each additional placement after the first. Note that while a placement might be included there is sometimes additional service fees that are applied to certain placement, for example large embroidery has an additional fee.", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalPlacements" } } } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/VariantsPriceData" } } } }, "VariantPrices": { "type": "object", "title": "VariantPrice", "description": "Variant prices information", "required": [ "currency", "product", "variant" ], "properties": { "currency": { "description": "Currency in which prices are returned", "type": "string", "example": "EUR" }, "product": { "type": "object", "properties": { "id": { "description": "Product Identifier", "type": "integer", "example": 1 }, "placements": { "description": "Array containing the pricing information about the placement prices", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalPlacements" } } } }, "variant": { "$ref": "#/components/schemas/VariantsPriceData" } } }, "VariantImage": { "type": "object", "title": "VariantImage", "required": [ "placement", "image_url", "background_color", "background_image", "mockup_style_id" ], "properties": { "placement": { "description": "Placement associated with the image", "type": "string", "example": "front" }, "image_url": { "description": "image URL", "type": "string", "nullable": true, "example": "https://printful-mockups-dev.s3.amazonaws.com/239-nl4600/medium/flat/front/05_nl4600_flat_front_base_whitebg.png?v=1666248709" }, "background_color": { "description": "Background color of an image. Null if background transparent", "type": "string", "example": "#0f0f0f" }, "background_image": { "description": "Background image of an image specified in the `image_url`. Null if no background image", "type": "string", "nullable": true, "example": "https://printful-mockups-dev.s3.amazonaws.com/239-nl4600/medium/flat/front/05_nl4600_flat_front_base_whitebg.png?v=1666248709" }, "mockup_style_id": { "description": "ID of the mockup style", "type": "integer", "example": 239 } } }, "VariantImages": { "type": "object", "title": "VariantImages", "required": [ "catalog_variant_id", "color", "primary_hex_color", "secondary_hex_color", "images" ], "properties": { "catalog_variant_id": { "description": "Variant ID", "type": "integer", "example": 4017 }, "color": { "description": "Variant color", "type": "string", "nullable": true, "example": "Turquoise" }, "primary_hex_color": { "description": "Primary variant hex color used. Use this hex color to fill the mockup.", "type": "string", "nullable": true, "example": "#15d0d2" }, "secondary_hex_color": { "description": "Secondary variant hex color used. Use this hex color to fill the mockup.", "nullable": true, "type": "string", "example": null }, "images": { "description": "Variant's images", "type": "array", "items": { "$ref": "#/components/schemas/VariantImage" } } } }, "ShippingCountry": { "type": "object", "title": "Country", "required": [ "code", "name", "states" ], "properties": { "code": { "type": "string", "description": "Country code", "example": "AU" }, "name": { "type": "string", "description": "Country name", "example": "Australia" } } }, "MockupStyles": { "type": "object", "title": "MockupStyles", "description": "Data containing information about the available mockup styles", "required": [ "placement", "display_name", "technique", "print_area_width", "print_area_height", "print_area_type", "dpi", "mockup_styles" ], "properties": { "placement": { "type": "string", "description": "Catalog product placement for which the mockup styles defined in `mockup_style_ids` could be used.", "example": "front" }, "display_name": { "type": "string", "description": "Placement display name that can be shown to end-customers.", "example": "Front print" }, "technique": { "type": "string", "description": "Technique name", "example": "dtg" }, "print_area_width": { "type": "number", "format": "float", "description": "Print area width of a placement defined in inches", "example": 5 }, "print_area_height": { "type": "number", "format": "float", "description": "Print area height of a placement defined in inches", "example": 5 }, "print_area_type": { "description": "Type of the print area.", "nullable": true, "type": "string", "enum": [ "simple", "advanced" ] }, "dpi": { "type": "integer", "description": "Print area DPI", "example": 150 }, "mockup_styles": { "type": "array", "description": "A list of available mockup styles for example:\n * On the hanger\n * On the Male/Female model\n * Flat on the table\n * etc.", "items": { "type": "object", "required": [ "id", "category_name", "view_name", "restricted_to_variants" ], "properties": { "id": { "type": "integer", "description": "Identifier of mockup style. This value is intended to be used when specifying the mockup styles during mockup generator task creation _[Create mockup generator tasks](#operation/createMockupGeneratorTasks)_.", "example": 1 }, "category_name": { "type": "string", "description": "The category name of the mockup style", "example": "Couple's" }, "view_name": { "type": "string", "description": "Display name of mockup view. View determines a point of view of the camera. E.g to the right or left to the mockup.", "example": "Front" }, "restricted_to_variants": { "type": "array", "nullable": true, "description": "A list of variants that this style is restricted to. If `null`, this means that there are no restrictions and the style can be used with all variants", "example": [ 4, 15032, 10750 ] } } } } } }, "MockupTemplates": { "type": "object", "title": "MockupTemplates", "description": "Data containing information about the available mockup templates which can be used for user-side positioning. For example for intention of generating mockups without the use of Printful's mockup generator.", "required": [ "catalog_variant_ids", "placement", "technique", "image_url", "background_url", "background_color", "template_width", "template_height", "print_area_width", "print_area_height", "print_area_top", "print_area_left", "template_positioning", "orientation" ], "properties": { "catalog_variant_ids": { "type": "array", "description": "A list of variant IDs for which the positions apply.", "items": { "type": "integer", "example": 4011 } }, "placement": { "type": "string", "description": "Catalog product placement that is used for the design.", "example": "front" }, "technique": { "type": "string", "description": "Catalog product technique that is used for the design.", "example": "dtg" }, "image_url": { "type": "string", "description": "Semi-transparent main template image URL.", "example": "https://www.printful.com/files/generator/40/11oz_template.png" }, "background_url": { "type": "string", "description": "Background image URL (optional). Used for certain mockups e.g. a wall behind hanged poster. If it's defined it is intended to be layered under the image defined in `image_url`.", "nullable": true, "example": null }, "background_color": { "type": "integer", "description": "HEX color code that should be used as a background color of `image_url`.", "nullable": true, "example": null }, "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 }, "template_positioning": { "type": "string", "enum": [ "overlay", "background" ], "description": "Should the main template image (image_url) be used as an overlay or as a background.", "example": "overlay" }, "orientation": { "type": "string", "description": "Wall art product orientation. Possible values: horizontal, vertical, any", "enum": [ "horizontal", "vertical", "any" ], "example": "any" }, "template_type": { "description": "Type of inside label used, \"native\" refers to labels that have preset information, \"custom\" are fully customizable and require the user to supply country of manufacturing origin, original garment size, and material information. \"advanced\" is for products like for products like AOP Tote. \"color_group\" for the new inside labels where there are multiple designs for the overlay.", "type": "string", "nullable": true, "enum": [ "custom", "native", "color_group", "advanced" ] }, "role": { "type": "string", "enum": [ "primary", "template", "extra", "unknown", "advanced_template" ], "description": "Mockup template role.", "example": "template" } } }, "SellingRegionStockAvailability": { "type": "object", "title": "SellingRegionStockAvailability", "required": [ "name", "availability", "placement_option_availability" ], "properties": { "name": { "description": "Name of the selling region for which the stock availability apply", "type": "string", "enum": [ "worldwide", "north_america", "canada", "europe", "spain", "latvia", "uk", "france", "germany", "australia", "japan", "new_zealand", "italy", "brazil", "southeast_asia", "republic_of_korea" ] }, "availability": { "type": "string", "description": "Availability status:\n * in stock: The product is stocked in this region and fulfillable with the specified technique\n * out of stock: Product went out of stock at the supplier in this region but is fulfillable with the specified technique\n * not fulfillable: (a) Printful does not stock this product in this region; or (b) the product is not fulfillable with the specified technique in this region\n * unknown: The exact stock status could not be determined\n", "enum": [ "in stock", "out of stock", "not fulfillable", "unknown" ] }, "placement_option_availability": { "description": "Availability of a placement options for a catalog variant in a specified selling region. If a placement option is present in this array and availability is set to true it means it is available for this product. If it is set to false it means that the placement option is available for the variant, but not currently fulfillable for the given selling region settings. If an option is not present in the array but is present as an option on the product (see: [Retrieve a single catalog product](#tag/Catalog-v2/operation/getProducts)) it means the option is always available for that product.\n", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "unlimited_color" }, "availability": { "type": "boolean", "example": true } } } } } }, "TechniqueStockAvailability": { "type": "object", "title": "TechniqueStockAvailability", "required": [ "technique", "selling_regions" ], "properties": { "technique": { "allOf": [ { "$ref": "#/components/schemas/TechniqueEnum" }, { "description": "Name of the technique for which the stock availability apply" } ] }, "selling_regions": { "description": "List of selling regions with stock availability", "type": "array", "items": { "$ref": "#/components/schemas/SellingRegionStockAvailability" } } } }, "VariantStockAvailability": { "type": "object", "title": "VariantStockAvailability", "description": "Stock availability data for a specific catalog variant", "required": [ "catalog_variant_id", "techniques", "_links" ], "properties": { "catalog_variant_id": { "description": "Catalog variant ID for which the the stock availability data apply", "type": "integer", "example": 4011 }, "techniques": { "description": "Stock availability data for specific techniques of a catalog variant", "type": "array", "items": { "$ref": "#/components/schemas/TechniqueStockAvailability" } }, "_links": { "type": "object", "description": "HATEOAS links", "properties": { "variant": { "description": "Link to the catalog variant details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/4011" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } }, "FilterSettings": { "type": "array", "title": "FilterSettings", "readOnly": true, "description": "The list of the filters that were used in the request", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Name of the filter", "example": "selling_region_name" }, "value": { "type": "string", "description": "Value of the filter", "example": "worldwide" } } } }, "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" } } }, "CalculationStatus": { "description": "If the costs are being calculated or recalculated, this will have the status `calculating`. Once finished the status will be `done`.", "type": "string", "enum": [ "done", "calculating", "failed" ], "example": "done" }, "Costs": { "type": "object", "title": "Costs", "description": "The Order costs (Printful prices)", "readOnly": true, "required": [ "calculation_status", "currency", "subtotal", "discount", "shipping", "digitization", "additional_fee", "fulfillment_fee", "retail_delivery_fee", "vat", "tax", "total" ], "properties": { "calculation_status": { "$ref": "#/components/schemas/CalculationStatus" }, "currency": { "description": "The code of the currency in which the costs are returned.", "type": "string", "nullable": true, "example": "USD" }, "subtotal": { "description": "Total cost of all items.", "type": "string", "nullable": true, "example": "14.95" }, "discount": { "description": "Discount sum.", "type": "string", "nullable": true, "example": "1.79" }, "shipping": { "description": "Shipping costs.", "type": "string", "nullable": true, "example": "4.79" }, "digitization": { "description": "Digitization costs.", "type": "string", "nullable": true, "example": "3.95" }, "additional_fee": { "description": "Additional fee for custom product.", "type": "string", "nullable": true, "example": "0.00" }, "fulfillment_fee": { "description": "Custom product fulfillment fee.", "type": "string", "nullable": true, "example": "0.00" }, "retail_delivery_fee": { "description": "Retail delivery fee.", "type": "string", "nullable": true, "example": "0.00" }, "vat": { "description": "Sum of vat (not included in the item price).", "type": "string", "nullable": true, "example": "4.60" }, "tax": { "description": "Sum of taxes (not included in the item price).", "type": "string", "nullable": true, "example": "0.00" }, "total": { "description": "Grand Total (subtotal-discount+tax+vat+shipping).", "type": "string", "nullable": true, "example": "26.50" } } }, "RetailCosts": { "type": "object", "title": "RetailCosts", "description": "The Order's retail costs", "readOnly": true, "required": [ "calculation_status", "currency", "subtotal", "discount", "shipping", "vat", "tax", "total" ], "properties": { "calculation_status": { "$ref": "#/components/schemas/CalculationStatus" }, "currency": { "description": "The code of the currency in which the retail costs are returned.", "type": "string", "example": "EUR" }, "subtotal": { "description": "Total cost of all items.", "type": "string", "nullable": true, "example": "26.55" }, "discount": { "description": "Discount sum.", "type": "string", "example": "0.00" }, "shipping": { "description": "Shipping costs.", "type": "string", "example": "4.79" }, "vat": { "description": "Sum of VAT (not included in the item price).", "type": "string", "example": "0.00" }, "tax": { "description": "Sum of taxes (not included in the item price).", "type": "string", "example": "0.00" }, "total": { "description": "Grand Total (subtotal-discount+tax+vat+shipping).", "type": "string", "nullable": true, "example": "31.34" } } }, "CatalogItemSummary": { "type": "object", "title": "CatalogItemSummary", "description": "Simplified information about the Catalog Item", "required": [ "id", "type", "source", "catalog_variant_id", "external_id", "quantity", "price", "retail_price", "currency", "retail_currency", "_links" ], "properties": { "id": { "description": "Item ID", "type": "integer", "example": 1234, "readOnly": true }, "type": { "description": "The item type", "type": "string", "example": "order_item", "enum": [ "order_item", "branding_item" ] }, "source": { "description": "Item source", "type": "string", "example": "catalog", "enum": [ "catalog" ] }, "catalog_variant_id": { "description": "Catalog Variant ID associated with the Item", "type": "integer", "example": 4011 }, "external_id": { "description": "Item user specified external ID", "type": "string", "nullable": true, "example": "123_abc" }, "quantity": { "description": "Item quantity", "type": "integer", "example": 1 }, "name": { "description": "Item custom name", "type": "string", "example": "Custom name" }, "price": { "description": "The price Printful charges for the Item", "type": "string", "example": "8.00" }, "retail_price": { "description": "Item retail price", "type": "string", "example": "10.00" }, "currency": { "description": "The price currency", "type": "string", "example": "EUR" }, "retail_currency": { "description": "The retail price currency", "type": "string", "example": "USD" }, "_links": { "type": "object", "readOnly": true, "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item", "format": "HateoasLink", "example": { "href": "/v2/orders/123/items/123" } } ] } } } } }, "WarehouseItemSummary": { "type": "object", "title": "WarehouseItemSummary", "description": "Simplified information about the Warehouse Item", "properties": { "id": { "description": "Item ID", "type": "integer", "example": 1234, "readOnly": true }, "type": { "description": "The item type", "type": "string", "example": "order_item", "enum": [ "order_item", "branding_item" ] }, "source": { "description": "Item source", "type": "string", "example": "warehouse", "enum": [ "warehouse" ] }, "warehouse_product_variant_id": { "description": "ID of warehouse product associated with the Item", "type": "integer", "example": 1123581321 }, "external_id": { "description": "Item user specified external ID", "type": "string", "nullable": true, "example": "123_abc" }, "quantity": { "description": "Item quantity", "type": "integer", "example": 1 }, "name": { "description": "Item custom name", "type": "string", "example": "Custom name" }, "price": { "description": "The price Printful charges for the Item", "type": "string", "example": "8.00" }, "retail_price": { "description": "Item retail price", "type": "string", "example": "10.00" }, "currency": { "description": "The price currency", "type": "string", "example": "EUR" }, "retail_currency": { "description": "The retail price currency", "type": "string", "example": "USD" }, "_links": { "type": "object", "readOnly": true, "description": "HATEOAS links", "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item", "format": "HateoasLink", "example": { "href": "/v2/orders/123/items/123" } } ] } } } } }, "OrderSummary": { "type": "object", "title": "OrderSummary", "description": "Order summary", "readOnly": true, "required": [ "id", "external_id", "store_id", "shipping", "status", "created_at", "updated_at", "recipient", "costs", "retail_costs", "order_items", "_links" ], "properties": { "id": { "description": "Order ID", "type": "integer", "example": 123 }, "external_id": { "description": "Order ID from the external system", "type": "string", "example": "4235234213", "nullable": true }, "store_id": { "description": "Store ID", "type": "integer", "example": 10 }, "shipping": { "description": "Shipping method. Defaults to 'STANDARD'", "type": "string", "example": "STANDARD" }, "status": { "description": "Order status:
\n**draft** - order is not submitted for fulfillment
\n**failed** - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
\n**inreview** - order is being reviewed but is still cancellable at this point
\n**pending** - order has been submitted for fulfillment
\n**canceled** - order is canceled
\n**onhold** - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
\n**inprocess** - order is being fulfilled and is no longer cancellable
\n**partial** - order is partially fulfilled (some items are shipped already, the rest will follow)
\n**fulfilled** - all items are shipped\n", "type": "string", "example": "draft" }, "created_at": { "description": "Time when the order was created", "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z" }, "updated_at": { "description": "Time when the order was updated", "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z" }, "recipient": { "description": "The recipient data.", "title": "Address", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "costs": { "$ref": "#/components/schemas/Costs" }, "retail_costs": { "$ref": "#/components/schemas/RetailCosts" }, "order_items": { "type": "array", "description": "Simplified order item list. For a full list of all items use the [Get Order Items](#operation/getItemsByOrderId) endpoint.", "items": { "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItemSummary", "warehouse": "#/components/schemas/WarehouseItemSummary" } }, "oneOf": [ { "$ref": "#/components/schemas/CatalogItemSummary" }, { "$ref": "#/components/schemas/WarehouseItemSummary" } ] } }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "order_items", "shipments" ], "properties": { "self": { "description": "Link to the order details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "order_items": { "description": "Link to all order items associated with the order", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "shipments": { "description": "Link to the shipments associated with the order", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/shipments" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } }, "ItemExternalId": { "description": "Item user specified external ID", "type": "string", "nullable": true, "example": "123_abc" }, "3dPuffOption": { "type": "object", "title": "3dPuffOption", "description": "Should thread use 3d puff technique", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "3d_puff", "enum": [ "3d_puff" ] }, "value": { "description": "Whether the 3d puff technique should be used for the layer.", "type": "boolean", "example": true } } }, "ThreadColorsOption": { "type": "object", "title": "ThreadColorsOption", "description": "Specify thread colors for embroidery technique", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "thread_colors", "enum": [ "thread_colors" ] }, "value": { "description": "Thread colors for embroidery technique", "type": "array", "items": { "type": "string", "example": "#FFFFFF" } } } }, "KnitwearOptionValue": { "description": "Option value", "type": "string", "example": "#fdfafa", "enum": [ "#090909", "#404040", "#563c33", "#d52213", "#6e5242", "#7f6a53", "#cd5e38", "#b57648", "#d1773b", "#d68785", "#c6b5a7", "#d6c6b4", "#dcd3cc", "#edd9d9", "#e2dfdc", "#fdfafa", "#999996", "#dda032", "#d1c6ae", "#eddea4", "#48542e", "#6e8c4b", "#c0c1bd", "#243f33", "#c5d1d0", "#175387", "#237d96", "#787979", "#343d55", "#4e59be", "#566e99", "#504372", "#4c1c29", "#f66274", "#eda6b4", "#ddabc8" ] }, "KnitwearYarnColor": { "type": "object", "title": "KnitwearYarnColorsOption", "description": "Used to specify the yarn colors for the whole product. These are the colors that will be used across the whole product.", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "yarn_colors", "enum": [ "yarn_colors" ] }, "value": { "description": "Option value", "type": "array", "items": { "$ref": "#/components/schemas/KnitwearOptionValue" } } } }, "LayerOptions": { "description": "List of layer options", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/3dPuffOption" }, { "$ref": "#/components/schemas/ThreadColorsOption" }, { "$ref": "#/components/schemas/KnitwearYarnColor" } ] } }, "LayerPosition": { "type": "object", "title": "LayerPosition", "description": "Information about the Layer position. If the positions are not provided then the design will be automatically centered.", "required": [ "top", "left", "width", "height" ], "properties": { "width": { "description": "Layer width in inches", "type": "number", "format": "float", "multipleOf": 0.001, "minimum": 0.3, "example": 10 }, "height": { "description": "Layer height in inches", "type": "number", "format": "float", "multipleOf": 0.001, "minimum": 0.3, "example": 10 }, "top": { "description": "Layer top position in inches", "type": "number", "format": "float", "multipleOf": 0.001, "example": 0 }, "left": { "description": "Layer left position in inches", "type": "number", "format": "float", "multipleOf": 0.001, "example": 0 } } }, "Layer": { "type": "object", "title": "Layer", "description": "Information about the Layer", "required": [ "type", "url" ], "properties": { "type": { "description": "Type of layer (e.g. file, text)", "type": "string", "example": "file" }, "url": { "description": "File image URL if layer type is file", "type": "string", "example": "​https://www.printful.com/static/images/layout/printful-logo.png" }, "layer_options": { "$ref": "#/components/schemas/LayerOptions" }, "position": { "$ref": "#/components/schemas/LayerPosition" } } }, "UnlimitedColorOption": { "type": "object", "title": "UnlimitedColorOption", "description": "Specify if the design should use unlimited color technique", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "unlimited_color", "enum": [ "unlimited_color" ] }, "value": { "description": "Whether the design should use unlimited color technique.", "type": "boolean", "example": true } } }, "InsideLabelTypeOption": { "type": "object", "title": "InsideLabelTypeOption", "description": "Specify the type of inside label", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "inside_label_type", "enum": [ "inside_label_type" ] }, "value": { "description": "Specifies type of inside label design that should be used", "type": "string", "enum": [ "native", "custom" ] } } }, "PlacementOptions": { "description": "List of placement options", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/UnlimitedColorOption" }, { "$ref": "#/components/schemas/InsideLabelTypeOption" } ] } }, "Placement": { "type": "object", "title": "Placement", "description": "A placement is used to represent the physical area in which a design will be printed, and the technique used. It includes the layers that will be printed on the placement.", "required": [ "placement", "technique", "layers", "status", "status_explanation" ], "properties": { "placement": { "description": "Name of the placement", "type": "string", "example": "front" }, "technique": { "description": "Placement's technique", "type": "string", "example": "dtg" }, "print_area_type": { "description": "Type of the print area. Defaults to simple. Advanced type might be specified only for some specific products\nfor example All-over Tote bag. In that case both sides of the product will be designed.\nAdvanced designs are often more complicated so it's advised to refer to the [mockup templates endpoint](#tag/Catalog-v2/operation/getMockupTemplatesByProductId) when using advanced designs.\nAvailable print area types for a specific product can be found in [Mockup Styles endpoint](/docs/#operation/createMockupGeneratorTasks).\n", "type": "string", "writeOnly": true, "default": "simple", "enum": [ "simple", "advanced" ] }, "layers": { "description": "Information about placement's layers", "type": "array", "items": { "$ref": "#/components/schemas/Layer" } }, "placement_options": { "$ref": "#/components/schemas/PlacementOptions" }, "status": { "type": "string", "readOnly": true, "enum": [ "ok", "failed" ], "description": "Status of the placement design" }, "status_explanation": { "type": "string", "readOnly": true, "example": "Product with ID: 656 cannot have disjointed design elements.", "description": "Reason behind failed status" } } }, "PlacementsList": { "description": "Each entry in this list represents a placement on the physical product and the design that will be printed in that location.", "type": "array", "items": { "$ref": "#/components/schemas/Placement" } }, "InsidePocketOption": { "type": "object", "title": "InsidePocketOption", "description": "Specify if inside pocket should be added to the product", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "inside_pocket", "enum": [ "inside_pocket" ] }, "value": { "description": "Whether inside pocket should be added to the product.", "type": "boolean", "example": true } } }, "StitchColorOption": { "type": "object", "title": "StitchColorOption", "description": "Specified what color should be used for stitches", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "stitch_color", "enum": [ "stitch_color" ] }, "value": { "description": "Option value", "type": "string", "example": "white" } } }, "NotesOption": { "type": "object", "title": "NotesOption", "description": "Include additional notes for fulfillment for embroidery prints", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "notes", "enum": [ "notes" ] }, "value": { "description": "Additional notes for fulfillment for embroidery prints.", "type": "string", "example": "Please make sure that top side of the print is within print area" } } }, "LifelikeOption": { "type": "object", "title": "LifelikeOption", "description": "Specifies if generated mockup should use lifelike effect", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "lifelike", "enum": [ "lifelike" ] }, "value": { "description": "Whether generated mockup should use lifelike effect.", "type": "boolean", "example": true } } }, "CustomBorderColorOption": { "type": "object", "title": "CustomBorderColorOption", "description": "Used to specify the border color of a sticker", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "custom_border_color", "enum": [ "custom_border_color" ] }, "value": { "description": "Color defined in hexadecimal format", "type": "string", "example": "#FF0000" } } }, "KnitwearBaseColor": { "type": "object", "title": "KnitwearBaseColorOption", "description": "Used to specify the base color on a knitwear product.", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "base_color", "enum": [ "base_color" ] }, "value": { "$ref": "#/components/schemas/KnitwearOptionValue" } } }, "KnitwearTrimColor": { "type": "object", "title": "KnitwearTrimColorOption", "description": "Used to specify the color of the trim on a knitwear product.", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "trim_color", "enum": [ "trim_color" ] }, "value": { "$ref": "#/components/schemas/KnitwearOptionValue" } } }, "KnitwearColorReductionMode": { "type": "object", "title": "KnitwearColorReductionMode", "description": "Used to set the color reduction mode for a knitwear product", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "color_reduction_mode", "enum": [ "color_reduction_mode" ] }, "value": { "description": "Option value", "type": "string", "enum": [ "solid", "pixelated" ], "example": "pixelated" } } }, "LicenseTypeOption": { "type": "object", "title": "LicenseTypeOption", "description": "Specifies the license types associated with the product design", "required": [ "name", "value" ], "properties": { "name": { "description": "Option identifier", "type": "string", "example": "license_type", "enum": [ "license_type" ] }, "value": { "description": "License types associated with the product design. Possible values:\n - `CLC` - Collegiate Licensing Company\n - `AFFINITY` - Affinity\n - `BR` - BR\n - `EX` - EX\n - `NCAA` - NCAA\n - `FAN` - Fan\n - `BCOMPLY` - BrandComply\n - `TAG` - Tag\n - `DLH` - DLH\n - `CORE81` - Core81\n", "type": "array", "items": { "type": "string", "enum": [ "CLC", "AFFINITY", "BR", "EX", "NCAA", "FAN", "BCOMPLY", "TAG", "DLH", "CORE81" ], "example": "NCAA" } } } }, "ProductOptions": { "description": "List of product options", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/InsidePocketOption" }, { "$ref": "#/components/schemas/StitchColorOption" }, { "$ref": "#/components/schemas/NotesOption" }, { "$ref": "#/components/schemas/LifelikeOption" }, { "$ref": "#/components/schemas/CustomBorderColorOption" }, { "$ref": "#/components/schemas/KnitwearBaseColor" }, { "$ref": "#/components/schemas/KnitwearTrimColor" }, { "$ref": "#/components/schemas/KnitwearColorReductionMode" }, { "$ref": "#/components/schemas/LicenseTypeOption" } ], "discriminator": { "propertyName": "name", "mapping": { "inside_pocket": "#/components/schemas/InsidePocketOption", "stitch_color": "#/components/schemas/StitchColorOption", "notes": "#/components/schemas/NotesOption", "lifelike": "#/components/schemas/LifelikeOption", "custom_border_color": "#/components/schemas/CustomBorderColorOption", "base_color": "#/components/schemas/KnitwearBaseColor", "trim_color": "#/components/schemas/KnitwearTrimColor", "color_reduction_mode": "#/components/schemas/KnitwearColorReductionMode", "license_type": "#/components/schemas/LicenseTypeOption" } } } }, "Item": { "type": "object", "title": "Item", "description": "Information about the Item", "properties": { "id": { "description": "Item ID", "type": "integer", "example": 1234, "readOnly": true }, "external_id": { "$ref": "#/components/schemas/ItemExternalId" }, "quantity": { "description": "Item quantity", "type": "integer", "example": 1 }, "retail_price": { "description": "Item retail price", "type": "string", "example": "10.00" }, "name": { "description": "Item custom name", "type": "string", "example": "Custom name" }, "placements": { "$ref": "#/components/schemas/PlacementsList" }, "orientation": { "description": "Orientation of the design. Applies only to the products that allow multiple orientations such as framed posters.", "type": "string", "readOnly": false, "nullable": true, "enum": [ "horizontal", "vertical", "any" ], "example": "horizontal" }, "product_options": { "$ref": "#/components/schemas/ProductOptions" }, "_links": { "type": "object", "readOnly": true, "description": "HATEOAS links", "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item", "format": "HateoasLink", "example": { "href": "/v2/orders/123/order-items/123" } } ] } } } } }, "CatalogItem": { "allOf": [ { "type": "object", "title": "Item", "description": "Information about the Item", "required": [ "placements", "catalog_variant_id", "source" ], "properties": { "source": { "description": "Catalog source", "type": "string", "enum": [ "catalog" ] }, "catalog_variant_id": { "description": "ID of catalog variant", "type": "integer", "example": 4011 } } }, { "$ref": "#/components/schemas/Item" } ] }, "ItemWithoutPlacements": { "type": "object", "title": "Item", "description": "Information about the Item", "properties": { "id": { "description": "Item ID", "type": "integer", "example": 1234, "readOnly": true }, "external_id": { "$ref": "#/components/schemas/ItemExternalId" }, "quantity": { "description": "Item quantity", "type": "integer", "example": 1 }, "retail_price": { "description": "Item retail price", "type": "string", "example": "10.00" }, "name": { "description": "Item custom name", "type": "string", "example": "Custom name" }, "_links": { "type": "object", "readOnly": true, "description": "HATEOAS links", "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item", "format": "HateoasLink", "example": { "href": "/v2/orders/123/order-items/123" } } ] } } } } }, "ProductTemplateItem": { "allOf": [ { "type": "object", "title": "Product Template Item", "description": "Information about the Product Template.", "required": [ "source", "product_template_id", "catalog_variant_id" ], "properties": { "source": { "description": "Product Template source.", "type": "string", "enum": [ "product_template" ] }, "product_template_id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "ID of Product Template. Allows external ID.", "example": "@12345" }, "catalog_variant_id": { "description": "ID of Catalog variant. Must correspond to Product Template.", "type": "integer", "example": 123 } } }, { "$ref": "#/components/schemas/ItemWithoutPlacements" } ] }, "Gift": { "type": "object", "title": "Gift", "description": "The gift subject and message", "properties": { "subject": { "type": "string", "description": "Gift message subject", "example": "To John" }, "message": { "type": "string", "description": "Gift message", "example": "Happy birthday!" } } }, "PackingSlip": { "type": "object", "title": "PackingSlip", "description": "The values for customized packing slip", "properties": { "email": { "type": "string", "description": "Customer service email", "example": "test@example.com" }, "phone": { "type": "string", "description": "Customer service phone", "example": "+48000000000" }, "message": { "type": "string", "description": "Custom packing slip message", "example": "This is a message" }, "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": "https://example.com/image.jpg" }, "store_name": { "type": "string", "description": "Store name override for the return address", "example": "A store" }, "custom_order_id": { "type": "string", "description": "Your own Order ID that will be printed instead of Printful's Order ID", "example": "11235813" } } }, "Customization": { "type": "object", "title": "Customization", "description": "The Order's customization values", "properties": { "gift": { "$ref": "#/components/schemas/Gift" }, "packing_slip": { "$ref": "#/components/schemas/PackingSlip" } } }, "RetailCosts-2": { "description": "Retail costs", "type": "object", "properties": { "currency": { "description": "The code of the currency in which the retail costs are returned.", "type": "string", "example": "EUR" }, "discount": { "description": "Discount sum.", "type": "string", "example": "123.40" }, "shipping": { "description": "Shipping costs.", "type": "string", "example": "123.40" }, "tax": { "description": "Sum of taxes (not included in the item price).", "type": "string", "example": "123.40" } } }, "AddressReadonly": { "type": "object", "title": "AddressReadonly", "description": "Information about the address", "required": [ "name", "company", "address1", "address2", "city", "state_code", "state_name", "country_code", "country_name", "zip", "phone", "email", "tax_number" ], "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" } } }, "PackingSlipReadonly": { "type": "object", "title": "PackingSlipReadonly", "description": "The values for customized packing slip", "required": [ "email", "phone", "message", "logo_url", "store_name", "custom_order_id" ], "properties": { "email": { "type": "string", "description": "Customer service email", "example": "test@example.com" }, "phone": { "type": "string", "description": "Customer service phone", "example": "+48000000000" }, "message": { "type": "string", "description": "Custom packing slip message", "example": "This is a message" }, "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": "https://example.com/image.jpg" }, "store_name": { "type": "string", "description": "Store name override for the return address", "example": "A store" }, "custom_order_id": { "type": "string", "description": "Your own Order ID that will be printed instead of Printful's Order ID", "example": "11235813" } } }, "CustomizationReadonly": { "type": "object", "title": "CustomizationReadonly", "description": "The Order's customization values", "required": [ "gift", "packing_slip" ], "properties": { "gift": { "$ref": "#/components/schemas/Gift" }, "packing_slip": { "$ref": "#/components/schemas/PackingSlipReadonly" } } }, "Order": { "type": "object", "title": "Order", "description": "Order", "readOnly": true, "required": [ "id", "external_id", "store_id", "shipping", "status", "created_at", "updated_at", "recipient", "costs", "retail_costs", "order_items", "_links" ], "properties": { "id": { "description": "Order ID", "type": "integer", "example": 123 }, "external_id": { "description": "Order ID from the external system", "type": "string", "example": "4235234213", "nullable": true }, "store_id": { "description": "Store ID", "type": "integer", "example": 10 }, "shipping": { "description": "Shipping method. Defaults to 'STANDARD'", "type": "string", "example": "STANDARD" }, "status": { "description": "Order status:
\n**draft** - order is not submitted for fulfillment
\n**failed** - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
\n**inreview** - order is being reviewed
\n**pending** - order has been submitted for fulfillment
\n**canceled** - order is canceled
\n**onhold** - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
\n**inprocess** - order is being fulfilled and is no longer cancellable
\n**partial** - order is partially fulfilled (some items are shipped already, the rest will follow)
\n**fulfilled** - all items are shipped\n", "type": "string", "example": "draft" }, "created_at": { "description": "Time when the order was created", "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z" }, "updated_at": { "description": "Time when the order was updated", "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z" }, "recipient": { "description": "The recipient data.", "title": "Address", "allOf": [ { "$ref": "#/components/schemas/AddressReadonly" } ] }, "costs": { "$ref": "#/components/schemas/Costs" }, "retail_costs": { "$ref": "#/components/schemas/RetailCosts" }, "order_items": { "type": "array", "description": "Simplified order item list. For a full list of all items use the [Get Order Items](#operation/getItemsByOrderId) endpoint.", "items": { "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItemSummary", "warehouse": "#/components/schemas/WarehouseItemSummary" } }, "oneOf": [ { "$ref": "#/components/schemas/CatalogItemSummary" }, { "$ref": "#/components/schemas/WarehouseItemSummary" } ] } }, "customization": { "$ref": "#/components/schemas/CustomizationReadonly" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "order_confirmation", "order_invoices", "order_items", "shipments" ], "properties": { "self": { "description": "Link to the order details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "order_confirmation": { "description": "Link to the order confirmation", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/confirmation" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "order_invoices": { "description": "Link to the order invoice", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/invoices" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "order_items": { "description": "Link to all order items associated with the order", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "shipments": { "description": "Link to the shipments associated with the order", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/shipments" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } }, "ItemReadonly": { "type": "object", "title": "Item", "description": "Information about the Item", "required": [ "id", "external_id", "quantity", "retail_price", "name", "placements", "product_options", "_links" ], "properties": { "id": { "description": "Item ID", "type": "integer", "example": 1234, "readOnly": true }, "external_id": { "$ref": "#/components/schemas/ItemExternalId" }, "quantity": { "description": "Item quantity", "type": "integer", "example": 1 }, "retail_price": { "description": "Item retail price", "type": "string", "example": "10.00" }, "name": { "description": "Item custom name", "type": "string", "example": "Custom name" }, "placements": { "$ref": "#/components/schemas/PlacementsList" }, "product_options": { "$ref": "#/components/schemas/ProductOptions" }, "_links": { "type": "object", "readOnly": true, "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item", "format": "HateoasLink", "example": { "href": "/v2/orders/123/order-items/123" } } ] } } } } }, "CatalogItemReadonly": { "allOf": [ { "type": "object", "title": "Item", "description": "Information about the Item", "required": [ "placements", "catalog_variant_id", "source" ], "properties": { "source": { "description": "Catalog source", "type": "string", "enum": [ "catalog" ] }, "catalog_variant_id": { "description": "ID of catalog variant", "type": "integer", "example": 4011 } } }, { "$ref": "#/components/schemas/ItemReadonly" } ] }, "ItemWithoutPlacementsReadonly": { "type": "object", "title": "Item", "description": "Information about the Item", "required": [ "id", "external_id", "quantity", "retail_price", "name", "_links" ], "properties": { "id": { "description": "Item ID", "type": "integer", "example": 1234, "readOnly": true }, "external_id": { "$ref": "#/components/schemas/ItemExternalId" }, "quantity": { "description": "Item quantity", "type": "integer", "example": 1 }, "retail_price": { "description": "Item retail price", "type": "string", "example": "10.00" }, "name": { "description": "Item custom name", "type": "string", "example": "Custom name" }, "_links": { "type": "object", "readOnly": true, "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item", "format": "HateoasLink", "example": { "href": "/v2/orders/123/order-items/123" } } ] } } } } }, "WarehouseItemReadonly": { "allOf": [ { "type": "object", "title": "Warehouse Item", "description": "Information about the Warehouse Item", "required": [ "source", "warehouse_product_variant_id" ], "properties": { "source": { "description": "Warehouse source", "type": "string", "enum": [ "warehouse" ] }, "warehouse_product_variant_id": { "description": "ID of warehouse variant", "type": "integer", "example": 1234 } } }, { "$ref": "#/components/schemas/ItemWithoutPlacementsReadonly" } ] }, "TrackingEvent": { "type": "object", "title": "Tracking Event", "properties": { "triggered_at": { "type": "string", "format": "date-time", "example": "2023-06-15T19:15:05Z" }, "description": { "type": "string", "example": "Arrived At Destination" } } }, "ShipmentItem": { "type": "object", "title": "ShipmentItem", "properties": { "id": { "type": "integer", "example": 10 }, "order_item_id": { "type": "integer", "example": 20 }, "order_item_external_id": { "type": "string", "nullable": true, "example": "item-external-id" }, "order_item_name": { "type": "string", "nullable": true, "example": "Item name" }, "quantity": { "type": "integer", "example": 1 }, "_links": { "type": "object", "properties": { "order_item": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/orders/2/order-items/20" } } } } } } }, "Shipment": { "type": "object", "title": "Shipment", "properties": { "id": { "type": "integer", "example": 1 }, "order_id": { "type": "integer", "example": 2 }, "order_external_id": { "type": "string", "nullable": true, "example": "my_custom_id_1234" }, "carrier": { "type": "string", "nullable": true, "example": "USPS", "description": "The carrier that will fulfill the shipment." }, "service": { "type": "string", "nullable": true, "example": "USPS Priority Mail", "description": "The service being used to fulfill the shipment." }, "shipment_status": { "type": "string", "enum": [ "pending", "onhold", "canceled", "packaged", "shipped", "returned", "outstock" ], "example": "canceled" }, "shipped_at": { "type": "string", "nullable": true, "format": "date-time", "example": "2023-06-15T16:35:35Z" }, "delivery_status": { "type": "string", "enum": [ "unknown", "delivered", "pre_transit", "in_transit", "out_for_delivery", "available_for_pickup", "return_to_sender", "failure", "canceled" ] }, "delivered_at": { "type": "string", "nullable": true, "format": "date-time", "example": "2023-06-15T16:35:35Z" }, "departure_address": { "type": "object", "properties": { "country_name": { "type": "string", "example": "United States" }, "country_code": { "type": "string", "example": "US" }, "state_code": { "type": "string", "example": "CA" } } }, "is_reshipment": { "type": "boolean", "description": "If there is an issue with items in a shipment, a reshipment might be necessary. This property will be false if it is the original shipment and true if it is a reshipment" }, "tracking_number": { "type": "string", "nullable": true, "example": "39925631", "description": "The tracking code associated with the shipment." }, "tracking_url": { "type": "string", "example": "​https://myorders.com/tracking/39925631" }, "tracking_events": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingEvent" } }, "estimated_delivery": { "type": "object", "nullable": true, "properties": { "from_date": { "type": "string", "format": "date", "example": "2023-06-15", "description": "Earliest estimated date the shipment will arrive" }, "to_date": { "type": "string", "format": "date", "example": "2023-06-15", "description": "Latest estimated date the shipment will arrive" }, "calculated_at": { "type": "string", "format": "date-time", "example": "2023-06-15T16:35:35Z" } } }, "shipment_items": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentItem" } }, "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/shipments/1" } } }, "order": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/orders/2" } } } } } } }, "TaskSummary": { "type": "object", "title": "OrderEstimationTaskSummary", "description": "Order estimation task summary", "readOnly": true, "required": [ "id", "status", "costs", "retail_costs", "failure_reasons" ], "properties": { "id": { "description": "Task ID", "type": "string", "example": "fc959efb-b3a0-4c12-9cc6-f54d3158291d" }, "status": { "description": "Task status", "type": "string", "enum": [ "pending", "failed", "completed" ] }, "costs": { "allOf": [ { "$ref": "#/components/schemas/Costs" }, { "type": "object", "nullable": true } ] }, "retail_costs": { "allOf": [ { "$ref": "#/components/schemas/RetailCosts" }, { "type": "object", "nullable": true } ] }, "failure_reasons": { "type": "array", "description": "Reasons why calculation failed.", "items": { "type": "string", "example": "Recipient: Country cannot be blank." }, "example": [] } } }, "EstimationAddress": { "type": "object", "title": "Estimation address", "description": "Information about the address for estimations.", "required": [ "country_code", "zip" ], "properties": { "state_code": { "description": "State code.", "type": "string", "example": "CA" }, "country_code": { "description": "Country code", "type": "string", "example": "US" }, "zip": { "description": "ZIP/Postal code", "type": "string", "example": "91311" } } }, "AddFile": { "type": "object", "title": "File", "description": "Information about the added File", "required": [ "url" ], "properties": { "role": { "type": "string", "enum": [ "printfile", "label", "preview" ], "default": "printfile", "description": "Role of the file", "example": "printfile" }, "url": { "type": "string", "description": "Source URL where the file is to be downloaded from. The use of .ai, .psd, and .tiff files has been deprecated, 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" }, "filename": { "type": "string", "description": "If the filename is not provided, and something looking like a filename is present in the URL (e.g. \"something.jpg\"), it will be used.\nOtherwise, it will default to `{file_id}.{file_extension}`, with file extension determined based on the media type of the file.\n", "example": "shirt1.png" }, "visible": { "type": "boolean", "description": "Show file in the Printfile Library", "default": true, "example": true } } }, "File": { "type": "object", "title": "File", "description": "Information about the File", "required": [ "id", "url", "hash", "filename", "mime_type", "size", "width", "height", "dpi", "status", "created", "thumbnail_url", "preview_url", "visible", "is_temporary", "_links" ], "properties": { "id": { "type": "integer", "description": "File ID", "example": 123, "readOnly": true }, "url": { "type": "string", "description": "Source URL where the file was downloaded from.", "example": "​https://www.example.com/files/tshirts/example.png" }, "hash": { "type": "string", "description": "MD5 checksum of the file", "example": "ea44330b887dfec278dbc4626a759547", "nullable": true, "readOnly": true }, "filename": { "type": "string", "description": "File name", "nullable": true, "example": "shirt1.png" }, "mime_type": { "type": "string", "description": "MIME type of the file", "example": "image/png", "nullable": true, "readOnly": true }, "size": { "type": "integer", "description": "Size in bytes", "example": 45582633, "readOnly": true }, "width": { "type": "integer", "description": "Width in pixels", "example": 1000, "nullable": true, "readOnly": true }, "height": { "type": "integer", "description": "Height in pixels", "example": 1000, "nullable": true, "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, "nullable": true, "readOnly": true }, "status": { "type": "string", "example": "ok", "enum": [ "waiting", "ok", "failed", "deleted" ], "description": "File processing status", "x-enumDescriptions": { "waiting": "File is waiting to be processed", "ok": "File processed correctly and ready to use", "failed": "File failed to process", "deleted": "File was deleted" }, "readOnly": true }, "created": { "type": "string", "description": "File creation date", "format": "date-time", "example": "2023-04-05T06:07:08Z" }, "thumbnail_url": { "type": "string", "description": "Small thumbnail URL", "example": "https://files.cdn.printful.com/files/ea4/ea44330b887dfec278dbc4626a759547_thumb.png", "nullable": true, "readOnly": true }, "preview_url": { "type": "string", "description": "Medium preview image URL", "example": "https://files.cdn.printful.com/files/ea4/ea44330b887dfec278dbc4626a759547_thumb.png", "nullable": true, "readOnly": true }, "visible": { "type": "boolean", "description": "Whether the file is shown in the Printfile Library.", "example": true }, "is_temporary": { "type": "boolean", "readOnly": true, "description": "Whether it is a temporary printfile.", "example": false }, "_links": { "type": "object", "readOnly": true, "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/files/123" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } }, "Country": { "type": "object", "title": "Country", "required": [ "code", "name", "states" ], "properties": { "code": { "type": "string", "description": "Country code", "example": "AU" }, "name": { "type": "string", "description": "Country name", "example": "Australia" }, "states": { "type": "array", "description": "This array contains all states available for a country. If states are not required or not applicable for a given country this array will be empty.", "items": { "type": "object", "title": "State", "properties": { "code": { "type": "string", "description": "State code", "example": "ACT" }, "name": { "type": "string", "description": "State name", "example": "Australian Capital Territory" } } } } } }, "ShippingRatesAddress": { "type": "object", "title": "Address", "description": "Information about the address.\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 }, "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": "Country code", "type": "string", "example": "US" }, "zip": { "description": "ZIP/Postal code", "type": "string", "example": "91311", "nullable": true } } }, "Placement-2": { "type": "object", "title": "Placement", "description": "A placement is used to represent the physical area in which a design will be printed, and the technique used.", "required": [ "placement", "technique" ], "properties": { "placement": { "description": "Name of the placement", "type": "string", "example": "front" }, "technique": { "description": "Placement's technique", "type": "string", "example": "dtg" }, "print_area_type": { "description": "Type of the print area. Defaults to simple. Advanced type might be specified only for some specific products\nfor example All-over Tote bag. In that case both sides of the product will be designed.\nAdvanced designs are often more complicated so it's advised to refer to the [mockup templates endpoint](#tag/Catalog-v2/operation/getMockupTemplatesByProductId) when using advanced designs.\nAvailable print area types for a specific product can be found in [Mockup Styles endpoint](/docs/#operation/createMockupGeneratorTasks).\n", "type": "string", "writeOnly": true, "default": "simple", "enum": [ "simple", "advanced" ] }, "placement_options": { "$ref": "#/components/schemas/PlacementOptions", "description": "Status of the placement design" } } }, "PlacementList": { "description": "Each entry in this list represents a placement on the physical product.", "type": "array", "items": { "$ref": "#/components/schemas/Placement-2" } }, "CatalogShippingRateItem": { "allOf": [ { "type": "object", "title": "Item", "required": [ "catalog_variant_id", "quantity", "source" ], "properties": { "source": { "description": "Catalog source", "type": "string", "enum": [ "catalog" ] }, "quantity": { "description": "Item quantity", "type": "integer", "minimum": 1, "maximum": 1000, "example": 1 }, "catalog_variant_id": { "description": "ID of catalog variant", "type": "integer", "example": 4011 }, "placements": { "$ref": "#/components/schemas/PlacementList" }, "product_options": { "$ref": "#/components/schemas/ProductOptions" } } } ] }, "WarehouseShippingRateItem": { "allOf": [ { "type": "object", "title": "Item", "required": [ "warehouse_variant_id", "quantity", "source" ], "properties": { "source": { "description": "Warehouse source", "type": "string", "enum": [ "catalog" ] }, "quantity": { "description": "Item quantity", "type": "integer", "minimum": 1, "maximum": 1000, "example": 1 }, "warehouse_variant_id": { "description": "ID of catalog variant", "type": "integer", "example": 4011 } } } ] }, "ShipmentItem-2": { "type": "object", "title": "ShipmentItem", "description": "Basic info about the shipment item.", "required": [ "catalog_variant_id", "quantity" ], "properties": { "catalog_variant_id": { "type": "number", "format": "integer", "description": "Catalog Variant ID of the shipment item.", "example": 4011 }, "quantity": { "description": "List of items included in the shipment.", "type": "number", "format": "integer", "example": 3 } } }, "Shipment-2": { "type": "object", "title": "Shipment", "description": "Basic info about the shipment.", "required": [ "departure_country", "shipment_items", "customs_fees_possible" ], "properties": { "departure_country": { "description": "Two-letter code (ISO 3166-1 alpha-2) associated with the departure country.", "type": "string", "example": "US", "nullable": true }, "shipment_items": { "description": "List of items included in the shipment.", "type": "array", "items": { "$ref": "#/components/schemas/ShipmentItem-2" } }, "customs_fees_possible": { "description": "Whether customs fees may be required for this shipment.", "type": "boolean" } } }, "Mockup": { "type": "object", "title": "Mockup", "description": "Result of mockup generator tasks.", "required": [ "placement", "display_name", "technique", "style_id", "mockup_url" ], "properties": { "placement": { "type": "string", "description": "Placement name for which the mockup was generated", "example": "front" }, "display_name": { "type": "string", "description": "This is a name that can be displayed to end customers.", "example": "Front Print" }, "technique": { "type": "string", "description": "Technique name for which the mockup was generated", "example": "dtg" }, "style_id": { "type": "integer", "description": "Mockup style identifier. Available mockup styles can be found under _[Retrieve catalog product mockup styles](#operation/retrieveMockupStylesByProductId)_.", "example": 1 }, "mockup_url": { "type": "string", "description": "Temporary URL to generated mockup image. Image will be removed from the hosting after a day so make sure to persist a copy if needed.", "example": "https://printful-upload.s3-accelerate.amazonaws.com/tmp/9c711aabb422cd386da3cb41735069f3/unisex-staple-t-shirt-white-front-659e8b94763bc.png" } } }, "HeaderSource": { "type": "object", "properties": { "header": { "type": "string", "description": "Name of the header which is incorrect", "example": "X-PF-Language" } } }, "ParameterSource": { "type": "object", "properties": { "parameter": { "type": "string", "description": "Name of the URL query parameter that is incorrect", "example": "limit" } } }, "PointerSource": { "type": "object", "properties": { "pointer": { "type": "string", "description": "Pointer to an invalid value in request body", "example": "/order_items/0/placements" } } }, "Error": { "type": "object", "title": "Error", "readOnly": true, "properties": { "type": { "type": "string", "description": "a URI that uniquely identifies the validation rule that failed. If it’s a URL, it should point to an explanation of the constraint in the documentation.", "example": "https://developers.printful.com/docs/v2/errors#specific-validation-error" }, "detail": { "type": "string", "description": "A human-readable explanation of the error", "example": "Parameter `xyz` was incorrect" }, "source": { "description": "Source of the value that caused the issue", "oneOf": [ { "$ref": "#/components/schemas/HeaderSource" }, { "$ref": "#/components/schemas/ParameterSource" }, { "$ref": "#/components/schemas/PointerSource" } ] }, "valid_values": { "type": "array", "description": "List of valid values that could be used instead to avoid the error", "items": { "type": "string", "example": "Front" } } } }, "MockupGeneratorTask": { "type": "object", "title": "MockupGeneratorTask", "description": "Result of mockup generator task", "required": [ "id", "status", "catalog_variant_mockups", "items", "failure_reasons", "_links" ], "properties": { "id": { "type": "integer", "description": "Unique task identifier used to check status of the task and retrieve the results once the task is ready.", "example": 597350033 }, "status": { "type": "string", "enum": [ "completed", "pending", "failed" ], "description": "Task status:\n * `completed` – Mockup Generator task was successfully processed\n * `pending` – Mockup Generator task is still being processed\n * `failed` – Mockup Generator task failed\n" }, "catalog_variant_mockups": { "type": "array", "description": "A list of mockups grouped by variant. Note that the same list of mockups can appear under multiple variants, this happens in cases where the variants have the same mockups, for example if the only difference is the size of the variant.", "items": { "type": "object", "required": [ "catalog_variant_id", "mockups" ], "properties": { "catalog_variant_id": { "type": "integer", "description": "ID of a catalog variant for which the mockup was generated.", "example": 4011 }, "mockups": { "type": "array", "description": "List of generated mockups", "items": { "$ref": "#/components/schemas/Mockup" } } } } }, "failure_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } }, "_links": { "type": "object", "description": "HATEOAS links", "readOnly": true, "required": [ "self" ], "properties": { "self": { "description": "Link to the Generator Task details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/mockup-tasks?id=597350033" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } }, "BaseMockupProduct": { "type": "object", "required": [ "source" ], "properties": { "source": { "description": "Mockup product source", "type": "string", "example": "catalog" }, "mockup_style_ids": { "type": "array", "description": "Used to specify style of mockups that should be generated.\nFor example:\n * On the hanger\n * On the Male/Female model\n * Flat on the table\n * etc.\n\nAvailable mockup styles for catalog product can be found under\n_[Retrieve catalog product mockup styles](#operation/retrieveMockupStylesByProductId)_.\n\n**Default:** Automatically set to the first available style ID.\nIf `orientation` is specified, only styles matching that orientation will be considered.\n", "items": { "type": "integer", "example": 123 } } } }, "CatalogMockupProduct": { "type": "object", "required": [ "catalog_product_id", "placements" ], "allOf": [ { "$ref": "#/components/schemas/BaseMockupProduct" }, { "properties": { "catalog_product_id": { "description": "Catalog product identifier", "type": "integer", "example": 71 }, "catalog_variant_ids": { "type": "array", "description": "List of catalog variant identifiers for which mockups will be generated.\nVariants must belong to the catalog product specified with `catalog_product_id`.\nMultiple variants of the same color do not count towards the daily number of files limit.\nMeaning that for a Red T-Shirt of (S,M) sizes we still generate only one mockup.\n\n**Default:** Automatically set to the first active variant ID associated with the given `catalog_product_id`.\n", "items": { "type": "integer", "example": 4011 } }, "orientation": { "type": "string", "enum": [ "vertical", "horizontal" ], "nullable": true, "description": "Define orientation of the product (used in case of e.g. canvas). This parameter:\n* is ignored for products without orientation\n* helps select default `mockup_style_ids` with the given orientation\n* must be compatible with any explicitly defined `mockup_style_ids`\n* should be set to enforce the same orientation for all layer coordinates, disabling automatic orientation detection based on image size\n" }, "placements": { "$ref": "#/components/schemas/PlacementsList" }, "product_options": { "$ref": "#/components/schemas/ProductOptions" } } } ] }, "TemplateMockupProduct": { "type": "object", "required": [ "source", "product_template_id" ], "allOf": [ { "$ref": "#/components/schemas/BaseMockupProduct" }, { "properties": { "source": { "description": "Mockup product source", "type": "string", "example": "template" }, "product_template_id": { "description": "Product Template identifier", "type": "integer", "example": 712152512 }, "catalog_variant_ids": { "type": "array", "description": "List of catalog variant identifiers for which mockups will be generated. Variants must be defined in the product template specified with `product_template_id`. Multiple variants of the same color do not count towards the daily number of files limit. Meaning that for a Red T-Shirt of (S,M) sizes we still generate only one mockup.", "items": { "type": "integer", "example": 12457 } }, "mockup_style_ids": { "type": "array", "description": "Used to specify style of mockups that should be generated. For example:\n * On the hanger\n * On the Male/Female model\n * Flat on the table\n * etc.\nAvailable mockup styles for catalog product can be found under _[Retrieve catalog product mockup styles](#operation/retrieveMockupStylesByProductId)_.\n", "items": { "type": "integer", "example": 123 } } } } ] }, "MockupTaskCreation": { "type": "object", "required": [ "products" ], "properties": { "format": { "type": "string", "description": "Generated file format. PNG will have a transparent background, JPG will have a smaller file size.", "enum": [ "jpg", "png" ] }, "mockup_width_px": { "type": "integer", "description": "Width of the mockup image in pixels. If not specified, the default value will be used. The default value is 1000px.\nIf the value is specified as 2000 that means that resulting mockups will be 2000x2000px.\n", "example": 1000 }, "products": { "type": "array", "items": { "type": "object", "title": "MockupProduct", "oneOf": [ { "$ref": "#/components/schemas/CatalogMockupProduct" }, { "$ref": "#/components/schemas/TemplateMockupProduct" } ], "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogMockupProduct", "product_template": "#/components/schemas/TemplateMockupProduct" } } } } } }, "Response200": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `200`", "example": 200 } } }, "EventConfigurationResponse": { "title": "EventConfiguration", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Event type.", "example": "catalog_stock_updated" }, "url": { "type": "string", "nullable": true, "description": "Webhook URL (HTTPS-only) that will receive the event notifications.", "example": "​https://www.example.com/printful/webhook" }, "params": { "type": "array", "items": { "type": "object", "title": "EventParam", "properties": { "name": { "type": "string", "description": "Param name." }, "value": { "description": "Param value." } } }, "example": [ { "name": "products", "value": [ { "id": 1 }, { "id": 71 } ] } ] } } }, "WebhookInfoResponse": { "title": "WebhookInfo", "required": [ "default_url", "expires_at", "events" ], "properties": { "default_url": { "type": "string", "nullable": true, "description": "Webhook URL (HTTPS-only) that will receive store's event notifications if no URL is set for the event.", "example": "​https://www.example.com/printful/webhook" }, "expires_at": { "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z", "nullable": true, "description": "Date-time indicating when the configuration will expire. The default value is `null` meaning it won't expire." }, "events": { "type": "array", "description": "Array of enabled webhook event configurations", "items": { "$ref": "#/components/schemas/EventConfigurationResponse" }, "example": [ { "type": "shipment_sent", "url": "​https://www.example.com/printful/webhook/shipment_sent" }, { "type": "catalog_stock_updated", "params": [ { "name": "products", "value": [ { "id": 1 }, { "id": 71 } ] } ] } ] }, "public_key": { "type": "string", "description": "Public key used to identify the specific settings.", "example": "SbF/9d/uWguI" } } }, "DefaultEventConfigurationRequest": { "title": "DefaultEventConfiguration", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Event type. The dropdown shows values required for webhook event configuration. During the setup of a new webhook\nevent please check this dropdown if the event does not require additional parameters to be set.\n", "example": "shipment_sent" }, "url": { "type": "string", "nullable": true, "description": "Webhook URL (HTTPS-only) that will receive the event notifications.", "example": "​https://www.example.com/printful/webhook" } } }, "ProductData": { "title": "ProductData", "properties": { "id": { "type": "integer", "description": "Product ID.", "example": 1 } } }, "ProductsParam": { "title": "ProductsParam", "properties": { "name": { "type": "string", "description": "Param name.", "enum": [ "products" ], "example": "products" }, "value": { "description": "Param value - list of product data.", "type": "array", "items": { "$ref": "#/components/schemas/ProductData" }, "example": [ { "id": 1 }, { "id": 71 } ] } } }, "CatalogStockUpdatedEventConfigurationRequest": { "title": "CatalogStockUpdatedEventConfiguration", "allOf": [ { "required": [ "params" ] }, { "$ref": "#/components/schemas/DefaultEventConfigurationRequest" }, { "properties": { "params": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ProductsParam" } ], "discriminator": { "propertyName": "name", "mapping": { "products": "#/components/schemas/ProductsParam" } } }, "example": [ { "name": "products", "value": [ { "id": 1 }, { "id": 71 } ] } ] } } } ] }, "EventConfigurationRequest": { "title": "EventConfiguration", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/DefaultEventConfigurationRequest" }, { "$ref": "#/components/schemas/CatalogStockUpdatedEventConfigurationRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "catalog_stock_updated": "#/components/schemas/CatalogStockUpdatedEventConfigurationRequest", "shipment_sent": "#/components/schemas/DefaultEventConfigurationRequest", "shipment_returned": "#/components/schemas/DefaultEventConfigurationRequest", "shipment_out_of_stock": "#/components/schemas/DefaultEventConfigurationRequest", "shipment_canceled": "#/components/schemas/DefaultEventConfigurationRequest", "order_created": "#/components/schemas/DefaultEventConfigurationRequest", "order_updated": "#/components/schemas/DefaultEventConfigurationRequest", "order_failed": "#/components/schemas/DefaultEventConfigurationRequest", "order_canceled": "#/components/schemas/DefaultEventConfigurationRequest", "product_synced": "#/components/schemas/DefaultEventConfigurationRequest", "product_updated": "#/components/schemas/DefaultEventConfigurationRequest", "product_deleted": "#/components/schemas/DefaultEventConfigurationRequest", "catalog_price_changed": "#/components/schemas/DefaultEventConfigurationRequest", "order_put_hold": "#/components/schemas/DefaultEventConfigurationRequest", "order_put_hold_approval": "#/components/schemas/DefaultEventConfigurationRequest", "order_remove_hold": "#/components/schemas/DefaultEventConfigurationRequest", "mockup_task_finished": "#/components/schemas/DefaultEventConfigurationRequest", "shipment_put_hold": "#/components/schemas/DefaultEventConfigurationRequest", "shipment_put_hold_approval": "#/components/schemas/DefaultEventConfigurationRequest", "shipment_remove_hold": "#/components/schemas/DefaultEventConfigurationRequest", "approval_sheet_status_changed": "#/components/schemas/DefaultEventConfigurationRequest" } } }, "WebhookInfoRequest": { "title": "WebhookInfo", "properties": { "default_url": { "type": "string", "nullable": true, "description": "Webhook URL (HTTPS-only) that will receive store's event notifications if no URL is set for the event.", "example": "​https://www.example.com/printful/webhook" }, "expires_at": { "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z", "nullable": true, "description": "Date-time indicating when the configuration should expire. The default value is `null` meaning it won't expire." }, "events": { "type": "array", "description": "Array of enabled webhook event configurations", "items": { "$ref": "#/components/schemas/EventConfigurationRequest" }, "example": [ { "type": "shipment_sent", "url": "​https://www.example.com/printful/webhook/shipment_sent" }, { "type": "catalog_stock_updated", "params": [ { "name": "products", "value": [ { "id": 1 }, { "id": 71 } ] } ] } ] } } }, "WebhookCreated": { "title": "WebhookInfo", "allOf": [ { "required": [ "secret_key" ] }, { "$ref": "#/components/schemas/WebhookInfoResponse" }, { "properties": { "secret_key": { "type": "string", "description": "A hexadecimal representation of the secret key used to generate and verify the event signature. Visible only once upon configuration set-up.", "example": "a01376f30766acf7f706cc84beb57b79f9779e4a3e79d5519b3a9069c2156807098aw1d2abb43d356e03a46e71eeb9ab4519b3774d993abde8a3fabcebeb30fe" } } } ] }, "InternalId": { "type": "integer", "description": "ID of the resource, assigned by Printful", "example": 1234 }, "StoreSchema": { "type": "object", "description": "Information about the Store", "required": [ "id", "type", "name" ], "properties": { "id": { "description": "Store ID", "type": "integer", "example": 10 }, "type": { "description": "The type of the store is a reference to the type of integration used, Shopify, Etsy, etc. If no first party integration is used, the type will be `native`.", "type": "string", "example": "native" }, "name": { "description": "The name given to the store, chosen by the user.", "type": "string", "example": "My Store" } } }, "SalesAndCosts": { "type": "array", "title": "SalesAndCostsValue", "description": "Sales and costs report", "items": { "type": "object", "required": [ "date", "sales", "fulfillment", "profit", "sales_discount", "fulfillment_discount", "sales_shipping", "fulfillment_shipping" ], "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": "string", "description": "Order retail price data. Available only if retail price fields are properly set up on the integration's side" }, "fulfillment": { "type": "string", "description": "Product fulfillment, digitization, branding, shipping costs and taxes that are charged by Printful" }, "profit": { "type": "string", "description": "The difference between Sales and Fulfillment. If retail price data is not available, profit might be negative" }, "sales_discount": { "type": "string", "description": "Any retail price discounts set up on the integration's side" }, "fulfillment_discount": { "type": "string", "description": "Any fulfillment discounts (such as the monthly discount) set up on Printful's side" }, "sales_shipping": { "type": "string", "description": "The retail shipping price that was paid by the buyer" }, "fulfillment_shipping": { "type": "string", "description": "Shipping costs that were charged by Printful" } } } }, "SalesAndCostsSummary": { "type": "array", "title": "SalesAndCostsSummaryValue", "description": "Sales and costs summary report", "required": [ "date", "order_count", "costs", "profit" ], "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": "string", "description": "Product fulfillment, digitization, branding, shipping costs and taxes that are charged by Printful" }, "profit": { "type": "string", "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", "required": [ "value", "relative_difference" ], "properties": { "value": { "type": "string", "description": "Amount paid to Printful for fulfillment and shipping." }, "relative_difference": { "type": "string", "nullable": true, "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", "required": [ "value", "relative_difference" ], "properties": { "value": { "type": "string", "description": "The difference between Sales and Fulfillment. If retail price data is not available, profit might be negative" }, "relative_difference": { "type": "string", "nullable": true, "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", "required": [ "value", "relative_difference" ], "properties": { "value": { "type": "integer", "description": "Number of unique orders for period" }, "relative_difference": { "type": "string", "nullable": true, "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", "required": [ "date", "product_amount", "digitization", "branding", "vat", "sales_tax", "shipping", "discount", "total" ], "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": "string", "description": "Product & fulfillment costs" }, "digitization": { "type": "string", "description": "Embroidery digitization costs" }, "branding": { "type": "string", "description": "Pack-in costs" }, "vat": { "type": "string", "description": "Tax amounts. If not applicable, it will be 0." }, "sales_tax": { "type": "string", "description": "Tax amounts. If not applicable, it will be 0." }, "shipping": { "type": "string", "description": "Shipping costs that were charged by Printful" }, "discount": { "type": "string", "description": "Any fulfillment discounts (such as the monthly discount) set up on Printful's side" }, "total": { "type": "string", "description": "Summary of all costs" } } } }, "CostsByProduct": { "type": "array", "title": "CostsByProductValue", "description": "Costs by product report", "items": { "type": "object", "required": [ "product_id", "product_name", "fulfillment", "sales", "quantity" ], "properties": { "product_id": { "type": "integer", "description": "Product ID. See [Catalog API](#tag/Catalog-API)." }, "product_name": { "type": "string", "description": "Product name." }, "fulfillment": { "type": "string", "description": "All fulfillment costs that are charged by Printful, excluding shipping." }, "sales": { "type": "string", "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", "required": [ "variant_id", "variant_name", "product_id", "fulfillment", "sales", "quantity" ], "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": "string", "description": "All fulfillment costs that are charged by Printful, excluding shipping." }, "sales": { "type": "string", "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", "required": [ "value", "relative_difference" ], "properties": { "value": { "type": "string", "description": "Average time it took Printful to fulfill your orders." }, "relative_difference": { "type": "string", "nullable": true, "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", "required": [ "store_id", "currency" ], "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" } } }, "ApprovalSheetStatuses": { "type": "string", "description": "Approval sheet status:
\n**waiting_for_action** - Approval sheet requires user action e.g. `Approval` or `Request changes`.
\n**approval_pending** - Intermediate status between `waiting_for_action` and `approved`. Happens when user has approved the approval sheet but the approval was not yet processed.
\n**approved** - The approval sheet has been approved.
\n**changes_requested** - User has requested minor changes to the approval sheet.
\n**files_changed** - Happens when the original design file was replaced e.g. user has changed the design. In that case the approval sheet is no longer relevant.
\n**withdrawn** - The order hold status has been lifted and the corresponding approval sheet got removed.
\n**replaced** - The approval sheet got replaced with the new suggestions.
\n**refused** - The changes to the approval sheet from the user got rejected by the customer support. Such case requires a complete design change by the user.
\n", "example": "waiting_for_action" }, "ApprovalSheet": { "type": "object", "title": "ApprovalSheet", "description": "Approval sheet", "required": [ "confirm_hash", "group_hash", "status", "submitted_design", "recommended_design", "approval_sheet", "order_id", "order_item_id", "_links" ], "properties": { "confirm_hash": { "type": "string", "description": "Confirmation hash value.", "example": "a14e51714be01f98487fcf5131727d31" }, "group_hash": { "type": "string", "description": "Common identifier used to group all approval sheets that relate to the same design.", "example": "5d41402abc4b2a76b9719d911017c592" }, "status": { "$ref": "#/components/schemas/ApprovalSheetStatuses" }, "submitted_design": { "type": "string", "description": "URL to submitted design.", "example": "https://s3.staging.printful.com/upload/approval-design/ae/ae7b3d3e965c238b3e5c1a4e15696f07_l" }, "recommended_design": { "type": "string", "description": "URL to recommended design.", "example": "https://s3.staging.printful.com/upload/approval-design/aa/aaf9e1c6b32cb7a2c04d2746108d4124_l" }, "approval_sheet": { "type": "string", "description": "URL to Approval sheet.", "example": "​https://example.com/approval-sheet.pdf" }, "pdf_download_url": { "type": "string", "description": "Link to the PDF version of approval sheet that can be programmatically downloaded.", "example": "https://api.printful.com/v2/approval-sheets/123/download" }, "order_id": { "type": "integer", "description": "Order ID.", "example": 123 }, "order_item_id": { "type": "integer", "description": "Item ID.", "example": 123 }, "placement": { "description": "Placement of the design on the product.", "type": "string", "example": "embroidery_chest_left" }, "placement_label": { "description": "Human readable label of the placement.", "type": "string", "example": "Left chest" }, "product_name": { "description": "Name of the product the design is placed on, including the variant.", "type": "string", "example": "Unisex Staple T-Shirt | Bella + Canvas 3001 (White / M)" }, "product_image_url": { "description": "URL to an image of the product.", "type": "string", "example": "https://s3-printful.stage.printful.dev/products/71/4011_1752236284.jpg" }, "variant_color": { "description": "Name of the product variant's color.", "type": "string", "example": "White" }, "variant_color_code": { "description": "Hex code of the product variant's color.", "type": "string", "example": "#ffffff" }, "original_artwork_url": { "description": "URL to the original artwork submitted by the customer.", "type": "string", "example": "https://s3-printful.stage.printful.dev/files/d82/d827a70449bfc968564db9404258cb63_preview.png" }, "thread_colors": { "description": "Thread colors recommended for the design, grouped by placement-specific thread color option.", "type": "array", "items": { "type": "object", "description": "Object keyed by a placement-specific thread color option (e.g. \"thread_colors_chest_left\"), mapping to an array of hex color codes.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": [ { "thread_colors_chest_left": [ "#FFFFFF" ] } ] }, "recommended_design_rotation": { "description": "Recommended rotation, in degrees, to apply to the design.", "type": "string", "example": "" }, "advanced_embroidery_details": { "description": "Additional details for advanced embroidery placements. Null if not applicable.", "type": "object", "nullable": true, "properties": { "digitiser_comment": { "description": "Comment left by the digitiser.", "type": "string", "example": "Some parts of the design were simplified to make them embroiderable." }, "additional_design_urls": { "description": "URLs to additional design files.", "type": "array", "items": { "type": "string" }, "example": [ "https://s3-printful.stage.printful.dev/files/d82/d827a70449bfc968564db9404258cb63_preview.png" ] }, "is_unlimited_color": { "description": "Whether the design uses unlimited thread colors.", "type": "boolean", "example": false } } }, "related_pending_approval_sheet_count": { "description": "Number of other approval sheets for the same design that are still waiting for action.", "type": "integer", "example": 0 }, "created_at": { "description": "Time when the approval sheet was created.", "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z" }, "updated_at": { "description": "Time when the approval sheet was last updated.", "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z" }, "issues": { "description": "List of issues detected with the submitted design.", "type": "array", "items": { "type": "object", "properties": { "code": { "description": "Issue code.", "type": "integer", "example": 1 }, "topic": { "description": "Topic the issue relates to.", "type": "string", "example": "Thread color changes" }, "description": { "description": "Description of the issue.", "type": "string", "example": "Some embroidery thread colors changed from the graphic you submitted. Too many thread colors were chosen for the graphic, and/or some of the colors can't be traced for embroidery." } } }, "example": [] }, "recommended_options": { "description": "Recommended option changes for the item. May be returned as null when there are no recommended changes.", "type": "object", "properties": { "thread_colors": { "description": "Recommended thread colors.", "type": "array", "items": { "type": "string" }, "example": [ "#FFFFFF", "#CC3333" ] }, "embroidery_type": { "description": "Recommended embroidery type.", "type": "string", "example": "flat" } }, "additionalProperties": true }, "item_options": { "description": "Options selected for the order item, such as thread colors used for embroidery. Additional placement-specific thread color options (e.g. \"thread_colors_\", \"text_thread_colors_\") may be present depending on the product's placements.", "type": "object", "properties": { "lifelike": { "description": "Whether lifelike embroidery is enabled.", "type": "boolean", "example": false }, "embroidery_type": { "description": "Type of embroidery selected.", "type": "string", "example": "flat" }, "thread_colors": { "description": "Thread colors selected for the design.", "type": "array", "items": { "type": "string" }, "example": [] }, "text_thread_colors": { "description": "Thread colors selected for embroidered text.", "type": "array", "items": { "type": "string" }, "example": [] }, "thread_colors_3d": { "description": "Thread colors selected for 3D puff embroidery.", "type": "array", "items": { "type": "string" }, "example": [] } }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "_links": { "type": "object", "title": "Approval sheet links", "description": "HATEOAS links", "required": [ "order", "order_item" ], "properties": { "order": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order." }, { "properties": { "href": { "example": "/v2/orders/123" } } } ] }, "order_item": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item." }, { "properties": { "href": { "example": "/v2/orders/123/order-items/123" } } } ] }, "approval_sheets": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Download link to approval sheet PDF." }, { "properties": { "href": { "example": "/v2/approval-sheets/123/download" } } } ] } } } } }, "Webhook": { "required": [ "type", "occurred_at", "retries", "store_id" ], "properties": { "type": { "type": "string", "description": "Event type" }, "occurred_at": { "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z", "description": "Event time" }, "retries": { "type": "integer", "description": "Number of previous attempts to deliver this webhook event", "example": 2 }, "store_id": { "type": "integer", "description": "ID of the store that the event occurred to", "example": 12 } } }, "WebhookShipmentData": { "title": "WebhookShipmentData", "required": [ "id", "status", "store_id", "tracking_number", "tracking_url", "created_at", "ship_date", "shipped_at", "delivered_at", "reshipment" ], "properties": { "id": { "type": "integer", "description": "Shipment's ID" }, "status": { "type": "string", "description": "Shipment's status" }, "store_id": { "type": "integer", "description": "ID of the store associated with the shipment" }, "tracking_number": { "type": "string", "description": "The tracking code associated with the shipment" }, "tracking_url": { "type": "string", "description": "Shipment tracking URL", "example": "​https://www.fedex.com/fedextrack/?tracknumbers=0000000000" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z", "description": "Shipment creation date-time" }, "ship_date": { "type": "string", "description": "Ship date (`Y-m-d`)", "example": "2023-03-21" }, "shipped_at": { "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z", "description": "Date-time of when the shipment was sent" }, "delivered_at": { "type": "string", "format": "date-time", "example": "2023-04-07T14:30:15Z", "description": "Date-time of when the shipment was delivered", "nullable": true }, "reshipment": { "type": "boolean", "description": "Whether this is a reshipment", "example": false } } }, "WebhookOrderData": { "title": "WebhookOrderData", "required": [ "id", "external_id", "status", "store_id", "dashboard_url", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Order's ID" }, "external_id": { "type": "string", "description": "Order's External ID" }, "status": { "type": "string", "description": "Order's status" }, "store_id": { "type": "integer", "description": "ID of the store associated with the order" }, "dashboard_url": { "type": "string", "description": "The URL to view the order in Printful dashboard" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z", "description": "Order creation date-time" }, "updated_at": { "type": "string", "format": "date-time", "example": "2023-04-05T06:07:08Z", "description": "Latest order's update date-time" } } }, "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": { "GetOAuthScopes": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthScope" } }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "description": "Link to the order details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/oauth-scopes" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "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." } } } } } } } }, "ServerError": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorDetails" }, "examples": { "InternalServerError": { "$ref": "#/components/examples/InternalServerError" } } } } }, "GetProducts": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductInfo" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "$ref": "#/components/schemas/ProductsLinks" } } } } } }, "GetProductById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProductInfo" } } } } } }, "GetVariantById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "type": "object", "title": "VariantInfo", "$ref": "#/components/schemas/Variant" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "product_variants", "product_details", "variant_prices", "variant_images" ], "properties": { "self": { "type": "object", "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_variants": { "description": "Link all variants associated with this variants product", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_details": { "description": "Link product data associated with this variant", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "variant_prices": { "description": "Link to variant prices", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/4011/prices" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "variant_images": { "description": "Link to variant images", "type": "object", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variant/4011/images" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetProductVariantsById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "title": "Variant", "items": { "$ref": "#/components/schemas/Variant" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "product_details" ], "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants?limit=20&offset=40" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants?limit=20&offset=60" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants?limit=20&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants?limit=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-variants?limit=20&offset=100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_details": { "description": "Link to the product details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetCategories": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "_links": { "description": "HATEOAS links", "type": "object", "required": [ "self", "first", "last" ], "properties": { "self": { "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories?limit=20&offset=0" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories?limit=20&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories?limit=20&offset=40" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories?limit=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories?limit=20&offset=90" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetCategoryById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "$ref": "#/components/schemas/Category" }, "_links": { "description": "HATEOAS links", "type": "object", "required": [ "all_categories" ], "properties": { "all_categories": { "type": "object", "description": "Link to all catalog categories", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetCategoriesByProductId": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "description": "HATEOAS links", "type": "object", "required": [ "self", "all_categories" ], "properties": { "self": { "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-categories?limit=20&offset=40" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-categories?limit=20&offset=60" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-categories?limit=20&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-categories?limit=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/catalog-categories?limit=20&offset=100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "all_categories": { "type": "object", "description": "Link to all catalog categories", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-categories" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetProductSizeGuideById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "$ref": "#/components/schemas/ProductSizeGuide" }, "_links": { "description": "HATEOAS links", "type": "object", "required": [ "self", "product_details" ], "properties": { "self": { "type": "object", "description": "Link to same resource", "example": { "href": "https://api.printful.com/v2/catalog-products/71/sizes" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_details": { "type": "object", "description": "Link to the catalog product", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "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" } } } } } } } }, "GetProductPricesById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "$ref": "#/components/schemas/ProductPrices" }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "description": "HATEOAS links", "type": "object", "required": [ "self", "product_details" ], "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/prices?limit=10&offset=0" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/prices?limit=10&offset=30" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/prices?limit=10&offset=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/prices?limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/prices?limit=10&offset=90" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_details": { "description": "Link to product details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetVariantPricesById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "$ref": "#/components/schemas/VariantPrices" }, "_links": { "description": "HATEOAS links", "type": "object", "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/4011/prices" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_prices": { "description": "Link to product prices", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/prices" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product_details": { "description": "Link to product details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetProductImagesById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VariantImages" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "product_details" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ], "description": "Link to same resource", "example": { "href": "https://api.printful.com/v2/catalog/products/71/images" } }, "product_details": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to product details", "example": { "href": "https://api.printful.com/v2/catalog-products/71" } } ] } } } } } } } }, "GetShippingCountries": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingCountry" } } } } } } }, "GetVariantImagesById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VariantImages" } }, "_links": { "type": "object", "description": "HATEOAS links", "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to the same resource", "example": { "href": "https://api.printful.com/v2/catalog-variants/4017/images" } } ] }, "variant_details": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to variant details", "example": { "href": "https://api.printful.com/v2/catalog-variants/4011" } } ] } } } } } } } }, "GetCatalogProductMockupsStyles": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MockupStyles" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-styles?limit=20&offset=40" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-styles?limit=20&offset=60" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-styles?limit=20&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-styles?limit=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-styles?limit=20&offset=100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product": { "description": "Link to the Catalog Product", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "Unauthorized-2": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "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" } } } } } } } }, "NotFound-2": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Actual error message", "example": "Not found" }, "error": { "type": "object", "properties": { "reason": { "type": "string", "example": "NotFound" }, "message": { "type": "string", "example": "Not found" } } } } } } } }, "GetCatalogProductMockupsTemplates": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MockupTemplates" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-templates?limit=20&offset=40" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-templates?limit=20&offset=60" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-templates?limit=20&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-templates?limit=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71/mockup-templates?limit=20&offset=100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product": { "description": "Link to the Catalog Product", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-products/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetProductStockAvailabilityById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "filter_settings", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VariantStockAvailability" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "filter_settings": { "$ref": "#/components/schemas/FilterSettings" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "product" ], "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-product/71/availability?limit=20&offset=40" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-product/71/availability?limit=20&offset=60" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-product/71/availability?limit=20&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-product/71/availability?limit=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-product/71/availability?limit=20&offset=100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "product": { "description": "Link to the catalog product details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-product/71" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "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" } } } } } } } }, "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!." } } } } } } } }, "GetVariantStockAvailabilityById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "filter_settings", "_links" ], "properties": { "data": { "$ref": "#/components/schemas/VariantStockAvailability" }, "filter_settings": { "$ref": "#/components/schemas/FilterSettings" }, "_links": { "type": "object", "description": "HATEOAS links", "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/4011/availability" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "variant": { "description": "Link to the catalog variant details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/catalog-variants/4011" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetOrders": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSummary" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders?limit=10&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders?limit=10&offset=30" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders?limit=10&limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders?limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders?limit=10&offset=90" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetOrderById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "NoContent": { "description": "No Content" }, "Conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "description": "Response status code `409`", "example": 409 }, "result": { "type": "string", "description": "An error message describing a conflict between the request and the current state of the resource.", "example": "Attempting to update a resource that is already being updated. Please try again after the previous update has completed" }, "error": { "type": "object", "properties": { "reason": { "type": "integer", "example": 409 }, "message": { "type": "string", "example": "Attempting to update a resource that is already being updated. Please try again after the previous update has completed" } } } } } } } }, "ConfirmOrderById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "order", "order_items", "shipments" ], "properties": { "self": { "description": "Link to the order details", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/confirmation" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "order": { "description": "Link to order", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "order_items": { "description": "Link to all order items associated with the order", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "shipments": { "description": "Link to the shipments associated with the order", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/shipments" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetOrderItemsById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/CatalogItemReadonly" }, { "$ref": "#/components/schemas/WarehouseItemReadonly" }, { "$ref": "#/components/schemas/ProductTemplateItem" } ], "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItemReadonly", "warehouse": "#/components/schemas/WarehouseItemReadonly", "product_template": "#/components/schemas/ProductTemplateItem" } } } }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "order" ], "properties": { "self": { "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items?limit=10&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items?limit=10&offset=30" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items?limit=10&limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items?limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items?limit=10&offset=90" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "order": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to the order", "format": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123" } } ] } } } } } } } }, "GetItemById": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItemReadonly", "warehouse": "#/components/schemas/WarehouseItemReadonly", "product_template": "#/components/schemas/ProductTemplateItem" } }, "oneOf": [ { "$ref": "#/components/schemas/CatalogItemReadonly" }, { "$ref": "#/components/schemas/WarehouseItemReadonly" }, { "$ref": "#/components/schemas/ProductTemplateItem" } ] }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "order", "all_items", "shipments" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order item", "format": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items/123" } } ] }, "order": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order", "format": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123" } } ] }, "all_items": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to all items associated with the order", "format": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-items" } } ] }, "shipments": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to all shipments associated with the order", "format": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/order-shipments" } } ] } } } } } } } }, "GetShipments": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } }, "_links": { "type": "object", "required": [ "self" ], "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/orders/123/shipments?limit=20&offset=0" } } }, "next": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/orders/123/shipments?limit=20&offset=20" } } }, "previous": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/orders/123/shipments?limit=20&offset=0" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/orders/123/shipments?limit=20&offset=0" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/orders/123/shipments?limit=20&offset=20" } } } } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "GetInvoiceByOrderId": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "media_type", "content", "_links" ], "properties": { "media_type": { "type": "string", "example": "application/pdf", "description": "This property is used to describe the media type of the encoded base64 value. It is necessary to use this property when decoding the content property." }, "content": { "type": "string", "example": "0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL01lZG", "description": "The base64 encoded document containing the invoice." }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self", "order" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to an order invoice", "format": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123/invoices" } } ] }, "order": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" }, { "description": "Link to a specific order", "format": "HateoasLink", "example": { "href": "https://api.printful.com/v2/orders/123" } } ] } } } } } } } } } }, "GetOrderEstimationTask": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TaskSummary" }, { "type": "object", "properties": { "status": { "example": "completed" } } } ] } } } } } }, "OrderEstimationTaskNotFound": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "error" ], "properties": { "data": { "type": "string", "description": "Actual error message", "example": "Couldn't find order estimation with this UUID." }, "error": { "type": "object", "required": [ "reason", "message" ], "properties": { "reason": { "type": "string", "example": "NotFound" }, "message": { "type": "string", "example": "Couldn't find order estimation with this UUID." } } } } } } } }, "CreateOrderEstimationTask": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TaskSummary" }, { "type": "object", "properties": { "costs": { "example": null }, "retail_costs": { "example": null } } } ] } } } } } }, "ShippingRatesResponse": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "required": [ "shipping", "shipping_method_name", "rate", "currency", "shipments" ], "type": "object", "properties": { "shipping": { "type": "string", "description": "Shipping method ID", "example": "STANDARD" }, "shipping_method_name": { "type": "string", "description": "A descriptive name of the shipping method including an estimate that can be displayed to customers", "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" }, "min_delivery_days": { "type": "integer", "description": "Estimated minimum delivery days. Warning! This value may not be present in response.", "example": 4 }, "max_delivery_days": { "type": "integer", "description": "Estimated maximum delivery days. Warning! This value may not be present in response.", "example": 7 }, "min_delivery_date": { "type": "string", "format": "date", "description": "Estimated minimum delivery date. Warning! This value may not be present in response.", "example": "2022-10-17" }, "max_delivery_date": { "type": "string", "format": "date", "description": "Estimated maximum delivery date. Warning! This value may not be present in response.", "example": "2022-10-20" }, "shipments": { "type": "array", "description": "List of shipments.", "items": { "$ref": "#/components/schemas/Shipment-2" } } } } } } } } } }, "BadRequest-2": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "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" } } } } } } } }, "GetWarehouseProducts": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "status", "currency", "image_url", "retail_price", "warehouse_variants", "_links" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the warehouse product", "example": 356 }, "name": { "type": "string", "description": "Name of the warehouse product", "example": "Black Heather" }, "status": { "type": "string", "enum": [ "draft", "awaiting_approval", "approved", "declined", "suspended" ], "description": "Current status of the warehouse product" }, "currency": { "type": "string", "description": "Currency code for the product's pricing (e.g., \"USD\")", "example": "USD" }, "image_url": { "type": "string", "description": "URL of the product's image", "example": "https://example.com/upload/product-templates/d1/d1341a6efb49f59cc58172ce1c15eb20_l" }, "retail_price": { "type": "string", "description": "Retail price of the product (base variant)", "example": 21.54 }, "warehouse_variants": { "type": "array", "description": "Array of variant details for the product", "items": { "type": "object", "required": [ "id", "name", "sku", "image_url", "retail_price", "quantity", "dimensions", "_links" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the variant", "example": 32453 }, "name": { "type": "string", "description": "Name of the variant", "example": "Black Heather" }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU) of the variant", "example": "some-sku-12" }, "image_url": { "type": "string", "description": "URL of the variant's image", "example": "url.to/your/image/location.png" }, "retail_price": { "type": "string", "description": "Retail price of the variant", "example": 32.56 }, "quantity": { "type": "integer", "description": "Available quantity of the variant", "example": 23 }, "dimensions": { "type": "object", "description": "Dimensions of the variant", "required": [ "width", "height", "weight", "measurement_system", "length" ], "properties": { "measurement_system": { "type": "string", "description": "The system of measurement used for the dimensions.", "enum": [ "imperial", "metric" ] }, "width": { "type": "number", "description": "Width of the variant.", "example": 3.21 }, "height": { "type": "number", "description": "Height of the variant.", "example": 4.56 }, "length": { "type": "number", "description": "Length of the variant. (NEW)", "example": 6.53 }, "weight": { "type": "number", "description": "Weight of the variant.", "example": 3 } } }, "_links": { "type": "object", "properties": { "self": { "type": "object", "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-variants/5678" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } }, "_links": { "type": "object", "description": "Links to related resources", "properties": { "self": { "type": "object", "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products/1234" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "warehouse_variants": { "type": "object", "description": "Link to warehouse variants of the warehouse product", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products/1234/warehouse-variants" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "properties": { "self": { "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products?limit=10&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products?limit=10&offset=30" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products?limit=10&limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products?limit=10" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products?limit=10&offset=90" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "GetWarehouseProduct": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "_links" ], "properties": { "data": { "type": "object", "required": [ "id", "name", "status", "currency", "image_url", "retail_price", "warehouse_variants", "_links" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the warehouse product", "example": 356 }, "name": { "type": "string", "description": "Name of the warehouse product", "example": "Black Heather" }, "status": { "type": "string", "enum": [ "draft", "awaiting_approval", "approved", "declined", "suspended" ], "description": "Current status of the warehouse product" }, "currency": { "type": "string", "description": "Currency code for the product's pricing (e.g., \"USD\")", "example": "USD" }, "image_url": { "type": "string", "description": "URL of the product's image", "example": "https://example.com/upload/product-templates/d1/d1341a6efb49f59cc58172ce1c15eb20_l" }, "retail_price": { "type": "string", "description": "Retail price of the product (base variant)", "example": 21.54 }, "warehouse_variants": { "type": "array", "description": "Array of variant details for the product", "items": { "type": "object", "required": [ "id", "name", "sku", "image_url", "retail_price", "quantity", "stock_location", "dimensions", "_links" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the warehouse variant", "example": 32453 }, "name": { "type": "string", "description": "Name of the variant", "example": "Black Heather" }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU) of the warehouse variant", "example": "some-sku-12" }, "image_url": { "type": "string", "description": "URL of the variant's image", "example": "url.to/your/image/location.png" }, "retail_price": { "type": "string", "description": "Retail price of the variant", "example": 32.56 }, "quantity": { "type": "integer", "description": "Available quantity of the variant", "example": 23 }, "stock_location": { "type": "array", "description": "Stock location of the variant", "items": { "type": "object", "required": [ "facility", "stocked", "available" ], "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 } } } }, "dimensions": { "type": "object", "description": "Dimensions of the variant", "required": [ "width", "height", "weight", "measurement_system", "length" ], "properties": { "measurement_system": { "type": "string", "description": "The system of measurement used for the dimensions.", "enum": [ "imperial", "metric" ] }, "width": { "type": "number", "description": "Width of the variant.", "example": 3.21 }, "height": { "type": "number", "description": "Height of the variant.", "example": 4.56 }, "length": { "type": "number", "description": "Length of the variant. (NEW)", "example": 6.53 }, "weight": { "type": "number", "description": "Weight of the variant.", "example": 3 } } }, "_links": { "type": "object", "properties": { "self": { "type": "object", "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-variants/5678" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } }, "_links": { "type": "object", "description": "Links to related resources", "properties": { "self": { "type": "object", "description": "Link to same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products/1234" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "warehouse_variants": { "type": "object", "description": "Link to warehouse variants of the warehouse product", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/warehouse-products/1234/warehouse-variants" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } } } }, "GetMockupGeneratorTasks": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "paging", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MockupGeneratorTask" } }, "paging": { "$ref": "#/components/schemas/Paging" }, "_links": { "type": "object", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "description": "Link to the same resource", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/mockup-tasks?id=1,2,3,4,5,6,7,8,9,10&limit=5" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "next": { "description": "Link to the next page (absent if the current page is the last one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/mockup-tasks?limit=5&offset=60" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "previous": { "description": "Link to the previous page (absent if the current page is the first one or if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/mockup-tasks?limit=5&offset=20" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "first": { "description": "Link to the first page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/mockup-tasks?limit=5" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] }, "last": { "description": "Link to the last page (absent if there is only one page)", "title": "HateoasLink", "example": { "href": "https://api.printful.com/v2/mockup-tasks?limit=5&offset=100" }, "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ] } } } } } } } }, "CreateMockupGeneratorTasks": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MockupGeneratorTask" } } } } } } }, "WebhookInfo": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/WebhookInfoResponse" } } } ] } } } }, "WebhookCreated": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/WebhookCreated" } } } ] } } } }, "EventInfo": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Response200" }, { "properties": { "result": { "$ref": "#/components/schemas/EventConfigurationResponse" } } } ] } } } }, "RetrieveStoresList": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links", "paging" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreSchema" } }, "_links": { "type": "object", "required": [ "self" ], "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/stores?limit=20&offset=0" } } }, "next": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/stores?limit=20&offset=20" } } }, "previous": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/stores?limit=20&offset=0" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/stores?limit=20&offset=0" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "example": "​https://api.printful.com/v2/stores?limit=20&offset=20" } } } } }, "paging": { "$ref": "#/components/schemas/Paging" } } } } } }, "Statistics": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/StoreStatistics" } } } } } }, "GetApprovalSheets": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "data", "_links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalSheet" } }, "_links": { "type": "object", "title": "Approval sheet links", "description": "HATEOAS links", "required": [ "self" ], "properties": { "self": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ], "description": "Link to the same resource", "example": { "href": "https://api.printful.com/v2/approval-sheets?limit=10&offset=20" } }, "next": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ], "description": "Link to the next page (absent if the current page is the last one or if there is only one page).", "example": { "href": "https://api.printful.com/v2/approval-sheets?limit=10&offset=30" } }, "previous": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ], "description": "Link to the previous page (absent if the current page is the first one or if there is only one page).", "example": { "href": "https://api.printful.com/v2/approval-sheets?limit=10&offset=10" } }, "first": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ], "description": "Link to the first page (absent if there is only one page).", "example": { "href": "https://api.printful.com/v2/approval-sheets?limit=10" } }, "last": { "allOf": [ { "$ref": "#/components/schemas/HateoasLink" } ], "description": "Link to the last page (absent if there is only one page).", "example": { "href": "https://api.printful.com/v2/approval-sheets?limit=10&offset=90" } } } } } } } } }, "DownloadApprovalSheetPdf": { "description": "OK — PDF file download", "headers": { "Content-Disposition": { "description": "Attachment with the suggested filename for the PDF", "schema": { "type": "string", "example": "attachment; filename=\"approval-sheet.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } }, "examples": { "InternalServerError": { "summary": "Internal Server Error", "value": { "type": "https://developers.printful.com/docs/v2-beta/#errors/internal-server-error", "status": 500, "title": "Internal Server Error", "details": "An error occurred and we have been notified. You can contact us for more information.", "instance": "tag:api.printful.com,2023-10-04:errors/86657" } } }, "parameters": { "ProductCategoryIds": { "in": "query", "name": "category_ids", "schema": { "type": "array", "items": { "type": "integer" } }, "explode": false, "examples": { "oneID": { "summary": "Using a single category ID", "value": [ 4 ] }, "multipleIDs": { "summary": "Multiple category IDs", "value": [ 4, 7 ] } }, "required": false, "description": "One or more category IDs to return only products in those categories. The IDs can be found in the response of the\noperation _[Get Categories](#operation/getCategories)_.\n" }, "ColorsFilter": { "in": "query", "name": "colors", "schema": { "type": "array", "items": { "type": "string" } }, "explode": false, "examples": { "oneColor": { "summary": "Grey.", "value": [ "grey" ] }, "oneUrlEncodedColor": { "summary": "Heather grey color.", "value": [ "heather%20grey" ] }, "multipleColors": { "summary": "Grey or heather grey color", "value": [ "grey", "heather%20grey" ] } }, "required": false, "description": "One or more color names to return only products with variants of one the those colors.\n" }, "Limit": { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "description": "The number of results to return per page." }, "NewFilter": { "in": "query", "name": "new", "schema": { "type": "boolean", "default": false }, "examples": { "true": { "summary": "Return only new products", "value": true } }, "required": false, "description": "If true only new Products will be returned." }, "Offset": { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "examples": { "startAt100": { "summary": "Return results after the initial 100", "value": 100 } }, "description": "The number of results to not include in the response starting from the beginning of the list.\n\nThis can be used to return results after the initial 100. For example, sending offset 100\n" }, "PlacementsFilter": { "in": "query", "name": "placements", "schema": { "type": "array", "items": { "type": "string" } }, "explode": false, "examples": { "onePlacement": { "summary": "Return products with variants that have front placement.", "value": [ "front" ] }, "multiplePlacements": { "summary": "Return products with variants that have front or back placement.", "value": [ "front", "back" ] } }, "required": false, "description": "One or more identifiers of a placement to return only products with variants that have that placement. The complete list of placements can be found [here](https://developers.printful.com/docs/#tag/Common/Placements)." }, "SellingRegion": { "in": "query", "name": "selling_region_name", "schema": { "type": "string", "default": "worldwide", "enum": [ "worldwide", "north_america", "canada", "europe", "spain", "latvia", "uk", "france", "germany", "australia", "japan", "new_zealand", "italy", "brazil", "southeast_asia", "republic_of_korea", "all" ] }, "description": "Only returns the products that can be sold in the specified region. If is set to 'all' returns each region availability for specified product." }, "SortDirection": { "in": "query", "name": "sort_direction", "schema": { "type": "string", "default": "descending", "enum": [ "ascending", "descending" ] }, "required": false, "description": "This parameter only is used if sort_type is also present and it changes the order of the returned products.\nThe exact meaning varies depending on the value of `sort_type`:\n* `sort_type=new`\n * ascending sorts from newest to oldest.\n * descending sorts from oldest to newest.\n* `sort_type=rating`\n\t* ascending from lowest to highest rated.\n\t* descending from highest to lowest rated.\n* `sort_type=price`\n\t* ascending from lowest to highest price.\n\t* descending from highest to lowest price.\n* `sort_type=bestseller`\n * ascending from non bestsellers to bestsellers.\n * descending from bestsellers to non bestsellers.\n" }, "SortType": { "in": "query", "name": "sort_type", "schema": { "type": "string", "enum": [ "new", "rating", "price", "bestseller" ] }, "required": false, "description": "The sorting strategy to use when sorting the result. When it's not present, no specific order is guaranteed.\n" }, "TechniquesFilter": { "in": "query", "name": "techniques", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TechniqueEnum" } }, "explode": false, "examples": { "oneTechnique": { "summary": "Products with variants that can be printed using the technique digital.", "value": [ "digital" ] }, "multipleTechniques": { "summary": "Products with variants that can be printed using the techniques digital or embroidery.", "value": [ "digital", "embroidery" ] } }, "required": false, "description": "One or more techniques to return only products with variants that can be printed using one of the techniques." }, "DestinationCountry": { "in": "query", "name": "destination_country", "schema": { "type": "string" }, "required": false, "description": "The ISO 3166-1 alpha-2 country code for the destination country. Only products shippable to the specified country will be returned.\n" }, "Locale": { "in": "header", "name": "X-PF-Language", "description": "Use this to specify which locale you would like to use in the responses, for some endpoints this can affect translations.\n", "schema": { "type": "string" }, "required": false }, "ProductId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "Product ID." }, "VariantId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "Variant ID" }, "CategoryId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "Category 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" }, "SellingRegionPrice": { "in": "query", "name": "selling_region_name", "schema": { "type": "string", "example": "worldwide" }, "description": "Specifies the region production currency that the product prices will be calculated in" }, "Currency": { "in": "query", "name": "currency", "description": "The currency (3-letter code) used to determine currency in which the prices will be displayed. The store currency will be used by default. The format is compliant with ISO 4217 standard.", "schema": { "type": "string", "example": "USD" }, "required": false }, "ProductionCurrency": { "in": "query", "name": "production_currency", "description": "The production currency (3-letter code) used to determine currency in which the prices will be calculated. The format is compliant with ISO 4217 standard.\nIf not provided, prices will be calculated for all available production currencies,\nand the highest price will be returned.\n", "schema": { "type": "string", "example": "USD" }, "required": false }, "MockupStyleIds": { "in": "query", "name": "mockup_style_ids", "schema": { "type": "integer", "example": "1, 2, 3" }, "description": "Used to specify style of images For example:\n * On the hanger\n * On the Male/Female model\n * Flat on the table\n * etc.\nAvailable mockup styles for catalog product can be found under _[Retrieve catalog product mockup styles](#operation/retrieveMockupStylesByProductId)_.\n" }, "VariantColor": { "in": "query", "name": "colors", "schema": { "type": "string", "example": "black,red" }, "description": "String values separated by comma. You can specify multiple variant colors filters." }, "Placement": { "in": "query", "name": "placement", "schema": { "type": "string", "example": "front" }, "description": "Filters result by specified placement" }, "LimitTwenty": { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 }, "required": false, "description": "The number of results to return per page." }, "MockupPlacementsFilter": { "in": "query", "name": "placements", "schema": { "type": "array", "items": { "type": "string" } }, "explode": false, "examples": { "onePlacement": { "summary": "Return mockup styles that match a specific placement.", "value": [ "front" ] }, "multiplePlacements": { "summary": "Return mockup styles that match a list of placements.", "value": [ "front", "back" ] } }, "required": false, "description": "One or more placement idenitifiers used to filter in mockup styles that match a given placement. The complete list of placements can be found [here](https://developers.printful.com/docs/#tag/Common/Placements)." }, "DefaultMockupStylesFilter": { "in": "query", "name": "default_mockup_styles", "schema": { "type": "boolean", "default": false, "description": "When set to true only the default mockup styles will be returned.\nFor example mockup styles such as Halloween or Lifestyle won't be returned.\n" } }, "Offset-2": { "in": "query", "name": "offset", "schema": { "type": "integer" }, "required": false, "description": "Result set offset" }, "Limit-2": { "in": "query", "name": "limit", "schema": { "type": "integer" }, "required": false, "description": "Number of items per page (max 100)" }, "SellingRegionAll": { "in": "query", "name": "selling_region_name", "schema": { "type": "string", "default": "worldwide", "enum": [ "worldwide", "north_america", "canada", "europe", "spain", "latvia", "uk", "france", "germany", "australia", "japan", "new_zealand", "italy", "brazil", "southeast_asia", "republic_of_korea", "all" ] }, "description": "Only returns the products that can be sold in the specified region. If is set to 'all' returns each region availability for specified product." }, "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/Stores-v2/operation/getStores) endpoint.\n", "schema": { "type": "string" }, "required": false }, "OrderId": { "in": "path", "name": "order_id", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "required": true, "description": "Order ID (integer) or Order External ID (string prepended with \"@\" symbol)" }, "Type": { "in": "query", "name": "type", "schema": { "type": "string" }, "required": false, "description": "Type of items returned (order_item, branding_item). By default all items are returned." }, "ItemId": { "in": "path", "name": "order_item_id", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "required": true, "description": "Item ID (integer) or Item External ID (string prepended with \"@\" symbol)" }, "OrderEstimationTaskId": { "in": "query", "name": "id", "schema": { "type": "string" }, "required": true, "description": "Order estimation task ID.", "example": null }, "FileId": { "in": "path", "name": "id", "schema": { "type": "integer" }, "required": true, "description": "File ID." }, "NameFilter": { "in": "query", "name": "filter[name*]", "schema": { "type": "string" }, "required": false, "description": "Wildcard match of the name value. Note that the value will be matched if the name property contains the value anywhere in the string." }, "WarehouseProductId": { "in": "path", "name": "warehouse_product_id", "schema": { "type": "integer" }, "required": true, "description": "Warehouse Product ID." }, "MockupGeneratorIds": { "in": "query", "name": "id", "schema": { "type": "array", "items": { "type": "string" } }, "explode": false, "examples": { "oneId": { "summary": "Return single specified mockup generator task result.", "value": "421699980" }, "multipleIds": { "summary": "Return multiple specified mockup generator task results.", "value": "421699980,421699981" } }, "required": true, "description": "One or more mockup generator task IDs to return only specified tasks. The IDs can be found in the response of the operation _[Create mockup generator tasks](#operation/createMockupGeneratorTasks)_." }, "ShowExpired": { "in": "query", "name": "show_expired", "description": "If this parameter is passed with value `true`, expired settings will be returned instead of a 404 warning.", "schema": { "type": "boolean" }, "required": false }, "EventType": { "in": "path", "name": "eventType", "description": "Event type", "schema": { "type": "string" }, "required": true }, "StoreId-2": { "in": "path", "name": "store_id", "schema": { "$ref": "#/components/schemas/InternalId" }, "required": true, "description": "Store ID" }, "StoreIdNotRequired": { "in": "header", "name": "X-PF-Store-Id", "description": "Use this to specify which store you want to use.\n\nThe store IDs can be retrieved with the [Get basic information about stores](#tag/Stores-v2/operation/getStores) endpoint.\n", "schema": { "type": "string" }, "required": false }, "PathStoreId": { "in": "path", "name": "store_id", "description": "Use this to specify which store you want to use.\nThe store IDs can be retrieved with the [Get basic information about stores](#tag/Stores-v2/operation/getStores) endpoint.\n", "schema": { "type": "integer" }, "required": true }, "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-2": { "in": "query", "name": "currency", "description": "The currency (3-letter code) to return the statistics in.\nThe store currency will be used by default.\n", "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", "enum": [ "sales_and_costs", "profit", "average_fulfillment_type", "costs_by_amount", "costs_by_product", "costs_by_variant", "printful_costs", "sales_and_costs_summary", "total_paid_orders" ] }, "required": true }, "OrderId-2": { "in": "query", "name": "order_id", "schema": { "type": "integer" }, "description": "Order ID." }, "GroupHash": { "in": "query", "name": "group_hash", "schema": { "type": "string" }, "description": "Filters results by the group hash common to all approval sheets that relate to the same design.", "example": "5d41402abc4b2a76b9719d911017c592" }, "ConfirmHash": { "in": "path", "name": "confirm_hash", "schema": { "type": "string" }, "description": "The confirm hash associated with the approval sheet." } }, "requestBodies": { "OrderInput": { "description": "POST request body", "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "order_items" ], "properties": { "external_id": { "description": "Order ID from the external system", "type": "string", "example": "4235234213" }, "shipping": { "description": "Shipping method. Defaults to 'STANDARD'", "type": "string", "example": "STANDARD" }, "recipient": { "description": "The recipient data.", "title": "Address", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "order_items": { "type": "array", "description": "Array of order items", "items": { "oneOf": [ { "$ref": "#/components/schemas/CatalogItem" }, { "$ref": "#/components/schemas/ProductTemplateItem" } ], "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItem", "product_template": "#/components/schemas/ProductTemplateItem" } } } }, "customization": { "$ref": "#/components/schemas/Customization" }, "retail_costs": { "$ref": "#/components/schemas/RetailCosts-2" } } } } } }, "OrderPatchInput": { "description": "PATCH request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "description": "Order ID from the external system", "type": "string", "example": "4235234213" }, "shipping": { "description": "Shipping method. Defaults to 'STANDARD'", "type": "string", "example": "STANDARD" }, "recipient": { "description": "The recipient data.", "title": "Address", "allOf": [ { "$ref": "#/components/schemas/Address" } ] }, "order_items": { "type": "array", "description": "Array of order items", "items": { "oneOf": [ { "$ref": "#/components/schemas/CatalogItem" }, { "$ref": "#/components/schemas/ProductTemplateItem" } ], "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItem", "product_template": "#/components/schemas/ProductTemplateItem" } } } }, "customization": { "$ref": "#/components/schemas/Customization" }, "retail_costs": { "description": "Retail costs", "type": "object", "properties": { "currency": { "description": "The code of the currency in which the retail costs are returned.", "type": "string", "example": "EUR" }, "discount": { "description": "Discount sum.", "type": "string", "example": "123.40" }, "shipping": { "description": "Shipping costs.", "type": "string", "example": "123.40" }, "tax": { "description": "Sum of taxes (not included in the item price).", "type": "string", "example": "123.40" } } } } } } } }, "ItemInput": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItem", "product_template": "#/components/schemas/ProductTemplateItem" } }, "oneOf": [ { "$ref": "#/components/schemas/CatalogItem" }, { "$ref": "#/components/schemas/ProductTemplateItem" } ] } } } }, "ItemPatchInput": { "description": "PATCH request body", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogItem" }, { "$ref": "#/components/schemas/ProductTemplateItem" } ], "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItem", "product_template": "#/components/schemas/ProductTemplateItem" } } } } } }, "CreateOrderEstimationTaskInput": { "description": "POST request body", "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "order_items" ], "properties": { "recipient": { "description": "The recipient data.", "title": "Address", "allOf": [ { "$ref": "#/components/schemas/EstimationAddress" } ] }, "order_items": { "type": "array", "description": "Array of order items", "items": { "oneOf": [ { "$ref": "#/components/schemas/CatalogItem" } ], "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogItem", "product_template": "#/components/schemas/ProductTemplateItem" } } } }, "retail_costs": { "$ref": "#/components/schemas/RetailCosts-2" } } } } } }, "AddFile": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFile" } } } }, "ShippingRatesInput": { "description": "POST request body", "content": { "application/json": { "schema": { "required": [ "recipient", "order_items" ], "type": "object", "properties": { "recipient": { "description": "The recipient data.", "allOf": [ { "$ref": "#/components/schemas/ShippingRatesAddress" } ] }, "order_items": { "type": "array", "description": "Array of order items", "items": { "oneOf": [ { "$ref": "#/components/schemas/CatalogShippingRateItem" }, { "$ref": "#/components/schemas/WarehouseShippingRateItem" } ], "discriminator": { "propertyName": "source", "mapping": { "catalog": "#/components/schemas/CatalogShippingRateItem", "warehouse": "#/components/schemas/WarehouseShippingRateItem" } } } }, "currency": { "type": "string", "description": "Currency code in which the rate is returned. If not provided will use the default currency for the store." } } } } } }, "CreateMockupGeneratorTasks": { "description": "This action schedules asynchronous mockup generation tasks. In the response of this request `id` will be returned which can be used to retrieve the result of the tasks _[Retrieve mockup generator tasks](#operation/getMockupGeneratorTasks)_. In addition, the webhook event will be sent informing about the task completion, if the correct webhook has been subscribed to _[Mockup generator task finished event](#operation/mockupTaskFinished)_. You can subscribe to webhook events by using _[Set up event configuration](#operation/createWebhookEventConfiguration)_.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MockupTaskCreation" } } } }, "CreateWebhook": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookInfoRequest" }, { "required": [ "events" ] } ] } } } }, "CreateWebhookEvent": { "description": "POST request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventConfigurationRequest" } } } }, "ShipmentSent": { "description": "Shipment sent.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `shipment_sent`", "enum": [ "shipment_sent" ] }, "data": { "description": "Shipment and order data", "title": "ShipmentInfo", "required": [ "shipment", "order" ], "properties": { "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "ShipmentDelivered": { "description": "Shipment delivered.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `shipment_delivered`", "enum": [ "shipment_delivered" ] }, "data": { "description": "Shipment and order data", "title": "DeliveryInfo", "required": [ "shipment", "order" ], "properties": { "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "ShipmentReturned": { "description": "Shipment returned.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `shipment_returned`", "enum": [ "shipment_returned" ] }, "data": { "description": "Shipment and order data", "title": "ReturnInfo", "required": [ "reason", "shipment", "order" ], "properties": { "reason": { "type": "string", "description": "Reason why the shipment was returned." }, "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "ShipmentOutOfStock": { "description": "Shipment out of stock/back in stock.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `shipment_out_of_stock`", "enum": [ "shipment_out_of_stock" ] }, "data": { "description": "Shipment and order data", "title": "ShipmentOutOfStockInfo", "required": [ "is_out_of_stock", "shipment", "order" ], "properties": { "is_out_of_stock": { "type": "boolean", "description": "Tells whether the items in a shipment went out of stock (`true`) or came back in stock (`false`)." }, "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "ShipmentCanceled": { "description": "Shipment canceled.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `shipment_canceled`", "example": "shipment_canceled" }, "data": { "description": "Cancel reason and shipment and order data", "title": "CancelInfo", "required": [ "reason", "shipment", "order" ], "properties": { "reason": { "type": "string", "description": "Reason why the shipment has been canceled." }, "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "OrderCreated": { "description": "Order created.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_created`", "example": "order_created" }, "data": { "description": "Created order data", "title": "CreateInfo", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "OrderUpdated": { "description": "Order updated.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_updated`", "example": "order_updated" }, "data": { "description": "Updated order data", "title": "UpdateInfo", "required": [ "order" ], "properties": { "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "OrderFailed": { "description": "Order failed.", "content": { "application/json": { "schema": { "required": [ "data" ], "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", "required": [ "reason", "order" ], "properties": { "reason": { "type": "string", "description": "Reason why the order has failed." }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "OrderCanceled": { "description": "Order canceled.", "content": { "application/json": { "schema": { "required": [ "data" ], "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", "required": [ "reason", "order" ], "properties": { "reason": { "type": "string", "description": "Reason why the order has been canceled." }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "CatalogStockUpdated": { "description": "Catalog stock updated.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `catalog_stock_updated`", "enum": [ "catalog_stock_updated" ], "example": "catalog_stock_updated" }, "data": { "title": "ChangedAvailabilities", "type": "array", "items": { "type": "object", "required": [ "catalog_product_id", "catalog_variant_id", "techniques", "availability" ], "properties": { "catalog_product_id": { "type": "integer", "description": "Product ID", "example": 71 }, "catalog_variant_id": { "type": "integer", "description": "Variant ID", "example": 4011 }, "techniques": { "type": "array", "items": { "type": "string" }, "description": "Technique list." }, "availability": { "type": "string", "description": "Availability status.", "enum": [ "in stock", "on demand", "out of stock", "not fulfilled", "discontinued", "unknown" ] } } } } } } ] } } } }, "CatalogPriceChanged": { "description": "Catalog price changed.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `catalog_price_changed`", "enum": [ "catalog_price_changed" ] }, "data": { "description": "Information about products which catalog product prices changed", "title": "ProductPriceChangedInfo", "required": [ "catalog_product_ids" ], "properties": { "catalog_product_ids": { "type": "array", "description": "List of catalog product IDs which prices has changed", "example": [ 71 ] } } } } } ] } } } }, "OrderPutHold": { "description": "Order put on hold.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_put_hold`", "example": "order_put_hold" }, "data": { "title": "OrderStatusChange", "required": [ "reason", "order" ], "properties": { "reason": { "type": "string", "description": "Reason why the order status was changed." }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "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": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_put_hold_approval`", "example": "order_put_hold_approval" }, "data": { "title": "OrderRequiresApproval", "required": [ "reason", "approval_files", "order" ], "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/WebhookOrderData" } } } } } ] } } } }, "OrderRemoveHold": { "description": "Order removed from on hold.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `order_remove_hold`", "example": "order_remove_hold" }, "data": { "title": "OrderStatusChange", "required": [ "reason", "order" ], "properties": { "reason": { "type": "string", "description": "Reason why the order status was changed." }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "OrderRefunded": { "description": "Order refunded.", "content": { "application/json": { "schema": { "required": [ "data" ], "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", "required": [ "currency", "amount", "order" ], "properties": { "currency": { "type": "string", "description": "Refund currency." }, "amount": { "type": "string", "description": "Refunded amount." }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "MockupTaskFinished": { "description": "Mockup task finished processing.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type – `mockup_task_finished`", "enum": [ "mockup_task_finished" ] }, "data": { "$ref": "#/components/schemas/MockupGeneratorTask" } } } ] } } } }, "ShipmentPutHold": { "description": "Shipment put on hold.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `shipment_put_hold`", "example": "shipment_put_hold" }, "data": { "title": "ShipmentPutOnHold", "properties": { "reason": { "type": "string", "description": "Reason why the shipment was put on hold." }, "details": { "type": "string", "description": "Details on why the shipment was put on hold. There might be multiple reasons that are separated by `;`" }, "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "ShipmentHoldApproval": { "description": "Shipment 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 - `shipment_put_hold_approval`", "example": "shipment_put_hold_approval" }, "data": { "title": "ShipmentRequiresApproval", "properties": { "reason": { "type": "string", "description": "Reason why the shipment was put on hold and requires approval." }, "details": { "type": "string", "description": "Details on why the shipment was put on hold. There might be multiple reasons that are separated by `;`" }, "approval_files": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalSheetWebhookFile" } }, "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "ShipmentRemoveHold": { "description": "Shipment removed from on hold.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `shipment_remove_hold`", "example": "shipment_remove_hold" }, "data": { "title": "ShipmentRemovedHold", "properties": { "reason": { "type": "string", "description": "Reason why the shipment was put on hold." }, "shipment": { "$ref": "#/components/schemas/WebhookShipmentData" }, "details": { "type": "string", "description": "Details on why the shipment was put on hold. There might be multiple reasons that are separated by `;`" }, "order": { "$ref": "#/components/schemas/WebhookOrderData" } } } } } ] } } } }, "ApprovalSheetStatusChanged": { "description": "Approval sheet status changed.", "content": { "application/json": { "schema": { "required": [ "data" ], "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "properties": { "type": { "type": "string", "description": "Event type - `approval_sheet_status_changed`", "enum": [ "approval_sheet_status_changed" ] }, "data": { "description": "Approval sheet, order and status data", "title": "ApprovalSheetStatusChangedInfo", "required": [ "order_id", "shipment_id", "approval_sheet", "previous_status", "status" ], "properties": { "order_id": { "type": "integer", "description": "ID of the order the approval sheet belongs to.", "example": 170478295 }, "shipment_id": { "type": "integer", "description": "ID of the shipment the approval sheet belongs to.", "example": 82459661 }, "approval_sheet": { "type": "object", "title": "ApprovalSheetStatusChangedReference", "description": "Identifiers of the approval sheet whose status changed.", "required": [ "confirm_hash", "group_hash" ], "properties": { "confirm_hash": { "type": "string", "description": "Confirmation hash value of the approval sheet.", "example": "c40d55a604a49af1e35486595a395d7c" }, "group_hash": { "type": "string", "description": "Common identifier used to group all approval sheets that relate to the same design.", "example": "a45bf6af259a9a56c0927f7cfc9da6a2" } } }, "previous_status": { "allOf": [ { "$ref": "#/components/schemas/ApprovalSheetStatuses" }, { "description": "Status of the approval sheet before the change." } ] }, "status": { "allOf": [ { "$ref": "#/components/schemas/ApprovalSheetStatuses" }, { "description": "Current status of the approval sheet." }, { "example": "changes_requested" } ] }, "reason": { "type": "string", "description": "Reason for the status change, if one was provided. For example, the comment left when changes were requested.", "example": "The design needs to be aligned to the left" } } } } } ] } } } } } } }