> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.goshippo.com/feedback
```json
{
"path": "/docs/ShippingElements/events",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Events
> Use Shippo Shipping Elements events to respond to user actions like label purchases, order creation, and errors.
The Shippo Shipping Elements supports events that you can use to integrate with your website.
## Events using `shippo.on()`
The Shipping Elements framework emits lifecycle and action events as the user is interacting with the widget. Event listeners can be added using the `on()` method as such:
```javascript theme={null}
shippo.on('LABEL_PURCHASED_SUCCESS', (event) => {
// do something when the user purchases a label!
});
```
## Event List
| Event | Description |
| ------------------------- | -------------------------------------------------------------------- |
| APP\_READY | The widget is rendered and ready to receive configuration or events. |
| CLOSE\_BUTTON\_CLICKED | The user clicked the close button to close the widget. |
| ORDER\_CREATED | A Shippo order object was created for the data passed into Elements. |
| LABEL\_PURCHASED\_SUCCESS | A label was successfully purchased. |
| ERROR | Any error has occurred. |
| ORDERS\_CREATED | Shippo orders object was created for the data passed into Elements. |
| ORDERS\_CREATED\_ERROR | Something went wrong in created orders within our system. |
**note**
Using the `shippo.off()` method removes the listener for that callback event.
## Event Parameters
Each event has unique parameters to the callback function, here are some examples:
### LABEL\_PURCHASED\_SUCCESS
The `LABEL_PURCHASED_SUCCESS` event returns an array of transaction objects as the parameter to the callback function passed to the `on()` method:
```typescript theme={null}
interface Transaction {
shipment_id?: string;
order_id?: string;
commercial_invoice_url?: string;
eta?: string;
entry_point?: string;
label_url?: string;
messages?: any[];
metadata?: string;
object_created?: string;
object_updated?: string;
object_id?: string;
object_owner?: string;
object_state?: string;
object_status?: string;
packing_slip_url?: string;
rate?: WebRate;
refund_request_date?: string;
tracking_number?: string;
tracking_url_provider?: string;
was_test?: boolean;
}
```
### ORDER\_CREATED
The `ORDER_CREATED` event returns a shipment object with the order\_id as the parameter to the callback function passed to the `on()` method:
```typescript theme={null}
interface OrderCreatedParams {
order_id: string;
shipment_id?: string;
address_from?: {
ip?: string;
is_residential?: boolean;
latitude?: string;
longitude?: string;
metadata?: string;
object_created?: string;
object_id?: string;
object_purpose?: 'PURCHASE' | 'QUOTE';
object_source?: string;
object_state?: string;
object_updated?: string;
};
address_return?: {
ip?: string;
is_residential?: boolean;
latitude?: string;
longitude?: string;
metadata?: string;
object_created?: string;
object_id?: string;
object_purpose?: 'PURCHASE' | 'QUOTE';
object_source?: string;
object_state?: string;
object_updated?: string;
};
address_to?: {
ip?: string;
is_residential?: boolean;
latitude?: string;
longitude?: string;
metadata?: string;
object_created?: string;
object_id?: string;
object_purpose?: 'PURCHASE' | 'QUOTE';
object_source?: string;
object_state?: string;
object_updated?: string;
};
alternate_address_to?: string;
carrier_accounts?: object[];
customs_declaration?: {
/** Automated Export System Internal Transaction Number (exports from USA) */
aes_itn?: string;
/** Name of the person who created the customs declaration and is responsible for the validity of all information provided */
authorized_person: string;
/** B13A Export Declaration, mandatory for Canadian exports valued at CAD$2000 or more */
b13a_filing_option?: 'FILED_ELECTRONICALLY' | 'NOT_REQUIRED' | 'SUMMARY_REPORTING';
/** Proof of Report Number, Summary ID Number, or Exemption Number, depending on B13A filing option */
b13a_number?: string;
certificate?: string;
/** Exemption and Exclusion Legend / Proof of Filing Citation (exports from USA) */
eel_pfc?: 'NOEEI_30_37_a' | 'NOEEI_30_37_h' | 'NOEEI_30_37_f' | 'NOEEI_30_36' | 'AES_ITN';
exporter_reference?: string;
importer_reference?: string;
incoterm?: 'DDP' | 'DDU' | 'FCA';
invoice_number?: string;
/** Expresses that the certify_signer has provided all information of this customs declaration truthfully */
is_certified: boolean;
is_vat_collected?: boolean;
items: {
/** export control classification number (ECCN/EAR99) for US exports */
control_classification?: string;
description: string;
is_test?: boolean;
/** @format uuid */
line_item_object_id?: string;
mass_unit: 'g'|'kg'|'oz'|'lb';
metadata?: string;
net_value?: string;
net_weight?: string;
/** @format uuid */
object_id?: string;
/**
* ISO 3166-2 alpha-2 country code
* @example "US"
*/
origin_country?: string;
object_state?: 'VALID' | 'INVALID';
quantity: number;
sku_code?: string;
/** The item's tariff number, e.g. Harmonized System (HS) Codes */
tariff_number?: string;
unit_value: string;
unit_weight: string;
/**
* ISO 4217 3-letter currency code
* @example "USD"
*/
value_currency: string;
}[];
license?: string;
metadata?: string;
non_delivery_handling?: 'ABANDON' | 'RETURN';
notes?: string;
/** Explanation of the type of goods of the shipment */
purpose_explanation?: string;
/** Reason for export */
purpose_of_shipment?:
| 'DOCUMENTS'
| 'GIFT'
| 'HUMANITARIAN_DONATION'
| 'MERCHANDISE'
| 'OTHER'
| 'RETURN_MERCHANDISE'
| 'SAMPLE';
tax_id?: string;
tax_id_type?: string;
} | null;
extras?: {
alcohol?: {
contains_alcohol?: boolean | null;
recipient_type?: 'CONSUMER' | 'LICENSEE' | null;
};
dry_ice?: {
contains_dry_ice?: boolean | null;
/** @format float */
weight?: number | null;
weight_unit_id?: string | null;
};
insurance?: {
amount?: string | null;
content?: string | null;
currency?: string | null;
use_imported_amount?: boolean | null;
};
dangerous_goods?: {
contains?: boolean | null;
contains_lithium_batteries?: boolean | null;
contains_biological_material?: boolean | null;
};
is_bypass_address_validation?: boolean | null;
is_bypass_customs?: boolean | null;
is_return_requested?: boolean | null;
packing_slip_text?: string | null;
signature_confirmation?: string | null;
};
is_return?: boolean;
line_items?: {
/** references to the ids of line_items in the WebOrder */
object_id?: string;
quantity?: number;
}[];
object_created?: string;
object_owner?: string;
object_updated?: string;
parcels?: {
distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
height?: string;
length?: string;
mass_unit?: 'g'|'kg'|'oz'|'lb';
use_item_weight?: boolean;
weight?: string;
width?: string;
carrier_parcel_template?: {
api_token?: string;
distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
height?: string;
is_variable_dimensions?: boolean;
length?: string;
name?: string;
carrier?: string;
token?: string;
width?: string;
} | null;
user_parcel_template?: {
distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
height?: string;
is_default?: boolean;
length?: string;
name?: string;
object_id?: string | null;
template?: {
api_token?: string;
distance_unit?: 'mm'|'cm'|'m'|'km'|'in'|'ft'|'yd'|'mi';
height?: string;
is_variable_dimensions?: boolean;
length?: string;
name?: string;
carrier?: string;
token?: string;
width?: string;
} | null;
weight?: string;
weight_unit?: 'g'|'kg'|'oz'|'lb';
width?: string;
};
}[];
rates?: {
amount?: string;
amount_local?: string;
arrives_by?: string;
attributes?: string[];
carrier_account?: string;
currency?: string;
currency_local?: string;
duration_terms?: string;
/** @format int32 */
estimated_days?: number;
included_insurance_price?: string;
messages?: string[];
object_created?: string;
object_id?: string;
object_owner?: string;
provider?: string;
provider_image_200?: string;
provider_image_75?: string;
servicelevel?: {
extended_token?: string;
name?: string;
parent_servicelevel?: string;
terms?: string;
token?: string;
};
shipment?: string;
test?: boolean;
zone?: string;
}[];
shipment_date?: string;
status?:
| 'PENDING'
| 'VALIDATING_ORDER'
| 'VALID_ORDER'
| 'INVALID_ORDER'
| 'PROCESSING_SHIPMENT'
| 'COMPLETE_SHIPMENT'
| 'EXCLUDED_ORDER'
| 'SHIPMENT_REQUEST_FAILED'
| 'PROCESSING_TRANSACTION'
| 'COMPLETE_TRANSACTION'
| 'TRANSACTION_REQUEST_FAILED'
| 'SHIPMENT_REQUEST_NOT_AVAILABLE'
| 'RATE_NOT_AVAILABLE';
transaction?: string;
}
```
The `ORDERS_CREATED` event sends an array of order objects (same as above) as the parameter to the callback function passed to the `on()` method.
### Errors
The `ERROR` event returns an error object as the parameter to the call function passed to the `on()` method:
```typescript theme={null}
interface Transaction {
code: 'UNAUTHORIZED'|'LABEL_PURCHASE_ERROR'|'COUNTRY_NOT_SUPPORTED'|'LOCALE_NOT_SUPPORTED'|'UNKNOWN';
detail: string;
}
```