Webhook API

Webhooksは、システムが特定のイベントに関する通知を受け取ることができるようにするAPI機能です。

イベントが発生すると、Printfulサーバーは、リクエスト本文にJSONオブジェクトを含む定義済みURLに対してPOSTリクエストを送信します。サーバーはHTTPステータス 200 OK で応答する必要があります。それ以外の場合、リクエストは間隔を空けて再試行されます(1、4、16、64、256、および1024分後)

JSONオブジェクトには常に次の属性が含まれます。

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 イベントの種類に応じた追加情報

Webhook event requests

現在利用可能なウェブフックイベントのタイプ:

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 イベントタイプ - package_shipped
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 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)
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 PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone. Should be formatted like this: 111-222-3333
message string Custom packing slip message

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 イベントタイプ - package_returned
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 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)
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 PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone. Should be formatted like this: 111-222-3333
message string Custom packing slip message

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 イベントタイプ - order_failed
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 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)
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 PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone. Should be formatted like this: 111-222-3333
message string Custom packing slip message

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 イベントタイプ - order_canceled
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 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)
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 PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone. Should be formatted like this: 111-222-3333
message string Custom packing slip message

product_synced Event

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

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

See Ecommerce Platform Sync API

Webhook request body data:
type string イベントタイプ - product_synced
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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

Is called when a new product or variant gets created or updated in any way.

See Ecommerce Platform Sync API

Webhook request body data:
type string イベントタイプ - product_updated
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 イベントタイプ - stock_updated
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 イベントタイプ - order_put_hold
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 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)
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 PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone. Should be formatted like this: 111-222-3333
message string Custom packing slip message

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 イベントタイプ - order_remove_hold
created timestamp イベントの時間
retries integer このウェブフックイベントの配信試行の回数
store integer イベントが発生したショップのID
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 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)
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 PackingSlip Custom packing slip for this order
email string Customer service email
phone string Customer service phone. Should be formatted like this: 111-222-3333
message string Custom packing slip message

Webhook Setup API

ウェブフックを設定するには下記のAPIリクエストを使用します:

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:
無し
レスポンス形式:
code integer ステータスコードのレスポンス 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
APIキー
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 [ ] Optional array of parameters for enabled webhook event types
レスポンス形式:
code integer ステータスコードのレスポンス 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
APIキー
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:
無し
レスポンス形式:
code integer ステータスコードのレスポンス 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
APIキー
Execute

Printfulを試す準備はできましたか?