Orders API

The Orders API is the most important part of the Printful API - it allows you to create new orders and confirm them for fulfillment.

Order life cycle and statuses

Each order will go through different states while being processed. The following order status types indicate those states:

draft The order is created but is not yet submitted for fulfillment. You still can edit it and confirm later.
pending The order has been submitted for fulfillment, but is not yet accepted for fulfillment. You can still cancel the order if you need.
failed Order was submitted for fulfillment but was returned for review because of an error (problem with address, missing printfiles, charging has failed, etc.).
canceled The order has been canceled and can no longer be processed. If the order was charged then the amount has been returned to your credit card.
inprocess The order is being fulfilled and can no longer be cancelled or modified. Contact customer support if there are any issues with the order at this point.
onhold The order has encountered a problem during the fulfillment that needs to be resolved together with Printful customer service before fulfillment can continue.
partial The order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilled All items have been shipped successfully

To sum up, the API allows you to create orders with status draft and then move them to state pending (both steps can be done with a single action). You are only charged for orders that have been confirmed. If the order encounters a problem after it has been submitted, then it is moved to the failed state so that the problem can be fixed and the order can be resubmitted.

External ID

External ID is an optional feature that allows you to link your Printful order with the Order ID from your system without the need to store additional data on your side. External ID can be up to 32 characters long and contain digits, Latin alphabet letters, dashes an underscores, however it is recommended to use integer numbers. Each order's External ID must be unique within the store.

To use the External ID feature, you just add the external_id attribute when creating the order. Later, when you need to access the order through the API, you can reference it by both the Order ID and by External ID (if you prefix it with the @ symbol).

GET /orders/11001  - reference by Printful Order ID
GET /orders/@988123  - reference by External ID
GET /orders/@AA123123  - reference by External ID

You can assign the external_id attribute to line items as well. In this case they have to be unique per order.

Specifying products

To specify the exact variant of the product, you have to use the variant_id attribute of the order item. Each available unique item (including size/color) has its own Variant ID that can be acquired through the Product Catalog API.

Adding print files

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

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

The second and the 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"},
],
...

Specifying multiple files per item

Each item in the order has to be linked with one or multiple files. The available file types for each product are available from the Products Catalog API.

You can add one file for each type by specifying the type attribute. For the default type, this attribute can be skipped.

...
"files":[
	{
		//Primary file - front print
		"type": "default",//This line is optional
		"url": "http://example.com/t-shirts/123/front.pdf"
	},
	{
		//Additional file - back print
		"type": "back"
		"url": "http://example.com/t-shirts/123/back.pdf"
	},
	{
		//Additional file - mockup image
		"type": "preview"
		"url": "http://example.com/t-shirts/123/preview.png"
	}
],
...

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

Retail costs

Printful allows you to specify your retail costs for the order so that the packing slip for international orders can contain your correct retail prices. To enable retail costs, each item in the order has to contain the retail_price attribute. You can also specify a custom discount sum, shipping costs and taxes in the retail_costs object when creating the order. If the retail costs are missing, the packing slip will contain the Printful prices instead.

Get list of orders

GET https://api.printful.com /orders

Returns list of order objects from your store
Input parameters:
status string Filter by order status
offset integer Result set offset
limit integer Number of items per page (max 100)
Response format:
code integer Response status code 200
result Order [ ] Array of Order data
id integer Order ID
external_id string Order ID from the external system
status string Order status:
draft - order is not submitted for fulfillment
failed - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
pending - order has been submitted for fulfillment
canceled - order is canceled
onhold - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
inprocess - order is being fulfilled and is no longer cancellable
partial - order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilled - all items are shipped
shipping string Shipping method. Defaults to 'STANDARD'
created timestamp Time when the order was created
updated timestamp Time when the order was updated
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
state_name string State name
country_code string Country code
country_name string Country name
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
id integer Line item ID
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
price string Printful price of the item
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
product ProductVariant Short information about the Product and Variant
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
costs Costs Order costs (Printful prices, in USD)
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
shipments Shipment [ ] Array of shipments already shipped for this order
id integer Shipment ID
carrier string Carrier name
service string Delivery service name
tracking_number string Shipment tracking number
tracking_url string Shipment tracking URL
created timestamp Shipping time
ship_date string Ship date
reshipment boolean Whether this is a reshipment
items ShipmentItem [ ] Array of items in this shipment
item_id integer Line item ID
quantity integer Quantity of items in this shipment
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
paging Paging Paging information
total integer Total items available
offset integer Current result set page offset
limit integer Max number of items per page
API key
status Filter by order status
offset Result set offset
limit Number of items per page (max 100)
Execute

