👥Customers

💡 Bulk upsert customers for a tenant with a single API call

🚀 TL;DR - Quick Reference

Endpoint: POST /customers/{tenantId}

Use When:

New customer signup (no purchase)
Updating customer preferences
Syncing customer profiles from your system
GDPR opt-in/opt-out updates

Required: At least one of CustomerId or Email Auth: x-replenit-auth-key header Returns: Count of upserted customers

Quickest Example:

POST /customers/{YOUR_TENANT_ID}
[{"CustomerId": "C-001", "Email": "user@example.com"}]

Jump to Full API Reference ↓

🔗 Endpoint

POST /customers/{tenantId}

📋 Parameters

Parameter

Type

Required

Description

tenantId

GUID

✅ Yes

The tenant identifier (must exist)

📨 Request

Body: JSON array of UpsertCustomerDto objects
Content-Type: application/json

✅ Success Response

Status: 200 OK
Body: Response envelope with data.count

❌ Error Responses

Status

Description

400 Bad Request

Invalid or missing tenant identifier

404 Not Found

Tenant does not exist in our system

500 Internal Server Error

Unexpected server errors

🎯 Identifier Behavior

Understanding how customer identifiers work is crucial for successful data synchronization.

How Customer Matching Works

When you send customer data, the system needs to determine whether you're creating a new customer or updating an existing one. This is done using an identifier field.

Your tenant configuration specifies which field takes priority:

Priority Setting

Identifier Used

When to Use

email

Customer's email address

Best for B2C where emails are unique and stable

customerid

Customer's ID from your system

Best for B2B or when emails can change

What This Means for You

If priority is email:

The system matches customers by their email address
If an email already exists, that customer record is updated
If the email is new, a new customer is created
CustomerId can be provided but won't be used for matching

If priority is customerid:

The system matches customers by your internal customer ID
If the ID already exists, that customer record is updated
If the ID is new, a new customer is created
Email can be provided but won't be used for matching

Best Practice

Always provide both CustomerId and Email when possible. This ensures:

Proper matching based on your tenant's configuration
Complete customer profiles
Better campaign personalization
Reliable customer identification even if one identifier changes

Example:

{
  "CustomerId": "USER-12345",  // Your internal ID
  "Email": "customer@example.com",  // Their email
  "Name": "Jane",
  "Surname": "Doe"
}

📝 Note: To view or change your identifier priority setting, navigate to your tenant configuration in the Replenit Dashboard.

📄 Request Schema

UpsertCustomerDto Fields

All fields are optional unless specified otherwise. The API uses intelligent defaults for missing values.

Field

Type

Max Length

Required

Description

CustomerId

string

100

⚠️ Conditional

Your unique identifier for this customer. Either this or Email is required depending on tenant settings.

Email

string

255

⚠️ Conditional

Customer's email address. Either this or CustomerId is required depending on tenant settings.

Name

string

100

❌

Customer's first name. Used in email personalization and campaign targeting.

Surname

string

300

❌

Customer's last name. Combined with Name for full personalization.

Phone

string

❌

Customer's phone number. Required for SMS campaigns. Can include country code.

Language

string

❌

Preferred language using IETF BCP 47 format (e.g., en-US, fr-FR). Determines campaign language.

Username

string

500

❌

Customer's username in your system. Useful for app-based businesses.

EmailOptin

bool

❌

Whether customer consented to email marketing. Default: false. Required for email campaigns.

SmsOptin

bool

❌

Whether customer consented to SMS marketing. Default: false. Required for SMS campaigns.

WhatsappOptin

bool

❌

Whether customer consented to WhatsApp messaging. Default: false. Required for WhatsApp campaigns.

AppPushOptin

bool

❌

Whether customer consented to app push notifications. Default: false. Required for push campaigns.

GdprOptin

bool

❌

Whether customer provided GDPR consent. Default: false. Important for EU compliance.

IsExcluded

bool

❌

Exclude this customer from all campaigns. Default: false. Useful for VIP manual-only communication.

Field Notes

Consent Fields (EmailOptin, SmsOptin, etc.):

These control which communication channels are enabled for this customer
Always respect customer preferences - sending to non-opted-in customers may violate regulations
Update these fields when customers change their preferences

Language Field:

Use standard language codes like en, de, fr
Or region-specific codes like en-US, es-MX, pt-BR
If omitted, campaigns will use your default language
See Best Practices - Language Standards for complete guide

