Get started with Elements

ShipEngine Elements can be integrated into your application in two ways: as an SDK or as a suite of React components.

Regardless of the integration method you choose, you'll need to generate a ShipEngine Platform token and establish a new ShipEngine Partner account.

To learn more about ShipEngine Platform tokens, refer to the Platform token documentation. For more information about ShipEngine Partner accounts, visit the Partners API documentation.

Step 1: Creating a ShipEngine Account

To create a ShipEngine Elements JWT, a ShipEngine Account ID (also known as a ShipEngine Seller ID or tenant in some cases) is required. To make a new ShipEngine Seller, run the following curl request. To learn more about creating ShipEngine accounts, check out the ShipEngine account documentation.

1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://api.shipengine.com/v1/partners/accounts' \
  --header 'api-key: [my-api-key]' \
  --header 'Content-Type: application/json' \
  --header 'partner-id: [my-partner-id]' \
  --data-raw '{
    "first_name": "John",
    "last_name": "Doe",
    "company_name": "Acme Corp.",
    "origin_country_code": "US"
  }'

You will use the account_id field on the ShipEngine account creation response that the above curl request to sign a ShipEngine Elements JWT.

1
2
3
4
5
6
7
8
9
10
11
{
    "api_key": {
        "encrypted_api_key": "[another-api-key]",
        ...
    },
    "account_id": 1234567,  # seller id needed to sign JWT
    "external_account_id": null,
    "created_at": "2023-03-12T15:02:26.523Z",
    "modified_at": "2023-03-12T15:02:26.523Z",
    ...
}

Step 2: Signing your JWT

The following pieces of information are required to sign ShipEngine Platform JWT.

The following is an example of one possible way of generating a ShipEngine Platform JWT. Keep in mind, the same sample JWT application we mentioned earlier can be used to sign your JWT's.

Copy

JavaScriptRubyPythonPHP

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
32
33
34
35
36
37
38
39
40
import fs from 'fs';
import jsonwebtoken from 'jsonwebtoken';
import express from 'express';
import cors from 'cors';
import 'dotenv/config';

const app = express();

app.use(cors());

const generateToken = async () => {
  const payload = {
    partner: process.env.SHIPENGINE_PARTNER_ID,
    tenant: process.env.SHIPENGINE_SELLER_ID, // The ShipEngine Seller ID you created
    scope: process.env.SCOPE,
  };

  const secretKey = fs.readFileSync('certs/private.pem', 'utf-8');

  if (!secretKey) throw new Error('Missing secret key');

  const token = await jsonwebtoken.sign(payload, secretKey, {
    algorithm: 'RS256',
    expiresIn: 3600,
    issuer: process.env.PLATFORM_TOKEN_ISSUER,
    keyid: process.env.PLATFORM_TOKEN_KEY_ID,
  });

  return token;
};

app.get('/generate-token', async (_req, res) => {
  const token = await generateToken();

  res.status(200).json({ token });
});

app.listen(3002, () => {
  console.log('Server listening on port 3002');
});

Step 3: Using Elements

Determine your preferred integration method:

If you're just getting started with ShipEngine Elements, it's helpful to know that by default, a ShipEngine Seller does not have warehouses (ship from locations) or carriers (USPS, UPS, DHL Express) attached to the seller account. These are required to purchase a label.

We recommend starting your users (ShipEngine Sellers) with the onboarding workflow via the Onboarding Element to set up their warehouse and carrier accounts.

Updates to warehouse and carrier accounts created during onboarding can be made through the Account Settings Element.

Carriers in Elements

Elements integrates with the leading global shipping carriers. Check out the complete carriers documentation to learn more about ShipEngine carriers.

Unless specified by carrier code in the globalFeatures.enabledShipEngineCarriers array within the features prop when initializing Elements, Elements will default to registering all supported US carriers. If you want to learn more about registering ShipEngine carriers, check out the Onboarding Element. If you want to learn more about managing existing ShipEngine Carrier connections, checkout the ShipEngine Carriers Element.

Supported ShipEngine Carriers

➤

US Carrier Codes

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

➤

GB Carrier Codes

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

➤

CA Carrier Codes