Create a new order

POST https://api.printful.com /orders

Creates a new order and optionally submits it for fulfillment
Input parameters:
Request body Order Order data
external_id string Order ID from the external system
shipping string Shipping method. Defaults to 'STANDARD'
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
country_code string Country code
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
url string Source URL where the file is downloaded from
filename string File name
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
currency string 3 letter currency code (optional), required if the retail costs should be convert from another currency instead of USD
confirm boolean Automatically submit the newly created order for fulfillment (skip the Draft phase)
update_existing boolean Try to update existing order if an order with the specified external_id already exists
Response format:
code integer Response status code 200
result Order Order data
id integer Order ID
external_id string Order ID from the external system
status string Order status:
draft - order is not submitted for fulfillment
failed - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
pending - order has been submitted for fulfillment
canceled - order is canceled
onhold - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
inprocess - order is being fulfilled and is no longer cancellable
partial - order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilled - all items are shipped
shipping string Shipping method. Defaults to 'STANDARD'
created timestamp Time when the order was created
updated timestamp Time when the order was updated
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
state_name string State name
country_code string Country code
country_name string Country name
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
id integer Line item ID
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
price string Printful price of the item
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
product ProductVariant Short information about the Product and Variant
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
costs Costs Order costs (Printful prices, in USD)
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
shipments Shipment [ ] Array of shipments already shipped for this order
id integer Shipment ID
carrier string Carrier name
service string Delivery service name
tracking_number string Shipment tracking number
tracking_url string Shipment tracking URL
created timestamp Shipping time
ship_date string Ship date
reshipment boolean Whether this is a reshipment
items ShipmentItem [ ] Array of items in this shipment
item_id integer Line item ID
quantity integer Quantity of items in this shipment
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
API key
Request body
confirm Automatically submit the newly created order for fulfillment (skip the Draft phase)
update_existing Try to update existing order if an order with the specified external_id already exists
Execute
Minimum required information to create an order.
Request body:
{
    "recipient": {
        "name": "John Doe",
        "address1": "19749 Dearborn St",
        "city": "Chatsworth",
        "state_code": "CA",
        "country_code": "US",
        "zip": "91311"
    },
    "items": [{
        "variant_id": 1,
        "quantity": 1,
        "files": [{
            "url": "http://example.com/files/posters/poster_1.jpg"
        }]
    }]
}
Response data:
{
    "code": 200,
    "result": {
        "id": 21510,
        "external_id": null,
        "status": "draft",
        "shipping": "STANDARD",
        "created": 1390825082,
        "updated": 1390825082,
        "recipient": {
            "name": "John Doe",
            "company": null,
            "address1": "19749 Dearborn St",
            "address2": null,
            "city": "Chatsworth",
            "state_code": "CA",
            "state_name": "California",
            "country_code": "US",
            "country_name": "United States",
            "zip": "91311",
            "phone": null,
            "email": null
        },
        "items": [{
            "id": 17621,
            "external_id": null,
            "variant_id": 1,
            "quantity": 1,
            "price": "13.00",
            "retail_price": null,
            "name": "Unframed Poster 18×24",
            "product": {
                "variant_id": 1,
                "product_id": 1,
                "image": "https://www.printful.com/storage/products/poster_18x24.jpg",
                "name": "Unframed Poster 18×24"
            },
            "files": [{
                "id": 11818,
                "type": "default",
                "hash": null,
                "url": "http://example.com/files/posters/poster_1.jpg",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1390823900,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            }],
            "options": []
        }],
        "costs": {
            "subtotal": "13.00",
            "discount": "0.00",
            "shipping": "7.95",
            "tax": "1.17",
            "total": "22.12"
        },
        "retail_costs": {
            "subtotal": null,
            "discount": null,
            "shipping": null,
            "tax": null,
            "total": null
        },
        "shipments": []
    }
}
Create order with external ID, custom item names and retail price information.
Request body:
{
    "external_id": "9887112",
    "recipient": {
        "name": "John Doe",
        "address1": "19749 Dearborn St",
        "city": "Chatsworth",
        "state_code": "CA",
        "country_code": "US",
        "zip": "91311"
    },
    "items": [{
        "variant_id": 2,
        "quantity": 1,
        "name": "Niagara Falls poster",
        "retail_price": "19.99",
        "files": [{
            "url": "http://example.com/files/posters/poster_2.jpg"
        }]
    }, {
        "variant_id": 1,
        "quantity": 3,
        "name": "Grand Canyon poster",
        "retail_price": "17.99",
        "files": [{
            "url": "http://example.com/files/posters/poster_3.jpg"
        }]
    }],
    "retail_costs": {
        "shipping": "24.50"
    }
}
Response data:
{
    "code": 200,
    "result": {
        "id": 21509,
        "external_id": "9887112",
        "status": "draft",
        "shipping": "STANDARD",
        "created": 1390825006,
        "updated": 1390825006,
        "recipient": {
            "name": "John Doe",
            "company": null,
            "address1": "19749 Dearborn St",
            "address2": null,
            "city": "Chatsworth",
            "state_code": "CA",
            "state_name": "California",
            "country_code": "US",
            "country_name": "United States",
            "zip": "91311",
            "phone": null,
            "email": null
        },
        "items": [{
            "id": 17619,
            "external_id": null,
            "variant_id": 2,
            "quantity": 1,
            "price": "18.00",
            "retail_price": "19.99",
            "name": "Niagara Falls poster",
            "product": {
                "variant_id": 2,
                "product_id": 1,
                "image": "https://www.printful.com/storage/products/poster_24x36.jpg",
                "name": "Unframed Poster 24×36"
            },
            "files": [{
                "id": 11819,
                "type": "default",
                "hash": null,
                "url": "http://example.com/files/posters/poster_2.jpg",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1390824712,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            }],
            "options": []
        }, {
            "id": 17620,
            "external_id": null,
            "variant_id": 1,
            "quantity": 3,
            "price": "13.00",
            "retail_price": "17.99",
            "name": "Grand Canyon poster",
            "product": {
                "variant_id": 1,
                "product_id": 1,
                "image": "https://www.printful.com/storage/products/poster_18x24.jpg",
                "name": "Unframed Poster 18×24"
            },
            "files": [{
                "id": 11820,
                "type": "default",
                "hash": null,
                "url": "http://example.com/files/posters/poster_3.jpg",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1390824712,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            }],
            "options": []
        }],
        "costs": {
            "subtotal": "57.00",
            "discount": "0.00",
            "shipping": "9.95",
            "tax": "5.13",
            "total": "72.08"
        },
        "retail_costs": {
            "subtotal": "73.96",
            "discount": "0.00",
            "shipping": "24.50",
            "tax": "0.00",
            "total": "98.46"
        },
        "shipments": []
    }
}
Order a shirt with a preview image added, both front and back print files specified and the option to tear off inside label selected.
Request body:
{
    "recipient": {
        "name": "John Doe",
        "address1": "19749 Dearborn St",
        "city": "Chatsworth",
        "state_code": "CA",
        "country_code": "US",
        "zip": "91311"
    },
    "items": [{
        "variant_id": 1118,
        "quantity": 1,
        "files": [{
            "url": "http://example.com/files/tshirts/shirt_front.ai"
        }, {
            "type": "back",
            "url": "http://example.com/files/tshirts/shirt_back.ai"
        }, {
            "type": "preview",
            "url": "http://example.com/files/tshirts/shirt_mockup.jpg"
        }],
        "options": []
    }]
}
Response data:
{
    "code": 200,
    "result": {
        "id": 21516,
        "external_id": null,
        "status": "draft",
        "shipping": "STANDARD",
        "created": 1390825437,
        "updated": 1390825437,
        "recipient": {
            "name": "John Doe",
            "company": null,
            "address1": "19749 Dearborn St",
            "address2": null,
            "city": "Chatsworth",
            "state_code": "CA",
            "state_name": "California",
            "country_code": "US",
            "country_name": "United States",
            "zip": "91311",
            "phone": null,
            "email": null
        },
        "items": [{
            "id": 17627,
            "external_id": null,
            "variant_id": 1118,
            "quantity": 1,
            "price": "20.50",
            "retail_price": null,
            "name": "Alternative 1070 Short Sleeve Men T-Shirt (Black / M)",
            "product": {
                "variant_id": 1118,
                "product_id": 14,
                "image": "https://www.printful.com/storage/products/14/1095.jpg",
                "name": "Alternative 1070 Short Sleeve Men T-Shirt (Black / M)"
            },
            "files": [{
                "id": 11822,
                "type": "default",
                "hash": null,
                "url": "http://example.com/files/tshirts/shirt_front.ai",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1390825349,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            }, {
                "id": 11823,
                "type": "back",
                "hash": null,
                "url": "http://example.com/files/tshirts/shirt_back.ai",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1390825349,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            }, {
                "id": 11824,
                "type": "preview",
                "hash": null,
                "url": "http://example.com/files/tshirts/shirt_mockup.jpg",
                "filename": null,
                "mime_type": null,
                "size": 0,
                "width": null,
                "height": null,
                "dpi": null,
                "status": "waiting",
                "created": 1390825349,
                "thumbnail_url": null,
                "preview_url": null,
                "visible": true
            }],
            "options": []
        }],
        "costs": {
            "subtotal": "20.50",
            "discount": "0.00",
            "shipping": "5.50",
            "tax": "1.85",
            "total": "27.85"
        },
        "retail_costs": {
            "subtotal": null,
            "discount": null,
            "shipping": null,
            "tax": null,
            "total": null
        },
        "shipments": []
    }
}

