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

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.

Some of the resources returned by the API are translated into several languages. By default, they are returned in English in the API responses.

If you want to get a response with texts in another language, you can use the X-PF-Language HTTP header. Its value should be the long version of the locale to use (e.g. es_ES for Spanish). Possible localisation parameters:

• en_US
• en_GB
• en_CA
• es_ES
• fr_FR
• de_DE
• it_IT
• ja_JP

Example

Product details (GET https://api.printful.com/products/71) response with default locale (en_US):

{
    "code": 200,
    "result": {
        "product": {
            "type_name": "T-Shirt",
            "title": "Unisex Staple T-Shirt | Bella + Canvas 3001",
            ...
        }
    }
}

Product details response with Spanish locale (X-PF-Language: es_ES):

{
    "code": 200,
    "result": {
        "product": {
            ...
            "type_name": "Camiseta",
            "title": "Camiseta esencial unisex | Bella + Canvas 3001",
            ...
        }
    }
}

OAuth API allows receiving data for token

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:

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.

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.

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:

• Product Prices
• Product Size Guides
• Product Images

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.

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.

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

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:

Not each table type might be available for the selected product.

See examples

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