API Documentation v2 | Printful (2.0.0-beta)

Download OpenAPI specification:Download

About the Printful API

Welcome to API v2 BETA

  • We’re excited to inform you that the new major version of our API just went live, and we want to invite you to participate in the Open Beta test. Please keep in mind that this release is still in BETA, although all presented endpoints can be used in a production environment. Since this is a BETA release, we are keen on adopting any changes to our API (which we encourage you to pass via this feedback form). We do not expect to introduce any breaking changes to the current form of endpoints, although the final form of each endpoint might slightly vary from the current version.

  • What is the plan for the new endpoints V2s.

  • Timeline

    • 2023
      • Q4 – Sync – Merging two similar APIs – Products and Ecommerce platform sync to one for all actions regarding the Sync Products and Sync Variant creation.
      • Q4 – Full Orders v2
    • 2024
      • Q1 – Mockup Generator v2
      • Product templates v2
    • 2025
      • Deprecation of the old versions of endpoints
  • How to use new endpoints? Create or use an already created private token for authorization. Unless it's stated otherwise, the v2 version of Printful API may be used like the v1 version. All v2 endpoints use /v2 prefix and the specifics of each endpoint are explained in a dedicated section.

  • Test and provide feedback: Explore the new features, experiment with the enhancements, and share your feedback through our dedicated feedback form.

What is new in the V2s

  • The flexibility of order creation with itemized order building (read more).
  • Simplifying embroidery orders: auto thread color detection as default, simplified thread colors definition on the layer level.
  • New, powerful design creation with multiple design layers support and positioning for order items and sync variants (read more).
  • New, more secure Webhooks by enforcing HTTPS, added expiration date, and request signing.
  • More flexibility in webhook per event configuration.
  • New webhook events – a new event for catalog price change, and the stock update event is now real-time with a refresh rate every 5 minutes (previously every 24h).
  • More information in the Catalog about the products (images, discounted pricing, placement information).
  • More flexibility in the catalog (extensive filtering and sorting options, DSR support, pagination).
  • More information on the order shipment level – more precise EDT, departure country, and shipment tracking events.
  • Standardization of returned time in API – standardized format according to ISO 8601, UTC time zone.
  • Standardization of returned price formats in API. Prices are displayed as a string with up to 2 decimal points.
  • Uniform pagination parameters across all endpoints.
  • Performance improvements for all endpoints.

Rate Limiting

Printful implements rate limiting to ensure the stability of the API while keeping it fair for all users. Rate limiting is handled differently depending on the version and endpoint being used.

Header values

Printful uses the following header values to communicate rate limits:

X-Ratelimit-Limit
X-Ratelimit-Remaining
X-Ratelimit-Reset
X-Ratelimit-Policy

However, the meaning of these values changes depending on the algorithm used.

V1 Rate limitting

V1 used a very simple rate limiting mechanism, you had a limit of 120, every request would reduce that limit by 1, if it hits 0 you would receive a 429 error, every minute the limit of 120 would be restored. See: V1 Rate Limits.

This system is good, because it's easy to understand for most users. However, we found it had a number of disadvantages both for users and for Printful.

  • A burst in traffic could lead to 120 requests in the first second. This is harmful for Printful and will lead to a bad user experience as all end users wait for the rate limit to be reset.
  • Some users will have close to 120 requests a minute, but most sites don't have such uniform traffic.

V2 Rate Limiting

Leaky Bucket

In V2 of the API Printful implements a Leaky Bucket rate limiting algorithm.

Note: The algorithm does not implement any queuing mechanisms in its current form so it can also be described as a Token Bucket algorithm.

Like with the old rate limiting algorithm, when you make a request to the API, the X-Ratelimit-Remaining header value will go down by one. However, the X-Ratelimit-Reset does not work the same, it states how long it will take to "refill the bucket". The bucket will be refilled one drop at a time instead of all at once, so the X-Ratelimit-Reset will be much smaller after the first request.

By default, after the first request the headers will look like this:

X-Ratelimit-Policy: 120;w=60;
X-Ratelimit-Limit: 120
X-Ratelimit-Remaining: 119
X-Ratelimit-Reset: 0.5

This means 120 requests can be made in a single burst, one request has already been made and X-Ratelimit-Remaining will reach 120 again in 0.5 seconds. The X-Ratelimit-Policy header indicates that in a window of 60 seconds 120 tokens (or "quota units") will be added to the bucket.

The headers are inspired by the format in RateLimit header fields for HTTP Internet-Draft.

What is rate-limited in V2

All endpoints are rate-limited with the leaky bucket rate limiter and the defaults. However, it is planned for future endpoints to have higher or lower limits depending on usage and the capacity of the API.

Using the leaky bucket effectively

There are a number of strategies you can use to take advantage of rate limiting.

  • When receiving a 429 you can use the retry-after header to check when the next request can be made, then schedule a request to trigger at that time.
  • You can implement a queue that only sends out requests at the rate indicated in the policy. You can calculate the rate of requests using the X-Ratelimit-Policy 120 ÷ 60 = 0.5, so the queue should send requests out at a rate of once every 500 milliseconds.
  • Some combination of the two, for example, allow requests to trigger at any rate, start queuing after the first 429, then turn off the queue after no new requests are sent and the X-Ratelimit-Reset time has been met.

Catalog v2

What is a catalog product?

A catalog product refers to a blank product and its variants. Each variant can be used as the base for custom designs. Catalog product consists of multiple catalog variants each of which might be a combination of size and color or it might be a variation with e.g. tear away label. The entire hierarchy is shown in the diagram below:

