> ## 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.

# Referral customers

> Create and manage customers in refer-a-friend programs

In refer-a-friend programs, customers are either **referring** (sharing links) or **referred** (signed up via a referral link). All customer endpoints use the same `/v1/customers` URL as affiliate programs, but the request and response fields differ.

## Create customer

```
POST https://api.partnero.com/v1/customers
```

### Request body

| Parameter                | Type   | Required | Description                                                 |
| ------------------------ | ------ | -------- | ----------------------------------------------------------- |
| `key`                    | string | No       | Unique customer identifier (auto-generated if not provided) |
| `id`                     | string | No       | Alternative customer identifier                             |
| `email`                  | string | No       | Customer's email address                                    |
| `name`                   | string | No       | Customer's first name                                       |
| `surname`                | string | No       | Customer's last name                                        |
| `metadata.date_of_birth` | date   | No       | Customer's date of birth                                    |
| `referring_customer.key` | string | No\*     | Referring customer's key (from `partnero_referral` cookie)  |
| `referring_customer.id`  | string | No\*     | Referring customer's ID                                     |

\*Provide at least one `referring_customer` field to attribute the new customer to a referrer.

### Request

<Tabs>
  <Tab title="Referring customer">
    Create a customer who will share referral links:

    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/customers' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "key": "customer_123",
        "name": "Alice",
        "surname": "Brown",
        "email": "alice.brown@example.com"
      }'
    ```
  </Tab>

  <Tab title="Referred customer">
    Create a customer who signed up via a referral link:

    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/customers' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "referring_customer": {
          "key": "customer_123"
        },
        "key": "customer_456",
        "name": "Bob",
        "surname": "Green",
        "email": "bob.green@example.com"
      }'
    ```
  </Tab>
</Tabs>

### Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "email": "alice.brown@example.com",
      "created_at": "2025-05-09T17:42:13.000000Z",
      "updated_at": "2025-05-09T17:42:13.000000Z",
      "id": "customer_123",
      "name": "Alice",
      "surname": "Brown",
      "approved": true,
      "status": "active",
      "referring_customer": null,
      "referrals_count": 0,
      "metadata": {
        "date_of_birth": null
      },
      "referral_link": "https://yoursite.com?ref=customer_123",
      "referral_links": ["https://yoursite.com?ref=customer_123"],
      "custom_fields": {}
    },
    "status": 1
  }
  ```
</ResponseExample>

### Response fields

<Accordion title="Customer — data">
  | Field                | Type         | Description                                   |
  | -------------------- | ------------ | --------------------------------------------- |
  | `id`                 | string       | Customer identifier                           |
  | `email`              | string       | Customer's email address                      |
  | `name`               | string       | Customer's first name                         |
  | `surname`            | string       | Customer's last name                          |
  | `status`             | string       | Customer status (`active`, `deleted`)         |
  | `approved`           | boolean      | Whether the customer is approved              |
  | `referring_customer` | object\|null | The customer who referred this person         |
  | `referrals_count`    | integer      | Number of customers referred by this customer |
  | `metadata`           | object       | Customer metadata (e.g., `date_of_birth`)     |
  | `referral_link`      | string       | Default referral link                         |
  | `referral_links`     | array        | All referral links for this customer          |
  | `custom_fields`      | object       | Custom signup field values                    |
  | `created_at`         | string       | ISO 8601 timestamp                            |
  | `updated_at`         | string       | ISO 8601 timestamp                            |
</Accordion>

## List customers

```
GET https://api.partnero.com/v1/customers
```

| Parameter      | Type    | Default | Description                          |
| -------------- | ------- | ------- | ------------------------------------ |
| `limit`        | integer | 15      | Results per page (1–250)             |
| `page`         | integer | 1       | Page number                          |
| `refer_status` | string  | —       | Filter: `referred` or `non_referred` |

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers?refer_status=referred' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Get customer

```
GET https://api.partnero.com/v1/customers/{id}
```

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers/customer_123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Update customer

```
PUT https://api.partnero.com/v1/customers/{id}
```

| Parameter                       | Type   | Required | Description                        |
| ------------------------------- | ------ | -------- | ---------------------------------- |
| `update`                        | object | Yes      | Object containing fields to update |
| `update.email`                  | string | No       | New email address                  |
| `update.name`                   | string | No       | Customer's first name              |
| `update.surname`                | string | No       | Customer's last name               |
| `update.key`                    | string | No       | New customer key                   |
| `update.metadata.date_of_birth` | date   | No       | Customer's date of birth           |

```bash cURL theme={null}
curl --location --request PUT 'https://api.partnero.com/v1/customers/customer_123' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "update": {
      "name": "Amanda",
      "metadata": {
        "date_of_birth": "1990-01-15"
      }
    }
  }'
