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.

➤

Supported Origin Countries in Elements

• US: United States of America
• GB: United Kingdom

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 is used by Elements and ShipEngine to keep track of where you are shipping from. As you may recall, a valid warehouse ID is required by shipments to purchase a label successfully.

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

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

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
30
type DefaultShipFrom: {
  isDefault: boolean,
  name: string, // The human readable name of the Warehouse
  originAddress: {
    addressLine1: string,
    addressLine2?: string,
    addressLine3?: string,
    cityLocality: string,
    companyName?: string,
    countryCode: string,
    email?: string,
    name: string,
    phone: string,
    postalCode: string,
    stateProvince: string,
  },
  returnAddress?: {
    addressLine1: string,
    addressLine2?: string,
    addressLine3?: string,
    cityLocality: string,
    companyName?: string,
    countryCode: string,
    email?: string,
    name: string,
    phone: string,
    postalCode: string,
    stateProvince: string,
  },
};

Configuring Enabled 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.

To start shipping with our carriers, you must name them explicitly by carrier code in the enabledCarriers array nested within the features prop.

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
...
type features: {
  carriers: {
    enabledCarriers: (
      | "stamps_com" // USPS
      | "ups"
      | "dhl_express_walleted"
      | "hermes" // Evri
      | "yodel_walleted"
      | "dpdwallet"
    )[];
  };
}

return (
  ...
  <Onboarding.Element
    features={{
       carriers: {
         enabledCarriers: ['ups', 'stamps_com', 'dhl_express_walleted'],
       },
     }
    }
  />
)

Supported ShipEngine Carriers in Elements

➤

US Carrier Codes

• UPS: ups_walleted
• USPS: stamps_com
• DHL Express: dhl_express_walleted

➤

GB Carrier Codes

• Yodel: yodel_walleted
• Evri: hermes
• DPD: dpdwallet

Create an Onboarding Element

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
30
31
import { Onboarding } from '@shipengine/elements';
import { AlchemyProvider } from '@shipengine/alchemy';
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 (
    <AlchemyProvider
      getToken={getToken}
      themeConfig={themeConfig}
      onError={handleError}
    >
      <Onboarding.Element
        onComplete={() => console.log('complete')}
        defaultShipFromAddress={defaultShipFromAddress}
        features={{
          carriers: {
            enabledCarriers: ['ups', 'stamps_com', 'dhl_express_walleted'],
          },
        }}
        partnerName="ShipEngine"
      />
    </AlchemyProvider>
  );
};

Onboarding User Flow

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: Enter an email address

This email address can differ from the email provided during seller account creation. It will be used only for registering with carriers that require an email address.

Step 2: Activate Carriers

Review carriers to be registered and agree to Terms of Service. Available carriers are sourced from the enabledCarriers array in the features prop. The Onboarding Element displays only the carriers relevant to the country code associated with the ShipEngine seller account being onboarded.

Step 3: 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 4: 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 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.

Purchase shipping labels with Elements