NAV Navbar
JSON

Printify Supply API v2019-06

Welcome!

Becoming a part of Printify's supplier network is a two-part process.

Once Print Providers have been integrated and their product offering is therefore visible on Printify, it will be convenient for our Merchants to discover your products and services, generate unique merchandise with our product generator app, and offer the merchandise in their online stores. Printify will then handle the merchandise creation process, communication with and support of individual Merchants, and arrange cancellations, reprints, error cases as well as merchant storefront integration – all on your, the Print Provider’s behalf.

Usage Guidelines

Printify Supply API endpoints are used internally by the core Printify Platform, and our engineering teams closely monitor the usage of the API. To ensure the highest quality experience for Printify users we ask that all integrations comply with the Printify API Terms and Printify Partnership Agreement. We also ask our Print Providers to ensure that requests resulting in an error response do not exceed 5% of our total requests.

If you have any technical questions, please send an email to [email protected].

Building blocks

API Features flow

Getting Started

What should I do now?

Here are the steps to set up your production facility with Printify:

  1. Register & create an account for your facility
  2. Sign and follow the provided Print Provider Agreement
  3. Develop and test your integration with our system (API documentation below)
  4. Provide additional info: SKU/stock/pricing data and endpoints, sizing info, etc.
  5. Successful test orders
  6. Launch! 🚀

What if I have questions or need help?

Once you've signed your Agreement, you'll have personalized attention from our technical team during the integration process. Also, you'll be able to contact us via private shared group chat or email.

However, we encourage you to first read through our API documentation below, and also check our list of Frequently Asked Questions. If anything is missing or unclear, please let us know!

Frequently Asked Questions (FAQ)

  1. Can I get help/tech assistance during integration/setup?

    Yes! We offer support via email, shared Slack channels, video calls, etc.

  2. Do you have a development system for testing integration? Can it point to our testing end points vs production end points?

    Yes: you will have access to a private web portal after signing the Agreement.

  3. Must we have all statuses up and running in order to launch, or can we launch with just created, packaged, canceled, and shipped, etc.?

    During initial phases of testing it's ok to miss some non-essential parts. But before the public launch, we'll need all test suit results to be green – that means all services must be supported and tested (see your Agreement). That includes: Stock, Helpdesk, etc.

  4. Is the Stock API required to be supported for the launch of this integration?

    Yes: we require support for all services, including the Stock API.

    When starting the integration and for SKUs available on demand, it's fine if you consistently respond with the number 999. This will give us better flexibility in the future, in case there are issues.

  5. Are we required to provide all statuses for the (Stock/Helpdesk/Tracking/etc.) API?

    Yes, full support is required in order to publicly launch your facility on our platform.

  6. Does Printify save and manage all of our products and variations?

    No: the stock list should come from your service and should represent available product variations and their availability levels. See the Stock API below.

  7. When orders are updated, how will the item information be sent? Will just the items that need updates to be sent or will an entirely new item list be sent containing all items in the order?

    The Helpdesk API PUT should accept one or multiple top-level attributes. If we ask you to update items, we send all items (top-level attribute) including the unchanged items. If it's not possible to update everything at once, we expect you to fail all the updates and leave the order unaffected.

    Also, we neither use nor plan to use line_items updates in the near future.

  8. Should the line item id be included when updating orders, and are line item ids guaranteed to be unique?

    Yes, the line item id is passed; this is necessary, for example when two unique items in an order being printed on the same SKU.

    Line item ids are guaranteed to be unique on the order level.

  9. Should we purge problematic orders from production and order systems and try completely over again? What if the order number you see different, because it comes from an automatically incremented column?

    Yes, this is how problematic orders should be handled. Also, we would prefer for order IDs to stay stable and consistent, so please don't change the order number. You can still indicate it via a Tracking API as a reprint event.

    If there are issues with an order we usually place separate orders with you.

  10. Not all of our items support all angles from some preview/print files; e.g. “sleeve”, “diagonal”. What should we do?

    This is fine; please reply with a 400 error along with a body and explanatory error messages. See a failed response example here.

  11. Re: firewalls and networking, will your system use a specific IP address or address ranges for outgoing requests?

    Yes: please ask via a secure channel and we will provide them.

  12. We see that email & phone_number are at the return and ship-to level: is this required or can we have them at the order level?

    Yes, this is required because these are 2 different addresses:

    address_to: client address, used to determine where to ship the order

    address_from: merchant address (default or custom specified) – used for returning packages.

  13. What shipping services (carrier, priority, etc.) does Printify Support?

    Generally, we can support the services you need, as mentioned in your Agreement – which also specifies the required API codes to submit orders to your API.

    During the testing stage, we generally support UPS Standard/Express and USPS Standard.

