Webhook API
Webhooks is an API feature that allows your system to receive notifications about certain events.
When an event occurs, the Printful server will make a POST request to your defined URL that will contain a JSON object in the request body. Your server has to respond with HTTP status 200 OK, otherwise the request will be retried in increasing intervals (after 1, 4, 16, 64, 256 and 1024 minutes)
The JSON object will always contain these attributes:
type |
string |
Event type |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
Object |
Additional data, depending on the event type |
Webhook event requests
Currently available webhook event types:
package_shipped Event
POST
http://example.com/your-webhook-url
Is called when a shipment with all or part of the ordered items is shipped.
If the order is shipped in multiple packages, this event will be called for every package sent.
If some items are reshipped, a shipping notification will be sent again for the same items.
Webhook request body data:
type |
string |
Event type - package_shipped |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
ShipmentInfo |
Shipment and order data |
shipment |
Shipment |
Shipment that was shipped |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
|
|
order |
Order |
Order data (including all shipments) |
id |
integer |
Order ID |
external_id |
string |
Order ID from the external system |
store |
integer |
Store ID |
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 |
sync_variant_id |
integer |
Sync variant ID of the item ordered. |
external_variant_id |
string |
External variant ID of the item ordered. |
warehouse_product_variant_id |
integer |
Warehousing product variant ID of the item ordered. See Warehouse 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 |
FileOption [ ] |
Array of additional options for this file |
id |
string |
Option ID |
value |
mixed |
Option value |
|
|
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 |
|
incomplete_items |
IncompleteItem [ ] |
Array of incomplete items in the order |
name |
string |
Incomplete item name |
quantity |
integer |
Incompleted item quantity |
sync_variant_id |
integer |
Sync variant ID of the incompleted item. |
external_variant_id |
string |
External variant ID of the incompleted item. |
external_line_item_id |
string |
External order line item id. |
|
costs |
Costs |
Order costs (Printful prices) |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
retail_costs |
Costs |
Retail costs 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. |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
pricing_breakdown |
array |
Difference between order price and retail costs. Will be shown only if order is completed. |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
OrderPackingSlip |
Custom packing slip for this order |
email |
string |
Customer service email |
phone |
string |
Customer service phone |
message |
string |
Custom packing slip message |
logo_url |
string |
URL address to a sticker we will put on a package |
|
|
|
package_returned Event
POST
http://example.com/your-webhook-url
Is called when a shipment is processed as returned to the fulfillment facility.
To learn more about the reasons why a shipment might be returned, take a look at Printful's Return Policy
Webhook request body data:
type |
string |
Event type - package_returned |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
ReturnInfo |
Shipment and order data |
reason |
string |
Reason why the shipment was returned. |
shipment |
Shipment |
Shipment that was returned |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
|
|
order |
Order |
Order data (including all shipments) |
id |
integer |
Order ID |
external_id |
string |
Order ID from the external system |
store |
integer |
Store ID |
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 |
sync_variant_id |
integer |
Sync variant ID of the item ordered. |
external_variant_id |
string |
External variant ID of the item ordered. |
warehouse_product_variant_id |
integer |
Warehousing product variant ID of the item ordered. See Warehouse 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 |
FileOption [ ] |
Array of additional options for this file |
id |
string |
Option ID |
value |
mixed |
Option value |
|
|
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 |
|
incomplete_items |
IncompleteItem [ ] |
Array of incomplete items in the order |
name |
string |
Incomplete item name |
quantity |
integer |
Incompleted item quantity |
sync_variant_id |
integer |
Sync variant ID of the incompleted item. |
external_variant_id |
string |
External variant ID of the incompleted item. |
external_line_item_id |
string |
External order line item id. |
|
costs |
Costs |
Order costs (Printful prices) |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
retail_costs |
Costs |
Retail costs 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. |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
pricing_breakdown |
array |
Difference between order price and retail costs. Will be shown only if order is completed. |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
OrderPackingSlip |
Custom packing slip for this order |
email |
string |
Customer service email |
phone |
string |
Customer service phone |
message |
string |
Custom packing slip message |
logo_url |
string |
URL address to a sticker we will put on a package |
|
|
|
order_failed Event
POST
http://example.com/your-webhook-url
Is called when a confirmed order changes its status to failed.
It can happen if printfiles can not be downloaded, are not valid image files or when charging of the payment card fails.
Webhook request body data:
type |
string |
Event type - order_failed |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
FailureInfo |
Failure reason and order data |
reason |
string |
Reason why the order has failed. |
order |
Order |
Order data |
id |
integer |
Order ID |
external_id |
string |
Order ID from the external system |
store |
integer |
Store ID |
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 |
sync_variant_id |
integer |
Sync variant ID of the item ordered. |
external_variant_id |
string |
External variant ID of the item ordered. |
warehouse_product_variant_id |
integer |
Warehousing product variant ID of the item ordered. See Warehouse 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 |
FileOption [ ] |
Array of additional options for this file |
id |
string |
Option ID |
value |
mixed |
Option value |
|
|
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 |
|
incomplete_items |
IncompleteItem [ ] |
Array of incomplete items in the order |
name |
string |
Incomplete item name |
quantity |
integer |
Incompleted item quantity |
sync_variant_id |
integer |
Sync variant ID of the incompleted item. |
external_variant_id |
string |
External variant ID of the incompleted item. |
external_line_item_id |
string |
External order line item id. |
|
costs |
Costs |
Order costs (Printful prices) |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
retail_costs |
Costs |
Retail costs 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. |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
pricing_breakdown |
array |
Difference between order price and retail costs. Will be shown only if order is completed. |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
OrderPackingSlip |
Custom packing slip for this order |
email |
string |
Customer service email |
phone |
string |
Customer service phone |
message |
string |
Custom packing slip message |
logo_url |
string |
URL address to a sticker we will put on a package |
|
|
|
order_canceled Event
POST
http://example.com/your-webhook-url
Is called when a confirmed order changes its status to canceled.
It can happen when a submitted order is canceled from the dashboard or through the API or when the order is cancelled by the Printful staff.
Webhook request body data:
type |
string |
Event type - order_canceled |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
CancelInfo |
Cancel reason and order data |
reason |
string |
Reason why the order has been canceled. |
order |
Order |
Order data |
id |
integer |
Order ID |
external_id |
string |
Order ID from the external system |
store |
integer |
Store ID |
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 |
sync_variant_id |
integer |
Sync variant ID of the item ordered. |
external_variant_id |
string |
External variant ID of the item ordered. |
warehouse_product_variant_id |
integer |
Warehousing product variant ID of the item ordered. See Warehouse 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 |
FileOption [ ] |
Array of additional options for this file |
id |
string |
Option ID |
value |
mixed |
Option value |
|
|
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 |
|
incomplete_items |
IncompleteItem [ ] |
Array of incomplete items in the order |
name |
string |
Incomplete item name |
quantity |
integer |
Incompleted item quantity |
sync_variant_id |
integer |
Sync variant ID of the incompleted item. |
external_variant_id |
string |
External variant ID of the incompleted item. |
external_line_item_id |
string |
External order line item id. |
|
costs |
Costs |
Order costs (Printful prices) |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
retail_costs |
Costs |
Retail costs 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. |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
pricing_breakdown |
array |
Difference between order price and retail costs. Will be shown only if order is completed. |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
OrderPackingSlip |
Custom packing slip for this order |
email |
string |
Customer service email |
phone |
string |
Customer service phone |
message |
string |
Custom packing slip message |
logo_url |
string |
URL address to a sticker we will put on a package |
|
|
|
product_synced Event
POST
http://example.com/your-webhook-url
Webhook request body data:
type |
string |
Event type - product_synced |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
SyncInfo |
|
sync_product |
SyncProduct |
Sync Product data |
id |
integer |
Sync Product ID |
external_id |
string |
Product ID from the Ecommerce platform |
name |
string |
Product name |
variants |
integer |
Total number of Sync Variants belonging to this product |
synced |
integer |
Number of synced Sync Variants belonging to this product |
thumbnail_url |
string |
Thumbnail image for the product |
|
|
product_updated Event
POST
http://example.com/your-webhook-url
Webhook request body data:
type |
string |
Event type - product_updated |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
SyncInfo |
|
sync_product |
SyncProduct |
Sync Product data |
id |
integer |
Sync Product ID |
external_id |
string |
Product ID from the Ecommerce platform |
name |
string |
Product name |
variants |
integer |
Total number of Sync Variants belonging to this product |
synced |
integer |
Number of synced Sync Variants belonging to this product |
thumbnail_url |
string |
Thumbnail image for the product |
|
|
stock_updated Event
POST
http://example.com/your-webhook-url
Is called when stock is updated for some of product's variants.
Contains product id and ids of it's discontinued variants and variants that are out of stock. Variant ids that are not present should be considered as active and in stock.
Webhook request body data:
type |
string |
Event type - stock_updated |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
ProductStock |
|
product_id |
integer |
Product ID |
variant_stock |
VariantStock |
Variant stock for this product |
out |
integer [ ] |
Variant IDs that are out of stock |
discontinued |
integer [ ] |
Variant IDs that are discontinued |
|
|
order_put_hold Event
POST
http://example.com/your-webhook-url
Is called when order is put on hold.
Webhook request body data:
type |
string |
Event type - order_put_hold |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
OrderStatusChange |
|
reason |
string |
Reason why the order status was changed. |
order |
Order |
Order data |
id |
integer |
Order ID |
external_id |
string |
Order ID from the external system |
store |
integer |
Store ID |
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 |
sync_variant_id |
integer |
Sync variant ID of the item ordered. |
external_variant_id |
string |
External variant ID of the item ordered. |
warehouse_product_variant_id |
integer |
Warehousing product variant ID of the item ordered. See Warehouse 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 |
FileOption [ ] |
Array of additional options for this file |
id |
string |
Option ID |
value |
mixed |
Option value |
|
|
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 |
|
incomplete_items |
IncompleteItem [ ] |
Array of incomplete items in the order |
name |
string |
Incomplete item name |
quantity |
integer |
Incompleted item quantity |
sync_variant_id |
integer |
Sync variant ID of the incompleted item. |
external_variant_id |
string |
External variant ID of the incompleted item. |
external_line_item_id |
string |
External order line item id. |
|
costs |
Costs |
Order costs (Printful prices) |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
retail_costs |
Costs |
Retail costs 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. |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
pricing_breakdown |
array |
Difference between order price and retail costs. Will be shown only if order is completed. |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
OrderPackingSlip |
Custom packing slip for this order |
email |
string |
Customer service email |
phone |
string |
Customer service phone |
message |
string |
Custom packing slip message |
logo_url |
string |
URL address to a sticker we will put on a package |
|
|
|
order_remove_hold Event
POST
http://example.com/your-webhook-url
Is called when order is removed from hold.
Webhook request body data:
type |
string |
Event type - order_remove_hold |
created |
timestamp |
Event time |
retries |
integer |
Number of previous attempts to deliver this webhook event |
store |
integer |
ID of the store that the event occured to |
data |
OrderStatusChange |
|
reason |
string |
Reason why the order status was changed. |
order |
Order |
Order data |
id |
integer |
Order ID |
external_id |
string |
Order ID from the external system |
store |
integer |
Store ID |
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 |
sync_variant_id |
integer |
Sync variant ID of the item ordered. |
external_variant_id |
string |
External variant ID of the item ordered. |
warehouse_product_variant_id |
integer |
Warehousing product variant ID of the item ordered. See Warehouse 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 |
FileOption [ ] |
Array of additional options for this file |
id |
string |
Option ID |
value |
mixed |
Option value |
|
|
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 |
|
incomplete_items |
IncompleteItem [ ] |
Array of incomplete items in the order |
name |
string |
Incomplete item name |
quantity |
integer |
Incompleted item quantity |
sync_variant_id |
integer |
Sync variant ID of the incompleted item. |
external_variant_id |
string |
External variant ID of the incompleted item. |
external_line_item_id |
string |
External order line item id. |
|
costs |
Costs |
Order costs (Printful prices) |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
retail_costs |
Costs |
Retail costs 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. |
currency |
string |
3 letter currency code |
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) |
vat |
string |
Sum of vat (not included in the item price) |
total |
string |
Grand Total (subtotal-discount+tax+vat+shipping) |
|
pricing_breakdown |
array |
Difference between order price and retail costs. Will be shown only if order is completed. |
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 |
shipped_at |
int |
Ship time in unix timestamp |
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 |
OrderPackingSlip |
Custom packing slip for this order |
email |
string |
Customer service email |
phone |
string |
Customer service phone |
message |
string |
Custom packing slip message |
logo_url |
string |
URL address to a sticker we will put on a package |
|
|
|
Webhook Setup API
To set up webhooks, use API requests described below:
GET
https://api.printful.com/webhooks
Returns configured webhook URL and list of webhook event types enabled for the store
Input parameters:
Response format:
code |
integer |
Response status code 200 |
result |
WebhookInfo |
|
url |
string |
Webhook URL that will receive store's event notifications |
types |
string [ ] |
Array of enabled webhook event types |
params |
array [ ] |
Optional array of parameters for enabled webhook event types |
|
Response data:
{
"code": 200,
"result": {
"url": "http://www.example.com/printful/webhook",
"types": [
"package_shipped",
"stock_updated"
],
"params": {
"stock_updated": {
"product_ids": [5, 12]
}
}
}
}
POST
https://api.printful.com/webhooks
Allows to enable webhook URL for the store and select webhook event types that will be sent to this URL.
Note that only one webhook URL can be active for a store, so calling this method disables all existing webhook configuration.
Method returns current webhook configuration after the update.
Input parameters:
Request body
|
WebhookInfo |
Webhook data |
url |
string |
Webhook URL that will receive store's event notifications |
types |
string [ ] |
Array of enabled webhook event types |
params |
array [ ] |
Optional array of parameters for enabled webhook event types |
|
Response format:
code |
integer |
Response status code 200 |
result |
WebhookInfo |
|
url |
string |
Webhook URL that will receive store's event notifications |
types |
string [ ] |
Array of enabled webhook event types |
params |
array [ ] |
Optional array of parameters for enabled webhook event types |
|
Enable webhook processing for new shipment event.
Request body:
{
"url": "http://www.example.com/printful/webhook",
"types": [
"package_shipped",
"stock_updated"
],
"params": {
"stock_updated": {
"product_ids": [5, 12]
}
}
}
Response data:
{
"code": 200,
"result": {
"url": "http://www.example.com/printful/webhook",
"types": [
"package_shipped",
"stock_updated"
],
"params": {
"stock_updated": {
"product_ids": [5, 12]
}
}
}
}
DELETE
https://api.printful.com/webhooks
Removes the webhook URL and selected event types from the store.
Method returns current webhook configuration after the update.
Input parameters:
Response format:
code |
integer |
Response status code 200 |
result |
WebhookInfo |
|
url |
string |
Webhook URL that will receive store's event notifications |
types |
string [ ] |
Array of enabled webhook event types |
params |
array [ ] |
Optional array of parameters for enabled webhook event types |
|