# 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 `` tag. For example: ```html Web Application App content. ``` 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. ## ![](/assets/step1.14ee6260337a0b326de06f1173e3703f933b52790e666cd390788635d3e7e0a6.9c1bb791.svg) `init()` - Initialize the widget framework Once you have generated a valid authentication token ([JWT](/docs/shippingelements/auth)), you will call the `init` function from the window-scoped `shippo` variable: ```javascript 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](/docs/shippingelements/auth) * **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](/docs/shippingelements/customisation#theme) documentation for supported values. ### Full example Here is a full example of the `init()` method: ```javascript shippo.init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c', org: 'john-doe-industries', locale: 'fr-CA', theme: { width: '100%', }, }); ``` ## ![](/assets/step2.37831ee18f1f0290fe49fb6b512319f7a374b18f4063f0302fe35b4afcd9816b.9c1bb791.svg) `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: ```javascript 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 ```typescript 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: ```javascript 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: ```javascript 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) ```html Web Application
```