> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Synchronise customers

> Match customer records without duplicates and preserve consent correctly.

Use a stable upstream identifier whenever possible. Email addresses and phone
numbers can change, be shared, or be entered differently across systems.

## Identity strategy

`external_ref` is unique within a Perkstar business. Namespace the value when
more than one source or account can produce the same native ID:

```text theme={null}
odoo:company_4:partner_981
shopify:shop_12:customer_981
```

When `POST /customers` includes an `external_ref`:

* an existing match is returned with `200` and is not overwritten;
* a missing match is created with `201`; and
* retries remain safe beyond the request idempotency window.

## Initial import

1. Page through the source system in stable order.
2. Upsert each customer with `external_ref`.
3. Store the returned Perkstar customer ID in the source system.
4. Checkpoint progress after each completed page.
5. Run a second pass for records changed during the import.

Limit concurrency and respect Perkstar's rate-limit headers. A large import
should use a durable job queue, not one browser request.

## Consent

Consent is not a convenience flag. Set `consent_marketing` or
`consent_ad_tracking` only when the source system contains a valid, auditable
permission for that purpose. A blank source value should not become `true`.

## Updates and deletion

* Send PATCH only for fields your integration owns.
* Normalise upstream phone numbers before matching where possible.
* Treat a Perkstar anonymisation response as permanent.
* Do not recreate an anonymised person automatically from a stale export.
* Keep API keys and personal payloads out of logs.

<Warning>
  Test keys can read customer records but cannot create, edit, or anonymise
  them. Perform customer writes only after certification with a live key that
  has `CUSTOMERS_WRITE`.
</Warning>


## Related topics

- [Get a customer](/api-reference/customers/get-a-customer.md)
- [Update a customer](/api-reference/customers/update-a-customer.md)
- [List customers](/api-reference/customers/list-customers.md)
- [Create or upsert a customer](/api-reference/customers/create-or-upsert-a-customer.md)
- [Find-or-create customer + enrolment (no transaction)](/api-reference/marketplace/find-or-create-customer-+-enrolment-no-transaction.md)