Products API

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

To configure products and variants at a Printful store based on Shopify, WooCommerce or another supported platform, please see Ecommerce Platform Sync API.

To manage Warehouse products, please see Warehouse Products API.

The basics

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.

Assigning a blank product variant

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

Assigning a single print file

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;

{
    ...
    "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.

External ID

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.

Native inside label

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 depracated. The ability to create orders with fully customized inside labels has been limited to only users who where actively using them in their stores before April 2020. This feature is no longer accessible to new users.

Get a list of Sync Products

GET https://api.printful.com/store/products

Returns a list of Sync Product objects from your custom Printful store.
Input parameters:
status string Filter by item status (synced/unsynced/all). If only some of the variants are synced,the product is returned by both unsynced and synced filters
search string Product search needle
offset integer Result set offset
limit integer Number of items per page (max 100)
Response format:
code integer Response status code 200
result SyncProduct [ ]
id integer Sync Product ID
external_id string Product ID from the Ecommerce platform
name string Product name
variants integer Total number of Sync Variants belonging to this product
synced integer Number of synced Sync Variants belonging to this product
thumbnail_url string Thumbnail image for the product
paging Paging Paging information
total integer Total number of items available
offset integer Current result set page offset
limit integer Max number of items per page
API key
status Filter by item status (synced/unsynced/all). If only some of the variants are synced,the product is returned by both unsynced and synced filters
search Product search needle
offset Result set offset
limit Number of items per page (max 100)
Execute
Response data: 
    {
        "code": 200,
        "result": [
            {
                "id": 79348721,
                "external_id": "e9460f6c67",
                "name": "API product",
                "variants": 2,
                "synced": 2
            }
        ],
        "extra": [],
        "paging": {
            "total": 1,
            "offset": 0,
            "limit": 20
        },
        "debug": []
    }

Create a new Sync Product

POST https://api.printful.com/store/products

Creates a new Sync Product together with its Sync Variants
Input parameters:
Request body RequestProductBody POST request body
sync_product RequestProduct Information about the Sync Product
external_id string Product ID from your Ecommerce platform
name string Product name
thumbnail string Thumbnail image URL. Although we do not limit thumbnail image size, we recommend to keep it reasonably small.
sync_variants RequestVariant [ ] Information about the Sync Variants
external_id string Variant ID from the Ecommerce platform
variant_id integer Printful Variant ID that this Sync Variant is synced to
retail_price float Retail price that this item is sold for
sku string SKU of this Sync Variant
files RequestFile [ ] Array of attached print files
type string Role of the file in the order
id integer File ID

* Required if no URL given
url string Source URL where the file is downloaded from

* Required if no File ID given
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
Response format:
code integer Response status code 200
result RequestProductResponse
id integer Sync Product id
external_id string Sync Product ID from the external system
name string Sync Product name
variants integer Total number of variants in Sync Product
synced integer Total number of Sync variants in Sync Product
API key
Request body
Execute
Request body: 
    {
        "sync_product": {
            "name": "API product Bella",
            "thumbnail": "https://example.com/image.jpg"
        },
        "sync_variants": [
            {
                "retail_price": "21.00",
                "variant_id": 4011,
                "files": [
                    {
                        "url": "https://example.com/image.jpg"
                    },
                    {
                        "type": "back",
                        "url": "https://example.com/image.jpg"
                    }
                ]
            },
            {
                "retail_price": "21.00",
                "variant_id": 4012,
                "files": [
                    {
                        "url": "https://example.com/image.jpg"
                    },
                    {
                        "type": "back",
                        "url": "https://example.com/image.jpg"
                    }
                ]
            }
        ]
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 79348732,
            "external_id": "5bd9947c709b34",
            "name": "API product Bella",
            "variants": 2,
            "synced": 2
        },
        "extra": [],
        "debug": []
    }
