How to Use EasyPost's Partner White Label

This guide will teach you how to use the Partner White Label API. We will show you how to create Referral Users and manage their billing. For Shipping API, Tracking API, Address Verification API, Shipping Insurance API, and more, use EasyPost's main API documentation.

This is also available in our client libraries.

This guide will help you use the EasyPost Partner White Label API. It will cover:

Before You Start

  1. Contact our Sales team to access this free API. Once you're a registered Partner, your EasyPost user account and API keys will be able to access the Partner API.
  2. Grab one of our official client libraries.
  3. Start using our Partner White Label API to manage your users' shipping and billing.

Creating & Managing Referral Users

Creating Referral Users

Production OnlyThis call will only work with your production API Key.

To create a Referral User, you must provide a name, email, and phone number. The API keys of the Referral User will be returned to you. Save the API keys securely as they will not be able to be retrieved again later.

NOTE: When a Referral User is created with your API key, you are certifying that the Referral User agrees to EasyPost Terms of Service.

Create a Referral User
curl -X POST "https://api.easypost.com/v2/referral_customers" \
  -u "<PARTNER_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
  "user": {
    "name": "Firstname Lastname",
    "email": "email@example.com",
    "phone_number": "8888888888"
  }
}'
Create a referral user JSON Response
{
  "id": "user_...",
  "object": "User",
  "parent_id": null,
  "created_at": "2022-02-03T00:38:06Z",
  "name": "Firstname Lastname",
  "email": "email@example.com",
  "phone_number": "8888888888",
  "verified": true,
  "balance": "0.00",
  "price_per_shipment": "0.0000",
  "recharge_amount": "100.00",
  "secondary_recharge_amount": "100.00",
  "recharge_threshold": "25.00",
  "has_billing_method": false,
  "cc_fee_rate": "0.03",
  "default_insurance_amount": null,
  "insurance_fee_rate": "0.005",
  "insurance_fee_minimum": "0.50",
  "children": [],
  "api_keys": [
    {
      "object": "ApiKey",
      "key": "...",
      "mode": "test",
      "created_at": "2022-02-03T00:38:06Z"
    },
    {
      "object": "ApiKey",
      "key": "...",
      "mode": "production",
      "created_at": "2022-02-03T00:38:06Z"
    }
  ]
}

Updating Referral Users' Emails

Production OnlyThis call will only work with your production API Key.

Partners are obligated to provide us with up-to-date Referral Customer emails. EasyPost does not plan to contact your customers; this information is for security purposes only.

Update a Referral User email
curl -X PUT "https://api.easypost.com/v2/referral_customers" \
  -u "<REFERRAL_USER_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
  "user": {
  "email": "email@example.com"
  }
}'
Update a referral user email JSON Response
{
  "message": "Email updated successfully"
}

Adding Billing Information

Production OnlyThis call will only work with your production API Key.

Our Partner White Label API only supports credit cards at the moment. Please let us know if you are interested in bank account support.

EasyPost allows each user to have one primary payment method and one secondary payment method. We highly recommend adding a secondary payment method to avoid interruptions.

Once a payment method has been added, EasyPost will automatically charge users their recharge_amount if their wallet balance is below their recharge_threshold. As a whitelabel partner of EasyPost, you should make every effort to educate users about how billing works with our recharge threshold and recharge amount system.

Billing setup steps:
  1. Attach a credit card to a Referral User (when using one of our client libraries, all of the following sub-steps will be handled on your behalf)
    1. Retrieve EasyPost's Stripe public key
    2. Submit above key and the Referral User's credit card info to Stripe to get a credit card token
    3. Using the Referral User's API key, submit the token from Stripe to EasyPost to attach the payment method to the user.
  2. Allow Referral Users to configure their recharge_amount and recharge_threshold
  3. (Optional) Allow Referral Users to add an initial deposit to the EasyPost wallet

Step 1a: Retrieve EasyPost's Stripe Public API Key

Please retrieve EasyPost's Stripe Public API key every time you need to create a new payment method, as we may rotate the key for security at any time.

Retrieve EasyPost's Stripe Public API Key
curl -X GET "https://api.easypost.com/v2/partners/stripe_public_key" \
  -u "<PARTNER_API_KEY>:"
Retrieve EasyPost's Stripe Public API Key JSON Response
{
  "public_key": "pk_..."
}

Step 1b: Get Token From Stripe

Use Stripe's JS library to create a token for the Referral User.

See Stripe JS documentation:
  1. Initializing
  2. Create Token
stripe = Stripe(<EP_STRIPE_PUBLIC_KEY>);
elements = stripe.elements();
cardElement = elements.create('card');
stripe.createToken(cardElement).then(function(result) {
  // handle result.token, "tok_1KPY4R2eZvKYlo2CGavzwUZv" for next step
});

See complete example

Step 1c: Submit Stripe Token to EasyPost

Submit Stripe Token to EasyPost
curl -X POST "https://api.easypost.com/v2/credit_cards" \
  -u "<REFERRAL_USER_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
  "credit_card": {
    "stripe_object_id": "tok_...",
    "priority": "primary"
  }
}'
Submit Stripe Token to EasyPost JSON Response
{
  "id": "card_...",
  "object": "CreditCard",
  "name": null,
  "last4": "1234",
  "exp_month": 1,
  "exp_year": 2025,
  "brand": "Visa"
}

Step 2: Configure Recharge Threshold and Recharge Amount

At this point, you've attached a credit card to a Referral User. You should educate the Referral Users about the recharge threshold and recharge amount system and allow them to configure their desired recharge threshold and recharge amount.

Configuring a recharge_threshold and recharge_amount is as simple as updating an email in the previous section.

Configure Recharge Threshold and Recharge Amount
curl -X PUT "https://api.easypost.com/v2/users" \
  -u "<REFERRAL_USER_API_KEY>:" \
  -H "Content-Type: application/json" \
  -d '{
  "recharge_amount": "100.00",
  "secondary_recharge_amount": "50.00",
  "recharge_threshold": "25.00",
}'
Configure Recharge Threshold and Recharge Amount JSON Response
{
  "id": "user_qqUy4rWef",
  "object": "User",
  "parent_id": null,
  "created_at": "2018-03-03T00:38:06Z",
  "name": "Update Me",
  "email": "c.vader@example.com",
  "phone_number": "555-123-4321",
  "verified": true,
  "balance": "1234.99000",
  "price_per_shipment": 0.05,
  "recharge_amount": "50.00",
  "secondary_recharge_amount": "250.00",
  "recharge_threshold": "100.00",
  "cc_fee_rate": "0.03",
  "insurance_fee_rate": "0.005",
  "insurance_fee_minimum": "0.50",
  "children": []
}

[Optional] Step 3: Fund a Wallet ("One Time Charge")

You can optionally allow users to deposit an initial sum of money into their EasyPost wallet so users can start shipping right away. Provide the amount in cents to be deposited into the user's wallet.

Fund your EasyPost wallet
# Fund wallet by using credit card payment method
curl -X POST https://api.easypost.com/v2/credit_cards/card_.../charges \
  -u "$EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": "2000"
}'

# Fund wallet by using bank account payment method
curl -X POST https://api.easypost.com/v2/bank_accounts/bank_.../charges \
  -u "$EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": "2000"
}'
Fund your EasyPost wallet JSON Response
{}