# Events

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
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
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
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
interface Transaction {
    code: 'UNAUTHORIZED'|'LABEL_PURCHASE_ERROR'|'COUNTRY_NOT_SUPPORTED'|'LOCALE_NOT_SUPPORTED'|'UNKNOWN';
    detail: string;
}
```