Nimbu Developer Docs

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 /customers answers 403 { "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 with 422 and a validation error on the current_password field. 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.

StatuscodeWhen
422confirmation_mismatchconfirm is missing or is not the customer's email (case-insensitive) or id
409not_erasablethe customer has active subscriptions; errors lists the blockers
404no 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_id on POST and PATCH /devices may only be null, "" (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.
  • token must be a string → otherwise 400 Invalid type for 'token': expected String.
  • When the installation id already belongs to another customer's device, POST /devices with a push token creates a new device (201, new id) and leaves the other device's customer and token alone. Without a token the answer is 403 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.

On this page