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 cover:

Before You Start

  1. You must contact our Sales team to access the free Partner White Label API. Once you're a registered Partner, your EasyPost user account and API keys will be able to access the Partner API.

    Note: After you register as a partner, our experienced Account Management Team will work with you to determine the optimal Partner integration method for attaching payment methods to your referral Users between direct credit card and Stripe Connect based on what best meets your needs.
  2. Once the Partner integration method is determined, our Account Management Team will configure your account with the correct settings to ensure the proper payment method is attached to your referral Users.
  3. Once you have registered as a Partner and configured your integration method, be sure to access one of our official client libraries.

If you haven't run through our Getting Started Guide, definitely do that before moving on to this one.


Creating & Managing ReferralCustomers

Creating ReferralCustomers

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 ReferralCustomer is created with your API key, you are certifying that the ReferralCustomer agrees to EasyPost Terms of Service.

Create a ReferralCustomer

POST /referral_customers
1curl -X POST https://api.easypost.com/v2/referral_customers \
2  -u "$PARTNER_API_KEY": \
3  -H "Content-Type: application/json" \
4  -d '{
5      "user": {
6        "name": "Firstname Lastname",
7        "email": "email@example.com",
8        "phone_number": "8888888888"
9      }
10  }'

Updating ReferralCustomers' Emails

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

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

Update a ReferralCustomer email

PUT /referral_customers
1curl -X PUT https://api.easypost.com/v2/referral_customers \
2  -u "$REFERRAL_USER_API_KEY": \
3  -H "Content-Type: application/json" \
4  -d '{
5      "user": {
6        "email": "new_email@example.com"
7      }
8  }'

Adding Billing Information

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

EasyPost allows each referral 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 partner of EasyPost, you should make every effort to educate referral users about how billing works with our recharge threshold and recharge amount system.

Billing setup steps:

  1. Create and attach Payment Methods to referral Users. EasyPost supports two methods of adding billing methods for referral Users. You can only choose one of the options below depending on the payment methods types to support. If you have already built an integration into one option but would like to migrate to a new option, a new EasyPost account must be created.

    1. Stripe Connect integration (supports credit cards and bank accounts)
    2. Direct credit card integration (only works for credit cards)
  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 1: Create and Attach Payment Methods to ReferralCustomers

There are two options to create and attach Payment Methods to referral Users. Option A "Stripe Connect integration" is recommended because it supports both credit cards and bank accounts, while Option B "Direct credit card integration" only supports credit cards. Option B is a quicker path if only credit card billing will be supported for your referral Users.

OPTION A: STRIPE CONNECT INTEGRATION

Follow the steps below to add bank accounts and credit cards to referral Users via the Stripe Connect integration.

Summarized steps are listed below for Option A.

  1. Create/link Stripe account to EasyPost
  2. Use Stripe to create customers, bank accounts, and credit cards
  3. Submit Stripe information to EasyPost

Option A.1: Create/Link Stripe Account to EasyPost

Use this link to create or connect your existing Stripe account to EasyPost.

Option A.2: Use Stripe to create customers, bank accounts, and credit cards

Using your new Stripe account, create Customers and use the Sources API to create bank accounts and credit cards.

Option A.3: Submit Stripe information to EasyPost

Submit Stripe information to EasyPost

POST /beta/referral_customers/payment_method
1curl -X POST https://api.easypost.com/beta/referral_customers/payment_method \
2  -u "$REFERRAL_USER_API_KEY": \
3  -H "Content-Type: application/json" \
4  -d '{
5      "payment_method": {
6        "stripe_customer_id": "cus_...",
7        "payment_method_reference": "card_...",
8        "priority": "primary"
9      }
10  }'

OPTION B: DIRECT CREDIT CARD INTEGRATION

Follow the steps below to attach a credit card to a referral User via a direct credit card integration. When using one of our client libraries, all of the following sub-steps will be handled on your behalf.

Summarized steps are listed below for Option A.

  1. Retrieve EasyPost's Stripe public API 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 referral User.

Option B.1: 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

GET /partners/stripe_public_key
1curl -X GET https://api.easypost.com/v2/partners/stripe_public_key \
2  -u "$PARTNER_API_KEY:"

Option B.2: Get Token From Stripe

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

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

Option B.3: Submit Stripe Token to EasyPost

Submit Stripe Token to EasyPost

POST /credit_cards
1curl -X POST "https://api.easypost.com/v2/credit_cards" \
2  -u "<REFERRAL_USER_API_KEY>:" \
3  -H "Content-Type: application/json" \
4  -d '{
5  "credit_card": {
6    "stripe_object_id": "tok_...",
7    "priority": "primary"
8  }
9}'

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

PUT /users
1curl -X PUT "https://api.easypost.com/v2/users" \
2  -u "<REFERRAL_USER_API_KEY>:" \
3  -H "Content-Type: application/json" \
4  -d '{
5  "recharge_amount": "100.00",
6  "secondary_recharge_amount": "50.00",
7  "recharge_threshold": "25.00",
8}'

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

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

Fund your EasyPost wallet

POST /credit_cards/:id/charges POST /bank_accounts/:id/charges
1# Fund wallet by using credit card payment method
2curl -X POST https://api.easypost.com/v2/credit_cards/card_.../charges \
3  -u "$EASYPOST_API_KEY": \
4  -H 'Content-Type: application/json' \
5  -d '{
6  "amount": "2000"
7}'
8
9# Fund wallet by using bank account payment method
10curl -X POST https://api.easypost.com/v2/bank_accounts/bank_.../charges \
11  -u "$EASYPOST_API_KEY": \
12  -H 'Content-Type: application/json' \
13  -d '{
14  "amount": "2000"
15}'