Download OpenAPI specification:Download
The Printful API is a RESTful API, that uses an HTTP protocol for communication. HTTP GET, POST, PUT and DELETE methods are used to access the API resources.
All API requests have to be sent to this URL:
https://api.printful.com/
If you are using a proxy, make sure that all requests have host header set to api.printful.com.
Some mandatory parameters (like object identifiers) must be included in the request URL path
GET /orders/123
Additional parameters can be passed as GET variables:
GET /orders?offset=10&limit=5
For POST and PUT requests, a more complex data structure can be passed as JSON encoded data in the request body:
POST /orders
{"recipient":{...},"items":[...]}
The response body is always a JSON object that contains a response status code (identical to the HTTP status code) and the result of the action. If the status code is 200, then the action was successful.
{
"code": 200, //Response status code
"result":{
//API method return data
//...
}
}
Sometimes the response includes paging information to allow to browse larger result sets by adding offset and limit GET parameters to the request URL.
{
"code": 200, //Response status code
"result":[
{
//Item 11
},
{
//Item 12
}
]
"paging": {
"total": 12, //Total items available
"offset": 10, //Items skipped from the beginning
"limit": 20 //Number of items per page
}
}
If the API call is not successful, then the response code is not in the 2xx range and the result
attribute contains an error description.
{
"code": 404,
"result": "Not Found",
"error": {
"reason": "NotFound",
"message": "Not Found"
}
}
In general, response codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with Printful's servers.
All timestamps from the API are returned as integers in UNIX timestamp format.
Printful API has a general rate limit of 120 API calls per minute. Additionally, endpoints that perform resource intensive operations (such as mockup generator) have a lower allowed request limit.
Some of the resources returned by the API are translated into several languages. By default, they are returned in English in the API responses.
If you want to get a response with texts in another language, you can use the X-PF-Language
HTTP header. Its value should be the long version of the locale to use (e.g. es_ES
for Spanish).
Product details (GET https://api.printful.com/products/71
) response with default locale (en_US
):
{
"code": 200,
"result": {
"product": {
"type_name": "T-Shirt",
"title": "Unisex Staple T-Shirt | Bella + Canvas 3001",
...
}
}
}
Product details response with Spanish locale (X-PF-Language: es_ES
):
{
"code": 200,
"result": {
"product": {
...
"type_name": "Camiseta",
"title": "Camiseta esencial unisex | Bella + Canvas 3001",
...
}
}
}
There are two different ways of using Printful OAuth - Private token and Public App. If you are developing an API solution for your personal store, you should choose Private Token. But if you are building an Public App that will be used by a wider audience, you should be choosing Public App.
There are two different client types - Store and Account. Store access level client is only able to access the
specific store. For Private tokens this store is specified when the token is created, but for Public apps this store
is specified when the app is installed. Account level tokens on the other hand can manage all the stores associated with
the account. For the endpoints that require specific store context, requests should contain X-PF-Store-Id
header.
Account level access currently is only available for Private tokens.
Scopes are used to limit access to specific resources and their methods. Scopes are defined in the developer portal when creating a Private Token or Public App. Customers on Public App installation grant screen will see all requested permissions, so be thoughtful about which scopes to request.
List of currently available scopes
Scope | Client type | Description |
---|---|---|
orders |
Store & Account | Read and Write access to Orders |
orders/read |
Store & Account | Read access to Orders |
sync_products |
Store & Account | Read and Write access to SyncProducts |
sync_products/read |
Store & Account | Read access to SyncProducts |
file_library |
Store & Account | Read and Write access access to File library |
file_library/read |
Store & Account | Read access to File library |
webhooks |
Store & Account | Read and Write access to Webhooks |
webhooks/read |
Store & Account | Read access to Webhooks |
product_templates |
Account | Read and Write access to Product templates |
product_templates/read |
Account | Read access to Product templates |
Developer Portal is specifically designed for developers that want to interact with the Printful API. In the Developer Portal, it's possible to create and manage your Public Apps and Private tokens.
Private OAuth tokens can be generated in the Developer Portal's Token page. These tokens do not require refreshing and are valid until they expire or are deleted manually. Usage of these tokens is described below.
For public apps to make requests on behalf of the customer, they must first acquire access tokens. In order to acquire these tokens, developers must follow these steps:
Client id
, Client secret
, and other parametersredirect_url
, use code
parameter to acquire OAuth tokensReturns a list of scopes associated with the token
code | integer Response status code |
object |
curl --location --request GET 'https://api.printful.com/oauth/scopes' --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "scopes": [
- {
- "scope": "orders/read",
- "display_name": "View all orders"
}
]
}
}
Printful has a substantial catalog of blank Products and Variants. A Product can describe a specific type, model and manufacturer of the item, while the Variant specifies the more detailed attributes of the product like the exact size/color of a T-shirt or the dimensions of a poster. Moreover, each item in the Printful Catalog has a unique Variant ID. When managing Sync Products or orders, you will need to specify the Variant ID of the specific blank item, hence you can use this API resource to find the needed Variant ID.
You can also use this API resource to find out the types of print files a product can be configured for as well as the additional price each print file would cost (e.g. the back print or inside label print for T-shirts). Moreover, some product types allow for additional options (e.g. embroidery type and thread colors) - these options are listed in the responses as well.
Important: Jewelry products are not supported via API.
Rate limiting: For unauthenticated usages, up to 30 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.
The Get Product Size Guide endpoint will return size guide data for the selected product.
There are three types of size tables available, as described by the following table:
Table type | API name | Description |
---|---|---|
Measure yourself | measure_yourself |
Measurements of the product to measure the body provided by the supplier. |
Product measurements | product_measure |
Measurements of the product provided by the supplier. |
International size conversion | international |
International size conversion – e.g. US, EU or UK sizes corresponding to the product sizes. |
Not each table type might be available for the selected product.
Returns list of Products available in the Printful
category_id | string A comma-separated list of Category IDs of the Products that are to be returned |
code | integer Response status code |
Array of objects (Product) |
curl --location --request GET 'https://api.printful.com/products'
{- "code": 200,
- "result": [
- {
- "id": 13,
- "main_category_id": 24,
- "type": "T-SHIRT",
- "type_name": "T-Shirt",
- "title": "Unisex Staple T-Shirt | Bella + Canvas 3001",
- "brand": "Gildan",
- "model": "2200 Ultra Cotton Tank Top",
- "variant_count": 30,
- "currency": "EUR",
- "files": [
- {
- "id": "default",
- "type": "front",
- "title": "Front print",
- "additional_price": "2.22",
- "options": [
- {
- "id": "full_color",
- "type": "bool",
- "title": "Unlimited color",
- "additional_price": 3.25
}
]
}
], - "options": [
- {
- "id": "embroidery_type",
- "title": "Embroidery type",
- "type": "radio",
- "values": {
- "flat": "Flat Embroidery",
- "3d": "3D Puff",
- "both": "Partial 3D Puff"
}, - "additional_price": "string",
- "additional_price_breakdown": {
- "flat": "0.00",
- "3d": "0.00",
- "both": "0.00"
}
}
], - "is_discontinued": false,
- "avg_fulfillment_time": 4.3,
- "description": "string",
- "techniques": [
- {
- "key": "DTG",
- "display_name": "DTG printing",
- "is_default": true
}
], - "origin_country": "Nicaragua"
}
]
}
Returns information about a specific Variant and its Product
id required | integer Variant id |
code | integer Response status code |
object (VariantInfo) |
curl --location --request GET 'https://api.printful.com/products/variant/4018'
{- "code": 200,
- "result": {
- "variant": {
- "id": 100,
- "product_id": 12,
- "name": "Gildan 64000 Unisex Softstyle T-Shirt with Tear Away (Black / 2XL)",
- "size": "2XL",
- "color": "Black",
- "color_code": "#14191e",
- "color_code2": "string",
- "price": "9.85",
- "in_stock": true,
- "availability_regions": {
- "US": "USA",
- "EU": "Europe"
}, - "availability_status": [
- {
- "region": "US",
- "status": "in_stock"
}
], - "material": [
- {
- "name": "cotton",
- "percentage": 100
}
]
}, - "product": {
- "id": 13,
- "main_category_id": 24,
- "type": "T-SHIRT",
- "type_name": "T-Shirt",
- "title": "Unisex Staple T-Shirt | Bella + Canvas 3001",
- "brand": "Gildan",
- "model": "2200 Ultra Cotton Tank Top",
- "variant_count": 30,
- "currency": "EUR",
- "files": [
- {
- "id": "default",
- "type": "front",
- "title": "Front print",
- "additional_price": "2.22",
- "options": [
- {
- "id": "full_color",
- "type": "bool",
- "title": "Unlimited color",
- "additional_price": 3.25
}
]
}
], - "options": [
- {
- "id": "embroidery_type",
- "title": "Embroidery type",
- "type": "radio",
- "values": {
- "flat": "Flat Embroidery",
- "3d": "3D Puff",
- "both": "Partial 3D Puff"
}, - "additional_price": "string",
- "additional_price_breakdown": {
- "flat": "0.00",
- "3d": "0.00",
- "both": "0.00"
}
}
], - "is_discontinued": false,
- "avg_fulfillment_time": 4.3,
- "description": "string",
- "techniques": [
- {
- "key": "DTG",
- "display_name": "DTG printing",
- "is_default": true
}
], - "origin_country": "Nicaragua"
}
}
}
Returns information about a specific product and a list of variants for this product.
id required | integer Product ID. |
code | integer Response status code |
object (ProductInfo) |
curl --location --request GET 'https://api.printful.com/products/71'
{- "code": 200,
- "result": {
- "product": {
- "id": 13,
- "main_category_id": 24,
- "type": "T-SHIRT",
- "type_name": "T-Shirt",
- "title": "Unisex Staple T-Shirt | Bella + Canvas 3001",
- "brand": "Gildan",
- "model": "2200 Ultra Cotton Tank Top",
- "variant_count": 30,
- "currency": "EUR",
- "files": [
- {
- "id": "default",
- "type": "front",
- "title": "Front print",
- "additional_price": "2.22",
- "options": [
- {
- "id": "full_color",
- "type": "bool",
- "title": "Unlimited color",
- "additional_price": 3.25
}
]
}
], - "options": [
- {
- "id": "embroidery_type",
- "title": "Embroidery type",
- "type": "radio",
- "values": {
- "flat": "Flat Embroidery",
- "3d": "3D Puff",
- "both": "Partial 3D Puff"
}, - "additional_price": "string",
- "additional_price_breakdown": {
- "flat": "0.00",
- "3d": "0.00",
- "both": "0.00"
}
}
], - "is_discontinued": false,
- "avg_fulfillment_time": 4.3,
- "description": "string",
- "techniques": [
- {
- "key": "DTG",
- "display_name": "DTG printing",
- "is_default": true
}
], - "origin_country": "Nicaragua"
}, - "variants": [
- {
- "id": 100,
- "product_id": 12,
- "name": "Gildan 64000 Unisex Softstyle T-Shirt with Tear Away (Black / 2XL)",
- "size": "2XL",
- "color": "Black",
- "color_code": "#14191e",
- "color_code2": "string",
- "price": "9.85",
- "in_stock": true,
- "availability_regions": {
- "US": "USA",
- "EU": "Europe"
}, - "availability_status": [
- {
- "region": "US",
- "status": "in_stock"
}
], - "material": [
- {
- "name": "cotton",
- "percentage": 100
}
]
}
]
}
}
Returns information about the size guide for a specific product.
id required | integer Product ID. |
unit | string Example: unit=inches,cm A comma-separated list of measurement unit in which size tables are to be returned ( |
code | integer Response status code |
object (ProductSizeGuide) Size Guide information for the Product |
curl --location --request GET 'https://api.printful.com/products/71/sizes'
{- "code": 200,
- "result": {
- "product_id": 13,
- "available_sizes": [
- "S",
- "M",
- "L"
], - "size_tables": [
- {
- "type": "measure_yourself",
- "unit": "inches",
- "description": "<p>Measurements are provided by suppliers.<br /><br />US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.</p>\\n<p>Product measurements may vary by up to 2\\\" (5 cm). </p>",
- "image_description": "<h6><strong>A Length</strong></h6>\\n<p dir=\\\"ltr\\\"><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure t</span><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">o the bottom of the shirt.</span></p>\\n<h6>B Chest</h6>\\n<p dir=\\\"ltr\\\">Measure yourself around the fullest part of your chest. Keep the tape measure horizontal.</p>",
- "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": "<p dir=\\\"ltr\\\">Measurements are provided by our suppliers. Product measurements may vary by up to 2\\\" (5 cm).</p>\\n<p dir=\\\"ltr\\\">US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.</p>\\n<p dir=\\\"ltr\\\">Pro tip! Measure one of your products at home and compare with the measurements you see in this guide.</p>",
- "image_description": "<h6><strong>A Length</strong></h6>\\n<p dir=\\\"ltr\\\"><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure t</span><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">o the bottom of the shirt.</span></p>\\n<h6>B Width</h6>\\n<p dir=\\\"ltr\\\">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.</p>",
- "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": "<p>Measurements are provided by suppliers.<br /><br />US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.</p>\\n<p>Product measurements may vary by up to 2\\\" (5 cm). </p>",
- "image_description": "<h6><strong>A Length</strong></h6>\\n<p dir=\\\"ltr\\\"><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure t</span><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">o the bottom of the shirt.</span></p>\\n<h6>B Chest</h6>\\n<p dir=\\\"ltr\\\">Measure yourself around the fullest part of your chest. Keep the tape measure horizontal.</p>",
- "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": "<p dir=\\\"ltr\\\">Measurements are provided by our suppliers. Product measurements may vary by up to 2\\\" (5 cm).</p>\\n<p dir=\\\"ltr\\\">US customers should order a size up as the EU sizes for this supplier correspond to a smaller size in the US market.</p>\\n<p dir=\\\"ltr\\\">Pro tip! Measure one of your products at home and compare with the measurements you see in this guide.</p>",
- "image_description": "<h6><strong>A Length</strong></h6>\\n<p dir=\\\"ltr\\\"><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">Place the end of the tape beside the collar at the top of the tee (Highest Point Shoulder). Pull the tape measure t</span><span id=\\\"docs-internal-guid-a3ac3082-7fff-5f98-2623-3eb38d5f43a1\\\">o the bottom of the shirt.</span></p>\\n<h6>B Width</h6>\\n<p dir=\\\"ltr\\\">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.</p>",
- "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"
}
]
}
]
}
]
}
}
Returns list of Catalog Categories available in the Printful
code | integer Response status code |
Array of objects (Category) |
curl --location --request GET 'https://api.printful.com/categories'
{- "code": 200,
- "result": [
- {
- "id": 24,
- "parent_id": 6,
- "size": "small",
- "title": "T-Shirts"
}
]
}
Returns information about a specific category.
id required | integer Category ID |
code | integer Response status code |
object (Category) Information about the Category |
curl --location --request GET 'https://api.printful.com/categories/24'
{- "code": 200,
- "result": {
- "id": 24,
- "parent_id": 6,
- "size": "small",
- "title": "T-Shirts"
}
}
The Products API resource lets you create, modify and delete products in a Printful store based on the Manual orders / API platform (you can create such store by going to the Stores section at your Printful dashboard.)
Important: Jewelry products are not supported via API.
To manage Warehouse products, please see Warehouse Products API.
Each product in your Printful store must contain one or multiple variants (imagine multiple sizes or colors of the same t-shirt design). Furthermore, for each variant, you have to specify both a blank product variant from our Printful Catalog and a print file. These two properties together with price and External ID (more on that later) will allow the variant to be purchasable. Please, see the following sections for more details. Finally, please note that for technical reasons a product in your Printful store is called a Sync Product and a variant of that product is called a Sync Variant. The maximum supported amount of Sync Variants a Sync Product can have is 100.
Printful has a substantial catalog of blank products and variants, where each variant (e.g. size and color combination of a particular product) has a unique ID, which we call variant_id. You can browse through the catalog via Catalog API to find a specific variant_id. Moreover, when creating a Sync Product at your Printful store, each of its Sync Variants must be associated with a variant_id from the Printful Catalog. Furthermore, to assign a specific variant_id to a specific Sync Variant, simply add it to the HTTP request body (see examples at the specific endpoint).
There are two ways to assign a print file to a Sync Variant. One is to specify the File ID if the file already exists in the File library of the authorized store;
Important: The Products API is not intended and will never support creating and managing products in external platforms such as Shopify, WooCommerce and others. For managing your products from external platforms please refer to Ecommerce Platform Sync API
{
...
"files": [
{
"id": 12345
}
],
...
}
The second and most convenient method is to specify the file URL. If a file with the same URL already exists, it will be reused.
{
...
"files": [
{
"url": "http://example.com/t-shirts/123/front.pdf"
}
],
...
}
Moreover, each Sync Variant has to be linked with one or multiple print files. The available file types for each product are available from the Printful Catalogue API. You can add one file for each type by specifying the type attribute. For the default type, this attribute can be skipped.
...
"files":[
{
"type": "default",
"url": "http://example.com/t-shirts/123/front.pdf"
},
{
"type": "back"
"url": "http://example.com/t-shirts/123/back.pdf"
}
],
...
Remember that using additional files can increase the price of the item.
When creating a Sync Product and/or Sync Variant you can specify an External ID, which you can then use as a reference when managing or even ordering the specific Sync Product or Sync Variant. In particular, when requesting a specific Sync Product and Sync Variant, you can use either the internal Printful ID or your External ID (prefixed with an @ symbol) at the request URL.
Printful previously allowed customers to upload a fully customized inside label. Since these labels had to contain specific information about fabric composition, manufacturing, etc. to meet the legal requirements, users usually encountered issues to get their labels printed.
Inside labels are printed on the inside of the garment and require the removal of the original manufacturer's tag. They're only available for apparel with tear-away labels. An inside label must include the country of manufacturing origin, original garment size, and material information. To use our native label template you only need to upload a graphic (such as your brand's logo). The mandatory content will be generated and placed automatically.
...
"files":[
{
"type": "label_inside",
"url": "http://example.com/logo/123/image.jpg",
"options": [{
"id": "template_type",
"value": "native"
}]
},
],
...
Printful previously supported fully customized inside labels. These have now been deprecated. The ability to create orders with fully customized inside labels has been limited to only users who were actively using them in their stores before April 2020. This feature is no longer accessible to new users.
Returns a list of Sync Product objects from your custom Printful store.
status | string Enum: "all" "synced" "unsynced" "ignored" "imported" "discontinued" "out_of_stock" Parameter used to filter results by status/group of Sync Products |
category_id | string A comma-separated list of Category IDs of the Products that are to be returned |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
object (Paging) Paging information | |
Array of objects (SyncProduct) Array of SyncProduct |
curl --location --request GET 'https://api.printful.com/store/products' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "paging": {
- "total": 100,
- "offset": 10,
- "limit": 100
}, - "result": [
- {
- "id": 13,
- "external_id": "4235234213",
- "name": "T-shirt",
- "variants": 10,
- "synced": 10,
- "thumbnail_url": "https://your-domain.com/path/to/image.png",
- "is_ignored": true
}
]
}
Creates a new Sync Product together with its Sync Variants (See examples).
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
POST request body
required | object (SyncProduct) Information about the SyncProduct |
required | Array of objects (SyncVariant) Information about the Sync Variants |
code | integer Response status code |
object (SyncProduct) Information about the SyncProduct |
{- "sync_product": {
- "external_id": "4235234213",
- "name": "T-shirt",
- "thumbnail": "http://your-domain.com/path/to/thumbnail.png",
- "is_ignored": true
}, - "sync_variants": [
- {
- "external_id": "12312414",
- "variant_id": 3001,
- "retail_price": "29.99",
- "is_ignored": true,
- "sku": "SKU1234",
- "files": [
- {
- "type": "default",
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "filename": "shirt1.png",
- "visible": true
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "availability_status": "active"
}
]
}
{- "code": 200,
- "result": {
- "id": 13,
- "external_id": "4235234213",
- "name": "T-shirt",
- "variants": 10,
- "synced": 10,
- "thumbnail_url": "https://your-domain.com/path/to/image.png",
- "is_ignored": true
}
}
Get information about a single Sync Product and its Sync Variants.
required | integer or string Sync Product ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
object (SyncProductInfo) |
curl --location --request GET 'https://api.printful.com/store/products/{sync_product_id}' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "sync_product": {
- "id": 13,
- "external_id": "4235234213",
- "name": "T-shirt",
- "variants": 10,
- "synced": 10,
- "thumbnail_url": "https://your-domain.com/path/to/image.png",
- "is_ignored": true
}, - "sync_variants": [
- {
- "id": 10,
- "external_id": "12312414",
- "sync_product_id": 71,
- "name": "Red T-Shirt",
- "synced": true,
- "variant_id": 3001,
- "retail_price": "29.99",
- "currency": "USD",
- "is_ignored": true,
- "sku": "SKU1234",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false,
- "stitch_count_tier": "stitch_tier_1"
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "main_category_id": 24,
- "warehouse_product_id": 3002,
- "warehouse_product_variant_id": 3002,
- "size": "XS",
- "color": "White",
- "availability_status": "active"
}
]
}
}
Deletes a Sync Product with all of its Sync Variants
required | integer or string Sync Product ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
object (SyncProductInfo) |
curl --location --request DELETE 'https://api.printful.com/store/products/161636638' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "sync_product": {
- "id": 13,
- "external_id": "4235234213",
- "name": "T-shirt",
- "variants": 10,
- "synced": 10,
- "thumbnail_url": "https://your-domain.com/path/to/image.png",
- "is_ignored": true
}, - "sync_variants": [
- {
- "id": 10,
- "external_id": "12312414",
- "sync_product_id": 71,
- "name": "Red T-Shirt",
- "synced": true,
- "variant_id": 3001,
- "retail_price": "29.99",
- "currency": "USD",
- "is_ignored": true,
- "sku": "SKU1234",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false,
- "stitch_count_tier": "stitch_tier_1"
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "main_category_id": 24,
- "warehouse_product_id": 3002,
- "warehouse_product_variant_id": 3002,
- "size": "XS",
- "color": "White",
- "availability_status": "active"
}
]
}
}
Modifies an existing Sync Product with its Sync Variants.
Please note that in the request body you only need to specify the fields that need to be changed. Furthermore, if you want to update existing sync variants, then in the sync variants array you must specify the IDs of all existing sync variants. All omitted existing sync variants will be deleted. All new sync variants without an ID will be created. See examples for more insights.
Rate limiting: Up to 10 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.
required | integer or string Sync Product ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
PUT request body
object (SyncProduct) Information about the SyncProduct | |
Array of SyncVariant (object) or SyncVariant (object) (SyncVariant) Information about the Sync Variants |
code | integer Response status code |
object (SyncProduct) Information about the SyncProduct |
{- "sync_product": {
- "external_id": "4235234213",
- "name": "T-shirt",
- "thumbnail": "http://your-domain.com/path/to/thumbnail.png",
- "is_ignored": true
}, - "sync_variants": [
- {
- "id": 10,
- "external_id": "12312414",
- "variant_id": 3001,
- "retail_price": "29.99",
- "is_ignored": true,
- "sku": "SKU1234",
- "files": [
- {
- "type": "default",
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "filename": "shirt1.png",
- "visible": true
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "availability_status": "active"
}
]
}
{- "code": 200,
- "result": {
- "id": 13,
- "external_id": "4235234213",
- "name": "T-shirt",
- "variants": 10,
- "synced": 10,
- "thumbnail_url": "https://your-domain.com/path/to/image.png",
- "is_ignored": true
}
}
Get information about a single Sync Variant.
required | integer or string Sync Variant ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
object (SyncVariant) Information about the SyncVariant |
{- "code": 200,
- "result": {
- "id": 10,
- "external_id": "12312414",
- "sync_product_id": 71,
- "name": "Red T-Shirt",
- "synced": true,
- "variant_id": 3001,
- "retail_price": "29.99",
- "currency": "USD",
- "is_ignored": true,
- "sku": "SKU1234",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false,
- "stitch_count_tier": "stitch_tier_1"
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "main_category_id": 24,
- "warehouse_product_id": 3002,
- "warehouse_product_variant_id": 3002,
- "size": "XS",
- "color": "White",
- "availability_status": "active"
}
}
Deletes a single Sync Variant.
required | integer or string Sync Variant ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
result | Array of arrays = 0 items |
curl --location --request DELETE 'https://api.printful.com/store/variants/1781126754' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": [ ]
}
Modifies an existing Sync Variant.
Please note that in the request body you only need to specify the fields that need to be changed. See examples for more insights.
required | integer or string Sync Variant ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
POST request body
id | integer Sync Variant ID. Please specify the IDs of all Sync Variants you wish to keep. |
external_id | string Variant ID from the Ecommerce platform |
variant_id | integer Printful Variant ID that this Sync Variant is synced to |
retail_price | string Retail price that this item is sold for |
is_ignored | boolean Indicates if this Sync Variant is ignored |
sku | string or null SKU of this Sync Variant |
Array of objects (SyncVariantFile) Array of attached printfiles / preview images | |
Array of objects (SyncVariantOption) Array of additional options for the configured product/variant See examples | |
availability_status | string Enum: "active" "discontinued" "out_of_stock" "temporary_out_of_stock" Indicates the status of the Sync Variant. |
code | integer Response status code |
object (SyncVariant) Information about the SyncVariant |
{- "id": 10,
- "external_id": "12312414",
- "variant_id": 3001,
- "retail_price": "29.99",
- "is_ignored": true,
- "sku": "SKU1234",
- "files": [
- {
- "type": "default",
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "filename": "shirt1.png",
- "visible": true
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "availability_status": "active"
}
{- "code": 200,
- "result": {
- "id": 10,
- "external_id": "12312414",
- "sync_product_id": 71,
- "name": "Red T-Shirt",
- "synced": true,
- "variant_id": 3001,
- "retail_price": "29.99",
- "currency": "USD",
- "is_ignored": true,
- "sku": "SKU1234",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false,
- "stitch_count_tier": "stitch_tier_1"
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "main_category_id": 24,
- "warehouse_product_id": 3002,
- "warehouse_product_variant_id": 3002,
- "size": "XS",
- "color": "White",
- "availability_status": "active"
}
}
Creates a new Sync Variant for an existing Sync Product (See examples).
required | integer or string Sync Product ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
POST request body
external_id | string Variant ID from the Ecommerce platform |
variant_id required | integer Printful Variant ID that this Sync Variant is synced to |
retail_price | string Retail price that this item is sold for |
is_ignored | boolean Indicates if this Sync Variant is ignored |
sku | string or null SKU of this Sync Variant |
required | Array of objects (SyncVariantFile) Array of attached printfiles / preview images |
Array of objects (SyncVariantOption) Array of additional options for the configured product/variant See examples | |
availability_status | string Enum: "active" "discontinued" "out_of_stock" "temporary_out_of_stock" Indicates the status of the Sync Variant. |
code | integer Response status code |
object (SyncVariant) Information about the SyncVariant |
{- "external_id": "12312414",
- "variant_id": 3001,
- "retail_price": "29.99",
- "is_ignored": true,
- "sku": "SKU1234",
- "files": [
- {
- "type": "default",
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "filename": "shirt1.png",
- "visible": true
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "availability_status": "active"
}
{- "code": 200,
- "result": {
- "id": 10,
- "external_id": "12312414",
- "sync_product_id": 71,
- "name": "Red T-Shirt",
- "synced": true,
- "variant_id": 3001,
- "retail_price": "29.99",
- "currency": "USD",
- "is_ignored": true,
- "sku": "SKU1234",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false,
- "stitch_count_tier": "stitch_tier_1"
}
], - "options": [
- {
- "id": "embroidery_type",
- "value": "flat"
}
], - "main_category_id": 24,
- "warehouse_product_id": 3002,
- "warehouse_product_variant_id": 3002,
- "size": "XS",
- "color": "White",
- "availability_status": "active"
}
}
The Product Templates API resource lets you retrieve the product templates information.
In case of a single template retrieval it is possible to get it by the External Product ID. In order to do this, the ID needs to be prepended with the '@' character. Here are the examples of how to get the template data by the Template ID and by the External Product ID.
GET /product-templates/11001 - reference by Printful Template ID
GET /product-templates/@988123 - reference by External ID
Returns a list of templates.
offset | integer Result set offset |
limit | integer Number of items per page (max 100) |
code | integer Response status code |
object (Product template) Information about the template | |
object (Paging) Paging information |
curl --location --request GET 'https://api.printful.com/product-templates' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "items": [
- {
- "id": 0,
- "product_id": 0,
- "external_product_id": "string",
- "title": "string",
- "available_variant_ids": [
- 0
], - "option_data": [
- {
- "id": "string",
- "value": [
- "string"
]
}
], - "colors": [
- {
- "color_name": "string",
- "color_codes": [ ]
}
], - "sizes": [
- "string"
], - "mockup_file_url": "string",
- "placements": [
- {
- "placement": "string",
- "display_name": "string",
- "technique_key": "SUBLIMATION",
- "technique_display_name": "Sublimation"
}
], - "created_at": 0,
- "updated_at": 0,
- "placement_option_data": [
- {
- "id": "embroidery_chest_left",
- "options": [
- {
- "id": "full_color",
- "value": true
}
]
}
]
}
]
}, - "paging": {
- "total": 100,
- "offset": 10,
- "limit": 100
}
}
Get information about a single product template
required | integer or string Template ID (integer) or External Product ID (if prefixed with @) |
code | integer Response status code |
object (Product template) Information about the template |
curl --location --request GET 'https://api.printful.com/product-templates/{template_id}' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "id": 0,
- "product_id": 0,
- "external_product_id": "string",
- "title": "string",
- "available_variant_ids": [
- 0
], - "option_data": [
- {
- "id": "string",
- "value": [
- "string"
]
}
], - "colors": [
- {
- "color_name": "string",
- "color_codes": [ ]
}
], - "sizes": [
- "string"
], - "mockup_file_url": "string",
- "placements": [
- {
- "placement": "string",
- "display_name": "string",
- "technique_key": "SUBLIMATION",
- "technique_display_name": "Sublimation"
}
], - "created_at": 0,
- "updated_at": 0,
- "placement_option_data": [
- {
- "id": "embroidery_chest_left",
- "options": [
- {
- "id": "full_color",
- "value": true
}
]
}
]
}
}
Delete product template by ID or External Product ID
required | integer or string Template ID (integer) or External Product ID (if prefixed with @) |
code | integer Response status code |
object |
curl --location --request DELETE 'https://api.printful.com/product-templates/{template_id}' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "success": true
}
}
The Orders API is the most important part of the Printful API - it allows you to create new orders and confirm them for fulfillment.
Important: Jewelry products are not supported via API.
Each order will go through different states while being processed. The following order status types indicate those states:
draft | The order is created but is not yet submitted for fulfillment. You still can edit it and confirm later. |
pending | The order has been submitted for fulfillment, but is not yet accepted for fulfillment. You can still cancel the order if you need. |
failed | Order was submitted for fulfillment but was returned for review because of an error (problem with address, missing printfiles, charging has failed, etc.). |
canceled | The order has been canceled and can no longer be processed. If the order was charged then the amount has been returned to your credit card. |
inprocess | The order is being fulfilled and can no longer be cancelled or modified. Contact customer support if there are any issues with the order at this point. |
onhold | The order has encountered a problem during the fulfillment that needs to be resolved together with Printful customer service before fulfillment can continue. |
partial | The order is partially fulfilled (some items are shipped already, the rest will follow) |
fulfilled | All items have been shipped successfully |
archived | The order has been archived and hidden from the UI |
To sum up, the API allows you to create orders with status draft
and then move them to state pending
(both steps can
be done with a single action). You are only charged for orders that have been confirmed. If the order encounters a
problem after it has been submitted, then it is moved to the failed state so that the problem can be fixed and the order
can be resubmitted.
Most of the times, when you submit an order, we'll perform the cost calculation and return it in the response.
However, we might not be able to calculate all the costs immediately, for example if the order contains a new advanced embroidery design. If that's the case, we'll automatically put your order on hold, calculate the order costs once it's possible, and then remove the order from hold.
Such an order will return to a draft status (even if it was created with the auto-confirm option) and will need to be confirmed.
You can subscribe to the order_remove_hold
event (see Webhook API) to be notified when the order is removed from hold.
External ID is an optional feature that allows you to link your Printful order with the Order ID from your system without the need to store additional data on your side. External ID can be up to 32 characters long and contain digits, Latin alphabet letters, dashes and underscores, however it is recommended to use integer numbers. Each order's External ID must be unique within the store.
To use the External ID feature, you just add the external_id
attribute when creating the order. Later, when you need
to access the order through the API, you can reference it by both the Order ID and by External ID (if you prefix it with
the @
symbol).
GET /orders/11001 - reference by Printful Order ID
GET /orders/@988123 - reference by External ID
GET /orders/@AA123123 - reference by External ID
You can assign the external_id
attribute to line items as well. In this case they have to be unique per order.
There are three general ways to specify a product’s variant when creating, updating or estimating an order:
(A) Using an existing product variant (sync variant) in your Printful store or warehouse. To specify the existing
product please use its sync_variant_id
or external_variant_id
, or warehouse_product_variant_id
.
Example using Sync Variant ID Example using External Variant ID
(B) Using a Catalog API variant without adding a product to the store. This method can be used when a Printful store
has no products in it. To construct a variant on-the-fly retrieve a specific variant_id
from the
Catalog API together with print files and an additional options.
(C) Using an existing template ID. This method can be used when a Printful store has assigned templates without the
need to create products. To create an order please use the product_template_id
and variant_id
that will be added to
the order.
There are two ways to assign a print file to the item. One is to specify the File ID if the file already exists in the file library of the authorized store:
...
"files": [
{
"id": 12345
},
],
...
The second and the most convenient method is to specify the file URL. If a file with the same URL already exists, it will be reused.
...
"files": [
{
"url": "http://example.com/t-shirts/123/front.pdf"
},
],
...
You can specify the image position inside the print area by providing a position object.
Important
limit_to_print_area
and set it to: false
.limit_to_print_area
determines if the image can cross the print area border. If limit_to_print_area
is set to true
then the request will result in 400 Bad Request
with "Invalid position" in error.message
once the image crosses the print area borders. If limit_to_print_area
is set to false
then it will be possible to place image partially or fully outside the print area.Steps
1.Retrieve printfile dimensions Printfiles
...
"printfiles":
[
{
"printfile_id": 1,
"width": 1800,
"height": 2400,
"dpi": 150,
"fill_mode": "fit",
"can_rotate": false
}
],
...
2.Specify file position for specific print placement while creating an order. Use items
-> files
-> position
object as in the example:
...
"items": [
{
"variant_id":4011,
"quantity":"1",
"files": [
{
"type": "front",
"url": "http://example.com/t-shirts/123/front.pdf",
"position": {
"area_width": 1800,
"area_height": 2400,
"width": 1800,
"height": 1800,
"top": 300,
"left": 0,
"limit_to_print_area": true
}
}
]
}
]
...
Position | Mockup | Payload |
Top left |
|
|
Top middle |
|
|
Top right |
|
|
Middle |
|
|
Bottom left |
|
|
Bottom middle |
|
|
Bottom right |
|
Each item in the order has to be linked with one or multiple files. The available file types for each product are available from the Catalog API.
You can add one file for each type by specifying the type
attribute. For the default
type, this attribute can be
skipped.
...
"files":[
{
"type": "default",
"url": "http://example.com/t-shirts/123/front.pdf"
},
{
"type": "back"
"url": "http://example.com/t-shirts/123/back.pdf"
},
{
"type": "preview"
"url": "http://example.com/t-shirts/123/preview.png"
}
],
...
Remember that using additional files can increase the price of the item.
Orders API allows also creating orders based on the product template created in the Printful account without the need to add the product to the Printful store.
To retrieve available templates for your account please use the Products Templates API.
To create an order from a template you need to specify a variant or variants that will be added to the order. It is
possible to use multiple templates with different variants in one request. To achieve that please use the items
object
below:
...
"items": [
{
"variant_id": 4012,
"quantity": 1,
"product_template_id": 123456789
},
{
"variant_id": 1,
"quantity": 2,
"product_template_id": 11235813
},
]
...
Important note: you can only create orders from templates for variant IDs from the Catalog API.
More examples are available here.
Printful allows you to specify your retail costs for the order so that the packing slip for international orders can
contain your correct retail prices. To enable retail costs, each item in the order has to contain the retail_price
attribute. You can also specify a custom discount sum, shipping costs and taxes in the retail_costs
object when
creating the order. If the retail costs are missing, the packing slip will contain the Printful prices instead.
Printful previously allowed customers to upload a fully customized inside label. Since these labels had to contain specific information about fabric composition, manufacturing, etc. to meet the legal requirements, users usually encountered issues to get their labels printed.
Inside labels are printed on the inside of the garment and require the removal of the original manufacturer's tag. They're only available for apparel with tear-away labels. An inside label must include the country of manufacturing origin, original garment size, and material information. To use our native label template you only need to upload a graphic (such as your brand's logo). The mandatory content will be generated and placed automatically.
...
"files":[
{
"type": "label_inside",
"url": "http://example.com/logo/123/image.jpg",
"options": [{
"id": "template_type",
"value": "native"
}]
},
],
...
Printful previously supported fully customized inside labels. These have now been deprecated. The ability to create orders with fully customized inside labels has been limited to only users who were actively using them in their stores before April 2020. This feature is no longer accessible to new users.
Embroidery is a technique which uses colored threads, sewn into a product, to recreate provided design. In order to use embroidery technique you first need to check if selected product support embroidery technique.
In order to do that you need to use Catalog API to determine if the selected product or variant contains EMBROIDERY
technique.
"techniques": [
{
"key": "EMBROIDERY",
"display_name": "Embroidery",
"is_default": true
}
]
After that you need to also get list of available embroidery placements. Those are listed under file
property with embroidery_
prefix. You can get list of all available placements in Placements.
"files": [
{
"id": "default",
"type": "embroidery_front",
"title": "Front",
"additional_price": null
},
{
"id": "back",
"type": "embroidery_back",
"title": "Back",
"additional_price": "3.75"
},
{
"id": "left",
"type": "embroidery_left",
"title": "Left side",
"additional_price": "3.75"
},
{
"id": "right",
"type": "embroidery_right",
"title": "Right side",
"additional_price": "3.75"
},
{
"id": "preview",
"type": "mockup",
"title": "Mockup",
"additional_price": null
}
]
To create an order using embroidery technique you can:
Finally, you can make an order using embroidery technique See example. Depending on the placement that you've used you need to specify the correct thread color option.
The packing slip fields can be configured at the store level and overridden for a specific order.
The packing slip settings can be found in Dashboard at Settings > Stores > Branding > Packing slip section.
To override the packing slip settings for the order, you can use packing_slip
or gift
fields.
Below you can find an example or a packing slip for a shipment with explained fields.
Field annotations:
packing_slip.logo_url
field.packing_slip.store_name
.packing_slip.phone
field.packing_slip.email
field.gift
field was provided in the order request.packing_slip.custom_order_id
field.packing_slip.message
field.See the examples section for more sample requests on how Orders API can be used in different scenarios.
Stickers can have a different border color which can be set by using the thread_colors_outline
option.
This option is available in options
for stickers. To showcase the usage we will use the order flow
which will create order with a sticker that will have a red border color:
Endpoint POST https://api.printful.com/orders
{
"shipping": "STANDARD",
"recipient": {
"name": "John Smith",
"address1": "19749 Dearborn St",
"city": "Chatsworth",
"country_code": "US",
"state_code": "CA",
"zip": "91311"
},
"items": [
{
"variant_id": 10163,
"files": [
{
"type": "default",
"url": "https://www.printful.com/static/images/layout/printful-logo.png"
}
],
"options": [
{
"id": "custom_border_color",
"value": "#FF0000"
}
]
}
]
}
Returns list of order objects from your store
status | string Filter by order status |
offset | integer Result set offset |
limit | integer Number of items per page (max 100) |
code | integer Response status code |
object (Paging) Paging information | |
Array of objects (Order) |
curl --location --request GET 'https://api.printful.com/orders' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "paging": {
- "total": 100,
- "offset": 10,
- "limit": 100
}, - "result": [
- {
- "id": 13,
- "external_id": "4235234213",
- "store": 10,
- "status": "draft",
- "shipping": "STANDARD",
- "shipping_service_name": "Flat Rate (3-4 business days after fulfillment)",
- "created": 1602607640,
- "updated": 1602607640,
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "branding_items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "incomplete_items": [
- {
- "name": "Red T-Shirt",
- "quantity": 1,
- "sync_variant_id": 70,
- "external_variant_id": "external-id",
- "external_line_item_id": "external-line-item-id"
}
], - "costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "digitization": "0.00",
- "additional_fee": "0.00",
- "fulfillment_fee": "0.00",
- "retail_delivery_fee": "0.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "pricing_breakdown": [
- {
- "customer_pays": "3.75",
- "printful_price": "6",
- "profit": "-2.25",
- "currency_symbol": "USD"
}
], - "shipments": [
- {
- "id": 10,
- "carrier": "FEDEX",
- "service": "FedEx SmartPost",
- "tracking_number": 0,
- "created": 1588716060,
- "ship_date": "2020-05-05",
- "shipped_at": 1588716060,
- "reshipment": false,
- "items": [
- {
- "item_id": 1,
- "quantity": 1,
- "picked": 1,
- "printed": 1
}
]
}
], - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
]
}
Creates a new order and optionally submits it for fulfillment (See examples)
confirm | boolean Automatically submit the newly created order for fulfillment (skip the Draft phase) |
update_existing | boolean Try to update existing order if an order with the specified external_id already exists |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
POST request body
external_id | string or null Order ID from the external system |
shipping | string Shipping method. Defaults to 'STANDARD' |
required | object (Address) Information about the address |
required | Array of objects (Item) Array of items in the order |
object (OrderRetailCosts) Retail costs that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the | |
object (OrderGift) Optional gift message for the packing slip | |
OrderPackingSlip (object) or OrderPackingSlip (object) or OrderPackingSlip (object) or OrderPackingSlip (object) (OrderPackingSlip) Custom packing slip for this order. Example of a packing slip with explained fields can be found here. |
code | integer Response status code |
object (Order) Information about the Order |
{- "external_id": "4235234213",
- "shipping": "STANDARD",
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "external_product_id": "template-123",
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "filename": "shirt1.png",
- "visible": true,
- "position": {
- "area_width": 1800,
- "area_height": 2400,
- "width": 1800,
- "height": 1800,
- "top": 300,
- "left": 0,
- "limit_to_print_area": true
}
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00"
}, - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
{- "code": 200,
- "result": {
- "id": 13,
- "external_id": "4235234213",
- "store": 10,
- "status": "draft",
- "shipping": "STANDARD",
- "shipping_service_name": "Flat Rate (3-4 business days after fulfillment)",
- "created": 1602607640,
- "updated": 1602607640,
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "branding_items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "incomplete_items": [
- {
- "name": "Red T-Shirt",
- "quantity": 1,
- "sync_variant_id": 70,
- "external_variant_id": "external-id",
- "external_line_item_id": "external-line-item-id"
}
], - "costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "digitization": "0.00",
- "additional_fee": "0.00",
- "fulfillment_fee": "0.00",
- "retail_delivery_fee": "0.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "pricing_breakdown": [
- {
- "customer_pays": "3.75",
- "printful_price": "6",
- "profit": "-2.25",
- "currency_symbol": "USD"
}
], - "shipments": [
- {
- "id": 10,
- "carrier": "FEDEX",
- "service": "FedEx SmartPost",
- "tracking_number": 0,
- "created": 1588716060,
- "ship_date": "2020-05-05",
- "shipped_at": 1588716060,
- "reshipment": false,
- "items": [
- {
- "item_id": 1,
- "quantity": 1,
- "picked": 1,
- "printed": 1
}
]
}
], - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
}
Returns order data by ID or External ID.
required | string or integer Order ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
object (Order) Information about the Order |
curl --location --request GET 'https://api.printful.com/orders/{order_id}' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "id": 13,
- "external_id": "4235234213",
- "store": 10,
- "status": "draft",
- "shipping": "STANDARD",
- "shipping_service_name": "Flat Rate (3-4 business days after fulfillment)",
- "created": 1602607640,
- "updated": 1602607640,
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "branding_items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "incomplete_items": [
- {
- "name": "Red T-Shirt",
- "quantity": 1,
- "sync_variant_id": 70,
- "external_variant_id": "external-id",
- "external_line_item_id": "external-line-item-id"
}
], - "costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "digitization": "0.00",
- "additional_fee": "0.00",
- "fulfillment_fee": "0.00",
- "retail_delivery_fee": "0.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "pricing_breakdown": [
- {
- "customer_pays": "3.75",
- "printful_price": "6",
- "profit": "-2.25",
- "currency_symbol": "USD"
}
], - "shipments": [
- {
- "id": 10,
- "carrier": "FEDEX",
- "service": "FedEx SmartPost",
- "tracking_number": 0,
- "created": 1588716060,
- "ship_date": "2020-05-05",
- "shipped_at": 1588716060,
- "reshipment": false,
- "items": [
- {
- "item_id": 1,
- "quantity": 1,
- "picked": 1,
- "printed": 1
}
]
}
], - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
}
Cancels pending order or draft. Charged amount is returned to the store owner's credit card.
required | string or integer Order ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
object (Order) Information about the Order |
curl --location --request DELETE 'https://api.printful.com/orders/{order_id}' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "id": 13,
- "external_id": "4235234213",
- "store": 10,
- "status": "draft",
- "shipping": "STANDARD",
- "shipping_service_name": "Flat Rate (3-4 business days after fulfillment)",
- "created": 1602607640,
- "updated": 1602607640,
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "branding_items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "incomplete_items": [
- {
- "name": "Red T-Shirt",
- "quantity": 1,
- "sync_variant_id": 70,
- "external_variant_id": "external-id",
- "external_line_item_id": "external-line-item-id"
}
], - "costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "digitization": "0.00",
- "additional_fee": "0.00",
- "fulfillment_fee": "0.00",
- "retail_delivery_fee": "0.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "pricing_breakdown": [
- {
- "customer_pays": "3.75",
- "printful_price": "6",
- "profit": "-2.25",
- "currency_symbol": "USD"
}
], - "shipments": [
- {
- "id": 10,
- "carrier": "FEDEX",
- "service": "FedEx SmartPost",
- "tracking_number": 0,
- "created": 1588716060,
- "ship_date": "2020-05-05",
- "shipped_at": 1588716060,
- "reshipment": false,
- "items": [
- {
- "item_id": 1,
- "quantity": 1,
- "picked": 1,
- "printed": 1
}
]
}
], - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
}
Updates unsubmitted order and optionally submits it for the fulfillment.
Note that you need to post only the fields that need to be changed, not all required fields.
If items array is given in the update data, the items will be:
a) updated, if the update data contains the item id or external_id parameter that alreay exists
b) deleted, if the request doesn't contain the item with previously existing id
c) created as new if the id is not given or does not already exist
required | string or integer Order ID (integer) or External ID (if prefixed with @) |
confirm | boolean Automatically submit the newly created order for fulfillment (skip the Draft phase) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
POST request body
external_id | string or null Order ID from the external system |
shipping | string Shipping method. Defaults to 'STANDARD' |
required | object (Address) Information about the address |
required | Array of objects (Item) Array of items in the order |
object (OrderRetailCosts) Retail costs that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the | |
object (OrderGift) Optional gift message for the packing slip | |
OrderPackingSlip (object) or OrderPackingSlip (object) or OrderPackingSlip (object) or OrderPackingSlip (object) (OrderPackingSlip) Custom packing slip for this order. Example of a packing slip with explained fields can be found here. |
code | integer Response status code |
object (Order) Information about the Order |
{- "external_id": "4235234213",
- "shipping": "STANDARD",
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "external_product_id": "template-123",
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "filename": "shirt1.png",
- "visible": true,
- "position": {
- "area_width": 1800,
- "area_height": 2400,
- "width": 1800,
- "height": 1800,
- "top": 300,
- "left": 0,
- "limit_to_print_area": true
}
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00"
}, - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
{- "code": 200,
- "result": {
- "id": 13,
- "external_id": "4235234213",
- "store": 10,
- "status": "draft",
- "shipping": "STANDARD",
- "shipping_service_name": "Flat Rate (3-4 business days after fulfillment)",
- "created": 1602607640,
- "updated": 1602607640,
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "branding_items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "incomplete_items": [
- {
- "name": "Red T-Shirt",
- "quantity": 1,
- "sync_variant_id": 70,
- "external_variant_id": "external-id",
- "external_line_item_id": "external-line-item-id"
}
], - "costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "digitization": "0.00",
- "additional_fee": "0.00",
- "fulfillment_fee": "0.00",
- "retail_delivery_fee": "0.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "pricing_breakdown": [
- {
- "customer_pays": "3.75",
- "printful_price": "6",
- "profit": "-2.25",
- "currency_symbol": "USD"
}
], - "shipments": [
- {
- "id": 10,
- "carrier": "FEDEX",
- "service": "FedEx SmartPost",
- "tracking_number": 0,
- "created": 1588716060,
- "ship_date": "2020-05-05",
- "shipped_at": 1588716060,
- "reshipment": false,
- "items": [
- {
- "item_id": 1,
- "quantity": 1,
- "picked": 1,
- "printed": 1
}
]
}
], - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
}
Approves for fulfillment an order that was saved as a draft. Store owner's credit card is charged when the order is submitted for fulfillment.
required | string or integer Order ID (integer) or External ID (if prefixed with @) |
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
code | integer Response status code |
object (Order) Information about the Order |
curl --location --request POST 'https://api.printful.com/orders/{order_id}/confirm' \ --header 'Authorization: Bearer {oauth_token}'
{- "code": 200,
- "result": {
- "id": 13,
- "external_id": "4235234213",
- "store": 10,
- "status": "draft",
- "shipping": "STANDARD",
- "shipping_service_name": "Flat Rate (3-4 business days after fulfillment)",
- "created": 1602607640,
- "updated": 1602607640,
- "recipient": {
- "name": "John Smith",
- "company": "John Smith Inc",
- "address1": "19749 Dearborn St",
- "address2": "string",
- "city": "Chatsworth",
- "state_code": "CA",
- "state_name": "California",
- "country_code": "US",
- "country_name": "United States",
- "zip": "91311",
- "phone": "2312322334",
- "tax_number": "123.456.789-10"
}, - "items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "branding_items": [
- {
- "id": 1,
- "external_id": "item-1",
- "variant_id": 1,
- "sync_variant_id": 1,
- "external_variant_id": "variant-1",
- "warehouse_product_variant_id": 1,
- "product_template_id": 1,
- "quantity": 1,
- "price": "13.00",
- "retail_price": "13.00",
- "name": "Enhanced Matte Paper Poster 18×24",
- "product": {
- "variant_id": 3001,
- "product_id": 301,
- "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / 4XL)"
}, - "files": [
- {
- "type": "default",
- "id": 10,
- "url": "https://www.example.com/files/tshirts/example.png",
- "options": [
- {
- "id": "template_type",
- "value": "native"
}
], - "hash": "ea44330b887dfec278dbc4626a759547",
- "filename": "shirt1.png",
- "mime_type": "image/png",
- "size": 45582633,
- "width": 1000,
- "height": 1000,
- "dpi": 300,
- "status": "ok",
- "created": 1590051937,
- "visible": true,
- "is_temporary": false
}
], - "options": [
- {
- "id": "OptionKey",
- "value": "OptionValue"
}
], - "sku": null,
- "discontinued": true,
- "out_of_stock": true
}
], - "incomplete_items": [
- {
- "name": "Red T-Shirt",
- "quantity": 1,
- "sync_variant_id": 70,
- "external_variant_id": "external-id",
- "external_line_item_id": "external-line-item-id"
}
], - "costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "digitization": "0.00",
- "additional_fee": "0.00",
- "fulfillment_fee": "0.00",
- "retail_delivery_fee": "0.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "retail_costs": {
- "currency": "USD",
- "subtotal": "10.00",
- "discount": "0.00",
- "shipping": "5.00",
- "tax": "0.00",
- "vat": "0.00",
- "total": "15.00"
}, - "pricing_breakdown": [
- {
- "customer_pays": "3.75",
- "printful_price": "6",
- "profit": "-2.25",
- "currency_symbol": "USD"
}
], - "shipments": [
- {
- "id": 10,
- "carrier": "FEDEX",
- "service": "FedEx SmartPost",
- "tracking_number": 0,
- "created": 1588716060,
- "ship_date": "2020-05-05",
- "shipped_at": 1588716060,
- "reshipment": false,
- "items": [
- {
- "item_id": 1,
- "quantity": 1,
- "picked": 1,
- "printed": 1
}
]
}
], - "gift": {
- "subject": "To John",
- "message": "Have a nice day"
}, - "packing_slip": {
- "phone": "+371 28888888",
- "message": "Message on packing slip",
- "logo_url": "http://www.your-domain.com/packing-logo.png",
- "store_name": "Your store name",
- "custom_order_id": "kkk2344lm"
}
}
}
Calculates the estimated order costs including item costs, print costs (back prints, inside labels etc.), shipping and taxes
X-PF-Store-Id | string Use this to specify which store you want to use (required only for account level token). The store IDs can be retrieved with the Get basic information about stores endpoint. |
POST request body
external_id | string or null Order ID from the external system |
shipping | string Shipping method. Defaults to 'STANDARD' |
required | object (Address) Information about the address |
required | Array of objects (Item) Array of items in the order |
object (OrderRetailCosts) Retail costs that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the | |
object (OrderGift) Optional gift message for the packing slip | |
OrderPackingSlip (object) or OrderPackingSlip (object) or OrderPackingSlip (object) or OrderPackingSlip (object) (OrderPackingSlip) Custom packing slip for this order. Example of a packing slip with explained fields can be found here. |
code | integer Response status code |
object |
{- "external_id": "4235234213",
- "shipping": "STANDARD",
- "recipient": {
- "name"