Custom Themes with the Partner API

You may wish to customize the onboarding experience for your customers. 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 Elements

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

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

Properties

The following properties are associated with the themes endpoint:

Property	Type	Description
name	string	Required The name of the theme Max 50 characters
logo.content_type	image/jpeg image/png	Image content type
logo.image_data	string	base64 encoded
brand	string	Required Brand name that appears on the Start screen
return_url	string	URL to return to upon logout Max 1000 characters
onboarding.start_title	string	Max 50 characters
onboarding.start_text	string	Max 1000 characters
onboarding.complete_title	string	Max 50 characters
onboarding.complete_text	string	Max 1000 characters
onboarding.complete_button_text	string	Max 50 characters
onboarding.complete_close_button	boolean	Default = false Determines whether to display the close button or not (see About section below for behavior details)
onboarding.complete_close_button_text	string	Max 50 characters
theme_id	string	uuid
created_at	string	date-time
modified_at	string	date-time

About the Close Button Behavior

The button will not close the onboarding window by itself, due to certain browser restrictions. To close the window, we'll post a message (shipengine.onboarding.close.clicked) 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.onboarding.close.clicked', '*');

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.onboarding.close.clicked') {
      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",
}

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

GET Themes

Lastly, you can get 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, get 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__