Features

Production API feature

The Production API allows Printify to submit orders to be fulfilled by a Print Provider. This is a required basic functionality to ensure order fulfilment.

Tracking API feature

The Tracking API allows Printify to track the status of Orders. This is a required basic functionality to ensure order status notifications for our merchants.

Helpdesk API feature

The Helpdesk API is meant to simplify the life of the first line of support, and reduce the volume of support inquiries towards Print Provider facilities. The Helpdesk API includes (but is not limited to) the following use cases:

Stock API feature

A Print Provider provides information about his inventory and stock levels, to ensure a smoother experience for Printify’s users in the Order submission process, as well as seamlessly update information about products being out of stock or discontinued.

API Access

API Reference

Printify Supply API is organized in accordance with REST architecture.

The API expects predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

To ensure it works best for all parties, we require that the API is used in secure way.

In this authentication model Print Providers grant access to Printify. The details a Print Provider must share with Printify before technical integration from Printify’s side can begin:

Production API

The Production API is used by Printify to submit an Order to be fulfilled by the Print Provider. The Print Provider receives an order request, accepts or rejects it, and if accepted proceeds with actual production and shipment of the Order.

What your system must provide for Production API

The Printify Print Provider integration is able to do the following with the Product resource:

Production order properties

idREAD-ONLY A unique string identifier for the Printify Order. Each id is unique across the Printify system. "id": "5cb87a8cd490a2ccb256cec4"
reference_id REQUIRED* A unique string identifier for the Printify Order in the Print Provider system. "reference_id": "1133456"
sample OPTIONAL DEPRECATED Optional boolean indicating if this is a sample order. "sample": true
reprint OPTIONAL DEPRECATED Optional boolean indicating if this is a reprint order. "reprint": true
xqc OPTIONAL DEPRECATED Optional boolean indicating if this order is eligible for an eXtra Quality Care.
The particular details what it entails are explained in business agreement signed by both parties (Printify and Print Provider). "xqc": true
address_to REQUIRED Address to ship an Order to. "address_to": { "address1": "1234 address1 line", "address2": "", "city": "EXAMPLE", "zip": "31345", "country": "US", "region": "NY", "company": "T-Shirt Company #1", "first_name": "john", "last_name": "smith", "email": "[email protected]", "phone": "3312312231" } See Address to properties for reference.
address_from REQUIRED Address to return an Order to, in case of issues with shipping. "address_from": { "address1": "1234 address1 line", "address2": "", "city": "EXAMPLE", "zip": "31345", "country": "US", "region": "NY", "company": "T-Shirt Company #1", "email": "[email protected]", "phone": "6512312231" } See Address from properties for reference.
shipping REQUIRED Shipping carrier configuration. "shipping": { "carrier": "UPS", "priority": "Express" } See Shipping properties for reference.
items REQUIRED Individual products (items) to be printed and shipped to the customer. "items": [ { "id": "62990be2d0827d94be27ba6b", "sku": "3001-BLACK-L", "preview_files": { "front": "https://images.printify.com/mockup/front-url.jpeg", "back": "https://images.printify.com/mockup/back-url.jpeg" }, "print_files": { "front": "https://images.printify.com/print/front-url.jpeg", "back": "https://images.printify.com/print/back-url.jpeg", "left_sleeve": "https://images.printify.com/print/left_sleeve-url.jpeg" }, "quantity": 1 }, { "id": "62990bebad471213f4276ab5", "sku": "3000-RED-L", "preview_files": { "front": "https://images.printify.com/mockup/front-url.jpeg", "back": "https://images.printify.com/mockup/back-url.jpeg" }, "print_files": { "front": "https://images.printify.com/print/front-url.jpeg" }, "quantity": 1 } ] See Item properties for reference.
tags NEW* OPTIONAL An array of tags to apply for an order. Added in backward compatible way, meaning that for existing integrations the previous way of receiving tags "sample", "reprint", "xqc" should be supported, but mentioned fields are deprecated and new integrations should use the new way of receiving order tags. "tags": [ "prioritised", "sample", "reprint" ] See order tags for reference.

