Custom the Onboarding Experience

You may wish to customize the onboarding experience for your customers with company-approved branding and messaging. We've provided a themes endpoint that allows you to customize the brand name, logo, and a few other elements within the onboarding flow.

Once you have created your theme, you can apply it by specifying the theme_id="your theme ID" as part of the direct login URL you generate for a ShipStation API user account.

Customizable Onboarding Elements

The following onboarding elements are customizable using the themes endpoint:

The Start Screen

Logo image (this image will persist throughout your customer's portal experience)
Brand name
Start title
Start text

The Completed Screen

Complete title
Complete text
Complete button text
Close button
Close button text

Go to our Themes Endpoint Reference page for a full list of properties available for the themes endpoint and their descriptions.

About the Close Button Behavior

The close button (complete_close_button) will not close the onboarding window by itself, due to certain browser restrictions. To close the window, we'll post a message (shipengine.dashboard.close) through the window.opener. The parent application must listen to that message and execute the close action.

For example, when the user clicks the close button, we will execute the following code:

1
window.opener.postMessage('shipengine.dashboard.close', '*');

Your parent application (that initially opened the dashboard) should have code similar to this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
let windowReference;

const openWebsite = () => {
  windowReference = window.open('https://dashboard.shipengine.com/onboarding');
};

window.addEventListener(
  'message',
  (event) => {
    // Due to security reasons, it's best if you confirm the origin
    if (event.origin !== "https://dashboard.shipengine.com") return;

    // Checks for the expected message
    if (event.data === 'shipengine.dashboard.close') {
      windowReference.close();
    }
  },
  false
);

Create a Theme

Use the themes endpoint to create a new theme. You can create a maximum of 10 themes per partner.

Example Request & Response

POST /v1/partners/themes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
POST /v1/partners/themes HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "name": "My theme",
  "brand": "Auctane brand",
  "return_url": "https://mydomain.com",
  "logo": {
    "content_type": "image/png",
    "image_data": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "onboarding": {
    "start_title": "Start shippping today!",
    "start_text": "Simply follow the steps to configure your carriers.",
    "complete_title": "You are done!",
    "complete_text": "Click continue to start shipping.",
    "skip_shipstation_api_carriers": false
  }
}

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "theme_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My theme",
  "brand": "Auctane brand",
  "return_url": "https://mydomain.com",
  "logo": {
    "content_type": "image/png",
    "image_data": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "onboarding": {
    "start_title": "Start shippping today!",
    "start_text": "Simply follow the steps to configure your carriers.",
    "complete_title": "You are done!",
    "complete_text": "Click continue to start shipping.",
    "skip_shipstation_api_carriers": false
  },
  "created_at": "2024-01-25T03:06:20.933Z",
  "modified_at": "2024-01-25T03:06:20.933Z",
}

Edit a Theme

When you create a theme, the response will include a theme_id. You can then use the ID to make edits to your existing theme(s).

Example Request & Response

PATCH /v1/partners/themes/{themeID}

1
2
3
4
5
6
7
8
9
10
11
PATCH /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "name": "My new theme name",
  "onboarding": {
    "start_title": "New title"
  }
}

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "theme_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My new theme name",
  "brand": "Auctane brand",
  "return_url": "https://mydomain.com",
  "logo": {
    "content_type": "image/png",
    "image_data": "iVBORw0KGgoAAAANSUhEUg..."
  },
  "onboarding": {
    "start_title": "New title",
    "start_text": "Simply follow the steps to configure your carriers.",
    "complete_title": "You are done!",
    "complete_text": "Click continue to start shipping.",
    "skip_shipstation_api_carriers": false
  },
  "created_at": "2024-01-25T03:06:20.933Z",
  "modified_at": "2024-01-25T08:06:20.933Z",
}

Delete a Theme

You can also delete any theme by its theme_id.

Example Request & Response

DELETE /v1/partners/themes/{themeId}

1
2
3
DELETE /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

Example response:

1
HTTP 204, No Content

List Themes

Lastly, you can list the themes you've created by ID...

GET /v1/partners/themes/{themeId}

1
2
3
GET /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

Or, list all the themes you've created...

GET /v1/partners/themes

1
2
3
GET /v1/partners/themes HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__