Create a new sync product with native inside label.
Request body: 
    {
        "sync_product": {
            "name": "API product custom"
        },
        "sync_variants": [
            {
                "retail_price": "19.00",
                "variant_id": 9575,
                "files": [
                    {
                        "type": "front",
                        "url": "https://picsum.photos/200/300"
                    },{
                        "type": "label_inside",
                        "url": "https://picsum.photos/200/300",
                        "options": [{
                            "id": "template_type",
                            "value": "native"
                        }]
                    }
                ],
                "options": [
                    {
                        "id": "embroidery_type",
                        "value": "flat"
                    },
                    {
                        "id": "thread_colors",
                        "value": []
                    },
                    {
                        "id": "thread_colors_3d",
                        "value": []
                    },
                    {
                        "id": "thread_colors_chest_left",
                        "value": []
                    }
                ]
            }
        ]
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 166266931,
            "external_id": "5e8db0013cf026",
            "name": "API product custom",
            "variants": 1,
            "synced": 1,
            "thumbnail_url": null
        },
        "extra": [],
        "debug": []
    }

Get information about a single Sync Product and its Sync Variants

GET https://api.printful.com/store/products/{id}

Returns information about an existing Sync Product together with a list of its Sync Variants.
Input parameters:
id integer / string Sync Product ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result SyncProductInfo
sync_product SyncProduct Information about the selected product
id integer Sync Product ID
external_id string Product ID from the Ecommerce platform
name string Product name
variants integer Total number of Sync Variants belonging to this product
synced integer Number of synced Sync Variants belonging to this product
thumbnail_url string Thumbnail image for the product
sync_variants SyncVariant [ ] Array of Sync Variants available for the selected product
id integer Sync Variant ID
external_id string Variant ID from the Ecommerce platform
sync_product_id integer Sync Product ID that this variant belongs to
name string Sync Variant name
synced boolean Indicates if this Sync Variant is properly linked with Printful product
variant_id integer Printful Variant ID that this Sync Variant is synced to
warehouse_product_variant_id integer Warehousing variant id. If sync variant is connected with a warehousing item, this is its id
retail_price float Retail price that this item is sold for
sku string SKU of this Sync Variant
currency string Currency in which prices are returned
product ProductVariant Short information about the Printful Product and Variant that this Sync Variant is synced to
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer 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.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
API key
id Sync Product ID (integer) or External ID (if prefixed with @)
Execute
Response data: 
    {
        "code": 200,
        "result": {
            "sync_product": {
                "id": 79348721,
                "external_id": "e9460f6c67",
                "name": "API product",
                "variants": 2,
                "synced": 2
            },
            "sync_variants": [
                {
                    "id": 866914574,
                    "external_id": "5bd967595a1174",
                    "sync_product_id": 79348721,
                    "name": "API product",
                    "synced": true,
                    "variant_id": 4011,
                    "retail_price": "18.00",
                    "currency": "USD",
                    "product": {
                        "variant_id": 4011,
                        "product_id": 71,
                        "image": "https://s3.dev.printful.com/products/71/4012_1517927381.jpg",
                        "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)"
                    },
                    "files": [
                        {
                            "id": 76564075,
                            "type": "default",
                            "hash": "7d6a2367c1e338750e68dc66b20cba1a",
                            "url": "https://picsum.photos/200/300",
                            "filename": "76564075.jpg",
                            "mime_type": "image/jpeg",
                            "size": 8245,
                            "width": 200,
                            "height": 300,
                            "dpi": null,
                            "status": "ok",
                            "created": 1539341673,
                            "thumbnail_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png",
                            "preview_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png",
                            "visible": true
                        },
                        {
                            "id": 76564075,
                            "type": "back",
                            "hash": "7d6a2367c1e338750e68dc66b20cba1a",
                            "url": "https://picsum.photos/200/300",
                            "filename": "76564075.jpg",
                            "mime_type": "image/jpeg",
                            "size": 8245,
                            "width": 200,
                            "height": 300,
                            "dpi": null,
                            "status": "ok",
                            "created": 1539341673,
                            "thumbnail_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png",
                            "preview_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png",
                            "visible": true
                        }
                    ],
                    "options": [
                        {
                            "id": "embroidery_type",
                            "value": "flat"
                        },
                        {
                            "id": "thread_colors",
                            "value": []
                        },
                        {
                            "id": "thread_colors_3d",
                            "value": []
                        },
                        {
                            "id": "thread_colors_chest_left",
                            "value": []
                        }
                    ]
                },
                {
                    "id": 866914580,
                    "external_id": "5bd96ea4a381f8",
                    "sync_product_id": 79348721,
                    "name": "API product",
                    "synced": true,
                    "variant_id": 4011,
                    "retail_price": "21.00",
                    "currency": "USD",
                    "product": {
                        "variant_id": 4011,
                        "product_id": 71,
                        "image": "https://s3.dev.printful.com/products/71/4012_1517927381.jpg",
                        "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)"
                    },
                    "files": [
                        {
                            "id": 76564390,
                            "type": "default",
                            "hash": "77440392f60d2346a1bf690c1564d973",
                            "url": "https://i.etsystatic.com/17947654/r/il/3a0750/1565927694/il_570xN.1565927694_gfxu.jpg",
                            "filename": "il_570xN.1565927694_gfxu.jpg",
                            "mime_type": "image/jpeg",
                            "size": 70053,
                            "width": 570,
                            "height": 570,
                            "dpi": null,
                            "status": "ok",
                            "created": 1540982496,
                            "thumbnail_url": "https://s3.dev.printful.com/files/774/77440392f60d2346a1bf690c1564d973_thumb.png",
                            "preview_url": "https://s3.dev.printful.com/files/774/77440392f60d2346a1bf690c1564d973_preview.png",
                            "visible": true
                        },
                        {
                            "id": 76564159,
                            "type": "back",
                            "hash": "ebd559858e5703088de8900ce99c37d3",
                            "url": "https://picsum.photos/200/300?image=2",
                            "filename": "76564159.jpg",
                            "mime_type": "image/jpeg",
                            "size": 11246,
                            "width": 200,
                            "height": 300,
                            "dpi": null,
                            "status": "ok",
                            "created": 1540797879,
                            "thumbnail_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_thumb.png",
                            "preview_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_preview.png",
                            "visible": true
                        },
                        {
                            "id": 76564391,
                            "type": "preview",
                            "hash": "a0b4fa4e51f3feeee7a5f14260a257ea",
                            "url": null,
                            "filename": "mockup-fafde22d.png",
                            "mime_type": "image/png",
                            "size": 222824,
                            "width": 600,
                            "height": 600,
                            "dpi": 72,
                            "status": "ok",
                            "created": 1540982574,
                            "thumbnail_url": "https://s3.dev.printful.com/files/a0b/a0b4fa4e51f3feeee7a5f14260a257ea_thumb.png",
                            "preview_url": "https://s3.dev.printful.com/files/a0b/a0b4fa4e51f3feeee7a5f14260a257ea_preview.png",
                            "visible": false
                        }
                    ],
                    "options": [
                        {
                            "id": "embroidery_type",
                            "value": "flat"
                        },
                        {
                            "id": "thread_colors",
                            "value": []
                        },
                        {
                            "id": "thread_colors_3d",
                            "value": []
                        },
                        {
                            "id": "thread_colors_chest_left",
                            "value": []
                        }
                    ]
                }
            ]
        },
        "extra": [],
        "debug": []
    }