Address to properties

address1REQUIRED First line of destination post address.
address2REQUIRED Second line of destination post address. Contains suite, apartment number, etc. May be sent as an empty string.
cityREQUIRED Destination city name
zipREQUIRED Destination ZIP code. If the destination country does not use ZIP codes it will be set to "00000".
countryREQUIRED Destination country code. ISO 3166 country codes are used.
regionOPTIONAL Destination state code. ISO 3166 state codes are used for the United States, and for other countries the region name will be used.
companyOPTIONAL Name of business to receive package
first_nameREQUIRED First name of package receiver.
last_nameREQUIRED Last name of package receiver.
emailOPTIONAL Email of package receiver.
phoneOPTIONAL Phone number of package receiver.

Address from properties

address1REQUIRED First line of return post address.
address2REQUIRED Second line of return post address. Contains suite, apartment number, etc. May be sent as an empty string.
cityREQUIRED Return city name
zipREQUIRED Return ZIP code. If the destination country does not use ZIP codes it will be set to "00000".
countryREQUIRED Return country code. ISO 3166 country codes are used.
regionOPTIONAL Return state code. ISO 3166 state codes are used for the United States, and for other countries the region name will be used.
companyREQUIRED Name of business for return address.
emailOPTIONAL Email of the seller for return address.
phoneOPTIONAL Phone number of the seller for return address.

Shipping properties

carrierREQUIRED Carrier name used for sending the package.
priorityREQUIRED Priority class of the shipment. Example: "express" or "standard"

Item properties

idREQUIRED Id of the line item for reference.
skuREQUIRED SKU (Stock keeping unit) that represents what kind of product and variation to be used.
preview_filesREQUIRED List of image links. These image links must show product with designs representing how the product should look after printing. There can be images from different angles.
print_filesREQUIRED List of print image links. These links will contain print files to be used for printing purposes. These print files are tailored for the respective printing process. If there are multiple areas to be printed there will be multiple print files.
quantityREQUIRED Represents the amount of items to be printed with this design.

Order tags

Represents additional order options passed to manufacturer. Currently, supported values below. List of supported tags could be extended.

sample Indicating if this is a sample order.
reprint Indicating if this is a reprint order.
prioritised NEW* Indicating if this is a prioritised order.

Endpoints

POST POST /v2019-06/orders.json
Submit a production order

POST /v2019-06/orders.json
{ "id": "5cb87a8cd490a2ccb256cec4", "sample": true, "reprint": false, "xqc": true, "tags": [ "prioritised", "sample" ], "address_to": { "address1": "1234 address1 line", "address2": "", "city": "EXAMPLE", "zip": "31345", "country": "US", "region": "NY", "first_name": "john", "last_name": "smith", "email": "[email protected]", "phone": "3312312231" }, "address_from": { "address1": "1234 address1 line", "address2": "", "city": "EXAMPLE", "zip": "31345", "country": "US", "region": "NY", "company": "T-Shirt Company #1", "email": "[email protected]", "phone": "6512312231" }, "shipping": { "carrier": "UPS", "priority": "Express" }, "items": [ { "id": "62990bebad471213f4276ab5", "sku": "3001-BLACK-L", "preview_files": { "front": "https://images.printify.com/mockup/front-url.jpeg", "back": "https://images.printify.com/mockup/back-url.jpeg" }, "print_files": { "front": "https://images.printify.com/print/front-url.jpeg", "back": "https://images.printify.com/print/back-url.jpeg", "left_sleeve": "https://images.printify.com/print/left_sleeve-url.jpeg" }, "quantity": 1 }, { "id": "6299c9aa18b4f73df073095a", "sku": "3000-RED-L", "preview_files": { "front": "https://images.printify.com/mockup/front-url.jpeg", "back": "https://images.printify.com/mockup/back-url.jpeg" }, "print_files": { "front": "https://images.printify.com/print/front-url.jpeg" }, "quantity": 1 } ] }
View sample successful response (HTTP 200)

