# 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 `User`accounts. If you feel this is applicable for your use case,
  please contact sales.

---

**Production Only**

## Create a ReferralCustomer

### Example: POST /referral_customers

#### cURL

```shell
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"
      }
  }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func create() {
	client := easypost.New("EASYPOST_API_KEY")

	name := "Test Referral"
	email := "test@example.com"
	phone := "5555555555"

	referralUser, _ := client.CreateReferralCustomer(
		&easypost.UserOptions{
			Name:  &name,
			Email: &email,
			Phone: &phone,
		},
	)

	fmt.Println(referralUser)
}
```

#### Java

```java
package referral;

import com.easypost.exception.EasyPostException;
import com.easypost.model.ReferralCustomer;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<>();

        params.put("name", "test test");
        params.put("email", "test@test.com");
        params.put("phone", "8888888888");

        ReferralCustomer referralUser = client.referralCustomer.create(params);

        System.out.println(referralUser);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.ReferralCustomer.Create parameters = new()
            {
                Name = "test user",
                Email = "email@example.com",
                Phone = "8888888888"
            };

            EasyPost.Models.API.ReferralCustomer referralUser = await client.ReferralCustomer.CreateReferral(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(referralUser, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const referralCustomer = await client.ReferralCustomer.create({
    name: 'Test Referral',
    email: 'test@example.com',
    phone: '1111111111',
  });

  console.log(referralCustomer);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$referralUser = $client->referralCustomer->create([
    'name' => 'Test Referral',
    'email' => 'test@test.com',
    'phone' => '8888888888'
]);

echo $referralUser;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

referral_user = client.referral_customer.create(
    name="test test",
    email="test@test.com",
    phone="8888888888",
)

print(referral_user)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

referral_user = client.referral_customer.create(
  name: 'test user',
  email: 'email@example.com',
  phone: '8888888888',
)

puts referral_user
```

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.

[Note: This object is immutable after creation. Review the rendered documentation for details.]

---

**Production Only**

## Add Payment Method to ReferralCustomer

### Example: POST /beta/referral_customers/payment_method

#### cURL

```shell
curl -X POST https://api.easypost.com/beta/referral_customers/payment_method \
  -u "$REFERRAL_USER_API_KEY": \
  -H "Content-Type: application/json" \
  -d '{
      "payment_method": {
        "stripe_customer_id": "cus_...",
        "payment_method_reference": "card_...",
        "priority": "primary"
      }
  }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func addPaymentMethodWithCreditCard() {
	client := easypost.New("EASYPOST_API_KEY")

	paymentMethod, _ := client.BetaAddPaymentMethod("cus_...", "card_...", easypost.PrimaryPaymentMethodPriority)

	fmt.Println(paymentMethod)
}
```

#### Java

```java
package referral;

import com.easypost.exception.EasyPostException;
import com.easypost.model.PaymentMethodObject;
import com.easypost.service.EasyPostClient;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        PaymentMethodObject paymentMethod = client.betaReferralCustomer.addPaymentMethod("cus_...", "card_...");

        System.out.println(paymentMethod);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Models.API.PaymentMethod paymentMethod = await client.Beta.ReferralCustomer.AddPaymentMethod("cus_...", "card_...", PaymentMethod.Priority.Primary);

            Console.WriteLine(JsonConvert.SerializeObject(paymentMethod, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const paymentMethod = await client.BetaReferralCustomer.addPaymentMethod('cus_...', 'card_...');

  console.log(paymentMethod);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$paymentMethod = $client->betaReferralCustomer->addPaymentMethod([
    'cus_...',
    'card_...',
    'primary'
]);

echo $paymentMethod;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

payment_method = client.beta_referral_customer.add_payment_method(
    stripe_customer_id="cus_...",
    payment_method_reference="card_...",
    primary_or_secondary="primary",
)

print(payment_method)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

payment_method = client.beta_referral_customer.add_payment_method(
  'cus_...',
  'card_...',
  'primary',
)

puts payment_method
```

  **Important**: This endpoint only works for `ReferralCustomers` or to
  manage Child `User`accounts. 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, Contact Support.

