The Printful API is a RESTful API, that uses an HTTP protocol for communication. HTTP GET, POST, PUT and DELETE methods are used to access the API resources.

Request endpoint

All API requests have to be sent to this URL:

https://api.printful.com/

If you are using a proxy, make sure that all requests have host header set to api.printful.com.

Request parameters

Some mandatory parameters (like object identifiers) must be included in the request URL path

GET /orders/123

Additional parameters can be passed as GET variables:

GET /orders?offset=10&limit=5

For POST and PUT requests, a more complex data structure can be passed as JSON encoded data in the request body:

POST /orders

{"recipient":{...},"items":[...]}

Response body

The response body is always a JSON object that contains a response status code (identical to the HTTP status code) and the result of the action. If the status code is 200, then the action was successful.

{
   "code": 200, //Response status code
   "result":{
      //API method return data
      //...
   }
}

Sometimes the response includes paging information to allow to browse larger result sets by adding offset and limit GET parameters to the request URL.

{
   "code": 200, //Response status code
   "result":[
       {
          //Item 11
       },
       {
          //Item 12
       }
   ]
   "paging": {
      "total": 12,  //Total items available
      "offset": 10, //Items skipped from the beginning
      "limit": 20   //Number of items per page
   }
}

If the API call is not successful, then the response code is not in the 2xx range and the result attribute contains an error description.

{
    "code": 404,
    "result": "Not Found",
    "error": {
        "reason": "NotFound",
        "message": "Not Found"
    }
}

In general, response codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with Printful's servers.

Timestamps

All timestamps from the API are returned as integers in UNIX timestamp format.

Printful API has a general rate limit of 120 API calls per minute. Additionally, endpoints that perform resource intensive operations (such as mockup generator) have a lower allowed request limit.

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

Private tokens and public apps

There are two different ways of using Printful OAuth - Private token and Public App. If you are developing an API solution for your personal store, you should choose Private Token. But if you are building an Public App that will be used by a wider audience, you should be choosing Public App.

Client types

There are two different client types - Store and Account. Store access level client is only able to access the specific store. For Private tokens this store is specified when the token is created, but for Public apps this store is specified when the app is installed. Account level tokens on the other hand can manage all the stores associated with the account. For the endpoints that require specific store context, requests should contain X-PF-Store-Id header. Account level access currently is only available for Private tokens.

Scopes

Scopes are used to limit access to specific resources and their methods. Scopes are defined in the developer portal when creating a Private Token or Public App. Customers on Public App installation grant screen will see all requested permissions, so be thoughtful about which scopes to request.

List of currently available scopes

Developer Portal

Developer Portal is specifically designed for developers that want to interact with the Printful API. In the Developer Portal, it's possible to create and manage your Public Apps and Private tokens.

Acquiring Private Tokens

Private OAuth tokens can be generated in the Developer Portal's Token page. These tokens do not require refreshing and are valid until they expire or are deleted manually. Usage of these tokens is described below.

Acquiring OAuth tokens for Public Apps

For public apps to make requests on behalf of the customer, they must first acquire access tokens. In order to acquire these tokens, developers must follow these steps:

• create an app in Apps page of developer portals
• generate app-specific installation URL with Client id, Client secret, and other parameters
• redirect the user to app installation url
• once the users returns to redirect_url, use code parameter to acquire OAuth tokens

Public App installation flow

Public App installation starts with a user redirection to an app-specific installation URL. Installation URL has to be generated in the following format:

https://www.printful.com/oauth/authorize?client_id={clientId}&state={stateValue}&redirect_url={redirectUrl}

In this URL, the customer is asked to register or log in to an existing account. After authorization, the customer is redirected to the OAuth grant screen. This screen shows information about your app, and the customer is asked to accept the requested scopes. If the customer rejects the app installation, he is redirected back to your provided redirect_url with success=0 parameter. If the customer accepts app installation, he is redirected to your redirect_url with state={stateValue}&code={authorizationCode}&success=1 parameters.

After receiving authorization code, apps should request access and refresh tokens. To request these tokens, the app should make a POST request to https://www.printful.com/oauth/token page with the following parameters:

• grant_type=authorization_code
• client_id={clientId}
• client_secret={clientSecret}
• code={authorizationCode}

If the request is successful the following response is returned:

{
  "access_token": "smk_GN0I1Os3OdfqzjJnTOWn1wlbqqq2Y2Pc10TS",
  "expires_at": "1562157895",
  "token_type": "bearer",
  "refresh_token": "902LmW0sWNlY-mbrLhb6AgexkI6K4OFo3Hknak8HDhTy_ifB5SdoLH1QgV9"
}