Delete a Sync Product

DELETE https://api.printful.com/store/products/{id}

Deletes a Sync Product with all of its Sync Variants
Input parameters:
id integer / string Sync Product ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result ProductInfo
product Product Information about the selected product
id integer Product ID
type string Product type identifier
type_name string Product type name
brand string Brand name
model string Model name
image string URL of a sample image for this product
variant_count integer Number of available variants for this product
currency string Currency in which prices are returned
files FileType [ ] Definitions of Print/Mockup file categories that can be attached to this product
id string Deprecated file type identifier. Please use type field instead!
type string File type identifier - use this to specify a file's purpose when creating an order
title string Display name
additional_price string Additional price when this print file type is used
options OptionType [ ] Definitions of additional options that are available for this product
id string Option identifier - use this to specify the option when creating an order
title string Display name
type string Data type of this option (currently only 'bool' is supported)
values array Option values - [key, value] map
additional_price string Additional price when this option is used
additional_price_breakdown array Additional price breakdown by type - [key, value] map
is_discontinued boolean If product is disabled in push
avg_fulfillment_time float Average number of days for order to be fulfilled
description string Product description
variants Variant [ ] Array of Variants available for the selected product
id integer Variant ID, use this to specify the product when creating orders
product_id integer ID of the product that this variant belongs to
name string Display name
size string Item size
color string Item color
color_code string Hexadecimal RGB color code. May not exactly reflect the real-world color
color_code2 string Secondary hexadecimal RGB color code. May not exactly reflect the real-world color
image string URL of a preview image for this variant
price string Variant's price (can change depending on print files and optional settings)
in_stock boolean Stock availability of this variant
availability_regions array Map of [region code, region name] of regions where the variant is available for fulfillment
availability_status AvailabilityStatus [ ] Detailed stock status per region
region string Region code
status string Stock status. Possible values include: 'in_stock' - available for fulfillment, 'stocked_on_demand' - available for fulfillment, 'discontinued' - permanently unavailable, 'out_of_stock' - temporarily unavailable
API key
id Sync Product ID (integer) or External ID (if prefixed with @)
Execute

