"Receivers" renamed to "Customers"

We're renaming "Receivers" to "Customers" across the entire BlindPay platform: API endpoints, SDKs, documentation, and dashboard.

TL;DR

• All /receivers endpoints now have /customers equivalents
• Both /receivers and /customers paths work identically through July 3, 2026
• After that date, /receivers endpoints return 301 Moved Permanently
• IDs stay the same (re_ prefix), no data migration needed
• SDKs add a customers accessor to their current majors and receivers is deprecated alongside, no import changes required

What changed

Every API endpoint that previously used /receivers in its path now has a /customers equivalent:

GET    /v1/instances/{instance_id}/receivers                →  GET    /v1/instances/{instance_id}/customers
POST   /v1/instances/{instance_id}/receivers                →  POST   /v1/instances/{instance_id}/customers
GET    /v1/instances/{instance_id}/receivers/{receiver_id}  →  GET    /v1/instances/{instance_id}/customers/{customer_id}
PUT    /v1/instances/{instance_id}/receivers/{receiver_id}  →  PUT    /v1/instances/{instance_id}/customers/{customer_id}
DELETE /v1/instances/{instance_id}/receivers/{receiver_id}  →  DELETE /v1/instances/{instance_id}/customers/{customer_id}

This applies to all sub-resources too: bank accounts, wallets, virtual accounts, blockchain wallets, offramp wallets, and limit increases.

Response changes

During the transition period, every customer record returned by either /customers or /receivers carries a customer_id alias of its primary key. The underlying ID still uses the re_ prefix and remains in the id field:

{
  "id": "re_abc123456789",
  "customer_id": "re_abc123456789",
  "first_name": "Alice"
}

Payouts and payins that reference a customer expose both receiver_id and customer_id foreign-key fields during the transition; either accepts the same re_* value. Sub-resources scoped under /customers/{id}/… (bank accounts, wallets, virtual accounts, blockchain wallets, offramp wallets) derive the parent from the URL, so no FK alias appears in the response body.

After the sunset, the customer_id alias becomes the canonical field name across the API.

Webhook changes

Three new webhook events fire alongside the existing ones:

• customer.new: fires whenever receiver.new fires
• customer.update: fires whenever receiver.update fires
• customer.delete: fires whenever receiver.delete fires

You must subscribe to customer.* before July 3, 2026. After the sunset, receiver.* events stop firing entirely. If you don't migrate, your endpoint goes silent.

During the transition window (June 4 → July 3), every create and update emits both events: the legacy receiver.* and its customer.* counterpart. If your endpoint is subscribed to both, your handler receives the same action twice. We intentionally dual-emit so you can migrate your handlers in any order, but make sure your processing is idempotent on the resource id, or drop the receiver.* subscription once customer.* is wired up.

SDK updates

No import path changes during the transition. Just update to the latest version of your current major and the customers accessor is there. For Node, Python, PHP, and Swift, a future major release (after sunset) removes the deprecated receivers surface; that's when imports change in those SDKs.

Go is treated differently. receivers stays as a thin deprecated forwarder in v1 indefinitely. gopls, staticcheck SA1019, and godoc will flag usage; nothing breaks.

Method signatures are unchanged. Only the resource accessor renames. For most projects this is a single find/replace. Example in Node.js SDK:

- await blindpay.receivers.list()
+ await blindpay.customers.list()

- await blindpay.receivers.bankAccounts.create({ ... })
+ await blindpay.customers.bankAccounts.create({ ... })

What you need to do

1. Update your API calls to use /customers instead of /receivers
2. Update field references from receiver_id to customer_id in your code
3. Update webhook subscriptions to use customer.new, customer.update, and customer.delete
4. Update your SDK to the latest version of its current major. The customers accessor is added there, no import changes required

Timeline

• June 4, 2026: /customers endpoints live. Both /receivers and /customers accept requests. Receiver responses include Deprecation: true and Sunset: Fri, 03 Jul 2026 00:00:00 GMT headers, plus a Link: rel="successor-version" pointing to the customer equivalent.
• July 3, 2026: Sunset date. /receivers endpoints return 301 Moved Permanently redirecting to /customers. SDK code calling receivers.* continues to work via the redirect.
• Later: /receivers endpoints removed entirely. New SDK majors ship for Node (v4), Python (v2), PHP (v2), and Swift (v2), dropping the deprecated receivers surface. The Go SDK keeps receivers as a deprecated forwarder in v1; no v2 planned for this rename. Previous SDK majors enter maintenance mode (security fixes only).

Detect deprecation programmatically

Every /receivers response carries deprecation metadata you can monitor in tests or runtime logs:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Fri, 03 Jul 2026 00:00:00 GMT
Link: </v1/instances/{instance_id}/customers>; rel="successor-version"
Content-Type: application/json

Useful in CI: fail a smoke test if production traffic still hits Deprecation: true endpoints close to the sunset date.

Verification checklist

Before considering your migration complete:

• Logs show zero requests to /v1/instances/*/receivers* paths from your services
• CI / monitoring asserts no Deprecation: true header on production responses
• Webhook handlers process customer.new, customer.update, and customer.delete
• No code paths reference response.receiver_id
• SDK updated to the latest minor release of its current major
• Saved dashboard URLs use /customers/

FAQ

What if I don't migrate before July 3, 2026?

/receivers paths return 301 Moved Permanently pointing to the equivalent /customers URL. Most HTTP clients (browsers, curl, requests, axios, official SDKs, Postman) follow redirects automatically, so traffic keeps working, but you spend an extra round-trip per call and rely on redirect semantics. Migrate before that date.

Can I migrate one resource group at a time?

Yes. The customer mirrors are independent per resource group (customers, bank accounts, wallets, virtual accounts, etc.). You can switch your customer-creation flow over this week and your bank-account-creation flow next week without coordination. Each endpoint accepts the new path independently.

Will I get duplicate webhook events during the transition?

Yes, every create and update emits both receiver.* and customer.* if you are subscribed to both. We dual-emit so you can migrate handlers in any order. Subscribe to one set or the other to avoid handling the same event twice.

Do I need to migrate my stored IDs?

No. All IDs keep the re_ prefix. The same ID works with both /receivers and /customers endpoints. We are renaming the API surface, not the underlying resource.

How do I report issues with the migration?

Use the feedback button in the dashboard (under your profile dropdown) or email support@blindpay.com with migration in the subject. Including the request ID from a deprecated response (x-blindpay-request-id header) speeds up the lookup.