What is a catalog variant?

Catalog variant might be a combination of size and color associated with the catalog product or additional variation of a product with certain features like tear away label. It can be thought of as an actual physical blank product. For example T-shirt Bella Canvas 3001 in White color and size M is considered to be a single variant. Catalog variants can have different availability as different regions could have different stock of some product colors and sizes.

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.

It is critically important to always refer to the Variant IDs (NOT Product IDs) when creating products or orders. Mixing up and using the Product ID instead of the Variant ID can lead to an entirely different product created or item ordered. The Product entity is only meant to allow of easier browsing of what Printful offers.

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: Up to 120 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.

Catalog general information

General introduction

This resource contains the list of all the products that are available in Printful for purchase and fulfillment. Apart from basic product data and availability it also contains the information about:

Filtering options

Filters can be used to search for particular set of products based on the provided values. Multiple filters can be used at the same time.

Filtering option name Description Where to find
colors Filters products by variants containing specified colors data[].color Catalog variants
new Filters products that are new -
placements Filters products by available placements specified in the list data[].placements[].placement Catalog products
category_ids Filters products by specified product categories data[].id Catalog categories
techniques Filters products by specified techniques data[].techniques[].key Catalog products
types Filters products by specified types of product e.g. T-Shirt. data[].type Catalog products

Sorting

Requires providing two parameters in the URL: sort_type And sort_direction. Sort type determines a type of sorting that will be used e.g. sort by price and the sort direction determines if the result should be sorted ascending or descending. Only one sort type can be used at a time.

Sorting option name Description
new Sorts resulting catalog products starting with new ones
rating Sorts resulting catalog products by their user-rating
price Sorts resulting catalog products by their base price

DSR

  • What is DSR? – DSR (Default Selling Region) is an option that lets you limit the results of a product catalog to products that could be shipped within a specified region. When choosing Worldwide, we'll display the entire Product Catalog. Delivery times depend on end-customer location and selected product.
  • Where DSR can be set and how it affects response? – DSR can be currently set in Catalog products and Product Prices.
  • Available DSRs
Region name Region name value
Worldwide worldwide
North America north_america
Canada canada
Europe europe
Spain spain
Latvia latvia
United Kingdom uk
France france
Australia australia
Japan japan
New Zealand new_zealand
Italy italy
Brazil brazil
Southeast Asia southeast_asia
Republic of Korea republic_of_korea
English speaking regions english_speaking_regions

Size guides

Get Product Size Guide endpoint will return size guides for the specified 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.

See examples

Categories

Catalog categories are used to group products with similar characteristics such as t-shirts, hats etc.

Categories have purely informational purposes and cannot be edited by the customers. Categories can be nested e.g.

  • Men’s clothing
    • All shirts
      • T-Shirts
      • Polo shirts
    • Jackets & vests

Apart from display purposes they can be also used for filtering the products in the API see Filtering options

Retrieve a list of catalog products

This endpoint retrieves a list of the products available in Printful's catalog. The list is paginated and can be filtered using various filters. The information returned includes details on how each product can be designed, such as the available placements, techniques, and additional options. For a visual representation of the design data, please see the following diagram:

Authorizations:
OAuth
query Parameters
category_ids
Array of integers
Examples:
  • category_ids=4 - Using a single category ID
  • category_ids=4,7 - Multiple category IDs

One or more category IDs to return only products in those categories. The IDs can be found in the response of the operation Get Categories.

colors
Array of strings
Examples:
  • colors=grey - Grey.
  • colors=heather%20grey - Heather grey color.
  • colors=grey,heather%20grey - Grey or heather grey color

One or more color names to return only products with variants of one the those colors.

limit
integer [ 1 .. 100 ]
Default: 20

The number of results to return per page.

new
boolean
Default: false
Examples:
  • new=true - Return only new products

If true only new Products will be returned.

offset
integer >= 0
Default: 0
Examples:
  • offset=100 - Return results after the initial 100

The number of results to not include in the response starting from the beginning of the list.

This can be used to return results after the initial 100. For example, sending offset 100

placements
Array of strings
Examples:
  • placements=front - Return products with variants that have front placement.
  • placements=front,back - Return products with variants that have front or back placement.

One or more identifiers of a placement to return only products with variants that have that placement. The complete list of placements can be found here.

selling_region_name
string
Default: "worldwide"
Enum: "worldwide" "north_america" "canada" "europe" "spain" "latvia" "uk" "france" "australia" "japan" "new_zealand" "italy" "brazil" "southeast_asia" "republic_of_korea" "english_speaking_regions"

Only returns the products that can be sold in the specified region.

sort_direction
string
Default: "descending"
Enum: "ascending" "descending"

This parameter only is used if sort_type is also present and it changes the order of the returned products. The exact meaning varies depending on the value of sort_type:

  • sort_type=new
    • ascending sorts from newest to oldest.
    • descending sorts from oldest to newest.
  • sort_type=rating
    • ascending from lowest to highest rated.
    • descending from highest to lowest rated.
  • sort_type=price
    • ascending from lowest to highest price.
    • descending from highest to lowest price.
sort_type
string
Enum: "new" "rating" "price"

The sorting strategy to use when sorting the result. When it's not present, no specific order is guaranteed.

techniques
Array of strings (TechniqueEnum)
Items Enum: "dtg" "digital" "cut-sew" "uv" "embroidery" "sublimation" "dtfilm"
Examples:
  • techniques=DIGITAL - Products with variants that can be printed using the technique DIGITAL.
  • techniques=DIGITAL,EMBROIDERY - Products with variants that can be printed using the techniques DIGITAL or EMBROIDERY.