Modify a Sync Product

PUT https://api.printful.com/store/products/{id}

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.
Input parameters:
id integer / string Sync Product ID (integer) or External ID (if prefixed with @)
Request body PutRequestProductBody PUT request body
sync_product PutRequestProduct Information about the Sync Product
external_id string Product ID from your Ecommerce platform
name string Product name
thumbnail string Thumbnail image URL. Although we do not limit thumbnail image size, we recommend to keep it reasonably small.
sync_variants PutRequestVariant [ ] Information about the Sync Variants
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 float Retail price that this item is sold for
sku string SKU of this Sync Variant
files RequestFile [ ] Array of attached print files
type string Role of the file in the order
id integer File ID

* Required if no URL given
url string Source URL where the file is downloaded from

* Required if no File ID given
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
Response format:
code integer Response status code 200
result RequestProductResponse
id integer Sync Product id
external_id string Sync Product ID from the external system
name string Sync Product name
variants integer Total number of variants in Sync Product
synced integer Total number of Sync variants in Sync Product
API key
id Sync Product ID (integer) or External ID (if prefixed with @)
Request body
Execute
Update a Sync Product's Name and Thumbnail
Request body: 
    {
        "sync_product": {
            "name": "API product new name",
            "thumbnail": "https://example.com/image.jpg"
        }
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 79348721,
            "external_id": "e9460f6c67",
            "name": "API product new name",
            "variants": 2,
            "synced": 2
        },
        "extra": [],
        "debug": []
    }
Update a Sync Product and one of its Sync Variants
Request body: 
    {
        "sync_product": {
            "name": "API product new name",
            "thumbnail": "https://example.com/image.jpg"
        },
        "sync_variants": [
            	{
                    "id": 866914574
                },
                {
                    "id": 866914580,
                    "retail_price": 21,
                    "files": [
                        {
                            "url": "https://example.com/image.jpg"
                        },
                        {
                            "type": "back",
                            "url": "https://example.com/image.jpg"
                        }
                    ]
                }
        ]
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 79348721,
            "external_id": "e9460f6c67",
            "name": "API product",
            "variants": 2,
            "synced": 2
        },
        "extra": [],
        "debug": []
    }

Create a new Sync Variant

POST https://api.printful.com/store/products/{id}/variants

Creates a new Sync Variant for an existing Sync Product.
Input parameters:
id integer / string Sync Product ID (integer) or External ID (if prefixed with @)
Request body RequestVariant POST request body
external_id string Variant ID from the Ecommerce platform
variant_id integer Printful Variant ID that this Sync Variant is synced to
retail_price float Retail price that this item is sold for
sku string SKU of this Sync Variant
files RequestFile [ ] Array of attached print files
type string Role of the file in the order
id integer File ID

* Required if no URL given
url string Source URL where the file is downloaded from