```

## Delete customer

```
DELETE https://api.partnero.com/v1/customers/{id}
```

<Warning>
  Deleting a customer is permanent. Consider using archive instead.
</Warning>

```bash cURL theme={null}
curl --location --request DELETE 'https://api.partnero.com/v1/customers/customer_123' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Archive customer

```
POST https://api.partnero.com/v1/customers/{id}/archive
```

Soft-deletes a customer. They can be restored later.

```bash cURL theme={null}
curl --location --request POST 'https://api.partnero.com/v1/customers/customer_123/archive' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Restore customer

```
POST https://api.partnero.com/v1/customers/{id}/revoke-archive
```

Restores a previously archived customer back to active status.

```bash cURL theme={null}
curl --location --request POST 'https://api.partnero.com/v1/customers/customer_123/revoke-archive' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Invite a customer

```
POST https://api.partnero.com/v1/customers:invite
```

Send an invitation email to a potential customer.

| Parameter         | Type   | Required | Description                                      |
| ----------------- | ------ | -------- | ------------------------------------------------ |
| `email`           | string | Yes      | Customer's email address                         |
| `name`            | string | No       | Customer's name                                  |
| `personalization` | object | No       | Custom personalization data for the invite email |

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers:invite' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "jane.smith@example.com",
    "name": "Jane"
  }'
```

## Search customers

```
GET https://api.partnero.com/v1/customers:search
```

| Parameter | Type   | Description              |
| --------- | ------ | ------------------------ |
| `key`     | string | Customer key             |
| `id`      | string | Customer ID              |
| `email`   | string | Customer's email address |

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers:search?email=alice@example.com' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Get customer stats

```
GET https://api.partnero.com/v1/customers/{id}/stats
```

Returns referral statistics, click counts, and social share links for a customer.

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers/customer_123/stats' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Get customer referrals

```
GET https://api.partnero.com/v1/customers/{id}/referrals
```

Returns all customers referred by this customer.

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers/customer_123/referrals' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Get customer transactions

```
GET https://api.partnero.com/v1/customers/{id}/transactions
```

Returns all transactions made by customers referred by this customer.

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers/customer_123/transactions' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Get customer balance

```
GET https://api.partnero.com/v1/customers/{id}/balance
```

Returns the reward balance for a customer.

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers/customer_123/balance' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Credit customer balance

```
POST https://api.partnero.com/v1/customers/{id}/balance/credit
```

Add credit to a customer's reward balance.

| Parameter      | Type    | Required | Description                    |
| -------------- | ------- | -------- | ------------------------------ |
| `amount`       | number  | Yes      | Credit amount                  |
| `amount_units` | string  | Yes      | Currency code (e.g., `USD`)    |
| `is_currency`  | boolean | Yes      | Whether the amount is monetary |

```bash cURL theme={null}
curl --location 'https://api.partnero.com/v1/customers/customer_123/balance/credit' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 10.00,
    "amount_units": "USD",
    "is_currency": true
  }'
```