Printful

API Documentation | Printful

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

E-commerce#shopping

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

About the Printful API

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.

Postman Collection

You can explore the API using the Postman collection:

Download Postman Collection

Requests and responses

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
   }
}

Error response

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.

Rate Limits

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 accounts have an individually agreed higher limit.

Every response returns your current allowance in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and requests over the limit receive a 429 Too Many Requests response with a Retry-After header. See Rate Limiting for the full limits, the header semantics and guidance on handling 429 responses.

Endpoints 56

OAuth API

  • GETGet scopes for token/oauth/scopesReturns a list of scopes associated with the token

Catalog API

  • GETGet Products/productsReturns list of Products available in the Printful
  • GETGet Variant/products/variant/:idReturns information about a specific Variant and its Product
  • GETGet Product/products/:idReturns information about a specific product and a list of variants for this product.
  • GETGet Product Size Guide/products/:id/sizesReturns information about the size guide for a specific product.
  • GETGet Categories/categoriesReturns list of Catalog Categories available in the Printful
  • GETGet Category/categories/:idReturns information about a specific category.

Products API

  • GETGet Sync Products/store/productsReturns a list of Sync Product objects from your custom Printful store.
  • POSTCreate a new Sync Product/store/productsCreates a new Sync Product together with its Sync Variants (See examples).
  • GETGet a Sync Product/store/products/:idGet information about a single Sync Product and its Sync Variants.
  • PUTModify a Sync Product/store/products/:idModifies an existing Sync Product with its Sync Variants. Please note that in the request body you only need to specify the fields that need to be changed.…
  • DELETEDelete a Sync Product/store/products/:idDeletes a Sync Product with all of its Sync Variants
  • GETGet a Sync Variant/store/variants/:idGet information about a single Sync Variant.
  • PUTModify a Sync Variant/store/variants/:idModifies an existing Sync Variant. Please note that in the request body you only need to specify the fields that need to be changed. See examples for more…
  • DELETEDelete a Sync Variant/store/variants/:idDeletes a single Sync Variant.
  • POSTCreate a new Sync Variant/store/products/:id/variantsCreates a new Sync Variant for an existing Sync Product (See examples).

Product Templates API

  • GETGet product template list/product-templatesReturns a list of templates.
  • GETGet product template/product-templates/:idGet information about a single product template
  • DELETEDelete product template/product-templates/:idDelete product template by ID or External Product ID

Orders API

  • GETGet list of orders/ordersReturns list of order objects from your store
  • POSTCreate a new order/ordersCreates a new order and optionally submits it for fulfillment (See examples)
  • GETGet order data/orders/:idReturns order data by ID or External ID.
  • PUTUpdate order data/orders/:idUpdates unsubmitted order and optionally submits it for the fulfillment. Note that you need to post only the fields that need to be changed, not all required…
  • DELETECancel an order/orders/:idCancels pending order or draft. Charged amount is returned to the store owner's credit card.
  • POSTConfirm draft for fulfillment/orders/:id/confirmApproves for fulfillment an order that was saved as a draft. Store owner's credit card is charged when the order is submitted for fulfillment.
  • POSTEstimate order costs/orders/estimate-costsCalculates the estimated order costs including item costs, print costs (back prints, inside labels etc.), shipping and taxes

File Library API

  • POSTAdd a new file/filesAdds a new File to the library by providing URL of the file. If a file with identical URL already exists, then the original file is returned. If a file does…
  • GETGet file/files/:idReturns information about the given file.
  • POSTReturn available thread colors from provided image URL/files/thread-colorsReturns colors in hexadecimal format. Returned thread colors are matched as closely as possible to provided image colors. See examples

Shipping Rate API

  • POSTCalculate shipping rates/shipping/ratesReturns available shipping options and rates for the given list of products. Recipient Address Requirements: Only country_code is required in the recipient…

Ecommerce Platform Sync API

  • GETGet list of Sync Products/sync/productsReturns list of Sync Product objects from your store.
  • GETGet a Sync Product/sync/products/:idGet information about a single Sync Product and its Sync Variants
  • DELETEDelete a Sync Product/sync/products/:idDeletes a Sync Product with all of its Sync Variants
  • GETGet a Sync Variant/sync/variant/:idGet information about a single Sync Variant
  • PUTModify a Sync Variant/sync/variant/:idModifies an existing Sync Variant. Please note that in the request body you only need to specify the fields that need to be changed. See examples for more…
  • DELETEDelete a Sync Variant/sync/variant/:idDeletes configuraton information (variant_id, print files and options) and disables automatic order importing for this Sync Variant.

Country/State Code API

  • GETRetrieve country list/countriesReturns list of countries and states that are accepted by the Printful.