* Required if no File ID given
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
Response format:
code integer Response status code 200
result RequestVariantResponse
id integer Sync Variant id
external_id string Sync Variant ID from the external system
sync_product_id integer Sync Variant ID in Printful
name string Sync Variant name
synced bool Is this variant synced
variant_id integer Printful Variant ID that this Sync Variant is synced to
retail_price float Retail price that this item is sold for
currency string Items currenct
product ProductMiniInfo
variant_id integer Printful Variant ID that this Sync Variant is synced to
product_id integer Printful Product ID that this Variant Id belongs to
image string Variants default image in Printfuls Catalog
name string Variants full name in Printfuls Catalog
files File [ ] Array of attached print files
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer 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.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
API key
id Sync Product ID (integer) or External ID (if prefixed with @)
Request body
Execute
Request body: 
    {
        "external_id": "my-external-id",
        "retail_price": "19.00",
        "variant_id": 4011,
        "files": [
            {
                "type": "default",
                "url": "https://example.com/image.jpg"
            },
            {
                "type": "back",
                "url": "https://example.com/image.jpg"
            }
        ],
        "options": [
            {
                "id": "embroidery_type",
                "value": "flat"
            },
            {
                "id": "thread_colors",
                "value": []
            },
            {
                "id": "thread_colors_3d",
                "value": []
            },
            {
                "id": "thread_colors_chest_left",
                "value": []
            }
        ]
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 866914592,
            "external_id": "my-external-id",
            "sync_product_id": 79348732,
            "name": "API product Bella",
            "synced": true,
            "variant_id": 4011,
            "retail_price": "19.00",
            "currency": "USD",
            "product": {
                "variant_id": 4011,
                "product_id": 71,
                "image": "https://s3.dev.printful.com/products/71/4012_1517927381.jpg",
                "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)"
            },
            "files": [
                {
                    "id": 76564159,
                    "type": "default",
                    "hash": "ebd559858e5703088de8900ce99c37d3",
                    "url": "https://example.com/image.jpg",
                    "filename": "76564159.jpg",
                    "mime_type": "image/jpeg",
                    "size": 11246,
                    "width": 200,
                    "height": 300,
                    "dpi": null,
                    "status": "ok",
                    "created": 1540797879,
                    "thumbnail_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_thumb.png",
                    "preview_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_preview.png",
                    "visible": true
                },
                {
                    "id": 76564159,
                    "type": "back",
                    "hash": "ebd559858e5703088de8900ce99c37d3",
                    "url": "https://example.com/image.jpg",
                    "filename": "76564159.jpg",
                    "mime_type": "image/jpeg",
                    "size": 11246,
                    "width": 200,
                    "height": 300,
                    "dpi": null,
                    "status": "ok",
                    "created": 1540797879,
                    "thumbnail_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_thumb.png",
                    "preview_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_preview.png",
                    "visible": true
                }
            ],
            "options": [
                {
                    "id": "embroidery_type",
                    "value": "flat"
                },
                {
                    "id": "thread_colors",
                    "value": []
                },
                {
                    "id": "thread_colors_3d",
                    "value": []
                },
                {
                    "id": "thread_colors_chest_left",
                    "value": []
                }
            ]
        },
        "extra": [],
        "debug": []
    }
Create an new sync variant with a native inside label. Please note that the inside label type must be specified in the file options.
Request body: 
    {
        "retail_price": "19.00",
        "variant_id": 4025,
        "files": [
            {
                "type": "default",
                "url": "https://example.com/image.jpg"
            },
            {
                "type": "label_inside",
                "url": "https://example.com/image.jpg",
                "options": [{
                    "id": "template_type",
                    "value": "native"
                }]
            }
        ],
        "options": [
            {
                "id": "embroidery_type",
                "value": "flat"
            },
            {
                "id": "thread_colors",
                "value": []
            },
            {
                "id": "thread_colors_3d",
                "value": []
            },
            {
                "id": "thread_colors_chest_left",
                "value": []
            }
        ]
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 1817548049,
            "external_id": "5e8dbb006e62d5",
            "sync_product_id": 162979476,
            "name": "lucia - White / XL",
            "synced": true,
            "variant_id": 4014,
            "retail_price": "19.00",
            "currency": "USD",
            "product": {
                "variant_id": 4014,
                "product_id": 71,
                "image": "https://s3.dev.printful.com/products/71/4014_1581412553.jpg",
                "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / XL)"
            },
            "files": [
                {
                "id": 185425195,
                "type": "default",
                "hash": null,
                "url": "https://example.com/image.jpg",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1586346752,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            },
            {
                "id": 185425195,
                "type": "label_inside",
                "hash": null,
                "url": "https://example.com/image.jpg",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1586346752,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            }
            ],
            "options": [
                {
                "id": "embroidery_type",
                "value": "flat"
                },
                {
                    "id": "thread_colors",
                    "value": []
                },
                {
                    "id": "text_thread_colors",
                    "value": []
                },
                {
                    "id": "thread_colors_3d",
                    "value": []
                },
                {
                    "id": "thread_colors_chest_left",
                    "value": []
                },
                {
                    "id": "text_thread_colors_chest_left",
                    "value": []
                },
                {
                    "id": "thread_colors_chest_center",
                    "value": []
                },
                {
                    "id": "text_thread_colors_chest_center",
                    "value": []
                }
            ]
        },
        "extra": [],
        "debug": []
    }

