Skip to main content
POST
/
v1
/
customers
Referral customers
curl --request POST \
  --url https://api.example.com/v1/customers
{
  "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

ParameterTypeRequiredDescription
keystringNoUnique customer identifier (auto-generated if not provided)
idstringNoAlternative customer identifier
emailstringNoCustomer’s email address
namestringNoCustomer’s first name
surnamestringNoCustomer’s last name
metadata.date_of_birthdateNoCustomer’s date of birth
referring_customer.keystringNo*Referring customer’s key (from partnero_referral cookie)
referring_customer.idstringNo*Referring customer’s ID
*Provide at least one referring_customer field to attribute the new customer to a referrer.

​
Request

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

​
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

FieldTypeDescription
idstringCustomer identifier
emailstringCustomer’s email address
namestringCustomer’s first name
surnamestringCustomer’s last name
statusstringCustomer status (active, deleted)
approvedbooleanWhether the customer is approved
referring_customerobject|nullThe customer who referred this person
referrals_countintegerNumber of customers referred by this customer
metadataobjectCustomer metadata (e.g., date_of_birth)
referral_linkstringDefault referral link
referral_linksarrayAll referral links for this customer
custom_fieldsobjectCustom signup field values
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

​
List customers

GET https://api.partnero.com/v1/customers
ParameterTypeDefaultDescription
limitinteger15Results per page (1-250)
pageinteger1Page number
refer_statusstring—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}
ParameterTypeRequiredDescription
updateobjectYesObject containing fields to update
update.emailstringNoNew email address
update.namestringNoCustomer’s first name
update.surnamestringNoCustomer’s last name
update.keystringNoNew customer key
update.metadata.date_of_birthdateNoCustomer’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.
ParameterTypeRequiredDescription
emailstringYesCustomer’s email address
namestringNoCustomer’s name
personalizationobjectNoCustom 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
ParameterTypeDescription
keystringCustomer key
idstringCustomer ID
emailstringCustomer’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.
ParameterTypeRequiredDescription
amountnumberYesCredit amount
amount_unitsstringYesCurrency code (e.g., USD)
is_currencybooleanYesWhether 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
  }'