E-commerce Platform Sync API

The ecommerce platform sync API allows you to automatically assign Printful products and print files to the products in your online store (Shopify, Woocommerce, etc.) that is linked to Printful.

Sync Products & Sync Variants explained

Each product in your store can contain one or multiple variants (some ecommerce platforms would call these options) that the customer can purchase (imagine multiple sizes or colors of the same t-shirt design). When you link your ecommerce store to Printful, we create a copy of your product and variant lists on our side - we call it Sync Products and Sync Variants.

Similar to your store, products that are sold by Printful also consist of multiple variants. Each t-shirt model is available in many sizes and colors.

The purpose of Sync Variants is to let you link each variant from your store that will be fulfilled by Printful with a design file(s) and specific variant from Printful's product catalogue. When synced products are ordered, we'll know which Printful product needs to be printed, and the order is imported into Printful for fulfillment.

You can configure each Sync Variant in the Printful Dashboard manually. However that can be quite a tedious and repetitive task if your store sells hundreds of products. This API is designed to help you automate this process.

Remember - product data is not imported to Printful immediately after the product is created/updated in your ecommerce platform. Depending on the platform, it can take from a couple of seconds up to a few hours for the products to be available on Printful. Before the products are imported, you will not be able to update product information through this API.

External ID

External ID is a feature that allows you to reference Sync Products and Sync Variants by using the ID from your store.

When requesting Sync Products and Sync Variants, you can use both the Printful ID and your External ID (if you prefix it with the @ symbol).

GET /sync/products/11001  - reference by Printful Sync Product ID
GET /sync/products/@988123  - reference by Shopify (or other platform's) Product ID
GET /sync/variant/123456  - reference by Printful Sync Variant ID
GET /sync/variant/@123123  - reference by Shopify (or other platform's)  Variant ID

Specifying products

To specify the exact variant of the product, you have to use the variant_id attribute of the order item. Each available unique item (including size/color) has its own Variant ID that can be acquired through the Product Catalog API.

Adding print files

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"},
],
...

Specifying multiple files per item

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 Products 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":[
	{
		//Primary file - front print
		"type": "default",//This line is optional
		"url": "http://example.com/t-shirts/123/front.pdf"
	},
	{
		//Additional file - back print
		"type": "back"
		"url": "http://example.com/t-shirts/123/back.pdf"
	},
	{
		//Additional file - mockup image
		"type": "preview"
		"url": "http://example.com/t-shirts/123/preview.png"
	}
],
...

Remember that using additional files can increase the price of the item.

Get list of Sync Products

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

Returns list of Sync Product objects from your 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
offset integer Result set offset
limit integer Number of items per page (max 100)
Response format:
code integer Response status code 200
result SyncProduct [ ] Array of SyncProduct data
id integer Sync Product ID
external_id string Product ID from the E-commerce 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
paging Paging Paging information
total integer Total 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
offset Result set offset
limit Number of items per page (max 100)
Execute
Get list of Sync Products
Response data:
{
    "code": 200,
    "result": [
        {
            "id": 1055834,
            "external_id": "387926136",
            "name": "Test product",
            "variants": 4,
            "synced": 0
        },
        {
            "id": 1055835,
            "external_id": "409040684",
            "name": "NYC Poster 18x24",
            "variants": 1,
            "synced": 1
        },
        {
            "id": 1055821,
            "external_id": "147988113",
            "name": "Michael Jackson T-Shirt",
            "variants": 6,
            "synced": 2
        }
    ],
    "paging": {
        "total": 3,
        "offset": 0,
        "limit": 20
    }
}

Get information about Sync Product and its variant list

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

Returns information about a specific sync product and a list of sync variants for this product.
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 data and array of Sync Variants
sync_product SyncProduct Information about the selected product
id integer Sync Product ID
external_id string Product ID from the E-commerce 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
sync_variants SyncVariant [ ] Array of Sync Variants available for the selected product
id integer Sync Variant ID
external_id string Variant ID from the E-commerce 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
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 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

Unlink all synced variants of this product from Printful

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