Add a payment method for a `ReferralCustomer`.

This endpoint is only used if you are using the Forge Decentralized integration.
Both a "primary" and "secondary" payment method can be set.

### Add Payment With Bank Account

### Example: Bank Account Payment Method

#### cURL

```shell
curl -X POST https://api.easypost.com/beta/referral_customers/payment_method \
  -u "$REFERRAL_USER_API_KEY": \
  -H "Content-Type: application/json" \
  -d '{
      "payment_method": {
        "stripe_customer_id": "cus_...",
        "payment_method_reference": "ba_...",
        "priority": "primary"
      }
  }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func addPaymentMethodWithBankAccount() {
	client := easypost.New("EASYPOST_API_KEY")

	paymentMethod, _ := client.BetaAddPaymentMethod("cus_...", "ba_...", easypost.PrimaryPaymentMethodPriority)

	fmt.Println(paymentMethod)
}
```

#### Java

```java
package referral;

import com.easypost.exception.EasyPostException;
import com.easypost.model.PaymentMethodObject;
import com.easypost.service.EasyPostClient;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        PaymentMethodObject paymentMethod = client.betaReferralCustomer.addPaymentMethod("cus_...", "ba_...");

        System.out.println(paymentMethod);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Models.API.PaymentMethod paymentMethod = await client.Beta.ReferralCustomer.AddPaymentMethod("cus_...", "ba_...", PaymentMethod.Priority.Primary);

            Console.WriteLine(JsonConvert.SerializeObject(paymentMethod, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const paymentMethod = await client.BetaReferralCustomer.addPaymentMethod('cus_...', 'ba_...');

  console.log(paymentMethod);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$paymentMethod = $client->betaReferralCustomer->addPaymentMethod([
    'cus_...',
    'ba_...',
    'primary'
]);

echo $paymentMethod;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

payment_method = client.beta_referral_customer.add_payment_method(
    stripe_customer_id="cus_...",
    payment_method_reference="ba_...",
    primary_or_secondary="primary",
)

print(payment_method)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

payment_method = client.beta_referral_customer.add_payment_method(
  'cus_...',
  'ba_...',
  'primary',
)

puts payment_method
```

---

**Production Only**

## Refund a ReferralCustomer

### Example: POST /beta/referral_customers/refunds

#### cURL

```shell
curl -x POST https://api.easypost.com/beta/referral_customers/refunds \
  -u "$REFERRAL_USER_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
        "refund_amount": 2000,
      }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func refundByAmount() {
	client := easypost.New("EASYPOST_API_KEY")

	refund, _ := client.BetaRefundByAmount(2000)

	fmt.Println(refund)
}
```

#### Java

```java
package referral;

import com.easypost.exception.EasyPostException;
import com.easypost.model.BetaPaymentRefund;
import com.easypost.service.EasyPostClient;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        BetaPaymentRefund refund = client.betaReferralCustomer.refundByAmount(2000);

        System.out.println(refund);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.ReferralCustomer.RefundByAmount parameters = new()
            {
                Amount = 2000,
            };

            EasyPost.Models.API.PaymentRefund refund = await client.Beta.ReferralCustomer.RefundByAmount(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(refund, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const refund = await client.BetaReferralCustomer.refundByAmount(2000);

  console.log(refund);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$refund = $client->betaReferralCustomer->refundByAmount(2000);

echo $refund;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

refund = client.beta_referral_customer.refund_by_amount(refund_amount=2000)

print(refund)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

refund = client.beta_referral_customer.refund_by_amount(2000)

puts refund
```

  **Important**: This endpoint only works for `ReferralCustomers` or to
  manage Child `User`accounts. 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, Contact Support.

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.

Contact Support for additional assistance.

### Refund by Payment Log

### Example: Payment Log

#### cURL

```shell
curl -x POST https://api.easypost.com/beta/referral_customers/refunds \
  -u "$REFERRAL_USER_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
        "payment_log_id": "paylog..."
      }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func refundByPaymentLog() {
	client := easypost.New("EASYPOST_API_KEY")

	refund, _ := client.BetaRefundByPaymentLog("paylog_...")

	fmt.Println(refund)
}
```