Get information about a single Sync Variant

GET https://api.printful.com/store/variants/{id}

Returns information about an existing Sync Variant.
Input parameters:
id integer Sync Variant ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result SyncVariantInfo
sync_variant SyncVariant Information about the selected Sync Variant
id integer Sync Variant ID
external_id string Variant ID from the Ecommerce platform
sync_product_id integer Sync Product ID that this variant belongs to
name string Sync Variant name
synced boolean Indicates if this Sync Variant is properly linked with Printful product
variant_id integer Printful Variant ID that this Sync Variant is synced to
warehouse_product_variant_id integer Warehousing variant id. If sync variant is connected with a warehousing item, this is its id
retail_price float Retail price that this item is sold for
sku string SKU of this Sync Variant
currency string Currency in which prices are returned
product ProductVariant Short information about the Printful Product and Variant that this Sync Variant is synced to
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer 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.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
sync_product SyncProduct Information about the Sync Product that the Sync Variant belongs to
id integer Sync Product ID
external_id string Product ID from the Ecommerce platform
name string Product name
variants integer Total number of Sync Variants belonging to this product
synced integer Number of synced Sync Variants belonging to this product
thumbnail_url string Thumbnail image for the product
API key
id Sync Variant ID (integer) or External ID (if prefixed with @)
Execute
Response data: 
    {
        "code": 200,
        "result": {
            "sync_variant": {
                "id": 866914574,
                "external_id": "5bd967595a1174",
                "sync_product_id": 79348721,
                "name": "API product",
                "synced": true,
                "variant_id": 4011,
                "retail_price": "18.00",
                "currency": "USD",
                "product": {
                    "variant_id": 4011,
                    "product_id": 71,
                    "image": "https://s3.dev.printful.com/products/71/4012_1517927381.jpg",
                    "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)"
                },
                "files": [
                    {
                        "id": 76564075,
                        "type": "default",
                        "hash": "7d6a2367c1e338750e68dc66b20cba1a",
                        "url": "https://picsum.photos/200/300",
                        "filename": "76564075.jpg",
                        "mime_type": "image/jpeg",
                        "size": 8245,
                        "width": 200,
                        "height": 300,
                        "dpi": null,
                        "status": "ok",
                        "created": 1539341673,
                        "thumbnail_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png",
                        "preview_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png",
                        "visible": true
                    },
                    {
                        "id": 76564075,
                        "type": "back",
                        "hash": "7d6a2367c1e338750e68dc66b20cba1a",
                        "url": "https://picsum.photos/200/300",
                        "filename": "76564075.jpg",
                        "mime_type": "image/jpeg",
                        "size": 8245,
                        "width": 200,
                        "height": 300,
                        "dpi": null,
                        "status": "ok",
                        "created": 1539341673,
                        "thumbnail_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png",
                        "preview_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png",
                        "visible": true
                    }
                ],
                "options": [
                    {
                        "id": "embroidery_type",
                        "value": "flat"
                    },
                    {
                        "id": "thread_colors",
                        "value": []
                    },
                    {
                        "id": "thread_colors_3d",
                        "value": []
                    },
                    {
                        "id": "thread_colors_chest_left",
                        "value": []
                    }
                ]
            },
            "sync_product": {
                "id": 79348721,
                "external_id": "e9460f6c67",
                "name": "API product",
                "variants": 1,
                "synced": 1
            }
        },
        "extra": [],
        "debug": []
    }

Delete a Sync Variant

DELETE https://api.printful.com/store/variants/{id}

