--- title: '"Receivers" renamed to "Customers"' description: We're renaming "Receivers" to "Customers" across the entire BlindPay platform. Both endpoints will work during a 1-month transition period. date: 2026-06-04 category: Migration categoryType: update isChangelog: true --- 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: ```json { "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 | SDK | Now (transition) | At/after sunset | | ------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Node.js | Minor release adds `customers`, marks `receivers` `@deprecated` in JSDoc. | Next major (4.0.0) removes `receivers`. | | Python | Minor release adds `customers`, marks `receivers` deprecated with warning. | Next major (2.0.0) removes `receivers`. | | Go | Minor release adds `customers` package, `// Deprecated:` on `receivers`. | **No v2 planned for this rename.** `receivers` stays as a deprecated forwarder in v1. | | PHP | Minor release adds `customers`, marks `receivers` `@deprecated` in PHPDoc. | Next major (2.0.0) removes `receivers`. | | Swift | Minor release adds `customers`, `@available(*, deprecated)` on `receivers`. | Next major (2.0.0) removes `receivers`. | 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: ```diff - 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 HTTP/1.1 200 OK Deprecation: true Sunset: Fri, 03 Jul 2026 00:00:00 GMT Link: ; 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.