> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partnero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer referrals

> Enable your customers to refer others and earn rewards

## Overview

Customer referrals allow your existing customers to become advocates for your product. Each customer gets a unique referral link they can share with friends.

## Setting Up Customer Referrals

### Step 1: Create a Referral Program

1. Go to **Programs → Create Program**
2. Select **Referral Program**
3. Configure basic settings

### Step 2: Define Rewards

Configure what customers earn for successful referrals:

<AccordionGroup>
  <Accordion title="Account Credits">
    Add credits to the customer's account balance.

    ```json theme={null}
    {
      "reward_type": "credit",
      "amount": 10,
      "currency": "USD"
    }
    ```
  </Accordion>

  <Accordion title="Discounts">
    Provide discount codes for future purchases.

    ```json theme={null}
    {
      "reward_type": "discount",
      "amount": 20,
      "unit": "percentage"
    }
    ```
  </Accordion>

  <Accordion title="Cash Rewards">
    Pay customers directly via PayPal or Wise.

    ```json theme={null}
    {
      "reward_type": "cash",
      "amount": 25,
      "currency": "USD"
    }
    ```
  </Accordion>
</AccordionGroup>

### Step 3: Set Triggers

Define when rewards are granted:

| Trigger          | Description                               |
| ---------------- | ----------------------------------------- |
| **signup**       | When referred friend creates an account   |
| **purchase**     | When referred friend makes first purchase |
| **subscription** | When referred friend subscribes           |

## Creating Customers

Customers are created when they sign up for your product. Sync them with Partnero:

### Automatic Sync (Recommended)

Use integrations to sync customers automatically:

* [Stripe Integration](/integrations/stripe)
* [WooCommerce Integration](/integrations/woocommerce)

### API Sync

Create customers via the API:

```bash theme={null}
curl -X POST https://api.partnero.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@partnero.com",
    "name": "Jane Doe",
    "key": "cust_123"
  }'
```

### JavaScript SDK

Create customers from your frontend:

```javascript theme={null}
po('createCustomer', {
  email: 'customer@partnero.com',
  name: 'Jane Doe',
  key: 'cust_123'
});
```

## Customer Referral Links

Each customer automatically receives a referral link:

```json theme={null}
{
  "customer": {
    "key": "cust_123",
    "referral_code": "JANE20",
    "referral_url": "https://yoursite.com/?ref=JANE20"
  }
}
```

### Get Customer's Referral Link

```bash theme={null}
curl -X GET https://api.partnero.com/v1/customers/cust_123/referral_links \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Create Custom Referral Link

```bash theme={null}
curl -X POST https://api.partnero.com/v1/customer_referral_links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_key": "cust_123",
    "destination_url": "https://yoursite.com/signup"
  }'
```

## Displaying Referral Info

### Get Customer Stats

Retrieve referral statistics to display in your app:

```bash theme={null}
curl -X GET https://api.partnero.com/v1/customers/cust_123/stats \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "total_referrals": 5,
  "successful_referrals": 3,
  "pending_referrals": 2,
  "total_rewards": 30.00,
  "currency": "USD"
}
```

### Get Customer Balance

```bash theme={null}
curl -X GET https://api.partnero.com/v1/customers/cust_123/balance \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "balance": 45.00,
  "currency": "USD",
  "pending": 10.00
}
```

## Embedding Referral Widgets

Add a referral widget to your customer dashboard:

```html theme={null}
<div id="referral-widget"></div>

<script>
  po('renderReferralWidget', {
    container: '#referral-widget',
    customer_key: 'cust_123',
    theme: 'light',
    show_stats: true
  });
</script>
```

## Managing Customers

### List Customers

```bash theme={null}
curl -X GET https://api.partnero.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Update Customer

```bash theme={null}
curl -X PUT https://api.partnero.com/v1/customers/cust_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "metadata": {"plan": "premium"}
  }'
```

### Credit Customer Balance

Add credits to a customer's account:

```bash theme={null}
curl -X POST https://api.partnero.com/v1/customers/cust_123/balance/credit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "currency": "USD",
    "note": "Referral bonus"
  }'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Refer-a-Friend" icon="user-group" href="/guides/referral-programs/refer-a-friend">
    Set up refer-a-friend campaigns
  </Card>

  <Card title="Customers API" icon="code" href="/api-reference/customers/list">
    Full customers API reference
  </Card>
</CardGroup>