Onboarding Element

The Onboarding Element is pre-configured to streamline the registration process by establishing a default ship from location, selecting a payment method, and linking ShipEngine carrier accounts to a ShipEngine seller account. These steps are essential for users to complete before they can purchase shipping labels.

Additionally, the Onboarding Element is designed to onboard ShipEngine Seller accounts according to the country of origin specified at the time of account creation. Below is a list of the countries of origin we currently support. For more information, refer to the full Partner API documentation.

US: United States of America
GB: United Kingdom
CA: Canada
AU: Australia

ShipEngine API Prerequisites

Before you get started with the Onboarding Element, it would be helpful to familiarize yourself with key ShipEngine API fundamentals such as Warehouses and Carriers.

Warehouses (ship from locations)

A warehouse is the origin location from which a seller ships. This location could be a home, an office, or anywhere. At its core, a warehouse contains two essential pieces of information: a ship-from address and a return address.

Each warehouse under a seller account has a unique warehouse ID, which Elements and ShipEngine use to keep track of where you are shipping from. Shipments require a ship-from address to purchase a label successfully. Using warehouses streamlines the management of your ship-from addresses throughout the shipment configuration and label purchase process.

To learn more about warehouses, check out the full warehouse documentation.

The Onboarding Element accepts a prop, defaultShipFromAddress which pre-populates the address form during onboarding. This creates the default warehouse ID used to purchase labels. After onboarding, warehouses can be added, updated, and deleted in the Account Settings Element.

Configuring Carriers

The Onboarding Element is designed to integrate with the leading global shipping carriers. Check out the complete carriers documentation to learn more about ShipEngine carriers.

If you wish to register ShipEngine carrier accounts in the Onboarding Element, you must explicitly list them by carrier code in the globalFeatures.enabledShipEngineCarriers array, which is nested within the features prop of the ElementsProvider or ElementsSDK class constructor.

For an in depth overview of the features object, please review the Configuring Elements Features step in either the ElementsProvider or the Elements SDK guides.

Supported ShipEngine Carriers in Elements

USPS: stamps_com
DHL Express: dhl_express_worldwide

Yodel: yodel_walleted
Evri: hermes
DPD: dpdwallet

GlobalPost: globalpost

Aramex Australia: aramex_au_walleted
Sendle: sendle_walleted
CouriersPlease : couriersplease_walleted

React Component

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import { Onboarding, ElementsProvider } from '@shipengine/elements';
import { themeConfig } from '../themeConfig';
import { defaultShipFromAddress } from '../address';

const tokenPath = '/path/to/token/endpoint';

const Foo = () => {
  const getToken = useCallback(() => {
    return fetch(tokenPath).then((res) => res.text());
  }, []);

  return (
    <ElementsProvider
      getToken={getToken}
      themeConfig={themeConfig}
      onError={handleError}
      features={{
        globalFeatures: {
          enabledShipEngineCarriers: ['stamps_com', 'globalPost'],
        },
      }}
    >
      <Onboarding.Element
        onComplete={() => console.log('complete')}
        defaultShipFromAddress={defaultShipFromAddress}
      />
    </ElementsProvider>
  );
};

SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Creates a new instance of the Elements SDK.
const elements = new ElementsSDK(getToken, {
  onError: (err: Error) => console.error(err),
  themeConfig: themeConfig,
  locale: 'en-US',
  features: {
    globalFeatures: {
      enabledShipEngineCarriers: ['stamps_com', 'globalPost'],
    },
  },
});

const onboarding = elements.create('onboarding', {
  onComplete: () => console.log('complete'),
  defaultShipFromAddress: defaultShipFromAddress,
});

Options

Args/Props	Description
`onComplete`	function, required A required callback function that is invoked when the user clicks the "Start Creating Labels" button on the final summary page of the Onboarding wizard.
`defaultShipFromAddress`	object, optional The address that will be auto filled during the address step of onboarding. reference
`onSellerOnboarded`	function, optional An optional callback function that is invoked after the final ShipEngine onboarding tasks are completed. This can be used to capture onboarding complete whether the user clicks the "Start Creating Labels" button or closes the Element.
`skipWelcomePage`	boolean, optional When set to `true`, the onboarding flow will bypass the default welcome page and proceed directly to the first step. This is intended for partners who wish to provide their own custom welcome or introductory experience.

Onboarding Workflow

This is an outline of the process users will follow to set up ShipEngine carrier accounts once the Onboarding Element has been created:

Step 1: Connect Carriers

Review carriers to be registered and agree to Terms of Service.

See Configuring Carriers for more information on how to enable ShipEngine carriers for user registration.

Step 2: Create a default warehouse

The Onboarding Element accepts a prop, defaultShipFromAddress, which will autofill the address form during onboarding. This will be used to create the default warehouse ID for purchasing labels. After onboarding, warehouses can be added, updated, and deleted in the Account Settings Element.

Step 3: Input a preferred payment method

This payment method will be used to fund label purchases and receive refunds from voided labels. After onboarding, payment methods can be updated in the Account Settings Element.

Step 4: Confirm warehouse and billing information

Confirm the information entered in the previous steps before submitting.

Step 5: Registration Complete

Upon registration success, users will be directed to a completion page. At this step, the function passed to the onComplete prop will be invoked when the completion button is clicked. Users are now onboarded with ShipEngine carrier accounts and are ready to begin shipping with ShipEngine Elements.