# 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](/apis/shipengine/docs/partners/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**

![Onboarding start screen with logo, brand, start title, and start text properties marked](/assets/partneronboarding-theme1_mrk.e9ea992eeecf393165041c766f1e96153b303243de9f59689bb7d2af0e6241ef.78ec57cc.png)

* 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](/assets/partneronboarding-theme2_mrk.8e0b4c2cd9291327911f4d15ec7a31bb81078edfa9927af853b24ee6512a28bb.78ec57cc.png)

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


Go to our [Themes Endpoint Reference page](/apis/shipengine/docs/partners/theme-reference) 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) (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:


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

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


```js
let windowReference;

const openWebsite = () => {
  windowReference = window.open('https://api-portal.shipstation.com/onboarding');
};

window.addEventListener(
  'message',
  (event) => {
    // Due to security reasons, it's best if you confirm the origin
    if (event.origin !== "https://api-portal.shipstation.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**


```http
POST /v1/partners/themes HTTP/1.1
Host: api.shipengine.com
API-Key: __PARTNER_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:**


```json
{
  "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}**


```http
PATCH /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.shipengine.com
API-Key: __PARTNER_API_KEY_HERE__
Content-Type: application/json

{
  "name": "My new theme name",
  "onboarding": {
    "start_title": "New title"
  }
}
```

**Example response:**


```json
{
  "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"
}
```

> **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](/apis/shipengine/docs/partners/set-carrier-countries) for details on setting the required property.


## Delete a Theme

You can also delete any theme by its `theme_id`.

### Example Request & Response

**DELETE /v1/partners/themes/{themeId}**


```http
DELETE /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.shipengine.com
API-Key: __PARTNER_API_KEY_HERE__
```

**Example response:**


```http
HTTP/1.1 204 No Content
```

## List Themes

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

**GET  /v1/partners/themes/{themeId}**


```http
GET /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.shipengine.com
API-Key: __PARTNER_API_KEY_HERE__
```

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

**GET /v1/partners/themes**


```http
GET /v1/partners/themes HTTP/1.1
Host: api.shipengine.com
API-Key: __PARTNER_API_KEY_HERE__
```