Referral customers

POST

customers

Referral customers

curl --request POST \
  --url https://api.example.com/v1/customers

import requests

url = "https://api.example.com/v1/customers"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/customers"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/customers")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "data": {
    "email": "[email protected]",
    "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
}

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

Referring customer
Referred customer

Create a customer who will share referral links:

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": "[email protected]"
  }'

Create a customer who signed up via a referral link:

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": "[email protected]"
  }'

Response

{
  "data": {
    "email": "[email protected]",
    "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
}

Response fields

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

List customers

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

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

cURL

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}

cURL

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

cURL

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}

Deleting a customer is permanent. Consider using archive instead.

cURL

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.

cURL

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.

cURL

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

cURL

curl --location 'https://api.partnero.com/v1/customers:invite' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "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

cURL

curl --location 'https://api.partnero.com/v1/customers:[email protected]' \
  --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.

cURL

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.

cURL

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.

cURL

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.

cURL

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

cURL

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
  }'

TransactionsTrack transactions from referred customers in refer-a-friend programs

Referral customers

curl --request POST \
  --url https://api.example.com/v1/customers

import requests

url = "https://api.example.com/v1/customers"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/customers"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/customers")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "data": {
    "email": "[email protected]",
    "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
}

Overview

Program

Partners

Customers

Transactions

Leads

Referral links

Coupons

Promotion codes

Webhooks

Refer-a-friend

Newsletter referral

Referral customers

Create customer

Request body

Request

Response

Response fields

List customers

Get customer

Update customer

Delete customer

Archive customer

Restore customer

Invite a customer

Search customers

Get customer stats

Get customer referrals

Get customer transactions

Get customer balance

Credit customer balance

​Create customer

​Request body

​Request

​Response

​Response fields

​List customers

​Get customer

​Update customer

​Delete customer

​Archive customer

​Restore customer

​Invite a customer

​Search customers

​Get customer stats

​Get customer referrals

​Get customer transactions

​Get customer balance

​Credit customer balance

Create customer

Request body

Request

Response

Response fields

List customers

Get customer

Update customer

Delete customer

Archive customer

Restore customer

Invite a customer

Search customers

Get customer stats

Get customer referrals

Get customer transactions

Get customer balance

Credit customer balance