View sample failed response (HTTP 400)

POST POST /v2019-06/facilities/{FACILITY-ID}/orders.json
Submit production order to the facility
This API is used to directly place an order to a specific facility.

POST /v2019-06/facilities/{FACILITY-ID}/orders.json
{ "id": "5cb87a8cd490a2ccb256cec4", "tags": [ "prioritised", "sample", "reprint" ], "address_to": { "address1": "108 West 13th Street", "city": "Wilmington", "zip": "19801", "country": "US", "region": "DE", "first_name": "John", "last_name": "Smith", "email": "[email protected]", "phone": "3312312231" }, "address_from": { "address1": "108 West 13th Street", "city": "Wilmington", "zip": "19801", "country": "US", "region": "DE", "company": "Printify Inc", "email": "[email protected]", "phone": "6512312231" }, "shipping": { "carrier": "UPS", "priority": "Express" }, "items": [ { "id": "6299c9b59abed8ddb15f2a76", "sku": "3001-BLACK-L", "preview_files": { "front": "https://images.printify.com/mockup/front-url.jpeg", "back": "https://images.printify.com/mockup/back-url.jpeg" }, "print_files": { "front": "https://images.printify.com/print/front-url.jpeg", "back": "https://images.printify.com/print/back-url.jpeg", "left_sleeve": "https://images.printify.com/print/left_sleeve-url.jpeg" }, "quantity": 1 } ] }
View expected successful response (HTTP 201 Created)

View expected failed response (HTTP 404 Not Found) (example - when FACILITY-ID is invalid)

View expected failed response (HTTP 422 Unprocessable Entity) (example 1 - address_to, shipping)

View expected failed response (HTTP 422 Unprocessable Entity) (example 2 - out of stock item)
Expected values of type field:

  • tags
  • address_to
  • address_from
  • shipping
  • items
  • other


View expected failed response (HTTP 409 Conflict) - duplicate in submitted order

GET /v2019-06/orders/{PRINTIFY-ID}.json
Retrieve a production order

GET /v2019-06/orders/{PRINTIFY-ID}.json
View response

Tracking API

The Tracking API is used to provide status of Order to Printify's Merchants; therefore, there must be an endpoint for fetching the status history and current state of an Order.

What your system must provide to the Tracking API

Your system must have an endpoint exposing event data over the Order lifecycle:
- GET /v2019-06/order/{PRINTIFY-ID}/events.json
Provide event log about order

Endpoints

GET /v2019-06/orders/events.json
Provide event log about an Order
GET /v2019-06/order/{PRINTIFY-ID}/events.json
View sample response

Order tracking properties

statusREQUIRED One of possible order statuses.
eventsREQUIRED Array of order events in chronological order. See tracking event for reference.

Tracking event properties

timeREQUIRED Date and time in UTC when the event has occurred.
actionREQUIRED Event type.
One of possible order item status changes.
affected_itemsREQUIRED The list of affected items IDs.
tracking_urlOPTIONAL Parcel tracking URL.
tracking_numberOPTIONAL Parcel tracking code.
carrierOPTIONAL Shipping carrier.
noteOPTIONAL Additional text notes.

List of available statuses and events

API Features flow