One or more techniques to return only products with variants that can be printed using one of the techniques.

Responses

Response Schema: application/json
Array of objects (Product)
object (Paging)

Paging information

object (Product links)

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve a single catalog product

Returns information about a single specified catalog product. See catalog product

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

query Parameters
selling_region_name
string
Default: "worldwide"
Enum: "worldwide" "north_america" "canada" "europe" "spain" "latvia" "uk" "france" "australia" "japan" "new_zealand" "italy" "brazil" "southeast_asia" "republic_of_korea" "english_speaking_regions"

Only returns the products that can be sold in the specified region.

Responses

Response Schema: application/json
object (Product)

Information about the Product

Response samples

Content type
application/json
{}

Retrieve information about specific catalog variant

Returns information about single specified catalog variant. See catalog variant

Authorizations:
OAuth
path Parameters
id
required
integer

Variant ID

Responses

Response Schema: application/json
object (Variant)
object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve information about catalog product variants

Returns information about all catalog variants associated with the specified catalog product. See catalog variant

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

Responses

Response Schema: application/json
Array of objects (Variant)
object (Paging)

Paging information

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve a list of catalog categories

Returns list of all categories that are present in the catalog. The categories specify the type of the product that is associated with it. For example, the category "Men’s T-shirts" indicates that the product is a subgroup of T-shirts specifically targeted at Men. Categories can be used to filter the product list by specific tags See categories_ids

Authorizations:
OAuth

Responses

Response Schema: application/json
Array of objects (Category)
object

HATEOAS links

Response samples

Retrieve information about specific category

Returns information about a specific catalog category. The categories specify the type of the product that is associated with it. For example, the category "Men’s T-shirts" indicates that the product is a subgroup of T-shirts specifically targeted at Men. Categories can be used to filter the product list by specific tags See categories_ids

Authorizations:
OAuth
path Parameters
id
required
integer

Category ID

Responses

Response Schema: application/json
object (Category)

Information about the Category

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve a list of catalog product categories

To retrieve information about a particular category, use this feature. It returns details about a specific catalog category. Categories help identify the type of product associated with them. For instance, the category "Men's T-shirts" denotes that the product is a subgroup of T-shirts intended for men.

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

Responses

Response Schema: application/json
Array of objects (Category)
object (Paging)

Paging information

object

HATEOAS links

Response samples

Retrieve size guide for a catalog product

Returns information about the size guide for a specific product.

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

query Parameters
unit
string
Example: unit=inches,cm

A comma-separated list of measurement unit in which size tables are to be returned (inches or cm). The default value is determined based on the locale country. The inches are used for United States, Liberia and Myanmar, for other countries the unit defaults to centimeters.

Responses

Response Schema: application/json
object (ProductSizeGuide)

Size Guide information for the Product

object

HATEOAS links

Response samples

Content type
application/json
{
  • "data": {
    },
}

Retrieve catalog product prices

Calculates prices for specific catalog product based on selling region and specified currency. Calculations also include Store discounts. Selling region is used to specify product production currency, that is the price that the product is natively manufactured in. Different selling regions might affect the overall price amount. Currency parameter is used only to define the currency that the prices will be displayed in.

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

query Parameters
selling_region_name
string
Example: selling_region_name=worldwide

Specifies the region production currency that the product prices will be calculated in

currency
string
Example: currency=USD

The currency (3-letter code) used to determine currency in which the prices will be displayed. The store currency will be used by default. The format is compliant with ISO 4217 standard.

Responses

Response Schema: application/json
object (ProductPrice)

Product prices information

object (Paging)

Paging information

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve pricing information for the catalog variant

Return pricing information from a single variant and the parent product

Authorizations:
OAuth
path Parameters
id
required
integer

Variant ID

query Parameters
selling_region_name
string
Example: selling_region_name=worldwide

Specifies the region production currency that the product prices will be calculated in

currency
string
Example: currency=USD

The currency (3-letter code) used to determine currency in which the prices will be displayed. The store currency will be used by default. The format is compliant with ISO 4217 standard.

Responses

Response Schema: application/json
object (VariantPrice)

Variant prices information

object

HATEOAS links

Response samples

Content type
application/json
{
  • "data": {
    },
}

Retrieve blank images for a catalog product

This feature helps to fetch blank images for a catalog product. These blank images are always white and semi-transparent and can be colored by the user on the client-side as per the specified color in the data.color field. The endpoint allows filtering of the result based on the type of the mockup, the placement, and the color of the product.

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

query Parameters
option_group
string
Example: option_group=men's,women's

String values separated by comma. You can specify multiple option groups filters.

colors
string
Example: colors=black,red

String values separated by comma. You can specify multiple variant colors filters.

placement
string
Example: placement=front

Filters result by specified placement

Responses

Response Schema: application/json
Array of objects (VariantImages)
object (Paging)

Paging information

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve blank images for a catalog variant

Returns images for a specified Variant.

Authorizations:
OAuth
path Parameters
id
required
integer

Variant ID

query Parameters
placement
string
Example: placement=front

Filters result by specified placement

Responses

Response Schema: application/json
Array of objects (VariantImages)
object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve catalog product mockup styles

Returns information about available mockup styles for specified catalog product.

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

query Parameters
placements
Array of strings
Examples:
  • placements=front - Return mockup styles that match a specific placement.
  • placements=front,back - Return mockup styles that match a list of placements.

