> ## Documentation Index
> Fetch the complete documentation index at: https://docs.accelebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/customers — Create or Retrieve Customer

> Create a customer record scoped to your merchant account, or retrieve an existing one by externalId. Returns the Accelebit customer UUID.

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.

<Note>
  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.
</Note>

## Headers

<ParamField header="X-API-Key" type="string" required>
  Your secret API key. Keep this value server-side and never expose it in client code.
</ParamField>

<ParamField header="Idempotency-Key" type="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.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="externalId" type="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.
</ParamField>

<ParamField body="email" type="string">
  Customer's email address. Must be a valid email format. Optional, but recommended for receipt delivery and dispute resolution.
</ParamField>

<ParamField body="metadata" type="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.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      Accelebit-generated UUID for this customer. Use this value when referencing the customer in payment and refund requests.
    </ResponseField>

    <ResponseField name="externalId" type="string">
      The external identifier you provided in the request.
    </ResponseField>

    <ResponseField name="email" type="string">
      The customer's email address, if one was provided.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      The key-value metadata attached to the customer record.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp indicating when the customer record was first created.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```typescript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Customer Created theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "externalId": "user_12345",
      "email": "jane@example.com",
      "metadata": {
        "plan": "premium"
      },
      "createdAt": "2026-04-09T12:00:00.000Z"
    }
  }
  ```

  ```json 201 - Existing Customer Returned theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "externalId": "user_12345",
      "email": "jane@example.com",
      "metadata": {
        "plan": "premium"
      },
      "createdAt": "2026-04-08T10:00:00.000Z"
    }
  }
  ```
</ResponseExample>