Deletes a single Sync Variant.
Input parameters:
id integer / string Sync Variant ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result VariantInfo
variant Variant Information about the selected Variant
id integer Variant ID, use this to specify the product when creating orders
product_id integer ID of the product that this variant belongs to
name string Display name
size string Item size
color string Item color
color_code string Hexadecimal RGB color code. May not exactly reflect the real-world color
color_code2 string Secondary hexadecimal RGB color code. May not exactly reflect the real-world color
image string URL of a preview image for this variant
price string Variant's price (can change depending on print files and optional settings)
in_stock boolean Stock availability of this variant
availability_regions array Map of [region code, region name] of regions where the variant is available for fulfillment
availability_status AvailabilityStatus [ ] Detailed stock status per region
region string Region code
status string Stock status. Possible values include: 'in_stock' - available for fulfillment, 'stocked_on_demand' - available for fulfillment, 'discontinued' - permanently unavailable, 'out_of_stock' - temporarily unavailable
product Product Information about the Product that the Variant belongs to
id integer Product ID
type string Product type identifier
type_name string Product type name
brand string Brand name
model string Model name
image string URL of a sample image for this product
variant_count integer Number of available variants for this product
currency string Currency in which prices are returned
files FileType [ ] Definitions of Print/Mockup file categories that can be attached to this product
id string Deprecated file type identifier. Please use type field instead!
type string File type identifier - use this to specify a file's purpose when creating an order
title string Display name
additional_price string Additional price when this print file type is used
options OptionType [ ] Definitions of additional options that are available for this product
id string Option identifier - use this to specify the option when creating an order
title string Display name
type string Data type of this option (currently only 'bool' is supported)
values array Option values - [key, value] map
additional_price string Additional price when this option is used
additional_price_breakdown array Additional price breakdown by type - [key, value] map
is_discontinued boolean If product is disabled in push
avg_fulfillment_time float Average number of days for order to be fulfilled
description string Product description
API key
id Sync Variant ID (integer) or External ID (if prefixed with @)
Execute

Modify a Sync Variant

PUT https://api.printful.com/store/variants/{id}

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.
Input parameters:
id integer / string Sync Variant ID (integer) or External ID (if prefixed with @)
Request body PutRequestVariant PUT 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 float Retail price that this item is sold for
sku string SKU of this Sync Variant
files RequestFile [ ] Array of attached print files
type string Role of the file in the order
id integer File ID

* Required if no URL given
url string Source URL where the file is downloaded from

* Required if no File ID given
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
Response format:
code integer Response status code 200
result RequestVariantResponse
id integer Sync Variant id
external_id string Sync Variant ID from the external system
sync_product_id integer Sync Variant ID in Printful
name string Sync Variant name
synced bool Is this variant synced
variant_id integer Printful Variant ID that this Sync Variant is synced to
retail_price float Retail price that this item is sold for
currency string Items currenct
product ProductMiniInfo
variant_id integer Printful Variant ID that this Sync Variant is synced to
product_id integer Printful Product ID that this Variant Id belongs to
image string Variants default image in Printfuls Catalog
name string Variants full name in Printfuls Catalog
files File [ ] Array of attached print files
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer 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.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
API key
id Sync Variant ID (integer) or External ID (if prefixed with @)
Request body
Execute
Update price of an existing Sync Variant
Request body: 
    {
        "retail_price": "29.00"
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 866914574,
            "external_id": "5bd967595a1174",
            "sync_product_id": 79348721,
            "name": "API product",
            "synced": true,
            "variant_id": 4011,
            "retail_price": "29.00",
            "currency": "",
            "product": {
                "variant_id": 4011,
                "product_id": 71,
                "image": "https://s3.dev.printful.com/products/71/4012_1517927381.jpg",
                "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)"
            },
            "files": [
                {
                    "id": 76564075,
                    "type": "default",
                    "hash": "7d6a2367c1e338750e68dc66b20cba1a",
                    "url": "https://example.com/image.jpg",
                    "filename": "76564075.jpg",
                    "mime_type": "image/jpeg",
                    "size": 8245,
                    "width": 200,
                    "height": 300,
                    "dpi": null,
                    "status": "ok",
                    "created": 1539341673,
                    "thumbnail_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png",
                    "preview_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png",
                    "visible": true
                },
                {
                    "id": 76564075,
                    "type": "back",
                    "hash": "7d6a2367c1e338750e68dc66b20cba1a",
                    "url": "https://example.com/image.jpg",
                    "filename": "76564075.jpg",
                    "mime_type": "image/jpeg",
                    "size": 8245,
                    "width": 200,
                    "height": 300,
                    "dpi": null,
                    "status": "ok",
                    "created": 1539341673,
                    "thumbnail_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_thumb.png",
                    "preview_url": "https://s3.dev.printful.com/files/7d6/7d6a2367c1e338750e68dc66b20cba1a_preview.png",
                    "visible": true
                }
            ],
            "options": [
                {
                    "id": "embroidery_type",
                    "value": "flat"
                },
                {
                    "id": "thread_colors",
                    "value": []
                },
                {
                    "id": "thread_colors_3d",
                    "value": []
                },
                {
                    "id": "thread_colors_chest_left",
                    "value": []
                }
            ]
        },
        "extra": [],
        "debug": []
    }