StatusDescriptionIs terminal state?
created An Order has been created and is waiting to be printed.
View event example
No
picked Blueprint for a specific item is sent for printing.
View event example
No
printed The item was printed and is awaiting packaging.
View event example
No
packaged The item is packed and ready to be shipped.
View event example
No
shipped The parcel has been shipped, and a tracking number has been obtained.
View event example
Yes
reprint The item had manufacturing issues on print providers side.
View event example
No
canceled The item have been canceled by Printify/merchant.
View event example
Yes
declined The item have been declined by print provider.
View event example
Yes

Helpdesk API

The Helpdesk API helps improve the functionality of your integration with Printify. It provides the ability to cancel or update orders through the API, without need for separate communication.

What your system must provide for Helpdesk API

Your system must implement these endpoints:

Endpoints

PUT PUT /v2019-06/order/{PRINTIFY-ID}.json
This endpoint should enable the possibility to update orders.
  • If it is not possible to update an Order, an error message and error code should be returned.
  • This endpoint is required to accept partial updates, e.g. each top level attribute could be updated separately.
PUT /v2019-06/order/{PRINTIFY-ID}.json
{ "reprint": true, "xqc": false, "tags": [ "reprint" ], "address_to": { "address1": "1234 updated address1 line", "address2": "", "city": "UPDATED CITY", "zip": "31345", "country": "US", "region": "NY", "first_name": "john", "last_name": "smith", "email": "[email protected]", "phone": "3312312231" }, "address_from": { "address1": "1234 address1 line", "address2": "", "city": "EXAMPLE", "zip": "31345", "country": "US", "region": "NY", "company": "T-Shirt Company #1", "email": "[email protected]", "phone": "6512312231" }, "shipping": { "carrier": "UPS", "priority": "Express" }, "items": [ { "id": "62990b962daa13b88874548a", "sku": "3001-BLACK-L", "preview_files": { "front": "https://images.printify.com/mockup/front-url.jpeg", "back": "https://images.printify.com/mockup/back-url.jpeg" }, "print_files": { "front": "https://images.printify.com/print/front-url.jpeg", "back": "https://images.printify.com/print/back-url.jpeg", "left_sleeve": "https://images.printify.com/print/left_sleeve-url.jpeg" }, "quantity": 1 }, { "id": "62990ba51e24323a378529fe", "sku": "3000-RED-L", "preview_files": { "front": "https://images.printify.com/mockup/front-url.jpeg", "back": "https://images.printify.com/mockup/back-url.jpeg" }, "print_files": { "front": "https://images.printify.com/print/front-url.jpeg", }, "quantity": 2 } ] }
View shipping details update example

View successful response
View address error response

List of error messages for order updating

CodeDescription
tagsTags change was not successful.
address_toaddress_to change was not successful.
address_fromaddress_from change was not successful.
shippingShipping method or carrier cannot be edited.
itemItem sku, quantity, or print images cannot be edited.
expiredIt is too late to make changes.
otherSome other error when updating order.

POST POST /v2019-06/order/{PRINTIFY-ID}/cancel.json

The request must either cancel all order line items requested or do not perform changes to the order.

This IS NOT idempotent operation and will not be retried.

Request
Method POST
URL path /v2019-06/order/{PRINTIFY-ID}/cancel.json
Body { "items": [ "62990bc71d9ee35dd32bae14", "62990bcf6b2e5692fddae37c" ] }

items is an array of order line items identifiers to cancel

Response 204 No Content

Must be returned when all the requested order line items were canceled.

Response 409 Conflict

Must be returned when at least one of the below is true:

  • at least one order line item can not be canceled,
  • at least one order line has been canceled already.

This means that whole cancelation failed and the order must not be changed.

Body { "errors": [ { "id": "62990bb59367f9afbc11ebd5", "message": "Order line item is already shipped and could not be canceled" } ] }
Body properties
errors
id Order line item identifier that could not be canceled
message Error message specifying why this particular order line item could not be canceled

Stock API

Stock API is aimed at making your integration with Printify more functional by enabling your system to notify Printify about inventory changes. The request parameter SKU has to be case-insensitive.

What your system must provide for integrating with Printify Stock API

The following endpoints must be available for Printify Stock API integration:

Stock item properties