Get order data

GET https://api.printful.com /orders/{id}

Returns order data by ID or External ID.
Input parameters:
id integer / string Order ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result Order Order data
id integer Order ID
external_id string Order ID from the external system
status string Order status:
draft - order is not submitted for fulfillment
failed - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
pending - order has been submitted for fulfillment
canceled - order is canceled
onhold - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
inprocess - order is being fulfilled and is no longer cancellable
partial - order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilled - all items are shipped
shipping string Shipping method. Defaults to 'STANDARD'
created timestamp Time when the order was created
updated timestamp Time when the order was updated
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
state_name string State name
country_code string Country code
country_name string Country name
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
id integer Line item ID
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
price string Printful price of the item
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
product ProductVariant Short information about the Product and Variant
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
costs Costs Order costs (Printful prices, in USD)
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
shipments Shipment [ ] Array of shipments already shipped for this order
id integer Shipment ID
carrier string Carrier name
service string Delivery service name
tracking_number string Shipment tracking number
tracking_url string Shipment tracking URL
created timestamp Shipping time
ship_date string Ship date
reshipment boolean Whether this is a reshipment
items ShipmentItem [ ] Array of items in this shipment
item_id integer Line item ID
quantity integer Quantity of items in this shipment
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
API key
id Order ID (integer) or External ID (if prefixed with @)
Execute