One or more placement idenitifiers used to filter in mockup styles that match a given placement. The complete list of placements can be found here.

selling_region_name
string
Default: "worldwide"
Enum: "worldwide" "north_america" "canada" "europe" "spain" "latvia" "uk" "france" "australia" "japan" "new_zealand" "italy" "brazil" "southeast_asia" "republic_of_korea" "english_speaking_regions"

Only returns the products that can be sold in the specified region.

offset
integer

Result set offset

limit
integer

Number of items per page (max 100)

Responses

Response Schema: application/json
Array of objects (MockupStyles)
object (Paging)

Paging information

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve catalog product mockup templates

Returns positional data for specified catalog product mockups. The data from this endpoint could be used to generate your own mockups without the need to use Printful's mockup generator. Mockup template

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

query Parameters
placements
Array of strings
Examples:
  • placements=front - Return products with variants that have front placement.
  • placements=front,back - Return products with variants that have front or back placement.

One or more identifiers of a placement to return only products with variants that have that placement. The complete list of placements can be found here.

selling_region_name
string
Default: "worldwide"
Enum: "worldwide" "north_america" "canada" "europe" "spain" "latvia" "uk" "france" "australia" "japan" "new_zealand" "italy" "brazil" "southeast_asia" "republic_of_korea" "english_speaking_regions"

Only returns the products that can be sold in the specified region.

limit
integer [ 1 .. 100 ]
Default: 20

The number of results to return per page.

offset
integer >= 0
Default: 0
Examples:
  • offset=100 - Return results after the initial 100

The number of results to not include in the response starting from the beginning of the list.

This can be used to return results after the initial 100. For example, sending offset 100

Responses

Response Schema: application/json
Array of objects (MockupTemplates)
object (Paging)

Paging information

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve catalog product stock availability

Provides information about the catalog product stock status. Stock availability is grouped by variants → techniques → selling regions.

Authorizations:
OAuth
path Parameters
id
required
integer

Product ID.

query Parameters
techniques
Array of strings (TechniqueEnum)
Items Enum: "dtg" "digital" "cut-sew" "uv" "embroidery" "sublimation" "dtfilm"
Examples:
  • techniques=DIGITAL - Products with variants that can be printed using the technique DIGITAL.
  • techniques=DIGITAL,EMBROIDERY - Products with variants that can be printed using the techniques DIGITAL or EMBROIDERY.

One or more techniques to return only products with variants that can be printed using one of the techniques.

selling_region_name
string
Default: "worldwide"
Enum: "worldwide" "north_america" "canada" "europe" "spain" "latvia" "uk" "france" "australia" "japan" "new_zealand" "italy" "brazil" "southeast_asia" "republic_of_korea" "english_speaking_regions"

Only returns the products that can be sold in the specified region.

limit
integer [ 1 .. 100 ]
Default: 20

The number of results to return per page.

offset
integer >= 0
Default: 0
Examples:
  • offset=100 - Return results after the initial 100

The number of results to not include in the response starting from the beginning of the list.

This can be used to return results after the initial 100. For example, sending offset 100

Responses

Response Schema: application/json
Array of objects (VariantStockAvailability)
object (Paging)

Paging information

Array of objects (FilterSettings)

The list of the filters that were used in the request

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve catalog variant stock availability

Provides information about the catalog variant stock status. Stock availability is grouped by variants → techniques → selling regions.

Authorizations:
OAuth
path Parameters
id
required
integer

Variant ID

query Parameters
techniques
Array of strings (TechniqueEnum)
Items Enum: "dtg" "digital" "cut-sew" "uv" "embroidery" "sublimation" "dtfilm"
Examples:
  • techniques=DIGITAL - Products with variants that can be printed using the technique DIGITAL.
  • techniques=DIGITAL,EMBROIDERY - Products with variants that can be printed using the techniques DIGITAL or EMBROIDERY.

One or more techniques to return only products with variants that can be printed using one of the techniques.

selling_region_name
string
Default: "worldwide"
Enum: "worldwide" "north_america" "canada" "europe" "spain" "latvia" "uk" "france" "australia" "japan" "new_zealand" "italy" "brazil" "southeast_asia" "republic_of_korea" "english_speaking_regions"

Only returns the products that can be sold in the specified region.

Responses

Response Schema: application/json
object (VariantStockAvailability)

Stock availability data for a specific catalog variant

Array of objects (FilterSettings)

The list of the filters that were used in the request

object

HATEOAS links

Response samples

Content type
application/json
{}

Sync v2

Sync v2

Get Sync Products

Get information about all Sync Products of your store.

Authorizations:
OAuth
query Parameters
offset
integer

Result set offset

limit
integer

Number of items per page (max 100)

header Parameters
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.

Responses

Response Schema: application/json
Array of objects (SyncProduct)
object (Sync products links)

HATEOAS links

object (Paging)

Paging information

Response samples

Content type
application/json
{}

Create a Sync Product

Creates a new Sync Product.

This endpoint is only available for "Manual order platform / API" stores (store type native).
Authorizations:
OAuth
header Parameters
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.

Request Body schema: application/json
required

POST request body

required
object (SyncProductCreationData)

Information about the Sync Product to be created

required
Array of any [ 1 .. 100 ] items

Information about the Sync Variants to be created within the Sync Product

Responses

Response Schema: application/json
object (SyncProduct)

Information about the SyncProduct

Request samples

Content type
application/json
{
  • "sync_product": {
    },
  • "sync_variants": [
    ]
}

