Customers
Rules for creating and updating storefront customers over the REST API: the signup setting, the current password on email and password changes, GDPR export and erasure, and binding push devices to customers.
This guide covers the customer rules that are easy to trip over. The routes themselves are in the API reference under Customers and Devices. Customer sessions and ACLs are explained in Authentication.
Creating customers
POST /customers creates a customer. Storefront apps call it with an anonymous or customer token for sign-up forms; integrations call it with a master token.
A site can turn self-registration off with the Allow customer signup setting (admin shop
settings → Accounts; allow_customer_signup in the site settings). It is on by default. When it is
off:
POST /customersanswers403 { "message": "Customer signup is disabled for this site" }for every caller without a master token, whatever the customer create ACL allows.- Signing a direct upload for a new customer's file field is refused the same way.
- Master tokens (CLI, MCP, back-office integrations) still create customers.
The storefront /register page and checkout signup follow the same setting. Themes can hide their
sign-up links with site.customer_signup_allowed.
POST /customers is also rate limited per IP address: 10 requests per minute and 50 per day. The
limit counts requests from that IP whatever the token, so pace bulk imports. Over the limit the
answer is 429 (see Rate limiting).
Changing email or password
PUT/PATCH /customers/{customer_id} takes
password, password_confirmation and current_password next to the other fields.
current_password is only checked, never stored.
- When you send
current_password, it is always checked, on any update. A wrong value fails the whole update with422and a validation error on thecurrent_passwordfield. Nothing is saved. - When you leave it out, it is not checked by default.
A site can require it with the Require current password for email and password changes setting
(admin shop settings → Accounts, off by default). With it on, a customer session that changes its
own email or password must send current_password; without it the update fails with 422 and a
current_password "can't be blank" error. An email counts as changed when it differs from the
stored one after trimming spaces and lowercasing. Name-only updates don't need it.
These callers are exempt from the setting:
- master tokens
- a customer the ACL allows to update other customers, when it updates someone else
- customers without a stored password (for example accounts created through social login)
curl -X PATCH "https://api.nimbu.io/customers/current" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "X-Nimbu-Session-Token: $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": "jane.new@example.net",
"current_password": "the-old-password"
}'A password change made through a customer session keeps that session signed in.
GDPR requests
Two routes handle data subject requests. Both need a master token with write_customers.
Export
POST /customers/{customer_id}/gdpr/export queues a zip (JSON plus files) of everything Nimbu stores about the customer:
curl -X POST "https://api.nimbu.io/customers/6731f2e0c3d4e5f607182a00/gdpr/export" \
-H "Authorization: Bearer $MASTER_TOKEN" \
-H "X-Nimbu-Site: $SITE_ID"{ "id": "3c9e0f1a2b3c4d5e6f708192a3b4c5d6", "status": "queued" }Poll GET /customers/gdpr/exports/{job_id}
with that id until status is completed, then download url:
{
"id": "3c9e0f1a2b3c4d5e6f708192a3b4c5d6",
"status": "completed",
"customer_id": "6731f2e0c3d4e5f607182a00",
"url": "https://…signed download URL…",
"created_at": "2026-11-05T13:40:00Z"
}status is one of queued, working, completed, failed or killed. The status stays
available for 3 days, also after the customer is erased; the export file for a month. url is a
signed link: hand it to the customer over a secure channel and don't log it.
Erasure
POST /customers/{customer_id}/gdpr/erase queues the erasure of the customer's personal data. It can't be undone. Export first when the customer also asked for a copy. The body must repeat the customer's email or id:
curl -X POST "https://api.nimbu.io/customers/6731f2e0c3d4e5f607182a00/gdpr/erase" \
-H "Authorization: Bearer $MASTER_TOKEN" \
-H "X-Nimbu-Site: $SITE_ID" \
-H "Content-Type: application/json" \
-d '{ "confirm": "jane@example.net" }'202 { "id": "…", "status": "queued" }. The customer is deleted; their orders, subscriptions and
gift cards are anonymized; channel entries they own are deleted and references to them removed.
| Status | code | When |
|---|---|---|
422 | confirmation_mismatch | confirm is missing or is not the customer's email (case-insensitive) or id |
409 | not_erasable | the customer has active subscriptions; errors lists the blockers |
404 | no such customer |
There is no status route for erasures. Subscribe to the customer.erased webhook
(or customer.data_exported for exports) when you need to know when the job finished.
Devices
Devices register push tokens for mobile apps. Send the
app installation id in the X-Nimbu-Installation-Id header (or Installation-Id); POST /devices
creates or updates the device for that installation.
Without a master token, a caller can only bind a device to the signed-in customer:
customer_idonPOSTandPATCH /devicesmay only benull,""(both unbind the device, for example on logout) or the current customer's own id. Anything else →403 Not allowed to assign this device to another customer.tokenmust be a string → otherwise400 Invalid type for 'token': expected String.- When the installation id already belongs to another customer's device,
POST /deviceswith a pushtokencreates a new device (201, new id) and leaves the other device's customer and token alone. Without atokenthe answer is403 Not allowed to register this device. - Re-registering your own device, switching accounts on the same device and rotating your own push token keep working as before.
Master tokens can bind any device to any customer.
Direct File Uploads
Upload files for channel entry, customer and product file fields straight to storage with a signed URL, then attach them with a FileRef instead of sending base64.
Working with Pages
Read and safely change page content through the REST API: the page document, merge vs replace updates, surgical batch operations with ETags and If-Match, dry runs, compact reads, drafts and preview links, schema and item reads, and page versions.