GDPR Compliance:

The GdprOptin field is critical for EU customers
Set to true only after obtaining explicit consent
When false, customer data is stored but marketing is restricted

🗑️ DELETE Endpoint

🔗 Delete Customer

DELETE /customers/{tenantId}/{customerId}

📋 Parameters

Parameter

Type

Required

Description

tenantId

GUID

✅ Yes

The tenant identifier

customerId

string

✅ Yes

The customer ID to delete

✅ Success Response

Status: 200 OK
Body: Response envelope with deleted customer ID

{
  "success": true,
  "message": "Customer removed.",
  "data": { 
    "customerId": "C-123",
    "deletedAt": "2024-12-22T14:02:49Z"
  }
}

❌ Error Responses

|| Status | Scenario | Example Response | || ------ | -------- | ---------------- | || 400 | Missing customer ID | {"success": false, "message": "Customer ID is required.", "data": {}} | || 404 | Tenant not found | {"success": false, "message": "Tenant not found.", "data": {}} | || 404 | Customer not found | {"success": false, "message": "Customer not found.", "data": {}} | || 500 | Storage failure | {"success": false, "message": "Failed to delete customer.", "data": {}} |

Note: The tenant validation is performed automatically by middleware before reaching the endpoint. If tenant doesn't exist, you'll receive a 404 error immediately.

🚀 DELETE Examples

cURL

curl -X DELETE "https://api.replen.it/customers/{tenantId}/C-123" \
  -H 'x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY'

Python

import requests

url = "https://api.replen.it/customers/{tenantId}/C-123"
headers = {
    "x-replenit-auth-key": "YOUR_BASE64_ACCESS_KEY"
}

response = requests.delete(url, headers=headers)
print(response.json())

Node.js

const axios = require('axios');

const url = 'https://api.replen.it/customers/{tenantId}/C-123';
const headers = {
    'x-replenit-auth-key': 'YOUR_BASE64_ACCESS_KEY'
};