Response samples

Content type
application/json
{}

Get a Sync Product

Get information about a single Sync Product.

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Product ID (integer) or External ID (if prefixed with @)

header Parameters
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.

Responses

Response Schema: application/json
object (SyncProduct)

Information about the SyncProduct

Response samples

Content type
application/json
{}

Delete a Sync Product

Deletes a single Sync Product.

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Product ID (integer) or External ID (if prefixed with @)

header Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "data": "Malformed Authorization header",
  • "error": {
    }
}

Update a Sync Product

Make a partial update of a Sync Product. This endpoint allows you to replace all Sync Variants with new ones. If you want to update one or more Sync Variants, Update a Sync Variant endpoint should be used instead.

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Product ID (integer) or External ID (if prefixed with @)

header Parameters
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.

Request Body schema: application/json

PATCH request body

object (SyncProductUpdateData)

Information about the Sync Product to be updated

Array of any [ 1 .. 100 ] items

Information about the Sync Variants to be created within the Sync Product

Responses

Response Schema: application/json
object (SyncProduct)

Information about the SyncProduct

Request samples

Content type
application/json
{
  • "sync_product": {
    },
  • "sync_variants": [
    ]
}

Response samples

Content type
application/json
{}

Get a Sync Variant

Get information about a single Sync Variant.

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Variant ID (integer) or External ID (if prefixed with @)

header Parameters
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.

Responses

Response Schema: application/json
object (SyncVariant)

Information about the SyncVariant

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Sync Variants

Get information about all the sync variants of a specific sync product.

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Product ID (integer) or External ID (if prefixed with @)

query Parameters
offset
integer

Result set offset

limit
integer

Number of items per page (max 100)

header Parameters
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.

Responses

Response Schema: application/json
Array of objects (SyncVariant)
object (Sync variants links)

HATEOAS links

object (Paging)

Paging information

Response samples

Content type
application/json
{}

Create a Sync Variant

Creates a new Sync Variant for an existing Sync Product

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Product ID (integer) or External ID (if prefixed with @)

header Parameters
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.

Request Body schema: application/json

POST request body

source
required
string

Source of the sync variant

catalog_variant_id
required
integer

Catalog Variant ID used for the Sync Variant (it can be found in Get Product Variants endpoint response).

external_id
string [ 1 .. 32 ] characters

Your own identifier for the Sync Variant. It must be unique across all Sync Variants in the store.

The external ID must not contain whitespace, 4-byte Unicode characters, and following characters: ,, @.

If the external ID is not provided in the request, we will generate a 14-character hexadecimal ID.

retail_price
string

Retail price of this sync variant

sku
string

SKU of product variant

Array of InsidePocketOption (object) or StitchColorOption (object) or NotesOption (object) or LifelikeOption (object) or CustomBorderColorOption (object) (ProductOptions)

List of product options

required
Array of objects (Placement) non-empty

Responses

Response Schema: application/json
object (SyncVariant)

Information about the SyncVariant

Request samples

Content type
application/json
{
  • "source": "catalog",
  • "catalog_variant_id": 4011,
  • "external_id": "external-1234",
  • "retail_price": "10.50",
  • "sku": "some-sku-12",
  • "product_options": [
    ],
  • "placements": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a Sync Variant

Delete a single Sync Variant.

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Product ID (integer) or External ID (if prefixed with @)

required
integer or string

Sync Variant ID (integer) or External ID (if prefixed with @)

header Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "data": "Malformed Authorization header",
  • "error": {
    }
}

Update a Sync Variant

Make a partial update of a Sync Variant. NOTE that the source of the Sync Variant can't be changed via a PATCH request, to create a Sync Variant from another source you must delete the current one and add a new one.

Authorizations:
OAuth
path Parameters
required
integer or string

Sync Product ID (integer) or External ID (if prefixed with @)

required
integer or string

Sync Variant ID (integer) or External ID (if prefixed with @)

header Parameters
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.

Request Body schema: application/json

PATCH request body

external_id
string [ 1 .. 32 ] characters

Your own identifier for the Sync Variant. It must be unique across all Sync Variants in the store.

The external ID must not contain whitespace, 4-byte Unicode characters, and following characters: ,, @.

If the external ID is not provided in the request, we will generate a 14-character hexadecimal ID.

retail_price
string

Retail price of this sync variant. Must be a numeric string with a value greater than 0. Has a precision of 2 decimal places.

sku
string <= 40 characters

SKU of product variant

Array of InsidePocketOption (object) or StitchColorOption (object) or NotesOption (object) or LifelikeOption (object) or CustomBorderColorOption (object) (ProductOptions)

List of product options

Array of objects (Placement) non-empty

Responses

Response Schema: application/json
object (SyncVariant)

Information about the SyncVariant

Request samples

