API Docs

Customer Portal

The Customer Portal enables platforms and marketplaces to direct sub accounts to a self-service interface for account_onboarding and account_management. This functionality is accessed using the account_link endpoint, which generates a secure, one-time-use session URL.

Endpoints
POST
/customer_portal/account_link

CustomerPortalAccountLink object

object
string
Always returns "CustomerPortalAccountLink".
link
string
One-time-use session URL for initiating the Customer Portal.
created_at
timestamp
One-time-use session URL for initiating the Customer Portal.
expires_at
timestamp
ISO 8601 timestamp when the link will expire (5 minutes from creation).
CustomerPortalAccountLink Object
{
  "object": "CustomerPortalAccountLink",
  "created_at": "2025-16-17T17:30:30Z",
  "expires_at": "2025-16-17T17:35:30Z",
  "link": "https://app.easypost.com/customer-portal/onboarding?session_id={SESSION_ID}"
}

Creating a Portal Session

This endpoint generates a one-time Customer Portal URL. The integrator must redirect the sub account user to this URL within the expiration window.

  • Production Key: Generates a live session URL.
  • Test API Key: Not currently supported.

Request Parameters

session_type
REQUIRED
enum

Type of Customer Portal session. Options include:

  • account_onboarding: Used to onboard a sub account.
  • account_management: Used to manage an existing sub account.
user_id
REQUIRED
string
The User ID of the sub account for which the portal session is being created.
refresh_url
REQUIRED
string
The URL to which the sub account will be redirected if the session URL is expired, reused, or otherwise invalid. This should trigger a new session request.
return_url
REQUIRED
string
The URL to which the sub account will be redirected after exiting the Customer Portal session. This does not confirm completion of the flow; webhook or API polling is recommended for confirmation.
metadata
object

Used to configure the Customer Portal session. Accepted values depend on the session_type:

  • account_onboarding: Use the fields object to pre-fill sub account information.
  • account_management: Use the target key to direct the user to a specific portal section. Accepted values include: account-settings (default), wallet, carriers, reports, branding, analytics, insurance.
POST /customer_portal/account_link
1curl -X POST https://api.easypost.com/v2/customer_portal/account_link \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "session_type": "account_management",
6    "user_id": "user_...",
7    "refresh_url": "https://example.com/refresh",
8    "return_url": "https://example.com/return",
9    "metadata": {"target": "wallet"}
10  }'
Response
1{
2  "object": "CustomerPortalAccountLink",
3  "created_at": "2025-16-17T17:30:30Z",
4  "expires_at": "2025-16-17T17:35:30Z",
5  "link": "https://app.easypost.com/customer-portal/onboarding?session_id={SESSION_ID}"
6}

Handling redirects

  • Refresh URL: Redirected here if the session link has expired or has already been used. Should trigger a new POST /customer_portal/account_link call.
  • Return URL: Redirected here when the session ends. Session outcome is not included; use webhooks or fetch account status via API.

Additional resources