Tax Rate API

  • GETGet a list of countries for tax calculation/tax/countriesRetrieve state list that requires sales tax calculation
  • POSTCalculate tax rate/tax/ratesDeprecated. Calculates sales tax rate for given address if required. <div class="alert alert-info"> ⚠️ <strong>Important – <tt>/tax/rates</tt> endpoint…

Webhook API

  • GETGet webhook configuration/webhooksReturns configured webhook URL and list of webhook event types enabled for the store
  • POSTSet up webhook configuration/webhooksUse this endpoint to enable a webhook URL for a store and select webhook event types that will be sent to this URL. Note that only one webhook URL can be…
  • DELETEDisable webhook support/webhooksRemoves the webhook URL and all event types from the store.

Store Information API

  • POSTChange packing slip/store/packing-slipModifies packing slip information of the currently authorized Printful store.
  • GETGet basic information about stores/storesGet basic information about stores depending on the token access level
  • GETGet basic information about a store/stores/:idGet basic information about a store based on provided ID

Mockup Generator API

  • POSTCreate a mockup generation task/mockup-generator/create-task/:idCreates an asynchronous mockup generation task. Generation result can be retrieved using mockup generation task retrieval endpoint.<br> Rate limiting: Up to…
  • GETRetrieve product variant printfiles/mockup-generator/printfiles/:idList of printfiles available for products variants. Printfile indicates what file resolution should be used to create a mockup or submit an order. <div…
  • GETMockup generation task result/mockup-generator/task?task_key=stringReturns asynchronous mockup generation task result. If generation task is completed, it will contain a list of generated mockups.
  • GETLayout templates/mockup-generator/templates/:idRetrieve list of templates that can be used for client-side positioning. <div class="alert alert-info"> This endpoint uses DTG as a default printing technique…

Warehouse Products API

  • GETGet a list of your warehouse products/warehouse/productsReturns a list of warehouse products from your store <div class="alert alert-info"> The response for this endpoint was documented as paginated, although it…
  • GETGet warehouse product data/warehouse/products/:idReturns warehouse product data by ID

Reports API

  • GETGet statistics/reports/statistics?date_from=2022-08-01&date_to=2022-08-31&report_types=sales_and_costs,profitReturns statistics for specified report types. You need to specify the report types you want to retrieve in the report_types query parameter as a…

Approval Sheets API

  • GETRetrieve a list of approval sheets/approval-sheetsRetrieve a list of approval sheets confirming suggested changes to files of on hold orders.
  • POSTApprove a design/approval-sheets?confirm_hash=a14e51714be01f98487fcf5131727d31Uses the confirm hash of an approval sheet to approve a design and remove the hold on an order
  • POSTSubmit changes to an approval sheet/approval-sheets/changes?confirm_hash=a14e51714be01f98487fcf5131727d31Use this to submit alternative changes to a design that has an approval sheet
  • POSTSubmit changes to an approval sheets in bulk/approval-sheets/bulk-changesUse this to submit alternative changes in bulk to a design that has an approval sheet via group_hash

API details

Base URL
https://api.printful.com
Authentication
OAuth 2.0 (authorization code flow) with 10 scopes
Operations
56 operations on 41 pathsGET 30POST 15DELETE 7PUT 4
1 marked deprecated
Main resources
Products API 9Orders API 7Catalog API 6Ecommerce Platform Sync API 6Approval Sheets API 4Mockup Generator API 4File Library API 3Product Templates API 3Store Information API 3Webhook API 3
Description format
OpenAPI 3.0.0, API version 1.0

How to test the API Documentation | Printful in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the API Documentation | Printful collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (authorization code flow) with 10 scopes. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Get scopes for token” (GET /oauth/scopes), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the API Documentation | Printful?

About the Printful API The Printful API is a RESTful API, that uses an HTTP protocol for communication. HTTP GET, POST, PUT and DELETE methods are used to… It is listed under E-commerce and has 56 endpoints.

Who publishes the API Documentation | Printful?

It is listed from Printful's public API description (an OpenAPI document), not published by Printful on Swastik Codes. Anyone who controls printful.com can claim the profile by adding a DNS TXT record.

What is the base URL of the API Documentation | Printful?

Requests go to https://api.printful.com. Endpoint paths are added to this base URL.

How do I authenticate with the API Documentation | Printful?

With OAuth 2.0 (authorization code flow) with 10 scopes.

How many endpoints does the API Documentation | Printful have?

56 operations on 41 paths (30 GET, 15 POST, 7 DELETE, 4 PUT). The largest groups are Products API, Orders API, Catalog API, Ecommerce Platform Sync API.

Is forking the API Documentation | Printful free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.