Content type
application/json
{
  • "external_id": "external-1234",
  • "retail_price": "10.50",
  • "sku": "some-sku-12",
  • "product_options": [
    ],
  • "placements": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Orders v2

Order Building

You can create a draft order without order items but you won’t be able to confirm it until at least one order item are added to that order. With this approach, you can create a draft order with all necessary recipient data and add items to it as you go (similar to a shopping cart) by using Create Order Item. After every order item addition, the order cost will be re-calculated.

A minimal DRAFT order can be created with just the address:

POST https://api.printful.com/v2/orders
Authorization: Bearer {{bearer_token}}
{
  "recipient": {
    "address1": "19749 Dearborn St",
    "city": "Chatsworth",
    "state_code": "CA",
    "state_name": "California",
    "country_code": "US",
    "country_name": "United States",
    "zip": "91311"
  }
}

After the order is created the order items can be added one by one.

POST https://api.printful.com/v2/orders/{{order_id}}/order-items
Authorization: Bearer {{bearer_token}}
{
    "catalog_variant_id": 4011,
    "source": "catalog",
    "quantity": 1,
    "placements": [
        {
            "placement": "front",
            "technique": "dtg",
            "layers": [
                {
                    "type": "file",
                    "url": "https://www.printful.com/static/images/layout/printful-logo.png"
                }
            ]
        }
    ]
}

It is also possible to create an order with all order items in a single request.

POST https://api.printful.com/v2/orders
Authorization: Bearer {{bearer_token}}
{
  "recipient": {
    "address1": "19749 Dearborn St",
    "city": "Chatsworth",
    "state_code": "CA",
    "state_name": "California",
    "country_code": "US",
    "country_name": "United States",
    "zip": "91311"
  },
  "order_items": [
    {
      "catalog_variant_id": 4011,
      "source": "catalog",
      "quantity": 1,
      "placements": [
        {
          "placement": "front",
          "technique": "dtg",
          "layers": [
            {
              "type": "file",
              "url": "https://www.printful.com/static/images/layout/printful-logo.png"
            }
          ]
        }
      ]
    }
  ]
}

Order life cycle and statuses

draft At this stage, the order has been created but has not yet been submitted for fulfillment. It can be freely edited, changed, or deleted at this stage. The order will not charged or fulfilled until it has been confirmed.
pending The order has been submitted for fulfillment and it will be charged in this stage, but is not yet accepted for fulfillment. The order can be cancelled at this stage so long as it has not been charged yet.
failed Order was submitted for fulfillment but it had some errors preventing it from being fulfilled (problem with the address, missing printfiles, failed to charge the wallet, etc.).
canceled The order has been canceled and can no longer be processed. If the order was already charged then the cost of the order will be returned to your store.
inprocess The order is being fulfilled and can no longer be canceled or modified. Contact customer support if there are any issues with the order at this point.
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.

You are only charged for orders when they have been confirmed with the “Confirm Order” operation and have the status “pending” Confirm Order. If the order encounters a problem after it has been confirmed, then it is moved to the failed state so that the problem can be fixed and the order can be resubmitted.

For order status updates please subscribe to one of the webhook events following webhook events:

Order items

Order items are representations of the actual products that will come with an order.

In the sections below we explain each order item source and provide examples of how a simple request might look like for each source.

Catalog Source

Catalog products are blank products available in Printful. Since they are blank you’ll need to specify design data during the order creation. This flow is intended if you allow your customers to specify their own designs which means that every order is unique.

To sell pre-defined products (Sync products) refer to Sync variant.

The following example request shows how an item structure might look in JSON.

POST https://api.printful.com/v2/orders/{{order_id}}/order-items
Authorization: Bearer {{bearer_token}}
{
    "catalog_variant_id": 4012,
    "source": "catalog",
    "quantity": 1,
    "placements": [
        {
            "placement": "front",
            "technique": "dtg",
            "layers": [
                {
                    "type": "file",
                    "url": "https://www.printful.com/static/images/layout/printful-logo.png"
                }
            ]
        }
    ]
}

Sync Source

In contrast to the catalog source, the sync source uses sync variants which already hold information about design and retail costs. More information about the sync variants can be found at Sync V2.

This means that you don’t need to specify all of the data that would otherwise be required when using the catalog source. To order a sync variant you just need to specify the sync_variant_id, quantity and source properties.

POST https://api.printful.com/v2/orders/{{order_id}}/order-items
Authorization: Bearer {{bearer_token}}
{
    "source": "sync",
    "sync_variant_id": {{sync_variant_id}},
    "quantity": 1
}
Note When an order item is created from the sync source the fulfilled item will have the design of the sync variant at the time the order item was created. If the design of the sync variant is changed after the order item is created those changes won’t be reflected in the order order unless the item is created again.

Design specification

Design data is the information used to customize the product. A design consists of placements, layers and unique product options. Placements refer to where a design will be printed, for example, a T-Shirt might have the placements front and left_sleeve. Placements can also constrict what techniques can be used in that area of the product, for example a product might have both front and embroidery_front and embroidery can only be used in the second placement. A layer is constrained to the print area of the placement that you’ve chosen. A design that is outside of the print area won’t be visible.

Depending on the product, placement, and technique different layers might be available.

You can check which layers are available using the Retrieve a single catalog product operation.

The design data structure is the same regardless of the flow (making orders, creating sync products etc.). So the solution can be re-used in the different endpoints.

Placements

The product placement is the part of the product where design layers will be printed, different placements will also offer different options and techniques, they will also have different limitations. The available placement list will vary depending on the product. To get the available placements of a product use the Retrieve a single catalog product endpoint with the product ID that you want to check.

Front placement:
Left sleeve placement:
Note depending on the type and quantity of the placement additional fees might apply.

Layers

Layers are what is printed in each placement, and there can be up to 5 of them per one placement. The layers are printed on top of each other with the 0th layer being the furthest back and the 4th element being on top of all other layers.

API supports only one layer type - file.

Layers are defined as an array per placement:

...
  "layers": [
    {
      "type": "file",
      "url": "https://picsum.photos/200",
      "layer_options": [
        {
          "name": "thread_colors",
          "value": [
            "#FFFFFF"
          ]
        }
      ],
      "position": {
        "width": 640,
        "height": 640,
        "left": 0,
        "top": 0
      }
    }
  ]
...

Layer Positioning

You can specify the image position inside the print area by providing a position object.

Each print area has specific dimensions, by default our system will assume that your file has to fit into those limitations and not exceed them. The (0,0) point is always located in the top left corner of the print area.

Note all values are in inches.

Example of positioning the 450x450 image on the front placement

Position Mockup Payload
Top left Top left mockup
  "position": {
    "area_width": 1800,
    "area_height": 2400,
    "width": 450,
    "height": 450,
    "top": 0,
    "left": 0
  }
Top middle Top left mockup
"position": {
  "area_width": 1800,
  "area_height": 2400,
  "width": 450,
  "height": 450,
  "top": 0,
  "left": 675
}
Top right Top left mockup
"position": {
  "area_width": 1800,
  "area_height": 2400,
  "width": 450,
  "height": 450,
  "top": 0,
  "left": 1350
}
Middle Top left mockup
"position": {
  "area_width": 1800,
  "area_height": 2400,
  "width": 450,
  "height": 450,
  "top": 975,
  "left": 675
}
Bottom left Top left mockup
"position": {
  "area_width": 1800,
  "area_height": 2400,
  "width": 450,
  "height": 450,
  "top": 1950,
  "left": 0
}
Bottom middle Top left mockup
"position": {
  "area_width": 1800,
  "area_height": 2400,
  "width": 450,
  "height": 450,
  "top": 1950,
  "left": 675
}
Bottom right Top left mockup
"position": {
  "area_width": 1800,
  "area_height": 2400,
  "width": 450,
  "height": 450,
  "top": 1950,
  "left": 1350
}

Options

Apart from placement and layers you can also specify options.

# Example of option data.
{
  "name": "unlimited_color",
  "value": true
}

Option always consist of the name of the option and the value. Value of the option can be different depending on the option type but they are always predefined for the specified product. You can always check what options and what values are available for a specific product by checking Retrieve a single catalog product

Options can be specified on three levels:

  • Product options - Those options specify additional design options for an entire product. E.g. inside_pocket allows you to define if a product should be fulfilled with an additional inside pocket. Or stitch_color lets you choose the stitch colors that will be used to stitch back All-Over print products.
  • Placement options - They specify options for an entire placement. Currently, the only placement option is unlimited_color which if specified causes the placement to be fulfilled using Unlimited Color embroidery
  • Layer options - Specify additional parameters for a single layer. E.g. 3d_puff option if set to true causes that particular layer to use 3D puff embroidery.

Order Customization

Packing Slip Customization

The packing slip information can be customized according to the store’s specific requirements. Some of the options are: a custom logo, the name of the store, customer service email/phone, and more.

The packing slip fields can be configured at the store level (in the Dashboard at Settings > Stores > Branding > Packing slip section.) and overridden for a specific order.

To override the packing slip settings for the order, you can use packing_slip fields for each order.

POST https://api.printful.com/v2/orders
Authorization: Bearer {{bearer_token}}
{
    "recipient": {
        "address1": "19749 Dearborn St",
        "city": "Chatsworth",
        "state_code": "CA",
        "state_name": "California",
        "country_code": "US",
        "zip": "91311"
    },
    "customization": {
        "packing_slip": {
            "email": "[email protected]",
            "phone": "+48000000000",
            "message": "this is a message",
            "logo_url": "https://example.com/image.jpg",
            "store_name": "a store"
        }
    }
}

Below you can find an example or a packing slip for a shipment with explained fields.

packing slip

Field annotations:

  • (1) Barcode unique for the shipment.
  • (2) Store logo defined in the store settings or overridded using packing_slip.logo_url field.
  • (3) The date of the shipment.
  • (4) Packing slip number consisting of order and shipment IDs in Printful database, divided with a hyphen.
  • (5) The country from which the shipment is made. If the recipient is in the United States, this field will be absent.
  • (6) Recipient address with phone, without email address.
  • (7) Store name. This can be overridden using packing_slip.store_name.
  • (8) The address to which the shipment should be returned. By default it will be a Printful’s return address, but you can set your own address in the store settings (Settings > Stores > Returns > Return address section).
  • (9) The customer service phone number defined in the store settings or overridden using packing_slip.phone field.
  • (10) The customer service email address defined in the store settings or overridden using packing_slip.email field.
  • (11) Gift message. This is only present if the gift field was provided in the order request.
  • (12) The order creation date.
  • (13) Printful Order ID which can be overridden using packing_slip.custom_order_id field.
  • (14) The list of order items with quantities. The items’ display names are localized, using the recipient’s country and include variant information such as color and size e.g. „Unisex Staple T-Shirt | Bella + Canvas 3001 ( Lilac / M)”.
  • (15) The packing slip message defined in the store settings or overridden using packing_slip.message field.

Gift

The order gift option is part of the order customization and contains two properties: subject and message. This option allows users to add a custom note that will be seen by the final customer who receives the product.

POST https://api.printful.com/v2/orders
Authorization: Bearer {{bearer_token}}
{
    "recipient": {
        "address1": "19749 Dearborn St",
        "city": "Chatsworth",
        "state_code": "CA",
        "state_name": "California",
        "country_code": "US",
        "zip": "91311"
    },
    "customization": {
        "gift": {
            "subject": "To John",
            "message": "Happy birthday!"
        }
    }
}

Notes for Beta

The Orders endpoints for the V2 Beta are incomplete. Some V1 endpoints will still need to be used to achieve certain functionality.

Order Cost Calculations

Order costs are calculated asynchronously. This means when you create or update an order you are likely to see a response from the API with costs and retail_costs fields set to null and "calculation_status": "calculating".

"costs": {
  "calculation_status": "calculating",
  "currency": null,
  "subtotal": null,
  "discount": null,
  "shipping": null,
  "digitization": null,
  "additional_fee": null,
  "fulfillment_fee": null,
  "retail_delivery_fee": null,
  "tax": null,
  "vat": null,
  "total": null
},
"retail_costs": {
  "calculation_status": "calculating",
  "currency": "USD",
  "subtotal": "0.00",
  "discount": "1.00",
  "shipping": "0.00",
  "tax": "0.00",
  "vat": "0.00",
  "total": null
},

Once the costs and retail costs are calculated the "calculation_status" will change the status to "done"

"costs": {
  "calculation_status": "done",
  "currency": "USD",
  "subtotal": "107.50",
  "discount": "0.00",
  "shipping": "14.84",
  "digitization": "0.00",
  "additional_fee": "0.00",
  "fulfillment_fee": "0.00",
  "retail_delivery_fee": "0.00",
  "tax": "11.20",
  "vat": "0.00",
  "total": "133.54"
},
"retail_costs": {
  "calculation_status": "done",
  "currency": "USD",
  "subtotal": "0.00",
  "discount": "1.00",
  "shipping": "0.00",
  "tax": "0.00",
  "vat": "0.00",
  "total": "134.54"
},

If you are subscribed to the order_updated webhook event, you will receive an event when the calculation is finished.

Retrieve a list of orders

Retrieve a list of orders from a specific store. The order list will be paginated with twenty items per page by default.

Authorizations:
OAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

The number of results to return per page.

offset
integer >= 0
Default: 0
Examples:
  • offset=100 - Return results after the initial 100

The number of results to not include in the response starting from the beginning of the list.

This can be used to return results after the initial 100. For example, sending offset 100

header Parameters
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.

Responses

Response Schema: application/json
Array of objects (OrderSummary)
object (Paging)

Paging information

object

HATEOAS links

Response samples

Content type
application/json
{}

Create a new order

This endpoint allows the creation of a new order in which the default status will be draft.

Authorizations:
OAuth
header Parameters
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.

Request Body schema: application/json

POST request body

external_id
string

Order ID from the external system

shipping
string

Shipping method. Defaults to 'STANDARD'

required
object (Address)

The recipient data.

required
Array of any

Array of order items

object (Customization)

The Order's customization values

object

Retail costs

Responses

Response Schema: application/json
object (Order)

Order

Request samples

Content type
application/json
{
  • "external_id": "4235234213",
  • "shipping": "STANDARD",
  • "recipient": {
    },
  • "order_items": [
    ],
  • "customization": {
    },
  • "retail_costs": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve a single order

Retrieve a single order from the specified store. The result object will contain links to the same resource, order items, and shipments.

Authorizations:
OAuth
path Parameters
required
integer or string

Order ID (integer) or Order External ID (string prepended with "@" symbol)

header Parameters
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.

Responses

Response Schema: application/json
object (Order)

Order

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete an order

Warning: The DELETE HTTP method in version 2 of order in the API will delete the order if the order can be deleted. This is distinct from version 1 where the DELETE method will actually cancel the order rather than delete it. Please, keep this in mind if you are migrating to version 2 from version 1

Delete the order if it can be deleted. An order can be deleted if it's status is draft, failed or cancelled. The order must also have not been charged yet and there must be no payments pending.

Authorizations:
OAuth
path Parameters
required
integer or string

Order ID (integer) or Order External ID (string prepended with "@" symbol)

header Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "result": "Malformed Authorization header.",
  • "error": {
    }
}

Update an order

Make a partial update of an order.

Authorizations:
OAuth
path Parameters
required
integer or string

Order ID (integer) or Order External ID (string prepended with "@" symbol)

header Parameters
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.

Request Body schema: application/json

PATCH request body

external_id
string

Order ID from the external system

shipping
string

Shipping method. Defaults to 'STANDARD'

object (Address)

The recipient data.

Array of any

Array of order items

object (Customization)

The Order's customization values

object

Retail costs

Responses

Response Schema: application/json
object (Order)

Order

Request samples

Content type
application/json
{
  • "external_id": "4235234213",
  • "shipping": "STANDARD",
  • "recipient": {
    },
  • "order_items": [
    ],
  • "customization": {
    },
  • "retail_costs": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Confirm an order

This endpoint allows customers to confirm the order and start the fulfillment in the production facility.

Authorizations:
OAuth
path Parameters
required
integer or string

Order ID (integer) or Order External ID (string prepended with "@" symbol)

header Parameters
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.

Responses

Response Schema: application/json
object (Order)

Order

object

HATEOAS links

Response samples

Content type
application/json
{}

Retrieve a list of order items

This endpoint retrieves the list of items that belong to the order.

Authorizations:
OAuth
path Parameters
required
integer or string

Order ID (integer) or Order External ID (string prepended with "@" symbol)

query Parameters
type
string

Type of items returned (order_item, branding_item). By default all items are returned.

limit
integer [ 1 .. 100 ]
Default: 20

The number of results to return per page.

offset
integer >= 0
Default: 0
Examples:
  • offset=100 - Return results after the initial 100

The number of results to not include in the response starting from the beginning of the list.

This can be used to return results after the initial 100. For example, sending offset 100

header Parameters
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.

Responses

Response Schema: application/json
Array of any