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

• Update the Base URL: Ensure your requests use the updated V2 base path. For V2, endpoints include the prefix /v2 ( e.g., https://api.printful.com/v2/orders).
• Authentication: Both V1 and V2 use private tokens for authorization. Confirm your token is still valid and configured for your store. No major changes are required here.
• Leverage New Features: V2 introduces several enhancements, including:
  • Improved order creation flexibility, allowing itemized order building.
  • Simplified embroidery orders with features like auto thread color detection.
  • New webhooks for real-time updates on events like stock changes.
  • Standardized returned time (ISO 8601) and price formats.
• Handle Pagination and Rate Limiting: V2 implements uniform pagination parameters and adopts a leaky bucket algorithm for rate limiting. The X-Ratelimit-* headers indicate usage and reset times. Adjust your application to handle these changes effectively.
• Test the Endpoints: Create a separate store to test scenarios in production cautiously. Provide feedback on any anomalies using Printful’s feedback form linked in their documentation.
• Explore Documentation for Changes: Thoroughly review the updated API reference to understand the specifics of V2 endpoints, parameters, and expected responses. Adjust your code for endpoints where behavior or parameters have changed compared to V1.

The errors in the API are formatted following the RFC 9457: Problem Details for HTTP APIs. The content type of error responses is application/problem+json and the response is a JSON object with the members:

Some error types may include some other additional information. For example, validation errors will contain the problem that was detected and a pointer to the invalid data.

An example of a response would be:

{
    "type": "https://developers.printful.com/docs/v2-beta/#errors/not-found",
    "status" : 404,
    "title" : "Not Found",
    "detail" : "The resource that you tried to access does not exist."
}

Internal Server Error

This error is returned when the server encounters an unexpected problem to complete the requested operation. Since this is usually an error on our end, resending the request will probably result in getting the error again.

You don't need to do any action to solve this since we are notified when this error happens. However, if you want, you can contact us through our support channels. If you decide to contact us, providing the returned instance will help us to identify the problem.

This error is returned when the server encounters an unexpected or incorrect value provided by the user. Usually the request can be corrected by providing the correct values specified in valid_values property on an error.

Sync endpoints and Product templates endpoints

Product management, with sync products or product templates, is not available in version 2 of the API yet.

How can I access the new API?

To access the new API (V2), update your endpoint URLs to include the /v2 prefix ( e.g., https://api.printful.com/v2/orders). You’ll also need a valid private token for authorization. The V2 API supports the same authentication method as V1, so you can continue using your existing token unless it has expired. Ensure that your applications are updated to use the V2 endpoints, as these include several new features and enhancements.

What happens if I don't migrate?

While the V1 API will continue to function for now, it is essential to migrate to V2 to take advantage of new features and optimizations. V2 includes enhancements like real-time webhook updates, better performance, standardized formats, and improved functionalities. Staying on V1 means missing out on these improvements and could lead to challenges as support for V1 may be phased out in the future. It’s strongly recommended to migrate to ensure compatibility and optimal performance.

How can I get help with my migration?

For migration assistance, you can:

• Refer to the V2 API documentation, which provides detailed information about endpoints, parameters, and response formats.
• Contact Printful Developer Support at devsupport@printful.com for specific questions or troubleshooting help.

Are there any changes to API Rate Limits?

Yes, there are changes to the rate-limiting mechanism in V2. Unlike the simple limit-reset system in V1, V2 implements a leaky bucket algorithm:

• The headers X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Reset, and X-Ratelimit-Policy provide detailed rate-limit information.
• V2 allows smoother traffic bursts by gradually refilling the bucket over time, improving performance and reducing the impact of hitting the limit.
• Default limits remain similar (120 requests per minute), but the reset mechanism is now more dynamic, reflecting the real-time refill process.
• These changes aim to provide more predictable behavior and better utilization of API resources. Adjust your application to handle the revised rate-limiting system effectively.

This section outlines practical use cases to help you estimate, create, update, and track orders effectively. Whether you're calculating shipment costs, determining potential custom fees, or leveraging webhooks for real-time updates, these use cases are designed to streamline your order workflows.

Key topics include:

• Estimating Shipments: Learn how to estimate shipment costs, types, and determine whether custom fees will apply.
• Order Estimation: Understand how to calculate the costs and details of an order before placing it.
• Creating Orders from Catalog Source: Discover how to create new orders using items directly from the catalog.
• Order Modifications: Includes deleting individual order items and updating existing orders.
• Order Confirmation: How to confirm yout orders and initiate fulfillment.
• Order Updates and Tracking: Access tools for receiving updates via webhook events, retrieving detailed order information through the API, and tracking shipments with precise shipping details.

These use cases are tailored to provide actionable insights for efficiently managing your Printful orders, ensuring a smooth integration experience.

Estimating orders

The cost of the order can be estimated before even placing the order by using the order estimation endpoint. The estimation is an asynchronous process so the response won’t contain the estimation data right away, but instead the task ID will be returned.

{
  "data": {
    "id": "fc959efb-b3a0-4c12-9cc6-f54d3158291d",
    "status": "pending",
    "costs": null,
    "retail_costs": null,
    "failure_reasons": []
  }
}

The task ID fc959efb-b3a0-4c12-9cc6-f54d3158291d can be then used to retrieve the result of the estimation with https://api.printful.com/v2/order-estimation-tasks?id=fc959efb-b3a0-4c12-9cc6-f54d3158291d.

The estimation task has 3 different statuses:

• pending
• failed
• completed

If the estimation fails the task status will be set to the failed and the reason will be included in the failure_reasons

Estimating Shipments

Shipping rates can be estimated by using the Estimating orders endpoint as it also returns the shipping cost.

{
  "data": {
    "id": "fc959efb-b3a0-4c12-9cc6-f54d3158291d",
    "status": "completed",
    "costs": {
      ...
      "shipping": "4.79",
      ...
    }
  }
}

That shipping cost however is always calculated for the standard shipping method.

How to estimate the shipment cost and type

To display the different shipping methods the shipping rates endpoint needs to be used. Three main things are required to correctly calculate the shipping costs:

• Recipient data
• Product variant + quantity
• Currency

The response will contain all the available shipment methods:

{
  "data": [
    {
      "shipping": "STANDARD",
      "shipping_method_name": "Flat Rate (Estimated delivery: May 19–24) ",
      "rate": "13.60",
      "currency": "EUR",
      "min_delivery_days": 4,
      "max_delivery_days": 7,
      "min_delivery_date": "2022-10-17",
      "max_delivery_date": "2022-10-20",
      "shipments": [
        {
          "departure_country": "US",
          "shipment_items": [
            {
              "catalog_variant_id": 4011,
              "quantity": 3
            }
          ],
          "customs_fees_possible": true
        }
      ]
    }
  ]
}

How to determine if the custom fees will be applied

Depending on where the shipment is shipped from and where it will be shipped the additional taxes and duties might apply. To check if the custom fees might apply the customs_fees_possible parameter from the shipping rates endpoint can be used to determine that.

{
  "data": [
    {
      ...
      "shipments": [
        {
          ...
          "customs_fees_possible": true
        }
      ]
    }
  ]
}

Creating order from catalog source

To create the order the recipient address and the catalog product with the designs needs to be specified. Order will be created with the draft status and the pending costs calculations.

Orders with the draft status won’t be charged, and they won’t be picked up by our fulfillment facilities. In order to mark the order as ready for fulfillment the order confirmation endpoint needs to be used.

Orders can be also created without specifying any items at first. In that case just the recipient address can be provided:

{
  "recipient": {
    "name": "John Smith",
    "address1": "19749 Dearborn St",
    "city": "Chatsworth",
    "country_code": "US",
    "state_code": "CA",
    "zip": "91311"
  }
}

The item creation endpoint can be then used in such order to add different products that should be included in the order. This functionality might be useful when implementing a user cart.

Deleting an order item

Individual items can be removed from the order by using the delete order item endpoint but only if the order is in either draft or failed state.

Updating an order

Order can be updated only in the draft and failed state. An entire order can be updated or just a specific item.

The updates in the V2 of the API use the PATCH method protocol. This means that only the values provided in the request will be updated. For example, sending a request with an empty body will not perform any changes to the order.

Example of updating a recipient name: PATCH https://api.printful.com/v2/orders/{order_id}

{
  "recipient": {
    "name": "John Smith"
  }
}

Some values can’t be updated separately, attempting to update an array's values requires sending a whole array. For example updating just the item design placement is not possible and will result in an error.

{
  "items": [
    {
      "placements": [
        {
          "placement": "front"
        }
      ]
    }
  ]
}

In such case a whole valid design data needs to be provided:

{
  "items": [
    {
      "quantity": 1,
      "catalog_variant_id": 4011,
      "source": "catalog",
      "placements": [
        {
          "placement": "front",
          "technique": "dtg",
          "layers": [
            {
              "type": "file",
              "url": "{{image_url}}"
            }
          ]
        }
      ]
    }
  ]
}

Order Confirmation

In V2 API the orders cannot be created immediately in a confirmed state. In order to confirm an order it first needs to be created in the draft state. Or if the order failed e.g. due to payment method missing it can be confirmed again.

If the order cost calculations are still calculating or they have failed to calculate then the order won’t be possible to be confirmed.

Example of order cost still 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
        },
...

Webhook events

To get the notifications about the order status, the webhook events endpoint can be used to subscribe to various webhook events e.g.:

• Order created
• Order updated
• Order failed
• Order cancelled
• Order put on hold
• Order put on hold approved
• Order removed from hold
• Order refunded

Get endpoints

The order list can be retrieved using the retrieve a list of orders endpoint. There is also an endpoint for retrieving the single order and the endpoint to retrieve a specific order item.

Shipping information

After an order is made it is split into shipments, meaning that a single order can have multiple shipments. You can retrieve the status of these shipments using the shipments endpoint.

The main use case of this endpoint is in providing tracking details about each shipment. Providing information about the status of the shipment and what events have occurred so far.

{
  ...
      "shipment_status": "canceled",
      "shipped_at": "2023-06-15T16:35:35Z",
      "delivery_status": "unknown",
      "delivered_at": "2023-06-15T16:35:35Z",
      "departure_address": {
        "country_name": "United States",
        "country_code": "US",
        "state_code": "CA"
      },
      "tracking_url": "​https://myorders.com/tracking/39925631",
      "tracking_events": [
        {
          "triggered_at": "2023-06-15T19:15:05Z",
          "description": "Arrived At Destination"
        }
      ],
...

Another important usage of this endpoint is in providing delivery time estimates:

{
  ...
  "estimated_delivery": {
    "from_date": "2023-06-15",
    "to_date": "2023-06-15",
    "calculated_at": "2023-06-15T16:35:35Z"
  },
  ...
}

Given that not all orders can fit in a single shipment it may be necessary to indicate which shipment will contain which item. The shipments endpoint can be used to link ordered items back to physical items.

{
  ...
  "shipment_items": [
    {
      "id": 10,
      "order_item_id": 20,
      "order_item_external_id": "item-external-id",
      "order_item_name": "Item name",
      "quantity": 1,
      "_links": {
        "order_item": {
          "href": "​https://api.printful.com/v2/orders/2/order-items/20"
        }
      }
    }
  ],
  ...
}

Product options, placements and techniques

In order to create order items and other designs it's important to know the specification of the product. The catalog products endpoints offers a way to expose these options so that designs can be created dynamically from blank Printful products.

Displaying the product

A request to https://api.printful.com/v2/catalog-products will provide a paged list of products along with descriptions and images of products to help users identify the product they would like.

[
  {
    "id": 294,
    "type": "T-SHIRT",
    "main_category_id": 7,
    "name": "Unisex Pullover Hoodie | Bella + Canvas 3719",
    "brand": "Bella + Canvas",
    "model": "3719",
    "image": "https://s3-printful.stage.printful.dev/upload/product-catalog-img/35/352d4f3cc9fbac9ee9173467bc7f200e_l",
    "variant_count": 20,
    "is_discontinued": false,
    "description": "A soft and comfy unisex hoodie that fits all your hoodie needs. The fleece fabric makes it a great partner all year round, be it a summer evening on the beach, or a Christmas dinner in a mountain cabin.\n\n• 52% airlume combed ring-spun cotton, 48% poly fleece\n• Heather colors are 60% airlume combed ring-spun cotton, 40% poly fleece\n• Fabric weight: 6.5 oz/yd² (220.4 g/m²)\n• Regular fit\n• Side-seamed construction\n• Blank product sourced from Honduras, Nicaragua or the US"
  },
  {
    "id": 262,
    "type": "CUT-SEW",
    "main_category_id": 49,
    "name": "All-Over Print Drawstring Bag",
    "brand": null,
    "model": null,
    "image": "https://s3-printful.stage.printful.dev/upload/product-catalog-img/0f/0f04d73474287ef01d6f5541c3a63de2_l",
    "variant_count": 1,
    "is_discontinued": false,
    "description": "Combine your love for vibrant prints and a sporty style with a cool drawstring bag. It's a must-have gym essential that can be worn as a backpack with drawstring closure at top, and narrow, contrasting shoulder straps. \n\n• 100% polyester\n• One size: 15″ × 17″ (38.1 cm × 43.2 cm)\n• Fabric weight (may vary by 5%): 6.64 oz/yd² (225 g/m²)\"\n• Maximum weight limit: 33 lbs (15 kg)\n• Twin cotton handles\n• Drawstring closure\n• Blank product components sourced from Israel",
  }
]

Selecting the product and creating a design

Once the product is selected additional information is needed in order to create a design with the blank product. The following is a valid item

{
  "quantity": 1,
  "catalog_variant_id": 4011,
  "source": "catalog",
  "placements": [
    {
      "placement": "front",
      "technique": "dtg",
      "layers": [
        {
          "type": "file",
          "url": "{{image_url}}"
        }
      ]
    }
  ]
}

A lot of the information in the above request depend on information taken from the catalog.

https://api.printful.com/v2/catalog-products/294

{
  "id": 294,
  "techniques": [
    {
      "key": "dtg",
      "display_name": "DTG printing",
      "is_default": true
    },
    {
      "key": "embroidery",
      "display_name": "Embroidery",
      "is_default": false
    }
  ],
  "placements": [
    {
      "placement": "embroidery_chest_left",
      "technique": "embroidery",
      "layers": [
        {
          "type": "file",
          "layer_options": [
            {
              "name": "thread_colors",
              "techniques": [
                "embroidery"
              ],
              "type": "array",
              "values": {
                "#FFFFFF": "1801 White",
                "#000000": "1800 Black",
                "#96A1A8": "1718 Grey",
                "#A67843": "1672 Old Gold",
                "#FFCC00": "1951 Gold",
                "#E25C27": "1987 Orange",
                "#CC3366": "1910 Flamingo",
                "#CC3333": "1839 Red",
                "#660000": "1784 Maroon",
                "#333366": "1966 Navy",
                "#005397": "1842 Royal",
                "#3399FF": "1695 Aqua/Teal",
                "#6B5294": "1832 Purple",
                "#01784E": "1751 Kelly Green",
                "#7BA35A": "1848 Kiwi Green"
              }
            }
          ]
        }
      ],
      "placement_options": []
    },
    {
      "placement": "front",
      "technique": "dtg",
      "layers": [
        {
          "type": "file",
          "layer_options": []
        }
      ],
      "placement_options": []
    },
    ...
  ],
  ...
}

The example above gives us most of the information necessary to design the item, it provides the techiques, placements and layers available for the product.

Mapped onto an item these values would look like this:

{
  "placements": [
    {
      "placement": "front",
      "technique": "dtg",
      "layers": [
        {
          "type": "file",
          "url": "{{image_url}}"
        }
      ]
    }
  ]
}

It also offers alternative options, for example the same product could use embroidery thread colors if embroidery placements are selected.

{
  "placements": [
    {
      "placement": "embroidery_chest_left",
      "technique": "embroidery",
      "layers": [
        {
          "type": "file",
          "layer_options": [
            {
              "name": "thread_colors",
              "value": [
                "#FFFFFF",
                "#000000"
              ]
            }
          ],
          "url": "{{image_url}}"
        }
      ]
    }
  ]
}

What's missing from this is the catalog_variant_id, the variant can be found using https://api.printful.com/v2/catalog-products/294/catalog-variants. Each variant is different in color and size and the user can view an image of each to help select their variant.

[
  {
    "id": 9224,
    "catalog_product_id": 294,
    "name": "Bella + Canvas 3719 Unisex Fleece Pullover Hoodie (White / XL)",
    "size": "XL",
    "color": "White",
    "color_code": "#ffffff",
    "color_code2": null,
    "image": "https://s3-printful.stage.printful.dev/products/294/9220_1526986863.jpg",
    ...
  },
  ...
]

With the catalog variant selected the design can be finished, and creating an item is just a matter of selecting the quantity and source of the design.

{
  "quantity": 1,
  "catalog_variant_id": 9224,
  "source": "catalog",
  "placements": [
    {
      "placement": "embroidery_chest_left",
      "technique": "embroidery",
      "layers": [
        {
          "type": "file",
          "layer_options": [
            {
              "name": "thread_colors",
              "value": [
                "#FFFFFF",
                "#000000"
              ]
            }
          ],
          "url": "{{image_url}}"
        }
      ]
    }
  ]
}

Getting the pricing information

The catalog API can also be used to indicate to the end customer what the price of the product will be.

https://api.printful.com/v2/catalog-variants/9224/prices

{
  "data": {
    "currency": "EUR",
    "product": {
      "id": 294,
      "placements": [
        {
          "id": "embroidery_chest_left",
          "title": "Left chest",
          "type": "Embroidery",
          "technique_key": "embroidery",
          "placement_options": [],
          "price": "2.95",
          "discounted_price": "2.95",
          "layers": [
            {
              "type": "file",
              "additional_price": "0.00",
              "layer_options": []
            }
          ]
        },
        {
          "id": "front",
          "title": "Front print",
          "type": "DTG printing",
          "technique_key": "dtg",
          "placement_options": [],
          "price": "5.75",
          "discounted_price": "5.75",
          "layers": [
            {
              "type": "file",
              "additional_price": "0.00",
              "layer_options": []
            }
          ]
        }
      ]
    },
    "variant": {
      "id": 9224,
      "techniques": [
        {
          "technique_key": "dtg",
          "technique_display_name": "DTG printing",
          "price": "28.95",
          "discounted_price": "28.95"
        },
        {
          "technique_key": "embroidery",
          "technique_display_name": "Embroidery",
          "price": "30.75",
          "discounted_price": "30.75"
        }
      ]
    },
    "discount_tiers": [
      {
        "quantity": 25,
        "bulk_discount_percentage": 0.08
      },
      ...
    ]
  },
}

The price of the product will depend upon the technique, the variant, the placement and the quantity of the product ordered. Furthermore, the first placement will be discounted by the discounted_price.

For more information on pricing please follow this link: https://www.printful.com/pricing

Price changed webhook

It may also be useful that a system can react to changes in product pricing, the Catalog Price Changed (catalog_price_changed) webhook can be used to handle this use case.

Getting the images for the products

The images provided in the catalog products and variants are only very simple. For more complex use cases where a larger variety of mockups of a single product may need to be displayed, the catalog product images and variant images endpoints can help. Note however, that these require additional work, Printful doesn't provide images for every color so most images on those endpoints are transparent and require the developer to overlay them on top of the color defined on the resource.

Getting the availability of products (stock information)

Stock of products changes daily at Printful so it's important to make sure to display this availability to the end customers.

One way to make sure end customers only see the products available in their region is to filter by selling region https://api.printful.com/v2/catalog-products?selling_region_name=brazil.

If more detailed availability information is needed it can be taken from the variant and product availability endpoints.

https://api.printful.com/v2/catalog-products/294/availability

{
  "data": [
    {
      "catalog_variant_id": 9231,
      "techniques": [
        {
          "technique": "dtg",
          "selling_regions": [
            {
              "name": "usa",
              "availability": "in stock",
              "placement_option_availability": []
            }
          ]
        },
        {
          "technique": "embroidery",
          "selling_regions": [
            {
              "name": "usa",
              "availability": "in stock",
              "placement_option_availability": []
            }
          ]
        }
        ...
      ]

This may be important in cases where the stock availability of specific techniques is important.

Stock updated webhook

It may also be useful that a system can react to changes in product availability, the catalog stock updated (catalog_stock_updated) webhook can be used to handle this use case.~~

Defining mockup styles

When creating a mockup a style first needs to be selected for the given product.

https://api.printful.com/v2/catalog-products/294/mockup-styles

{
  "data": [
    {
      "placement": "front",
      "display_name": "Front print",
      "technique": "dtg",
      "print_area_width": 12.0,
      "print_area_height": 12.0,
      "print_area_type": "simple",
      "dpi": 150,
      "mockup_styles": [
        {
          "id": 16652,
          "category_name": "Flat",
          "view_name": "Front",
          "restricted_to_variants": null
        },
        ...

These styles contain a view and category and are limited by placement to help select the correct style.

Creating mockups

Once the style is retrieved creating a mockup is very similar to creating an order item. All of this data from the order item created above can be reused to create a mockup

{
  "source": "catalog",
  "placements": [
    {
      "placement": "embroidery_chest_left",
      "technique": "embroidery",
      "layers": [
        {
          "type": "file",
          "layer_options": [
            {
              "name": "thread_colors",
              "value": [
                "#FFFFFF",
                "#000000"
              ]
            }
          ],
          "url": "{{image_url}}"
        }
      ]
    }
  ]
}

The placements are all that is needed to create a design. A mockup also needs these properties

{
  "mockup_style_ids": [
    16652 # The style selected before
  ],
  "catalog_product_id": 1, # The catalog product
  "catalog_variant_ids": [ # A list of catalog variants
    16365
  ],
  ...
}

The mockup generator can then take a list of products in order to create multiple mockups at a time.

{
  "format": "jpg",
  "products": [
    {
      "source": "catalog",
      "mockup_style_ids": [
        16652
      ],
      "catalog_product_id": 294,
      "catalog_variant_ids": [
        9231
      ],
      "placements": [
        {
          "placement": "embroidery_chest_left",
          "technique": "embroidery",
          "layers": [
            {
              "type": "file",
              "layer_options": [
                {
                  "name": "thread_colors",
                  "value": [
                    "#FFFFFF",
                    "#000000"
                  ]
                }
              ],
              "url": "{{image_url}}"
            }
          ]
        }
      ]
    }
  ]
}

Fetching the mockup task

The response of the above request will look something like this:

{
  "id": 752213059,
  "status": "pending",
  "catalog_variant_mockups": [],
  "failure_reasons": [],
  "_links": {
    "self": {
      "href": "https://api.printful.com/v2/mockup-tasks?id=752213059"
    }
  }
}

Mockups are generated asynchronously so they will not be present right after making the request.

Webhook events

When the mockup is finished processing a webhook will be triggered which can be listened to using the Mockup task finished webhook (mockup_task_finished).

GET endpoint

It may not be possible to set up webhooks in some systems, or it may simply be too complicated for the scope of a given project. If this is the case the mockup can also be retrieved by polling the endpoint to retrieve mockup tasks, e.g. https://api.printful.com/v2/mockup-tasks?id=752213059.

Even if a system uses webhook events, the GET endpoint should still be used as a backup in case the message is never received from the webhook. Setting a server up to automatically check the process of mockup tasks can improve the reliability of an integration.

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