ShopEazydevelopers
API referenceMerchant API BetaCustomers

Edit a customer

Beta
Credentials
  • OAuth access token
Scopes
customers:write
Subscription
Needs an active plan. Otherwise 403 subscription_locked.
Idempotency
Send an Idempotency-Key header. A retry with the same key does the work once.
PATCH
/v1/merchant/stores/{storeId}/customers/{customerId}

Access: OAuth scope customers:write; write-gated by the subscription.

Authorization

merchantOAuth customers:write
headerAuthorizationBearer <token>

OAuth 2.1 (authorization code + PKCE S256, public clients, dynamic registration) for connected AI apps. Effective power is scopes granted AND the person's role today AND the plan. orders:refund, billing:write and team:write are opt-in on the consent screen. Write implies read for marketing:read and messages:read, so a grant holding marketing:write passes a marketing:read check, and messages:send passes messages:read.

Scope: customers:write

Path Parameters

storeId*string

A store the person can reach. Any other id answers 404, never 403.

customerId*string

Header Parameters

Idempotency-Key*string

Required on every write. Minted on the device when the person taps, reused on every retry. A write without one, or with one that does not match the pattern, is refused with 422 validation_error. Scoped to the token's subject, remembered 24 hours. A replay returns the first 2xx response with Idempotent-Replay: true; a request still running answers 409 in_flight; the same key with a different method, path or body answers 409 idempotency_key_reused; non-2xx results are not remembered. If the key store cannot be read nothing is processed and the answer is 503 idempotency_unavailable: retry with the same key.

Match^[A-Za-z0-9_-]{8,128}$

Request Body

application/json
  1. body

On create name is required. On PATCH only the keys present change; a key sent as null or empty clears it. orderCount and totalSpent are never writable.

name?string
Lengthlength <= 120
email?|
Lengthlength <= 254
phone?|
Lengthlength <= 40
address?|

The platform Address. Old app versions may still send line1 / line2 / suburb; the server maps them, and addressLine / localArea win when both are sent.

notes?|
Lengthlength <= 2000
tags?array<>
Itemsitems <= 20
marketingOptIn?boolean

Response Body

OK

application/json
  1. response
data*
Example Request
curl -X PATCH 'https://api.shopeazy.co/v1/merchant/stores/<storeId>/customers/<customerId>' \  -H 'Authorization: Bearer <access_token>' \  -H 'Idempotency-Key: <unique_key>' \  -H 'Content-Type: application/json' \  -d '{  "notes": "Likes low-light plants. Prefers WhatsApp. Bought a monstera.",  "tags": [    "plant club",    "repeat"  ]}'
Example Response
{  "data": {    "id": "dX3fN9Vqb9YKrX8GsA1H",    "name": "Thandi Mokoena",    "email": "thandi.mokoena@example.com",    "phone": "+27 82 000 0000",    "orderCount": 0,    "totalSpent": {      "amount": 0,      "currency": "ZAR"    },    "lastOrderAt": null,    "address": {      "addressLine": "5 Example Avenue",      "localArea": "Parkhurst",      "city": "Johannesburg",      "province": "Gauteng",      "postalCode": "2193",      "country": "ZA",      "line1": "5 Example Avenue",      "suburb": "Parkhurst"    },    "notes": "Likes low-light plants. Prefers WhatsApp. Bought a monstera.",    "tags": [      "plant club",      "repeat"    ],    "marketingOptIn": false,    "status": "active",    "hasAccount": false,    "createdAt": 1792924390822  }}

One customer GET

Access: OAuth scope `customers:read`; not write-gated.

Archive a customer (soft delete) DELETE

Access: OAuth scope `customers:write`; write-gated by the subscription.