Site Logo

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 ShipEngine user account.

Customizable Onboarding Elements

The following onboarding elements are customizable using the themes endpoint:

The Start Screen

Onboarding start screen with logo, brand, start title, and start text properties marked
  • Logo image (this image will persist throughout your customer's portal experience)
  • Brand name
  • Start title
  • Start text

The Completed Screen

Onboarding complete screen with logo, complete title, and complete text properties marked
  • 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.

Create Theme Example Request

POST /v1/partners/themes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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."
}
}

Create Theme Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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."
},
"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).

Edit Theme Example Request

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"
}
}

Edit Theme Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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."
},
"created_at": "2024-01-25T03:06:20.933Z",
"modified_at": "2024-01-25T08:06:20.933Z",
}

Tip:

Set Carrier Selection by Country

You can also set which country's carriers your customers can connect when creating or editing a theme. Review Set Available Carriers by Country for details on setting the required property.

Delete a Theme

You can also delete any theme by its theme_id.

Delete Theme Example Request

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__

Delete Theme 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__