statusREQUIRED enum possible values:
  • in-stock - sku is in stock, quantity > 0
  • out-of-stock - sku is out of stock. Quantity is not applicable
  • discontinued - sku is discontinued, restock is not planned in the nearest future. Quantity is not applicable
  • on-demand - sku is in stock for unlimited amount (paper, fabric). Quantity is not applicable
stockREQUIRED Amount (quantity) of available items in an inventory (integer), required only for in-stock status. 999 might be returned if items are available, but there is no possibility to calculate the exact amount.
restock_estimate OPTIONAL Date and time of current estimation on when the stock will be renewed. Applicable for out-of-stock status
discontinued_since OPTIONAL In case if the status is discontinued, date and time value of when it has happened must be provided.

Date and time fields must be in UTC timezone and conform to the ISO 8601 standard.

Endpoints

GET GET /v2019-06/stock.json
Provide stock availability for products
The endpoint returns an array of all available product variations. Each variation must display the remaining stock quantity and stock status.
GET /v2019-06/stock.json?limit=20&offset=0
View sample response

GET GET /v2019-06/stock/{SKU}.json
Provide stock availability for a single product variation
The endpoint returns stock availability info for one product variation by its SKU. This info must contain the remaining stock quantity and stock status. SKU is case insensitive
GET /v2019-06/stock/{SKU}.json
View sample response

GET GET /v2019-06/facilities/{FACILITY-ID}/stock/{SKU}.json
Provide stock availability for a single product variation on the facility level
The endpoint returns stock availability info for one product variation by its SKU at the particular facility. This info must contain the remaining stock quantity and stock status. SKU is case insensitive. See details of FACILITY-ID in Submit production order to the facility

GET /v2019-06/facilities/{FACILITY-ID}/stock/{SKU}.json

View expected successful response (HTTP 200 in-stock)

View expected successful response (HTTP 200 out-of-stock)

View expected failed response (HTTP 404 Not Found) (example - when FACILITY-ID is invalid)

View expected failed response (HTTP 404 Not Found) (example - when SKU does not exist)

HTTP Status Codes

Printify API relies heavily on standard HTTP response codes codes. Please find a brief summary of status codes used below.

Success

Code Name Description
200 OK Request completed successfully.
201 Created The request has been fulfilled and has resulted in one or more new resources being created.
202 Accepted The request has been accepted for processing, but processing has not been completed.
204 No Content Indicates that the server has successfully fulfilled the request and that there is no content to send in the response payload body.

Idempotency

Code Name Description
304 Not modified The request has already been received.

User error codes

These errors generally indicate a problem on the client side. If you are getting one of these, check your code and the request details.

Code Name Description
400 Bad Request The request encoding is invalid; the request can't be parsed as valid JSON.
401 Unauthorized Accessing a protected resource without authorization or with invalid credentials.
402 Payment Required The account associated with the API key making requests hits a quota.
403 Forbidden Accessing a protected resource with API credentials that don't have access to that resource.
404 Not Found Route or resource is not found. This error is returned when the request hits an undefined route, or if the resource doesn't exist (e.g. has been deleted).
409 Conflict Indicates a request conflict with current state of the target resource. For example trying to cancel already canceled order line item.
413 Request Entity Too Large The request exceeded the maximum allowed payload size. Shouldn't appear under normal use.
422 Invalid Request The request data is invalid. This includes most of the base-specific validations. You will receive a detailed error message and code pointing to the exact issue.
429 Too Many Requests Too Many Requests response status code indicates that the system has sent too many requests in a given amount of time ("rate limiting").

Server error codes

These errors generally represent an error on our side. In the event of a 5xx error code, detailed information about the error will be automatically recorded, and Printify's developers will be notified.

Code Name Description
500 Internal Server Error The server encountered an unexpected condition.
502 Bad Gateway Servers are restarting or an unexpected outage is in progress. Requests must be safe to retry.
503 Service Unavailable The server could not process your request in time. The server could be temporarily unavailable, or it could have timed out processing your request. You should retry the request with backoffs.

History