Install the Shippo Shipping Elements SDK

The Shippo Shipping Elements SDK is a client-side javascript SDK that provides mechanisms for rendering and controlling the Shipping Elements shipping workflow.

Installation

To install the SDK, include the javascript file from our Content Delivery Network (CDN): https://js.goshippo.com/embeddable-client.js (32 kb file size) on your web application just before the closing </body> tag.

For example:

Copy
Copied
<!doctype html>
<html class="no-js" lang="">
<head>
    <meta charset="utf-8">
    <title>Web Application</title>
</head>
<body>
    App content.
    <script src="https://js.goshippo.com/embeddable-client.js"></script>
</body>
</html>

This script initializes a shippo window variable that contains variables and methods for using the SDK.

Overview

The Shippo Shipping Elements SDK has two primary methods for setting up and rendering the Shipping Elements label purchase flow: init() and labelPurchase(). The init() method authenticates and configures all Shippo widgets and is typically called once per page. The labelPurchase() function renders the widget and passes any required data to prepopulate shipment information such as address, order items, etc. The labelPurchase() method may be called multiple times per page as the user is creating shipping labels for multiple orders.

init() - Initialize the widget framework

Once you have generated a valid authentication token (JWT), you will call the init function from the window-scoped shippo variable:

Copy
Copied
shippo.init()

Parameters

The init function takes an object of the following:

  • token : string (required) - a JWT-style authentication token derived from the /authz endpoint
  • org : string (required) - an identifier for your organization
  • locale : string (optional, defaults to en-US ) - The locale string in "IETF language tag" format used to translate the widget. Supported values:
    • en
    • en-GB
    • ru
    • de
    • fr
    • tr
    • it
    • es
    • pl
    • uk
    • nl
    • en-au
  • theme : Theme (optional) - Custom theme for the Shippo Shipping Elements. See Theme documentation for supported values.

Full example

Here is a full example of the init() method:

Copy
Copied
shippo.init({
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
  org: 'john-doe-industries',
  locale: 'fr-CA',
  theme: {
    width: '100%',
  },
});

labelPurchase() - Start label purchase flow

When you want the widget rendered, typically on a "Purchase Shipping Label" button click or equivalent, you will call the labelPurchase() method with the selector of the element you want to render the widget inside of and any shipment information you would like to prepopulate. You will call the labelPurchase function from the window-scoped shippo variable:

Copy
Copied
shippo.labelPurchase()

Parameters

  • element : string (required) - a document.querySelector-compatible selector for the element that the widget would be rendered inside of
  • orderDetails : OrderDetails|OrderDetails[] (required) - a JSON object (or array of JSON objects) with details about the order to be fulfilled

    OrderDetails

    Copy
    Copied
    export interface Address {
  name: string;
  company?: string;
  street_no?: string;
  street1: string;
  street2?: string;
  street3?: string;
  city: string;
  state: string;
  zip: string;
  country: string;
  phone?: string;
  email?: string;
}
export interface Item {
  id?: number;
  title: string;
  sku?: string;
  quantity: number;
  currency: string;
  unit_amount: string;
  unit_weight: string;
  weight_unit: string;
  country_of_origin?: string;
}
export interface OrderDetails {
  address_from?: Address;
  address_to: Address;
  line_items: Item[];
  address_return?: Address;
  object_id?: string;
  order_number?: string;
  order_status?: string;
  placed_at?: string;
  notes?: string;
  // end of order information
  shipment_date?: Date;
  extras?: {
    insurance?: {
      amount: string;
      currency: string;
    };
    signature_confirmation?: string;
  };
}

    Full example

    Here is a full example of the labelPurchase() method for a single order:

    Copy
    Copied
    shippo.labelPurchase('#shippoWidget', {
    address_to: {
          name: 'William Faulkner',
          company: '',
          street1: '916 Old Taylor Rd',
          city: 'Oxford',
          state: 'MS',
          zip: '38655',
          country: 'US',
          phone: '662-234-3284',
          email: 'william@rowanoak.com',
    },
    line_items: [
      {
            title: 'Book',
            sku: 'TS-123',
            quantity: 1,
            currency: 'USD',
            unit_amount: '12',
            unit_weight: '0.40',
            weight_unit: 'lb',
            country_of_origin: 'US',
        }
    ],
    order_number: '12345'
});

And an example for multiple orders:

Copy
Copied
    shippo.labelPurchase('#shippoWidget', [
      {
        address_to: {
          name: 'William Faulkner',
          company: '',
          street1: '916 Old Taylor Rd',
          city: 'Oxford',
          state: 'MS',
          zip: '38655',
          country: 'US',
          phone: '662-234-3284',
          email: 'william@rowanoak.com',
        },
        line_items: [
          {
            title: 'Book',
            sku: 'TS-123',
            quantity: 1,
            currency: 'USD',
            unit_amount: '12',
            unit_weight: '0.40',
            weight_unit: 'lb',
            country_of_origin: 'US',
          }
        ],
        order_number: '12345'
      },
      {
        address_to: {
          name: 'John Steinbeck',
          company: '',
          street1: '132 Central Ave, Salinas, CA 93901',
          city: 'Salinas',
          state: 'CA',
          zip: '93901',
          country: 'US',
          phone: '831-424-2735',
          email: 'admin@steinbeckhouse.net',
        },
        line_items: [
          {
            title: 'Book',
            sku: 'TS-123',
            quantity: 1,
            currency: 'USD',
            unit_amount: '12',
            unit_weight: '0.40',
            weight_unit: 'lb',
            country_of_origin: 'US',
          }
        ],
        order_number: '23456'
      }
    ]);

Full Example (install, init and labelPurchase)

Copy
Copied
<!doctype html>
<html class="no-js" lang="">
<head>
        <meta charset="utf-8">
        <title>Web Application</title>
</head>
<body>
    <button id="purchaseLabelButton">Purchase Label</button>
    <div id="shippoWidget"></div>
    <script src="https://js.goshippo.com/embeddable-client.js"></script>
    <script type="application/javascript">
      if (shippo) {
        shippo.init({
          token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c',
          org: 'john-doe-industries',
          locale: 'fr-CA',
          theme: {
            width: '100%',
          },
        });
      }
      document.getElementById('purchaseLabelButton').addEventListener('click', (event) => {
      	event.preventDefault();
        shippo.labelPurchase('#shippoWidget', {
          address_to: {
            name: 'William Faulkner',
            company: '',
            street1: '916 Old Taylor Rd',
            city: 'Oxford',
            state: 'MS',
            zip: '38655',
            country: 'US',
            phone: '662-234-3284',
            email: 'william@rowanoak.com',
          },
          line_items: [
            {
              title: 'Book',
              sku: 'TS-123',
              quantity: 1,
              currency: 'USD',
              unit_amount: '12',
              unit_weight: '0.40',
              weight_unit: 'lb',
              country_of_origin: 'US',
            }
          ],
          order_number: '12345'
        });
      }, false);
    </script>
</body>
</html>