Cancel an order

DELETE https://api.printful.com /orders/{id}

Cancels pending order or draft. Charged amount is returned to the store owner's credit card.
Input parameters:
id integer / string Order ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result Order Order data
id integer Order ID
external_id string Order ID from the external system
status string Order status:
draft - order is not submitted for fulfillment
failed - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
pending - order has been submitted for fulfillment
canceled - order is canceled
onhold - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
inprocess - order is being fulfilled and is no longer cancellable
partial - order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilled - all items are shipped
shipping string Shipping method. Defaults to 'STANDARD'
created timestamp Time when the order was created
updated timestamp Time when the order was updated
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
state_name string State name
country_code string Country code
country_name string Country name
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
id integer Line item ID
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
price string Printful price of the item
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
product ProductVariant Short information about the Product and Variant
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
costs Costs Order costs (Printful prices, in USD)
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
shipments Shipment [ ] Array of shipments already shipped for this order
id integer Shipment ID
carrier string Carrier name
service string Delivery service name
tracking_number string Shipment tracking number
tracking_url string Shipment tracking URL
created timestamp Shipping time
ship_date string Ship date
reshipment boolean Whether this is a reshipment
items ShipmentItem [ ] Array of items in this shipment
item_id integer Line item ID
quantity integer Quantity of items in this shipment
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
API key
id Order ID (integer) or External ID (if prefixed with @)
Execute

Update order data

PUT https://api.printful.com /orders/{id}

Updates 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 fields.

If items array is given in the update data, the items will be:
a) updated, if the update data contains the item id or external_id parameter that alreay exists
b) deleted, if the request doesn't contain the item with previously existing id
c) created as new if the id is not given or does not already exist

