# Clients

Create each counterparty once, reference them everywhere — payment links, invoices, reporting.

A client is a general-purpose counterparty record, not an e-invoicing artifact: use it to group
[payment links](https://developers.baxpay.com/payment-links) per customer, to prefill invoices, or simply as the customer
book behind your own app. Clients are mode-scoped like everything else — test clients exist only
for test keys.

Only `name` is required. The identifiers (`siren`, `siret`, `vatId`) matter when you invoice a
French business under the [e-invoicing mandate](https://developers.baxpay.com/einvoicing); a consumer or a non-French client
simply doesn't have them.

## Create a client

- `POST /clients` — Idempotency-Key required

```bash
curl -X POST https://sandbox-api.baxpay.com/v1/clients \
  -H "Authorization: Bearer $BAXPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ACME SAS",
    "email": "compta@acme.example",
    "address": {
      "line1": "12 rue de la Paix",
      "city": "Paris",
      "postalCode": "75002",
      "countryCode": "FR"
    },
    "siren": "552100554",
    "vatId": "FR96552100554"
  }'
```

```js
const res = await fetch('https://sandbox-api.baxpay.com/v1/clients', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BAXPAY_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  // A consumer: only the name is required.
  body: JSON.stringify({ name: 'Marie Dupont', email: 'marie@example.com', clientKind: 'B2C' }),
});
const body = await res.json();
if (!res.ok) throw new Error(JSON.stringify(body));
console.log(JSON.stringify(body, null, 2));
```

```json
{
  "success": true,
  "data": {
    "id": "b7e1c2d0-…",
    "name": "…",
    "clientKind": "B2B",
    "email": "…",
    "livemode": false,
    "archivedAt": null,
    "createdAt": "2026-07-16T14:00:00.000Z"
  }
}
```

| Field | Meaning |
| --- | --- |
| `name` | Required. The name you use day to day |
| `legalName` | Registered name when it differs (printed on invoices) |
| `clientKind` | `B2B` (default), `B2C` or `B2B_INTERNATIONAL` |
| `email`, `phone` | Contact; the email receives payment links and invoices |
| `address` | `line1`, `line2`, `city`, `postalCode`, `countryCode` |
| `siren`, `siret`, `vatId` | French identifiers, checked when present; a SIREN is unique per mode in your account |
| `electronicAddress` | The client's e-invoicing address, when it differs from its SIREN |
| `buyerReference` | Default purchase reference stamped on that client's invoices |
| `notes` | Free text for your team |

## Manage clients

- `GET /clients?search=acme&kind=B2B&includeArchived=false&page=1&limit=25`
- `GET /clients/{id}`
- `PUT /clients/{id}` — Idempotency-Key required
- `POST /clients/{id}/archive` — Idempotency-Key required
- `POST /clients/{id}/unarchive` — Idempotency-Key required
- `DELETE /clients/{id}` — Idempotency-Key required

```bash
curl "https://sandbox-api.baxpay.com/v1/clients?search=acme&limit=25" \
  -H "Authorization: Bearer $BAXPAY_API_KEY"
```

```json
{
  "success": true,
  "data": { "data": [{ "id": "b7e1c2d0-…", "name": "ACME SAS", "siren": "552100554" }], "total": 1, "page": 1, "limit": 25 }
}
```

`search` matches name, SIREN and email; `kind` filters by `clientKind`.

```bash
curl -X PUT https://sandbox-api.baxpay.com/v1/clients/b7e1c2d0-… \
  -H "Authorization: Bearer $BAXPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "email": "factures@acme.example", "buyerReference": "PO-ACME-2026" }'
```

```json
{ "success": true, "data": { "id": "b7e1c2d0-…", "email": "factures@acme.example", "buyerReference": "PO-ACME-2026" } }
```

**Archive** hides a client from pickers while keeping its history; prefer it over delete.

```bash
curl -X POST https://sandbox-api.baxpay.com/v1/clients/b7e1c2d0-…/archive \
  -H "Authorization: Bearer $BAXPAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

> **Editing or deleting a client never rewrites history**
> Issued invoices carry a legal snapshot of the buyer at issuance, and paid links keep their
> transaction record. Updating a client only affects what you create next; deleting one just
> unlinks it.

## Where clients plug in

- **[Payment links](https://developers.baxpay.com/payment-links)** — pass `clientId` at creation to group charges per
  customer; it's echoed in the `payment_link.paid` webhook.
- **[E-invoicing](https://developers.baxpay.com/einvoicing)** — pass `clientId` instead of the inline buyer block; the
  client's SIREN, VAT id and address fill the invoice (inline fields override per invoice).