Skip to main content
Use this endpoint to create a new customer record scoped to your merchant account. The endpoint behaves as an upsert: if a customer with the given externalId already exists under your account, the API returns that existing record rather than creating a duplicate. This makes it safe to call on every checkout or sign-in flow without needing to track whether you have already registered a customer.
The externalId is your primary deduplication key. Choose a stable, unique identifier from your own system — such as a database user ID — and use it consistently across requests.

​
Headers

​
X-API-Key
string
required
Your secret API key. Keep this value server-side and never expose it in client code.
​
Idempotency-Key
string
required
A unique string you generate per request. Reuse the same key to safely retry a failed request without creating a duplicate customer record.
​
Content-Type
string
required
Must be application/json.

​
Body

​
externalId
string
required
Your own unique identifier for this customer. Must be between 1 and 255 characters. This value is used for deduplication — if a customer with this externalId already exists, their record is returned.
​
email
string
Customer’s email address. Must be a valid email format. Optional, but recommended for receipt delivery and dispute resolution.
​
metadata
object
Arbitrary key-value pairs you want to attach to the customer record. Useful for storing plan tier, region, or any other context relevant to your integration.

​
Response

​
data
object
curl -X POST https://api.gateway.accelebit.com/v1/customers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smtgw_sk_test_your_secret_key" \
  -H "Idempotency-Key: cust_abc123" \
  -d '{
    "externalId": "user_12345",
    "email": "jane@example.com",
    "metadata": {
      "plan": "premium"
    }
  }'

const response = await fetch('https://api.gateway.accelebit.com/v1/customers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.ACCELEBIT_SECRET_KEY!,
    'Idempotency-Key': `cust_${crypto.randomUUID()}`,
  },
  body: JSON.stringify({
    externalId: 'user_12345',
    email: 'jane@example.com',
    metadata: { plan: 'premium' },
  }),
});

const result = await response.json();

import requests
import uuid

response = requests.post(
    'https://api.gateway.accelebit.com/v1/customers',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': ACCELEBIT_SECRET_KEY,
        'Idempotency-Key': f'cust_{uuid.uuid4()}',
    },
    json={
        'externalId': 'user_12345',
        'email': 'jane@example.com',
        'metadata': {'plan': 'premium'},
    },
)

result = response.json()

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "user_12345",
    "email": "jane@example.com",
    "metadata": {
      "plan": "premium"
    },
    "createdAt": "2026-04-09T12:00:00.000Z"
  }
}

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "user_12345",
    "email": "jane@example.com",
    "metadata": {
      "plan": "premium"
    },
    "createdAt": "2026-04-08T10:00:00.000Z"
  }
}