axios.delete(url, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

💡 Real-World Use Cases

Scenario: Customer creates account on your website (no purchase yet)

What to send:

[{
  "CustomerId": "WEB-2024-12345",
  "Email": "newcustomer@example.com",
  "Name": "Sarah",
  "Surname": "Johnson",
  "Language": "en-US",
  "EmailOptin": true,
  "GdprOptin": true
}]

What happens:

✅ Customer profile created in Replenit
🎯 Added to "Welcome" campaign
📧 Receives welcome email series

Scenario: User subscribes to newsletter without creating account

What to send:

[{
  "Email": "subscriber@example.com",
  "EmailOptin": true,
  "GdprOptin": true,
  "Language": "de-DE"
}]

Why minimal fields: You only have email, that's enough!

Scenario: Customer requests to stop receiving emails

What to send:

[{
  "CustomerId": "C-123",
  "EmailOptin": false,
  "SmsOptin": false,
  "WhatsappOptin": false
}]

What happens:

✅ Customer preferences updated
🚫 Removed from all marketing campaigns
✅ GDPR compliance maintained

Use Case 4: Bulk Customer Import

Scenario: Migrating 10,000 customers from old system

Best practice:

# Batch in chunks of 500
for i in range(0, len(customers), 500):
    batch = customers[i:i+500]
    response = requests.post(url, json=batch)
    time.sleep(0.5)  # Rate limiting

Performance: ~20 batches = ~10 seconds total (vs 10,000 individual calls = 30+ minutes)

📝 Complete Example Request (All Fields)

[
  {
    "CustomerId": "C-123",
    "Email": "john.doe@example.com",
    "Name": "John",
    "Surname": "Doe",
    "Phone": "+1-555-123-4567",
    "Language": "en-US",
    "Username": "johndoe",
    "EmailOptin": true,
    "SmsOptin": false,
    "WhatsappOptin": true,
    "AppPushOptin": true,
    "GdprOptin": true,
    "IsExcluded": false
  },
  {
    "CustomerId": "C-124",
    "Email": "jane.smith@example.com",
    "Name": "Jane",
    "Surname": "Smith",
    "Phone": "+44-20-1234-5678",
    "Language": "en-GB",
    "Username": "janesmith",
    "EmailOptin": true,
    "SmsOptin": true,
    "WhatsappOptin": false,
    "AppPushOptin": false,
    "GdprOptin": true,
    "IsExcluded": false
  },
  {
    "CustomerId": "C-125",
    "Email": "pedro.garcia@ejemplo.es",
    "Name": "Pedro",
    "Surname": "García",
    "Phone": "+34-91-123-4567",
    "Language": "es-ES",
    "Username": "pedrogarcia",
    "EmailOptin": false,
    "SmsOptin": false,
    "WhatsappOptin": true,
    "AppPushOptin": true,
    "GdprOptin": true,
    "IsExcluded": true
  }
]

📝 Minimal Example Request (Required Fields Only)

[
  {
    "CustomerId": "C-126"
  }
]

📝 Email-Based Customer (When Priority is Email)

[
  {
    "Email": "customer@example.com",
    "Language": "fr-FR",
    "GdprOptin": true,
    "Name": "Marie",
    "Surname": "Dubois"
  }
]

🚀 cURL Example

curl -sS \
  -X POST "https://api.replen.it/customers/{tenantId}" \
  -H 'Content-Type: application/json' \
  -H 'x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY' \
  -d @customers.json

🐍 Python Example

import requests
import json

url = "https://api.replen.it/customers/{tenantId}"
headers = {
    "Content-Type": "application/json",
    "x-replenit-auth-key": "YOUR_BASE64_ACCESS_KEY"
}

customers = [
    {
        "CustomerId": "C-123",
        "Email": "john.doe@example.com",
        "Name": "John",
        "Surname": "Doe",
        "EmailOptin": True
    }
]

response = requests.post(url, headers=headers, json=customers)
print(response.json())

🟢 Node.js Example

const axios = require('axios');

const url = 'https://api.replen.it/customers/{tenantId}';
const headers = {
    'Content-Type': 'application/json',
    'x-replenit-auth-key': 'YOUR_BASE64_ACCESS_KEY'
};

const customers = [
    {
        CustomerId: 'C-123',
        Email: 'john.doe@example.com',
        Name: 'John',
        Surname: 'Doe',
        EmailOptin: true
    }
];

axios.post(url, customers, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

📊 Response Examples

✅ Success Response (200)

{
  "success": true,
  "message": "Customers saved.",
  "data": {
    "count": 3,
    "processedAt": "2024-12-22T14:05:51Z"
  }
}

❌ Validation Error (400) - Missing Identifier (CustomerId or Email)

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-abc123...",
  "errors": {
    "": [
      "At least one of the following properties must have a value: CustomerId, Email"
    ]
  }
}

📖 What this means:

You must provide at least one identifier: either CustomerId OR Email
This validation ensures we can identify the customer in our system
Both can be provided for better data quality

✅ How to fix:

[
  {
    "CustomerId": "C-123",
    "Name": "John",
    "Surname": "Doe"
  }
]

Or with email:

[
  {
    "Email": "customer@example.com",
    "Name": "John",
    "Surname": "Doe"
  }
]

Best practice (both identifiers):

[
  {
    "CustomerId": "C-123",
    "Email": "customer@example.com",
    "Name": "John",
    "Surname": "Doe"
  }
]

💡 Common causes:

Sending empty customer object {}
Both CustomerId and Email are null, empty string, or omitted
Whitespace-only values in identifier fields

❌ Validation Error (400) - Missing Required Fields

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-abc123...",
  "errors": {
    "[0].Language": [
      "The Language field is required."
    ],
    "[0].GdprOptin": [
      "The GdprOptin field is required."
    ]
  }
}

📖 What this means:

Your first customer (index [0]) is missing required fields
Note: These fields are only required if your tenant configuration enforces them
Check your tenant settings to see which fields are mandatory

✅ How to fix:

[
  {
    "CustomerId": "C-123",
    "Email": "customer@example.com",
    "Language": "en-US",
    "GdprOptin": true
  }
]

💡 Common causes:

Missing Language field (use IETF BCP 47 format: en-US, de-DE, etc.)
Missing GdprOptin field (must be true or false, not omitted)
Tenant configuration requires these fields

❌ Validation Error (400) - String Length Exceeded

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-def456...",
  "errors": {
    "[0].CustomerId": [
      "The field CustomerId must be a string with a maximum length of 100."
    ],
    "[0].Language": [
      "The field Language must be a string with a maximum length of 10."
    ]
  }
}

📖 What this means:

