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.
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
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 }'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.
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
Priority of the payment method in EasyPost. Possible values:
- primary
- secondary
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 }'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}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 }'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.
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 to refund back to the ReferralCustomer's original payment methodReferralCustomer's wallet. Amount must be less than or equal to the ReferralCustomer's current balance.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 }'1{
2 "refunded_amount": 2000,
3 "payment_log_id": "paylog_...",
4 "refunded_payment_logs": ["paylog...", "paylog..."],
5 "errors": []
6}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 }'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.
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
after_id.before_id.1curl -X GET "https://api.easypost.com/v2/referral_customers" \
2 -u "$PARTNER_API_KEY":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.
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.
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 }'1{
2 "message": "Referral Customer email updated successfully"
3}