Embroidery on apparel is here!
Sign up Sign up
Sign in Sign in

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
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
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
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 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)
vat string Sum of vat (not included in the item price)
total string Grand Total (subtotal-discount+tax+vat+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)
vat string Sum of vat (not included in the item price)
total string Grand Total (subtotal-discount+tax+vat+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
currency string 3 letter currency code (optional), required if the retail costs should be convert from another currency instead of USD

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
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
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 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)
vat string Sum of vat (not included in the item price)
total string Grand Total (subtotal-discount+tax+vat+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)
vat string Sum of vat (not included in the item price)
total string Grand Total (subtotal-discount+tax+vat+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
currency string 3 letter currency code (optional), required if the retail costs should be convert from another currency instead of USD

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
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
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 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)
vat string Sum of vat (not included in the item price)
total string Grand Total (subtotal-discount+tax+vat+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)
vat string Sum of vat (not included in the item price)
total string Grand Total (subtotal-discount+tax+vat+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
currency string 3 letter currency code (optional), required if the retail costs should be convert from another currency instead of USD

product_synced Event

POST http://example.com/your-webhook-url

Is called when a new product or variant is imported from store's e-commerce integration.

See E-commerce Platform Sync API

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 E-commerce 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

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

Webhook Setup API

To set up webhooks, use API requests described below:

Get webhook configuration

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

Returns configured webhook URL and list of webhook event types enabled for the store

Input parameters:
None
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 [ ] Array of parameters for enabled webhook event types
API key
Execute
Response data: 
{
    "code": 200,
    "result": {
        "url": "http://www.example.com/printful/webhook",
        "types": [
            "package_shipped",
            "stock_updated"
        ],
        "params": {
            "stock_updated": {
                "product_ids": [5, 12]
            }
        }
    }
}

Set up webhook configuration

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 [ ] 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 [ ] Array of parameters for enabled webhook event types
API key
Request body
Execute
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]
            }
        }
    }
}

Disable webhook support

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:
None
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 [ ] Array of parameters for enabled webhook event types
API key
Execute

Ready to try Printful ?

Get Me Started

So much more than printing

Trusted to print 3 645 127 shirts since 2013