Field values exceed maximum allowed length
CustomerId: maximum 100 characters
Language: maximum 10 characters

✅ How to fix:

Use shorter customer IDs
Use standard language codes (e.g., en-US instead of long text)

💡 Field length limits:

Field

Max Length

CustomerId, Name, Surname

100

Username

500

255

Phone

Language

❌ Not Found (404)

{
  "success": false,
  "message": "Tenant not found.",
  "data": {}
}

❌ Internal Server Error (500)

{
  "success": false,
  "message": "An unexpected error occurred. Please try again.",
  "data": {}
}

🔁 Best Practices

Batch Operations: Send multiple customers in a single request for better performance (recommended batch size: 100-500)
Validation: Ensure email addresses are valid before submission
GDPR Compliance: Always obtain proper consent before setting opt-in flags
Error Handling: Implement retry logic for 500 errors with exponential backoff
Rate Limiting: Respect API rate limits to avoid throttling
CustomerId: Please ensure that it is also set as an identifier in your Marketing Automation platform, so users can be consistently matched across systems and events
Language Format: Use IETF language tags (BCP 47) format:
- Examples: en, en-US, en-GB, es-ES, fr-FR, de-DE, pt-BR
- Pattern: language[-script][-region]
- Reference: IETF BCP 47

PreviousBest Practices Guide NextError Responses

Last updated 6 days ago

hashtag🚀 TL;DR - Quick Reference

hashtag🔗 Endpoint

hashtag📋 Parameters

hashtag📨 Request

hashtag✅ Success Response

hashtag❌ Error Responses

hashtag🎯 Identifier Behavior

hashtagHow Customer Matching Works

hashtagWhat This Means for You

hashtagBest Practice

hashtag📄 Request Schema

hashtagUpsertCustomerDto Fields

hashtagField Notes

hashtag🗑️ DELETE Endpoint

hashtag🔗 Delete Customer

hashtag📋 Parameters

hashtag✅ Success Response

hashtag❌ Error Responses

hashtag🚀 DELETE Examples

hashtagcURL

hashtagPython

hashtagNode.js

hashtag💡 Real-World Use Cases

hashtagUse Case 1: E-commerce Customer Signup

hashtagUse Case 2: Newsletter Subscription

hashtagUse Case 3: GDPR Opt-Out

hashtagUse Case 4: Bulk Customer Import

hashtag📝 Complete Example Request (All Fields)

hashtag📝 Minimal Example Request (Required Fields Only)

hashtag📝 Email-Based Customer (When Priority is Email)

hashtag🚀 cURL Example

hashtag🐍 Python Example

hashtag🟢 Node.js Example

hashtag📊 Response Examples

hashtag✅ Success Response (200)

hashtag❌ Validation Error (400) - Missing Identifier (CustomerId or Email)

hashtag❌ Validation Error (400) - Missing Required Fields

hashtag❌ Validation Error (400) - String Length Exceeded

hashtag❌ Not Found (404)

hashtag❌ Internal Server Error (500)

hashtag🔁 Best Practices

hashtag🔍 Related Resources

🚀 TL;DR - Quick Reference

🔗 Endpoint

📋 Parameters

📨 Request

✅ Success Response

❌ Error Responses

🎯 Identifier Behavior

How Customer Matching Works

What This Means for You

Best Practice

📄 Request Schema

UpsertCustomerDto Fields

Field Notes

🗑️ DELETE Endpoint

🔗 Delete Customer

📋 Parameters

✅ Success Response

❌ Error Responses

🚀 DELETE Examples

cURL

Python

Node.js

💡 Real-World Use Cases

Use Case 1: E-commerce Customer Signup

Use Case 2: Newsletter Subscription

Use Case 3: GDPR Opt-Out

Use Case 4: Bulk Customer Import

📝 Complete Example Request (All Fields)

📝 Minimal Example Request (Required Fields Only)

📝 Email-Based Customer (When Priority is Email)

🚀 cURL Example

🐍 Python Example

🟢 Node.js Example

📊 Response Examples

✅ Success Response (200)

❌ Validation Error (400) - Missing Identifier (CustomerId or Email)

❌ Validation Error (400) - Missing Required Fields

❌ Validation Error (400) - String Length Exceeded

❌ Not Found (404)

❌ Internal Server Error (500)

🔁 Best Practices

🔍 Related Resources