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	Description
`resource_url`	string, required	The REST API URL used to retrieve the event object.
`resource_type`	string, required	`API_TRACK`
`data`	Object	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, returned by carrier.
`actual_delivery_date`	string, optional	An ISO 8601 string that represents the date of delivery, 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
`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	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	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	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	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	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 order.

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

Name	Data Type	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	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	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	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	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 when the order was created
`modified_at`	string, required	The date and time when the order was last modified
`payment_details`	object	Object containing the payment details for the sales order
`subtotal`	object	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	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	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	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	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	Object containing billing information
`email`	string, optional	The email address for billing
`address`	object	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	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	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	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	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	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	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	Object containing price summary information for the line item
`unit_price`	object	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	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	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