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.

ShipEngine Partner ID: You should have received this after you had completed partner onboarding with your ShipEngine technical contact. This is a unique identifier for your ShipEngine Partner account.
Tenant ID: The ID of the ShipEngine account that was created. This is also known as the ShipEngine Seller ID you may have been given during partner onboarding.
Public/Private RSA keys: You should have registered the public key with ShipEngine during partner onboarding. We recommend you store the private RSA key you created in a secure container format, like .pem.
Platform Token Key ID: You should have received this after you had completed partner onboarding with your ShipEngine technical contact. This will be the name of the platform token key you registered with ShipEngine during partner onboarding.
Scope: You should have received this after you had completed partner onboarding with your ShipEngine technical contact. The scope enforces the usage of a specific subset of ShipEngine API endpoints.
Platform Token Issuer: You should have received this after you had completed partner onboarding with your ShipEngine technical contact.

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.

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:

Elements SDK
This is the simplest of the two integration methods, but it provides the least flexibility.
React Components
For React developers that want more flexibility and customizablity.

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.