ShipStation API partners have the ability to create and manage ShipStation API accounts on behalf of their customers.
For your customers to access ShipStation API's discounted carrier rates, they must complete the ShipStation API Onboarding Element or onboard within the ShipStation API Carrier Portal.
During either process, your customer will need to accept carrier terms, enter billing information, and then fund a balance to pay for ShipStation Carrier labels.
The ShipStation API Carrier Portal is a special version of the ShipStation API Dashboard designed to let customers of partners complete a branded onboarding wizard or manage carriers and billing information.
The direct login feature allows a partner to generate a URL to the ShipStation API Carrier Portal for a specific customer, without requiring them to enter their username or password.
This guide will go through how to generate a link to the ShipStation API Carrier Portal for your merchants.
To access the ShipStation API Carrier Portal, you must generate an authorization token. This token has a 10 second lifespan so it should be generated just-in-time each time dashboard access is requested.
The On-Behalf-Of header should be set to the customer account ID for which you wish to generate an authorization token.
See the “Configure a URL” section below for details on how to determine where the user is directed after successful authentication.
POST /v1/tokens/ephemeral?redirect=shipengine-dashboard HTTP/1.1
Host: api.shipengine.com
API-Key: __PARTNER_API_KEY_HERE__
On-Behalf-Of: __ACCOUNT_ID_HERE__
Content-Type: application/jsonExample response:
{
"token": "eyJ..",
"redirect_url": "https://dashboard.shipengine.com/api/directlogin?token=eyJ.."
}The call to generate a token also generates a URL you can use to redirect your customer to the ShipStation API carrier portal.
- Use the
redirect_toparameter to determine which page your customer will land on by default. You can redirect to the Carriers, Billing, or Onboarding pages. - Add the
theme_idparameter to this URL before redirecting your customer so they will be directed to a branded experience. - Query parameters should be appended to the end of the URL string.
| Query Parameter | Type | Description |
|---|---|---|
theme_id | string | The theme ID value, returned in the create theme response. |
redirect_to | string | Available values are carriers, billing, and onboarding. If onboarding is not complete, the customer will always be redirected to the Onboarding screen. Otherwise, if this parameter is not specified, the customer be redirected to the Carriers screen. If using onboarding as the value but onboarding is complete, the customer will be redirected to the Carriers page. |
Review our Customize the Onboarding Experience page for more details about creating a branded onboarding experience.
URLs are limited to 2000 characters in most browsers. The token and the root URL may take up to 700 characters, so your brand and return URL must total under 1300 characters.
Example:
https://dashboard.shipengine.com/api/directlogin?token=eyJ..&theme_id=550e8400-e29b-41d4-a716-446655440000Below you can find a series of screenshots for the onboarding default flow.
The following items can be customized in the onboarding experience for your customers using the Theme endpoint:
- Custom logo image
- Custom start title and message
- Custom complete title and messge
- Carriers available for your customers to connect (by country)
We may offer partners additional customization of the ShipStation API Carrier Portal for an additional fee as part of their contractual agreement. Below are some of the bespoke options available:
- Users subscribe to a ShipStation API billing plan
- Show additional discounted carriers
- User can access label branding
- User can access branded tracking page setup
- Whitelist/Blacklist Carriers
- Customer Chat Support