Refreshing tokens

The access_token will expire in one hour. When access_token expires you must refresh it with the refresh_token. After refreshing tokens, you will receive a new set of access_token and refresh_token. If tokens are not refreshed within 90 days, refresh_token will expire, and the app will have to ask the user to reauthorize it. To refresh tokens you must make a POST request to https://www.printful.com/oauth/token with the parameters:

• grant_type=refresh_token
• client_id={clientId}
• client_secret={clientSecret}
• refresh_token={refreshToken}

The successful refresh request will result in a similar response that you received previously:

{
  "access_token": "smk_GN0I1Os3OdfqzjJnTOWn1wlbqqq2Y2Pc10TS",
  "expires_at": "1562157895",
  "token_type": "bearer",
  "refresh_token": "902LmW0sWNlY-mbrLhb6AgexkI6K4OFo3Hknak8HDhTy_ifB5SdoLH1QgV9"
}

OAuth API allows receiving data for token

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: For unauthenticated usages, up to 30 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.

Size guides

The Get Product Size Guide endpoint will return size guide data for the selected 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

The Products API resource lets you create, modify and delete products in a Printful store based on the Manual orders / API platform (you can create such store by going to the Stores section at your Printful dashboard.)

Important: Jewelry products are not supported via API.

To manage Warehouse products, please see Warehouse Products API.

The basics

Each product in your Printful store must contain one or multiple variants (imagine multiple sizes or colors of the same t-shirt design). Furthermore, for each variant, you have to specify both a blank product variant from our Printful Catalog and a print file. These two properties together with price and External ID (more on that later) will allow the variant to be purchasable. Please, see the following sections for more details. Finally, please note that for technical reasons a product in your Printful store is called a Sync Product and a variant of that product is called a Sync Variant. The maximum supported amount of Sync Variants a Sync Product can have is 100.

Assigning a blank product variant

Printful has a substantial catalog of blank products and variants, where each variant (e.g. size and color combination of a particular product) has a unique ID, which we call variant_id. You can browse through the catalog via Catalog API to find a specific variant_id. Moreover, when creating a Sync Product at your Printful store, each of its Sync Variants must be associated with a variant_id from the Printful Catalog. Furthermore, to assign a specific variant_id to a specific Sync Variant, simply add it to the HTTP request body (see examples at the specific endpoint).

Assigning a single print file

There are two ways to assign a print file to a Sync Variant. One is to specify the File ID if the file already exists in the File library of the authorized store;

Limitations

Important: The Products API is not intended and will never support creating and managing products in external platforms such as Shopify, WooCommerce and others. For managing your products from external platforms please refer to Ecommerce Platform Sync API

{
    ...
    "files": [
        {
            "id": 12345
        }
    ],
    ...
}

The second and most convenient method is to specify the file URL. If a file with the same URL already exists, it will be reused.

{
    ...
    "files": [
        {
            "url": "http://example.com/t-shirts/123/front.pdf"
        }
    ],
    ...
}

Moreover, each Sync Variant has to be linked with one or multiple print files. The available file types for each product are available from the Printful Catalogue API. You can add one file for each type by specifying the type attribute. For the default type, this attribute can be skipped.

...
"files":[
    {
        "type": "default",
        "url": "http://example.com/t-shirts/123/front.pdf"
    },
    {
        "type": "back"
        "url": "http://example.com/t-shirts/123/back.pdf"
    }
],
...

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

External ID

When creating a Sync Product and/or Sync Variant you can specify an External ID, which you can then use as a reference when managing or even ordering the specific Sync Product or Sync Variant. In particular, when requesting a specific Sync Product and Sync Variant, you can use either the internal Printful ID or your External ID (prefixed with an @ symbol) at the request URL.

Native inside label

Printful previously allowed customers to upload a fully customized inside label. Since these labels had to contain specific information about fabric composition, manufacturing, etc. to meet the legal requirements, users usually encountered issues to get their labels printed.

Inside labels are printed on the inside of the garment and require the removal of the original manufacturer's tag. They're only available for apparel with tear-away labels. An inside label must include the country of manufacturing origin, original garment size, and material information. To use our native label template you only need to upload a graphic (such as your brand's logo). The mandatory content will be generated and placed automatically.

...
"files":[
        {
            "type": "label_inside",
            "url": "http://example.com/logo/123/image.jpg",
            "options": [{
                "id": "template_type",
                "value": "native"
            }]
        },
],
...

Printful previously supported fully customized inside labels. These have now been deprecated. The ability to create orders with fully customized inside labels has been limited to only users who were actively using them in their stores before April 2020. This feature is no longer accessible to new users.

See examples