Input parameters:
id integer Order ID (integer) or External ID (if prefixed with @)
confirm boolean Automatically submit the newly created order for fulfillment (skip the Draft phase)
Request body Order Order data
external_id string Order ID from the external system
shipping string Shipping method. Defaults to 'STANDARD'
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
country_code string Country code
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
url string Source URL where the file is downloaded from
filename string File name
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
currency string 3 letter currency code (optional), required if the retail costs should be convert from another currency instead of USD
Response format:
code integer Response status code 200
result Order Order data
id integer Order ID
external_id string Order ID from the external system
status string Order status:
draft - order is not submitted for fulfillment
failed - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
pending - order has been submitted for fulfillment
canceled - order is canceled
onhold - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
inprocess - order is being fulfilled and is no longer cancellable
partial - order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilled - all items are shipped
shipping string Shipping method. Defaults to 'STANDARD'
created timestamp Time when the order was created
updated timestamp Time when the order was updated
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
state_name string State name
country_code string Country code
country_name string Country name
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
id integer Line item ID
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
price string Printful price of the item
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
product ProductVariant Short information about the Product and Variant
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
costs Costs Order costs (Printful prices, in USD)
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
shipments Shipment [ ] Array of shipments already shipped for this order
id integer Shipment ID
carrier string Carrier name
service string Delivery service name
tracking_number string Shipment tracking number
tracking_url string Shipment tracking URL
created timestamp Shipping time
ship_date string Ship date
reshipment boolean Whether this is a reshipment
items ShipmentItem [ ] Array of items in this shipment
item_id integer Line item ID
quantity integer Quantity of items in this shipment
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
API key
id Order ID (integer) or External ID (if prefixed with @)
confirm Automatically submit the newly created order for fulfillment (skip the Draft phase)
Request body
Execute

Confirm draft for fulfillment

POST https://api.printful.com /orders/{id}/confirm

Approves for fulfillment an order that was saved as a draft. Store owner's credit card is charged when the order is submitted for fulfillment.
Input parameters:
id integer / string Order ID (integer) or External ID (if prefixed with @)
Response format:
code integer Response status code 200
result Order Order data
id integer Order ID
external_id string Order ID from the external system
status string Order status:
draft - order is not submitted for fulfillment
failed - order was submitted for fulfillment but was not accepted because of an error (problem with address, printfiles, charging, etc.)
pending - order has been submitted for fulfillment
canceled - order is canceled
onhold - order has encountered a problem during the fulfillment that needs to be resolved together with the Printful customer service
inprocess - order is being fulfilled and is no longer cancellable
partial - order is partially fulfilled (some items are shipped already, the rest will follow)
fulfilled - all items are shipped
shipping string Shipping method. Defaults to 'STANDARD'
created timestamp Time when the order was created
updated timestamp Time when the order was updated
recipient Address Shipping address
name string Full name
company string Company name
address1 string Address line 1
address2 string Address line 2
city string City
state_code string State code
state_name string State name
country_code string Country code
country_name string Country name
zip string ZIP/Postal code
phone string Phone
email string E-mail
items Item [ ] Array of items in the order
id integer Line item ID
external_id string Line item ID from the external system
variant_id integer Variant ID of the item ordered. See Products API
quantity integer Number of items ordered
price string Printful price of the item
retail_price string Original retail price of the item to be displayed on the packing slip
name string Display name of the item. If not given, a name from the Printful system will be displayed on the packing slip
product ProductVariant Short information about the Product and Variant
variant_id integer Variant ID
product_id integer Product ID of this variant
image string URL of a sample image for this variant
name string Display name of this variant
files File [ ] Array of attached printfiles / preview images
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
options ItemOption [ ] Array of additional options for this product
id string Option ID
value mixed Option value
sku string Product identifier (SKU) from the external system
costs Costs Order costs (Printful prices, in USD)
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
retail_costs Costs Original retail costs in USD that are to be displayed on the packing slip for international shipments. Retail costs are used only if every item in order contains the retail_price attribute.
subtotal string Total cost of all items
discount string Discount sum
shipping string Shipping costs
digitization string Digitization costs
tax string Sum of taxes (not included in the item price)
total string Grand Total (subtotal-discount+tax+shipping)
shipments Shipment [ ] Array of shipments already shipped for this order
id integer Shipment ID
carrier string Carrier name
service string Delivery service name
tracking_number string Shipment tracking number
tracking_url string Shipment tracking URL
created timestamp Shipping time
ship_date string Ship date
reshipment boolean Whether this is a reshipment
items ShipmentItem [ ] Array of items in this shipment
item_id integer Line item ID
quantity integer Quantity of items in this shipment
gift GiftData Optional gift message for the packing slip
subject string Gift message title
message string Gift message text
packing_slip PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone (111-222-3333)
message string Custom packing slip message
API key
id Order ID (integer) or External ID (if prefixed with @)
Execute

Ready to try Printful ?

Get Me Started

Printing is what we do best.

Trusted to print 1 944 910 shirts since 2013