#### Java

```java
package referral;

import com.easypost.exception.EasyPostException;
import com.easypost.model.BetaPaymentRefund;
import com.easypost.service.EasyPostClient;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        BetaPaymentRefund refund = client.betaReferralCustomer.refundByAmount(2000);

        System.out.println(refund);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.ReferralCustomer.RefundByPaymentLog parameters = new()
            {
                PaymentLogId = "paylog_...",
            };

            EasyPost.Models.API.PaymentRefund refund = await client.Beta.ReferralCustomer.RefundByPaymentLog(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(refund, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const refund = await client.BetaReferralCustomer.refundByPaymentLog('paylog_...');

  console.log(refund);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$refund = $client->betaReferralCustomer->refundByPaymentLog('paylog_...');

echo $refund;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

refund = client.beta_referral_customer.refund_by_payment_log(payment_log_id="paylog_...")

print(refund)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

refund = client.beta_referral_customer.refund_by_payment_log('paylog_...')

puts refund
```

---

**Production Only**

## Retrieve all ReferralCustomers

### Example: GET /referral_customers

#### cURL

```shell
curl -X GET https://api.easypost.com/v2/referral_customers \
  -u "$PARTNER_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func list() {
	client := easypost.New("EASYPOST_API_KEY")

	referralCustomerCollection, _ := client.ListReferralCustomers(
		&easypost.ListOptions{
			PageSize: 5,
		},
	)

	fmt.Println(referralCustomerCollection)
}
```

#### Java

```java
package referral;

import com.easypost.exception.EasyPostException;
import com.easypost.model.ReferralCustomer;
import com.easypost.model.ReferralCustomerCollection;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;
import java.util.List;

public class All {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<String, Object>();

        params.put("page_size", 5);

        ReferralCustomerCollection referallCustomorCollection = client.referralCustomer.all(params);

        List<ReferralCustomer> referallUsers = referallCustomorCollection.getReferralCustomers();

        System.out.println(referallUsers);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.ReferralCustomer.All parameters = new()
            {
                PageSize = 5
            };

            EasyPost.Models.API.ReferralCustomerCollection referralCustomerCollection = await client.ReferralCustomer.All(parameters);

            List<EasyPost.Models.API.ReferralCustomer> referralCustomers = referralCustomerCollection.ReferralCustomers;

            Console.WriteLine(JsonConvert.SerializeObject(referralCustomers, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const referralCustomers = await client.ReferralCustomer.all({
    page_size: 5,
  });

  console.log(referralCustomers);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$referralUsers = $client->referralCustomer->all([
    'page_size' => 5,
]);

echo $referralUsers;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

referral_users = client.referral_customer.all(page_size=5)

print(referral_users)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

referral_users = client.referral_customer.all(
  page_size: 5,
)

puts referral_users
```

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.

---

**Production Only**

## Update a ReferralCustomer

### Example: PUT /referral_customers/:id

#### cURL

```shell
curl -X PUT https://api.easypost.com/v2/referral_customers \
  -u "$REFERRAL_USER_API_KEY": \
  -H "Content-Type: application/json" \
  -d '{
      "user": {
        "email": "new_email@example.com"
      }
  }'
```

#### Go

```go
package example

import (
	"github.com/EasyPost/easypost-go/v5"
)

func update() {
	client := easypost.New("EASYPOST_API_KEY")

	_, _ = client.UpdateReferralCustomerEmail("user_...", "new_email@example.com")
}
```

#### Java

```java
package referral;

import com.easypost.exception.EasyPostException;
import com.easypost.service.EasyPostClient;

public class Update {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        client.referralCustomer.updateEmail("user_...", "new_email@example.com");
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            await client.ReferralCustomer.UpdateReferralEmail("user_...", "new_email@example.com");
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  await client.ReferralCustomer.updateEmail('user_...', 'new_email@example.com');
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$client->referralCustomer->updateEmail('user_...', 'new_email@example.com');
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

client.referral_customer.update_email(
    "usr_...",
    "new_email@example.com",
)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

message = client.referral_customer.update_email(
  'user_...',
  'new_email@example.com',
)

puts message
```

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.