Deletes configuraton information (variant_id, print files and options) and disables automatic order importing for all synced variants of this Sync Product.
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 data and array of Sync Variants
sync_product SyncProduct Information about the selected product
id integer Sync Product ID
external_id string Product ID from the E-commerce 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
sync_variants SyncVariant [ ] Array of Sync Variants available for the selected product
id integer Sync Variant ID
external_id string Variant ID from the E-commerce 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
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 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

Get information about Variant

GET https://api.printful.com /sync/variant/{id}

Returns information about a 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 data and Sync Product data
sync_variant SyncVariant Information about the selected Sync Variant
id integer Sync Variant ID
external_id string Variant ID from the E-commerce 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
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 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 E-commerce 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
API key
id Sync Variant ID (integer) or External ID (if prefixed with @)
Execute

Update linked product and print file information for Sync Variant

PUT https://api.printful.com /sync/variant/{id}

Allows to configure selected Sync Variant with correct product, print files and additional options.
Input parameters:
Request body SyncVariant Sync Variant configuration data
variant_id integer Printful Variant ID that this Sync Variant is synced to
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
url string Source URL where the file is downloaded from
filename string File name
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for the configured product/variant
id string Option ID
value mixed Option value
id integer Sync Variant ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result SyncVariantInfo Sync Variant data and Sync Product data
sync_variant SyncVariant Information about the selected Sync Variant
id integer Sync Variant ID
external_id string Variant ID from the E-commerce 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
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 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 E-commerce 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
API key
Request body
id Sync Variant ID (integer) or External ID (if prefixed with @)
Execute
Links Sync Variant with T-shirt with front and back images
Request body:
{
    "variant_id": 1118,
    "files": [
        {
            "url": "http://example.com/files/tshirts/shirt_front.ai"
        },
        {
            "type": "back",
            "url": "http://example.com/files/tshirts/shirt_back.ai"
        }
    ],
    "options": []
}
Response data:
{
    "code": 200,
    "result": {
        "sync_variant": {
            "id": 4699529,
            "external_id": "1117068664",
            "sync_product_id": 1055835,
            "name": "Michael Jackson T-Shirt - Medium",
            "synced": true,
            "variant_id": 1118,
            "product": {
                "variant_id": 1118,
                "product_id": 14,
                "image": "https://d1yg28hrivmbqm.cloudfront.net/products/14/1095.jpg",
                "name": "Alternative 1070 Short Sleeve Men T-Shirt (Black / M)"
            },
            "files": [
                {
                    "id": 304995,
                    "type": "default",
                    "hash": null,
                    "url": "http://example.com/files/tshirts/shirt_front.ai",
                    "filename": null,
                    "mime_type": null,
                    "size": 0,
                    "width": null,
                    "height": null,
                    "dpi": null,
                    "status": "waiting",
                    "created": 1426839420,
                    "thumbnail_url": null,
                    "preview_url": null,
                    "visible": true
                },
                {
                    "id": 304996,
                    "type": "back",
                    "hash": null,
                    "url": "http://example.com/files/tshirts/shirt_back.ai",
                    "filename": null,
                    "mime_type": null,
                    "size": 0,
                    "width": null,
                    "height": null,
                    "dpi": null,
                    "status": "waiting",
                    "created": 1426839420,
                    "thumbnail_url": null,
                    "preview_url": null,
                    "visible": true
                }
            ],
            "options": []
        },
        "sync_product": {
            "id": 1055835,
            "external_id": "409040684",
            "name": "Michael Jackson T-Shirt",
            "variants": 1,
            "synced": 1
        }
    }
}

Unlink synced variant from Printful

DELETE https://api.printful.com /sync/variant/{id}

Deletes configuraton information (variant_id, print files and options) and disables automatic order importing for this 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 data and Sync Product data
sync_variant SyncVariant Information about the selected Sync Variant
id integer Sync Variant ID
external_id string Variant ID from the E-commerce 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
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 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 E-commerce 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
API key
id Sync Variant ID (integer) or External ID (if prefixed with @)
Execute

Ready to try Printful ?

Get Me Started

Printing is what we do best.

Trusted to print 2 212 803 shirts since 2013