Create a customer (v2) — Acme Commerce API

POST /api/v2/customers Requires authentication v2

Send a bearer token in the Authorization header.

Creates a customer and, unless send_invite is false, emails them an invitation.

Full URL: https://api.acme.example/api/v2/customers

Body parameters

Name	Type	Required	Description
email	string<email>	yes	Must be unique across your account.
name	string, maxLength 255	yes	Display name.
send_invite	boolean	no	Defaults to true.
metadata	object	no	Arbitrary key/value pairs echoed back on reads.
metadata.plan	string	no

Responses

201 The created customer.

Field	Type	Description
id	integer
email	string<email>
name	string
status	string, one of active, invited, archived
created_at	string<date-time>

422 Validation failed.

Example request

cURL

curl -X POST 'https://api.acme.example/api/v2/customers' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe",
    "send_invite": true,
    "metadata": {
        "plan": "pro"
    }
}'

JavaScript

const response = await fetch('https://api.acme.example/api/v2/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "email": "jane@example.com",
      "name": "Jane Doe",
      "send_invite": true,
      "metadata": {
          "plan": "pro"
      }
  })
});

const data = await response.json();

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer YOUR_TOKEN',
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
])->post('https://api.acme.example/api/v2/customers', [
    'email' => 'jane@example.com',
    'name' => 'Jane Doe',
    'send_invite' => true,
    'metadata' => [
        'plan' => 'pro',
    ],
]);

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://api.acme.example/api/v2/customers', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
        'email' => 'jane@example.com',
        'name' => 'Jane Doe',
        'send_invite' => true,
        'metadata' => [
            'plan' => 'pro',
        ],
    ],
]);

$data = json_decode((string) $response->getBody(), true);

Example response

201

{
    "id": 42,
    "email": "jane@example.com",
    "name": "Jane Doe",
    "status": "invited",
    "created_at": "2026-02-01T11:00:00Z"
}

422

{
    "message": "The email has already been taken.",
    "errors": {
        "email": [
            "The email has already been taken."
        ]
    }
}