• GlobalPost: globalpost

➤

AU Carrier Codes

• Aramex Australia: aramex_au_walleted

Supported External Carriers

To start setting up external carrier connections, you must name them explicitly by carrier code in the globalFeatures.enabledExternalCarriers array within the features prop on the Elements Provider or through the Elements SDK class constructor. To learn more about getting started shipping with external carriers checkout the Connect External Carrier Element.

Migration guide to Elements v2

1. ShipEngine Alchemy is no longer a required package

To better address our partner's bundle size requirements in their applications, we have removed the need for the @shipengine/alchemy package. The core functionality of @shipengine/alchemy has been baked into the @shipengine/elements package. Similarly rather than wrapping your app in the <AlchemyProvider/> in v2, we have exposed the new <ElementsProvider/>.

To learn more about getting started with the Elements React components, check out the Elements React Components documentation.

2. Elements name changes

Some of the Elements names have be changed to better align the Elements with proper naming conventions.

3. Features added to the Elements Provider and Elements SDK constructor

To improve the developer experience while implementing Elements, we have added a features prop/parameter to the Elements Provider and Elements SDK constructor. In essence, this new features parameter rolls all the features throughout the Elements project into one object. For organizational purposes, we nested each Element's features under the Element's respective key within the object.

Features used throughout the Elements project, especially those pertaining to carriers like enabledShipEngineCarriers were hoisted up to a global features object shared throughout the project.

Any Element, in v1, whose only features are related to carriers i.e. enabledShipEngineCarriers or enabledExternalCarriers, have been moved up to the global features context. See the list of Elements who where effected by this change below.

➤

Effected Elements

• Onboarding: No longer has a features prop.
• ManageExternalCarriers: No longer has a features prop.
• ManageCarriers: No longer has any props.
• CarrierServices: No longer has any props.
• ConnectExternalCarrier: No longer has a features prop.
• AccountSettings: No longer requires carriers in its features prop.
• VoidLabel: No longer has a features prop.

We recommend setting the features you wish to use in the Elements Provider or SDK constructor for the Element, but if you want to override Element specefic features later, you can use that Element's feature prop if it has one.

Learn more about each elements respective features.

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
32
33
34
35
36
const elementsFeatures = {
  globalFeatures: {
    // Availible "Bring your own carrier" carrier codes for carriers that may be added. If this is omitted, new carriers may not be added by this element.
    enabledExternalCarriers: [
        'apc',
        'asendia',
        'better_trucks',
        'courierpost',
        'dpd',
        'seko',
        'ups',
        'yodel',
    ],

    // list of all walleted carriers that are enabled for use in Elements.
    enabledShipEngineCarriers: ['ups', 'stamps_com'],

    // Enables the `Powered by ShipEngine` logo in the footer various elements.
    poweredByShipEngine: false,
  },
  purchaseLabelFeatures: { ... },
  shipmentSummaryFeatures: { ... },
  accountSettingsFeatures: { ... },
}

// Create a new instance of the Elements SDK with features.
const elements = new ElementsSDK(
  getToken,
  {
    onError: (err: Error) => console.error(err),
    baseURL: 'https://elements.shipengine.com',
    themeConfig: themeConfig,
    locale: 'en-US',
    features: elementsFeatures
  }
);

4. Elements SDK improvements

In a effort to more closely allign the Elements SDK with the functionality provided by the Element React components we have made significat improvement to the Elements SDK.

Mount Elements anywhere in the DOM

Using the new create method on the Elements SDK class, you can now pass an HTML ID attribute or HTML element to the mount method to mount any Elements anywhere in your application HTML document. See here to learn more about mounting Elements.

Rendering in a Side Panel

Methods like elements.onboardUser or elements.purchaseLabel, accessible via the Elements SDK class, have been deprecated in Elements v2 and will be removed in future versions. We have replaced these methods with the renderInSidePanel method, which is available in the returned object via the create method. Please follow the recommended workflow in the rendering elements section to render elements in a side panel.

Destroy method

In v1 of the Elements SDK, the unmount method, available via the SDK class, removed the React root and the HTML element to which the SDK attached the side panel. This method has been renamed destroy.