Events - Shippo API Documentation

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:

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.

noteUsing 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:

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:

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:

interface Transaction {
    code: 'UNAUTHORIZED'|'LABEL_PURCHASE_ERROR'|'COUNTRY_NOT_SUPPORTED'|'LOCALE_NOT_SUPPORTED'|'UNKNOWN';
    detail: string;
}

​Events using shippo.on()

​Event List

​Event Parameters

​LABEL_PURCHASED_SUCCESS

​ORDER_CREATED

​Errors

Events using `shippo.on()`

Event List

Event Parameters

LABEL_PURCHASED_SUCCESS

ORDER_CREATED

Errors