Webhooks Schema

The following webhook events are available through ShipEngine:

Tracking
Batch Completed
Rate Updated
Carrier Connected
Report Complete
Order Source Refresh Complete
Sales Order Imported (Beta)

Each webhook event returns a unique payload. Click through the links below to see the full webhooks schema for each event.

Tracking

Subscribe to this webhook to get updates on any tracking event.

Click to view the Tracking Webhook schema

The body of the tracking webhook request has the following attributes:

Name	Data Type	Required?	Description
`resource_url`	string	required	The REST API URL used to retrieve the event object.
`resource_type`	string	required	`API_TRACK`
`data`	Object	optional	Object containing tracking information.
`label_url`	string	optional	Populated if tracking event is associated with a label created in ShipEngine. This is the label image associated with this tracking number.
`tracking_number`	string	required	Tracking number provided by the carrier.
`status_code`	string	required	Must contain one of the following values: `UN: Unknown` `AC: Accepted` `IT: In Transit` `DE: Delivered` `EX: Exception` `AT: Delivery Attempt` `NY: Not Yet in System`
`carrier_detail_code`	string	optional	Additional tracking details provided by the carrier.
`status_description`	string	optional	Status description of the tracked package. Could include the following: Unknown, Accepted, In Transit, Delivered, Exception, Delivery Attempt, Not Yet in System
`carrier_status_code`	string	required	Status of tracked package provided by the carrier.
`carrier_status_description`	string	optional	More detailed description of tracked package returned from the carrier.
`ship_date`	string	optional	An ISO 8601 string that represents date and time the tracked package was sent/returned from the carrier.
`estimated_delivery_date`	string	optional	An ISO 8601 string that represents the estimated date of delivery or returned by carrier.
`actual_delivery_date`	string	optional	An ISO 8601 string that represents the date of delivery or returned by carrier.
`exception_description`	string	optional	Additional description provided by the carrier when a package is in a state that may delay or prevent delivery.
`events`	array	required	The events that have occurred during the lifetime of this tracking number.
`occurred_at`	string	required	Timestamp for the carrier event.
`carrier_occurred_at`	string	optional	Carrier timestamp for the event. It is assumed to be the local time of where the event occurred. Not fully supported for all carriers.
`description`	string	optional	A description of the event, for example: Shipment Received, Package Acceptance Pending, etc.
`city_locality`	string	optional	City where shipment is being sent.
`state_province``	string	optional	State where shipment is being sent.
`postal_code`	string	optional	Postal code where the shipment is being sent.
`country_code`	string	optional	A two-letter ISO 3166-1 country code.
`company_name`	string	optional	Returns the value entered into the Company Name field.
`signer`	string	optional	Information of the signer of shipment.
`event_code`	string	optional	Tracking event code provided by the carrier.
`event_description`	string	optional	This is the carrier provided description. The `carrier_status_description` at the top level turns into this field when it is applied to an event.
`carrier_detail_code`	string	optional	Additional tracking code that may be provided by the carrier.
`status_code`	string	optional	This is the normalized event code provided by ShipEngine.
`latitude`	number	optional	Latitude coordinate of tracking event.
`longitude`	number	optional	Longitude coordinate of tracking event.

Batch Completed

Subscribe to this webhook to get updates for completed batches.

Click to view the Batch Completed webhook schema

The body of the Batch Completed webhook request has the following attributes:

Name	Data Type	Required?	Description
`resource_url`	string	required	The REST API URL used to retrieve the event object.
`resource_type`	string	required	`API_BATCH`

Shipment Rate Updated

Subscribe to this webhook to get updates when a shipment rate has been updated.

Click to view the Shipment Rate Updated webhook schema

The body of the Shipment Rate webhook request has the following attributes:

Name	Data Type	Required?	Description
`resource_url`	string	required	The REST API URL used to retrieve the event object.
`resource_type`	string	required	`API_RATE`

Carrier Connected

Subscribe to this webhook to get updates when a carrier is connected.

Click to view the Carrier Connected webhook schema

The body of the Carrier Connected webhook request has the following attributes:

Name	Data Type	Required?	Description
`resource_url`	string	required	The REST API URL used to retrieve the event object.
`resource_type`	string	required	`API_CARRIER_CONNECTED`

Report Complete

Subscribe to this webhook to get updates when a requested report is ready.

Click to view the Report Complete webhook schema

The body of the Report Complete webhook request has the following attributes:

Name	Data Type	Required?	Description
`resource_url`	string	required	The REST API URL used to retrieve the event object.
`resource_type`	string	required	`API_REPORT_COMPLETE`

Order Source Refresh Complete

Subscribe to this webhook to get updates when an order source has been refreshed.

Click to view the Order Source Refresh Complete webhook schema

The body of the Order Source Refresh Complete webhook request has the following attributes:

Name	Data Type	Required?	Description
`resource_url`	string	required	The REST API URL used to retrieve the event object.
`resource_type`	string	required	`API_ORDER_SOURCE_REFRESH_COMPLETE`

Sales Order Imported (Beta)

Subscribe to this webhook to get updated information for imported sales orders.

Click to view the Sales Order Imported (Beta) webhook schema

Name	Data Type	Required?	Description
`resource_url`	string	required	The REST API URL used to retrieve the event object.
`resource_type`	string	required	API_SALES_ORDERS_IMPORTED
`data`	array	optional	The array containing the event data
`sales_order_id`	string	required	The ID of the sales order
`external_order_id`	string	optional	The external ID of the order
`external_order_number`	string	optional	The external order number
`order_source`	object	optional	Object containing information about the order source
`order_source_id`	string	required	The ID of the order source
`order_source_nickname`	string	required	The nickname of the order source
`order_source_code`	string	required	The code of the order source
`order_source_friendly_name`	string	required	The friendly name of the order source
`refresh_info`	object	optional	Object containing information about the refresh status of the order source
`status`	enum	required	The status of the refresh
`last_refresh_attempt`	string	required	The date and time of the last refresh attempt
`refresh_date`	string	required	The date and time of the last successful refresh
`active`	boolean	required	Indicates if the order source is active
`connection_id`	string	optional	Identifier for the store connection authorization
`sales_order_status`	object	optional	Object containing the payment and fulfillment status of the sales order
`payment_status`	enum	required	The payment status of the sales order
`fulfillment_status`	enum	required	The fulfillment status of the sales order
`is_cancelled`	boolean	required	Indicates if the sales order is cancelled
`order_date`	string	required	The date and time of the order
`created_at`	string	required	The date and time the order was created
`modified_at`	string	required	The date and time the order was last modified
`payment_details`	object	optional	Object containing the payment details for the sales order
`subtotal`	object	optional	Object containing information about the subtotal amount
`currency`	enum	optional	The currency of the subtotal amount
`amount`	float	optional	The subtotal amount
`estimated_shipping`	object	optional	Object containing information about the estimated shipping amount
`currency`	enum	optional	The currency of the estimated shipping amount
`amount`	float	optional	The estimated shipping amount
`estimated_tax`	object	optional	Object containing information about the estimated tax amount
`currency`	enum	optional	The currency of the estimated tax amount
`amount`	float	optional	The estimated tax amount
`grand_total`	object	optional	Object containing information about the grand total amount
`currency`	enum	optional	The currency of the grand total amount
`amount`	float	optional	The grand total amount
`customer`	object	optional	Object containing customer information
`name`	string	optional	The name of the customer
`phone`	string	optional	The phone number of the customer
`email`	string	optional	The email address of the customer
`bill_to`	object	optional	Object containing billing information
`email`	string	optional	The email address for billing
`address`	object	optional	Object containing address details for billing
`name`	string	optional	The name associated with the billing address
`phone`	string	optional	The phone number associated with the billing address
`company_name`	string	optional	The company name associated with the billing address
`address_line1`	string	optional	The first line of the billing address
`address_line2`	string	optional	The second line of the billing address
`address_line3`	string	optional	The third line of the billing address
`city_locality`	string	optional	The city or locality of the billing address
`state_province`	string	optional	The state or province of the billing address
`postal_code`	string	optional	The postal code of the billing address
`country_code`	string	optional	The country code of the billing address
`address_residential_indicator`	string	optional	Indicates if the billing address is residential. Will be Yes or No.
`ship_to`	object	optional	Object containing shipping information
`name`	string	optional	The name of the recipient
`phone`	string	optional	The phone number of the recipient
`address_line1`	string	optional	The first line of the shipping address
`city_locality`	string	optional	The city or locality of the shipping address
`state_province`	string	optional	The state or province of the shipping address
`postal_code`	string	optional	The postal code of the shipping address
`country_code`	string	optional	The country code of the shipping address
`address_residential_indicator`	string	optional	Indicates if the shipping address is residential. Will be Yes or No.
`sales_order_items`	array	optional	An array containing the sales order items
`sales_order_item_id`	string	optional	The ID of the sales order item
`external_order_item_id`	string	optional	Marketplace's identifier for the order item
`line_item_details`	object	optional	Object containing details about the line item
`name`	string	optional	The name of the line item
`sku`	string	optional	The SKU of the line item
`asin`	string	optional	Amazon Standard Identification Number (ASIN) provided by order source
`weight`	object	optional	Object containing information about the weight of the line item
`value`	float	optional	The weight value
`unit`	enum	optional	The unit of weight
`ship_to`	object	optional	Object containing shipping information for the line item
`name`	string	optional	The name of the recipient
`phone`	string	optional	The phone number of the recipient
`address_line1`	string	optional	The first line of the shipping address
`city_locality`	string	optional	The city or locality of the shipping address
`state_province`	string	optional	The state or province of the shipping address
`postal_code`	string	optional	The postal code of the shipping address
`country_code`	string	optional	The country code of the shipping address
`address_residential_indicator`	enum	optional	Indicates if the shipping address is residential. Will be Yes or No.
`requested_shipping_options`	object	optional	Object containing requested shipping options for the line item
`shipping_service`	string	optional	The requested shipping service
`ship_date`	string	optional	The requested ship date
`price_summary`	object	optional	Object containing price summary information for the line item
`unit_price`	object	optional	Object containing information about the unit price
`currency`	enum	optional	The currency of the unit price
`amount`	float	optional	The unit price
`estimated_tax`	object	optional	Object containing information about the estimated tax amount
`currency`	enum	optional	The currency of the estimated tax amount
`amount`	float	optional	The estimated tax amount
`estimated_shipping`	string	optional	The estimated shipping amount
`total`	object	optional	Object containing information about the total amount
`currency`	enum	optional	The currency of the total amount
`amount`	float	optional	The total amount
`quantity`	int	optional	The quantity of the line item
`is_gift`	boolean	optional	Indicates if the line item is a gift