ReferralCustomer

A ReferralCustomer is a white label User that can have its own billing methods.

Important: This endpoint only works for ReferralCustomers or to manage Child Useraccounts. If you feel this is applicable for your use case, please contact sales.


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

Create a ReferralCustomer

Use the ReferralCustomers endpoint to create a white label User.

To create a ReferralCustomer, you must provide a name, email, and phone number. The API keys of the ReferralCustomer will be returned to you. Save these 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.

A ReferralCustomer object is immutable once created. All information must be provided during creation; it cannot be modified later.

Request Parameters

name
i.e. Firstname Lastname
email
i.e. support@easypost.com
phone
i.e. 415-123-4567
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  }'
Response
1{
2  "id": "user_50d792728c504bd4a34642ecdfd915b2",
3  "object": "User",
4  "parent_id": null,
5  "name": "test test",
6  "phone_number": "8888888888",
7  "verified": true,
8  "created_at": "2024-01-24T00:07:18Z",
9  "default_carbon_offset": false,
10  "has_elevate_access": false,
11  "balance": "0.00000",
12  "price_per_shipment": "0.00000",
13  "recharge_amount": null,
14  "secondary_recharge_amount": null,
15  "recharge_threshold": null,
16  "has_billing_method": null,
17  "cc_fee_rate": "0.0375",
18  "default_insurance_amount": "50.00",
19  "insurance_fee_rate": "0.005",
20  "insurance_fee_minimum": "0.25",
21  "email": "referral_customer_50f0324e81a94c4baa5bcc8644624e34@donotemail.easypost.com",
22  "children": [],
23  "api_keys": [
24    {
25      "object": "ApiKey",
26      "key": "<REDACTED>",
27      "mode": "test",
28      "created_at": "2024-01-24T00:07:19Z",
29      "active": true,
30      "id": "ak_b5aad6a37ee9493fb3af53e2e7dbbbd8"
31    },
32    {
33      "object": "ApiKey",
34      "key": "<REDACTED>",
35      "mode": "production",
36      "created_at": "2024-01-24T00:07:19Z",
37      "active": true,
38      "id": "ak_af20f85584744cf79933aae294ba59ba"
39    }
40  ]
41}

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

Add Payment Method to ReferralCustomer

Important: This endpoint only works for ReferralCustomers or to manage Child Useraccounts. If you feel this is applicable for your use case, please contact sales.

BETA: This feature is in beta and subject to change. For feedback or questions, please contact our Support team.

Add a payment method for a ReferralCustomer.

This endpoint is only used if you are using the Stripe Connect integration for the Partner White Label API. Both a "primary" and "secondary" payment method can be set.

Request Parameters

stripe_customer_id
i.e. cus_...
Unique customer ID provided by Stripe
payment_method_reference
i.e. card_...
ID of the card or bank account provided by Stripe
priority
i.e. primary

Priority of the payment method in EasyPost. Possible values:

  • primary
  • secondary
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  }'
Response
1{
2  "id": "card_...",
3  "disabled_at": null,
4  "object": "CreditCard",
5  "name": null,
6  "last4": "1234",
7  "exp_month": 7,
8  "exp_year": 2024,
9  "brand": "MasterCard"
10}

Add Payment With Bank Account

Bank Account 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": "ba_...",
8        "priority": "primary"
9      }
10  }'
Response
1{
2  "id": "ba_...",
3  "disabled_at": null,
4  "object": "BankAccount",
5  "bank_name": "WELLS FARGO",
6  "last4": "1234",
7  "country": "US"
8}

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

Refund a ReferralCustomer

Important: This endpoint only works for ReferralCustomers or to manage Child Useraccounts. If you feel this is applicable for your use case, please contact sales.

BETA: This feature is in beta and subject to change. For feedback or questions, please contact our Support team.

For partners integrated with Stripe Connect, a ReferralCustomer's EasyPost wallet balance can be refunded back to a payment method when necessary. An example use case is if a ReferralCustomer accidentally added too many funds in their wallet.

There are two ways to specify a refund. A refund can be specified by payment_log, which will refund the amount to the original payment method of that payment_log. A refund can also be specified for a specific amount, which will refund a ReferralCustomer using the most recent payment logs back to their original payment method. For both options, refunds are limited to charges within the last 90 days.

Please contact our Support team for additional assistance.

Request Parameters

payment_log_id
i.e. paylog_...
A previously created EasyPost charge payment_log_id to refund back to the ReferralCustomer's original payment method
refund_amount
i.e. 2000
Amount, in cents, to be refunded from the ReferralCustomer's wallet. Amount must be less than or equal to the ReferralCustomer's current balance.
POST /beta/referral_customers/refunds
1curl -x POST https://api.easypost.com/beta/referral_customers/refunds \
2  -u "$REFERRAL_USER_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5        "refund_amount": 2000,
6      }'
Response
1{
2  "refunded_amount": 2000,
3  "payment_log_id": "paylog_...",
4  "refunded_payment_logs": ["paylog...", "paylog..."],
5  "errors": []
6}

Refund by Payment Log

Payment Log
1curl -x POST https://api.easypost.com/beta/referral_customers/refunds \
2  -u "$REFERRAL_USER_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5        "payment_log_id": "paylog..."
6      }'
Response
1{
2  "refunded_amount": 2000,
3  "payment_log_id": "paylog_...",
4  "refunded_payment_logs": ["paylog...", "paylog..."],
5  "errors": []
6}

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

Retrieve all ReferralCustomers

A list of all ReferralCustomer objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

before_id
i.e. user_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. user_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
page_size
i.e. 30
The number of records to return on each page. The maximum value is 100, and default is 10.
GET /referral_customers
1curl -X GET https://api.easypost.com/v2/referral_customers \
2  -u "$PARTNER_API_KEY":
Response
1{
2  "has_more": true,
3  "referral_customers": [
4    {
5      "id": "user_634b6daa05744bfaa205058f06864363",
6      "object": "User",
7      "parent_id": null,
8      "name": "Firstname Lastname",
9      "phone_number": "8888888888",
10      "verified": true,
11      "created_at": "2022-04-26T15:50:28Z",
12      "default_carbon_offset": false,
13      "has_elevate_access": false,
14      "balance": "0.00000",
15      "price_per_shipment": "0.00000",
16      "recharge_amount": null,
17      "secondary_recharge_amount": null,
18      "recharge_threshold": null,
19      "has_billing_method": null,
20      "cc_fee_rate": "0.0325",
21      "default_insurance_amount": "50.00",
22      "insurance_fee_rate": "0.005",
23      "insurance_fee_minimum": "0.25",
24      "email": "email@example.com",
25      "children": []
26    }
27  ]
28}

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

Update a ReferralCustomer

Partners have the ability to update the email address of a ReferralCustomer. Partners are obligated to provide us with an up-to-date email for each ReferralCustomer. EasyPost will not contact your customers; this information is used for security purposes only.

PUT /referral_customers/:id
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  }'
Response
1{
2  "message": "Referral Customer email updated successfully"
3}