{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/partners/customize-theme","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/partners/customize-theme","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/partners/customize-theme","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Custom the Onboarding Experience","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"custom-the-onboarding-experience","__idx":0},"children":["Custom the Onboarding Experience"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You may wish to customize the onboarding experience for your customers with company-approved branding and messaging. We've provided a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["themes"]}," endpoint that allows you to customize the brand name, logo, and a few other elements within the onboarding flow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have created your theme, you can apply it by specifying the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme_id=\"your theme ID\""]}," as part of the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/partners/direct-login"},"children":["direct login"]}," URL you generate for a ShipStation API user account."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customizable-onboarding-elements","__idx":1},"children":["Customizable Onboarding Elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following onboarding elements are customizable using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["themes"]}," endpoint:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The Start Screen"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/partneronboarding-theme1_mrk.e9ea992eeecf393165041c766f1e96153b303243de9f59689bb7d2af0e6241ef.78ec57cc.png","alt":"Onboarding start screen with logo, brand, start title, and start text properties marked"},"children":[]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Logo image (this image will persist throughout your customer's portal experience)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Brand name"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Start title"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Start text"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The Completed Screen"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/partneronboarding-theme2_mrk.8e0b4c2cd9291327911f4d15ec7a31bb81078edfa9927af853b24ee6512a28bb.78ec57cc.png","alt":"Onboarding complete screen with logo, complete title, and complete text properties marked"},"children":[]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete title"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete text"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Complete button text"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Close button"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Close button text"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to our ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/partners/theme-reference"},"children":["Themes Endpoint Reference page"]}," for a full list of properties available for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["themes"]}," endpoint and their descriptions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"about-the-close-button-behavior","__idx":2},"children":["About the Close Button Behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The close button (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["complete_close_button"]},") will not close the onboarding window by itself, due to certain browser restrictions. To close the window, we'll ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage"},"children":["post a message"]}," (shipengine.dashboard.close) through the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["window.opener"]},". The parent application ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["must"]}," listen to that message and execute the close action."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, when the user clicks the close button, we will execute the following code:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"window.opener.postMessage('shipengine.dashboard.close', '*');\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your parent application (that initially opened the dashboard) should have code similar to this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"let windowReference;\n\nconst openWebsite = () => {\n  windowReference = window.open('https://dashboard.shipengine.com/onboarding');\n};\n\nwindow.addEventListener(\n  'message',\n  (event) => {\n    // Due to security reasons, it's best if you confirm the origin\n    if (event.origin !== \"https://dashboard.shipengine.com\") return;\n\n    // Checks for the expected message\n    if (event.data === 'shipengine.dashboard.close') {\n      windowReference.close();\n    }\n  },\n  false\n);\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-theme","__idx":3},"children":["Create a Theme"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["themes"]}," endpoint to create a new theme. You can create a maximum of 10 themes per partner."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request--response","__idx":4},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/partners/themes"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/partners/themes HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __PARTNER_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"name\": \"My theme\",\n  \"brand\": \"Auctane brand\",\n  \"return_url\": \"https://mydomain.com\",\n  \"logo\": {\n    \"content_type\": \"image/png\",\n    \"image_data\": \"iVBORw0KGgoAAAANSUhEUg...\"\n  },\n  \"onboarding\": {\n    \"start_title\": \"Start shippping today!\",\n    \"start_text\": \"Simply follow the steps to configure your carriers.\",\n    \"complete_title\": \"You are done!\",\n    \"complete_text\": \"Click continue to start shipping.\",\n    \"skip_shipstation_api_carriers\": false\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"theme_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"My theme\",\n  \"brand\": \"Auctane brand\",\n  \"return_url\": \"https://mydomain.com\",\n  \"logo\": {\n    \"content_type\": \"image/png\",\n    \"image_data\": \"iVBORw0KGgoAAAANSUhEUg...\"\n  },\n  \"onboarding\": {\n    \"start_title\": \"Start shippping today!\",\n    \"start_text\": \"Simply follow the steps to configure your carriers.\",\n    \"complete_title\": \"You are done!\",\n    \"complete_text\": \"Click continue to start shipping.\",\n    \"skip_shipstation_api_carriers\": false\n  },\n  \"created_at\": \"2024-01-25T03:06:20.933Z\",\n  \"modified_at\": \"2024-01-25T03:06:20.933Z\",\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"edit-a-theme","__idx":5},"children":["Edit a Theme"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a theme, the response will include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme_id"]},". You can then use the ID to make edits to your existing theme(s)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request--response-1","__idx":6},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PATCH /v1/partners/themes/{themeID}"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PATCH /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __PARTNER_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"name\": \"My new theme name\",\n  \"onboarding\": {\n    \"start_title\": \"New title\"\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"theme_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"name\": \"My new theme name\",\n  \"brand\": \"Auctane brand\",\n  \"return_url\": \"https://mydomain.com\",\n  \"logo\": {\n    \"content_type\": \"image/png\",\n    \"image_data\": \"iVBORw0KGgoAAAANSUhEUg...\"\n  },\n  \"onboarding\": {\n    \"start_title\": \"New title\",\n    \"start_text\": \"Simply follow the steps to configure your carriers.\",\n    \"complete_title\": \"You are done!\",\n    \"complete_text\": \"Click continue to start shipping.\",\n    \"skip_shipstation_api_carriers\": false\n  },\n  \"created_at\": \"2024-01-25T03:06:20.933Z\",\n  \"modified_at\": \"2024-01-25T08:06:20.933Z\",\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TIP:"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"set-carrier-selection-by-country","__idx":7},"children":["Set Carrier Selection by Country"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also set which country's carriers your customers can connect when creating or editing a theme. Review ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/partners/set-carrier-countries"},"children":["Set Available Carriers by Country"]}," for details on setting the required property."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delete-a-theme","__idx":8},"children":["Delete a Theme"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also delete any theme by its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme_id"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request--response-2","__idx":9},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["DELETE /v1/partners/themes/{themeId}"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"DELETE /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __PARTNER_API_KEY_HERE__\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"HTTP 204, No Content\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-themes","__idx":10},"children":["List Themes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lastly, you can list the themes you've created by ID..."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["GET  /v1/partners/themes/{themeId}"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /v1/partners/themes/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __PARTNER_API_KEY_HERE__\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Or, list all the themes you've created..."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["GET /v1/partners/themes"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /v1/partners/themes HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __PARTNER_API_KEY_HERE__\n","lang":"http"},"children":[]}]},"headings":[{"value":"Custom the Onboarding Experience","id":"custom-the-onboarding-experience","depth":1},{"value":"Customizable Onboarding Elements","id":"customizable-onboarding-elements","depth":2},{"value":"About the Close Button Behavior","id":"about-the-close-button-behavior","depth":3},{"value":"Create a Theme","id":"create-a-theme","depth":2},{"value":"Example Request & Response","id":"example-request--response","depth":3},{"value":"Edit a Theme","id":"edit-a-theme","depth":2},{"value":"Example Request & Response","id":"example-request--response-1","depth":3},{"value":"Set Carrier Selection by Country","id":"set-carrier-selection-by-country","depth":3},{"value":"Delete a Theme","id":"delete-a-theme","depth":2},{"value":"Example Request & Response","id":"example-request--response-2","depth":3},{"value":"List Themes","id":"list-themes","depth":2}],"frontmatter":{"seo":{"title":"Custom the Onboarding Experience"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/partners/customize-theme","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}