Add a native inside label to an existing Sync Variant
Request body: 
    {
        "files": [
        {
            "type": "label_inside",
            "url": "https://picsum.photos/200/300",
            "options": [{
                "id": "template_type",
                "value": "native"
            }]
        }
    ]
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 1817548049,
            "external_id": "5e8dbb006e62d5",
            "sync_product_id": 162979476,
            "name": "lucia - White / XL",
            "synced": true,
            "variant_id": 4014,
            "retail_price": "19.00",
            "currency": "USD",
            "product": {
                "variant_id": 4014,
                "product_id": 71,
                "image": "https://s3.dev.printful.com/products/71/4014_1581412553.jpg",
                "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / XL)"
            },
            "files": [
                {
                    "id": 185425196,
                    "type": "label_inside",
                    "hash": null,
                    "url": "https://picsum.photos/200/300",
                    "filename": null,
                    "mime_type": null,
                    "size": 0,
                    "width": null,
                    "height": null,
                    "dpi": null,
                    "status": "waiting",
                    "created": 1586351368,
                    "thumbnail_url": null,
                    "preview_url": null,
                    "visible": true
                },
            ],
            "options": [
                {
                "id": "embroidery_type",
                "value": "flat"
                },
                {
                    "id": "thread_colors",
                    "value": []
                },
                {
                    "id": "text_thread_colors",
                    "value": []
                },
                {
                    "id": "thread_colors_3d",
                    "value": []
                },
                {
                    "id": "thread_colors_chest_left",
                    "value": []
                },
                {
                    "id": "text_thread_colors_chest_left",
                    "value": []
                },
                {
                    "id": "thread_colors_chest_center",
                    "value": []
                },
                {
                    "id": "text_thread_colors_chest_center",
                    "value": []
                }
            ]
        },
        "extra": [],
        "debug": []
    }
Update the variant t-shirt to have only front print instead of both front and back prints.
Request body: 
    {
        "files": [
            {
                "type": "default",
                "url": "https://example.com/image.jpg"
            }
        ]
    }
Response data: 
    {
        "code": 200,
        "result": {
            "id": 866914574,
            "external_id": "5bd967595a1174",
            "sync_product_id": 79348721,
            "name": "API product",
            "synced": true,
            "variant_id": 4011,
            "retail_price": "29.00",
            "currency": "",
            "product": {
                "variant_id": 4011,
                "product_id": 71,
                "image": "https://s3.dev.printful.com/products/71/4012_1517927381.jpg",
                "name": "Bella + Canvas 3001 Unisex Short Sleeve Jersey T-Shirt with Tear Away Label (White / S)"
            },
            "files": [
                {
                    "id": 76564159,
                    "type": "default",
                    "hash": "ebd559858e5703088de8900ce99c37d3",
                    "url": "https://example.com/image.jpg",
                    "filename": "76564159.jpg",
                    "mime_type": "image/jpeg",
                    "size": 11246,
                    "width": 200,
                    "height": 300,
                    "dpi": null,
                    "status": "ok",
                    "created": 1540797879,
                    "thumbnail_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_thumb.png",
                    "preview_url": "https://s3.dev.printful.com/files/ebd/ebd559858e5703088de8900ce99c37d3_preview.png",
                    "visible": true
                }
            ],
            "options": [
                {
                    "id": "embroidery_type",
                    "value": "flat"
                },
                {
                    "id": "thread_colors",
                    "value": []
                },
                {
                    "id": "thread_colors_3d",
                    "value": []
                },
                {
                    "id": "thread_colors_chest_left",
                    "value": []
                }
            ]
        },
        "extra": [],
        "debug": []
    }

Ready to try Printful ?

Get started

Products

Services

Resources

Features

Printful

From the blog

Printful
So much more than printing

Trusted to deliver 20.1M items
since 2013

Payment methods we accept:

We deliver with:

© 2013 - 2020 Printful® Inc. All Rights reserved.