> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/api-reference/subscribers.md).

# Subscribers

Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.

## List subscribers

> Returns the paginated set of subscribers owned by the authenticated provider, with optional filtering and sorting.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"SubscriberResponseDto":{"properties":{"address":{"$ref":"#/components/schemas/AddressDto"},"assignedPackageId":{"description":"Share's internal package reference","type":"object"},"billingCycleEnd":{"description":"ISO date of billing expiry","format":"date-time","type":"object"},"billingCycleStart":{"description":"ISO date of current billing period start","format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"email":{"type":"object"},"externalUserId":{"description":"Subscriber ID in the partner's platform","type":"string"},"firstName":{"type":"string"},"id":{"description":"Share internal identifier","type":"string"},"lastName":{"type":"object"},"metadata":{"description":"Arbitrary key-value metadata","type":"object"},"nextPlanId":{"description":"Queued plan ID for next billing cycle (mid-cycle change or migration)","format":"uuid","type":"object"},"nextPlanName":{"description":"Human-readable label of the queued plan","type":"object"},"packageName":{"description":"Human-readable plan label","type":"object"},"paymentStatus":{"description":"Payment status aggregated across the subscriber’s live subscriptions (an ACTIVE subscription wins over PENDING/SCHEDULED). `null` when the subscriber has no subscription (no payment obligation).","enum":["active","pending","suspended","overdue"],"nullable":true,"type":"string"},"phone":{"type":"object"},"planChangeEffectiveDate":{"description":"ISO date when the queued plan change takes effect (current billing cycle end date)","format":"date-time","type":"object"},"pppoeUsername":{"description":"PPPoE username generated by Share","type":"object"},"providerId":{"description":"Owning provider (partner) id","format":"uuid","type":"string"},"providerName":{"description":"Owning provider display name (network name); null when the provider has none on file","nullable":true,"type":"object"},"serviceHandle":{"description":"Stable 13-digit handle derived from a subscriber-scoped sequence and the owning provider country code. Read-only and deterministic — safe to expose in support tooling and partner integrations as a stand-in for the internal UUID.","pattern":"^\\d{13}$","type":"string"},"updatedAt":{"format":"date-time","type":"object"}},"required":["id","providerId","serviceHandle","externalUserId","firstName","createdAt"],"type":"object"},"AddressDto":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"object"},"region":{"type":"object"},"street":{"type":"string"}},"required":["street","city","country"],"type":"object"}}},"paths":{"/v1/subscribers":{"get":{"description":"Returns the paginated set of subscribers owned by the authenticated provider, with optional filtering and sorting.","operationId":"SubscribersController_listSubscribers_v1","parameters":[{"description":"1-based page number. Defaults to 1 when omitted.","in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"type":"number"}},{"description":"Number of items per page. Capped at 100 server-side. Defaults to 20 when omitted.","in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"number"}},{"description":"Free-text search across `firstName`, `lastName`, `email`, and `phone`. Case-insensitive substring match.","in":"query","name":"search","required":false,"schema":{"type":"string"}},{"description":"Derived subscription-status filter. Subscribers with at least one subscription in this state are returned. `EXPIRED` and `SUSPENDED` are filter-only aliases (see Subscriber Lifecycle guide).","in":"query","name":"subscriptionStatus","required":false,"schema":{"enum":["ACTIVE","EXPIRED","SUSPENDED"],"type":"string"}},{"description":"Filter to subscribers whose active subscription uses this plan.","in":"query","name":"planId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Field to sort by. Defaults to `createdAt`. Allowed: `createdAt`, `firstName`, `lastName`, `email`.","in":"query","name":"sortBy","required":false,"schema":{"type":"string"}},{"description":"Sort direction. Defaults to `desc` (newest first).","in":"query","name":"sortDirection","required":false,"schema":{"enum":["asc","desc"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/SubscriberResponseDto"},"type":"array"},"success":{"type":"boolean"}}}]}}},"description":"Paginated list of subscribers."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"List subscribers","tags":["Subscribers"]}}}}
```

## Create a subscriber

> Creates a subscriber under the authenticated provider. Plan assignment, CPE creation, and demarcation-point selection are performed separately via \`POST /v1/subscriptions\`. Sending any of those fields on this endpoint returns 400.\
> \
> Existing PPPoE credentials may be supplied via the optional \`pppoeUsername\`/\`pppoePassword\` pair (DEV-1207) — they are stored on the CPE at import time so migration reuses them; credential rotation still lives on \`/v1/subscriptions\`.\
> \
> The optional \`radiusIpAssignment\` object (DEV-1220) captures the subscriber's RADIUS IP scenario on that same CPE; it requires the PPPoE credential pair. Only the pool modes (\`DEFAULT\_POOL\`, \`CUSTOM\_POOL\`) are accepted at create time — \`STATIC\_IP\` and \`DUAL\_UPLINK\` need a demarcation point for uniqueness validation and are rejected with 400 \`STATIC\_MODE\_REQUIRES\_DEMARCATION\_POINT\`; set them via \`PATCH /v1/subscriptions/:id\` once the subscription exists. Omitted = demarcation-point default behavior. The subscriber is created first, then the assignment is applied — a rejected assignment (e.g. 422 \`CPE\_NOT\_FOUND\`) leaves the subscriber created and returns its id in the error \`data.id\`; retry via \`PATCH /v1/subscriptions/:id\`. The assignment lands on the import-time CPE, which the subscription's credentials must adopt (same \`pppoeUsername\`) for it to take effect — a different username strands the assignment on the unused import CPE.\
> \
> Provenance: pass the optional \`X-Inbound-Channel\` header to mark the request as \`API\` (default) or \`BULK\` (offline importer). The \`SPLYNX\` channel is reserved for the integrations adapter and is rejected here.\
> \
> \*\*Error codes:\*\* \`NOT\_ALLOWED\` (400) when any of \`planId\`, \`cpeMacAddress\`, or \`demarcationPointId\` is sent (those fields live on \`/v1/subscriptions\`). See the \[Error codes]\(../errors/error-codes.md) reference.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"CreateSubscriberRequestDto":{"properties":{"address":{"$ref":"#/components/schemas/AddressRequestDto"},"email":{"type":"string"},"externalUserId":{"description":"Subscriber ID in the partner's platform","type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"metadata":{"description":"Arbitrary key-value metadata for the subscriber","type":"object"},"phone":{"type":"string"},"pppoePassword":{"description":"The subscriber's existing PPPoE password. Supply together with `pppoeUsername` — a one-sided pair is ignored. Never logged.","type":"string"},"pppoeUsername":{"description":"The subscriber's existing PPPoE username, captured at import time so migration reuses it instead of issuing a new one. Stored on the CPE (`authType=PPPOE`); supply together with `pppoePassword` — a one-sided pair is ignored.","type":"string"},"radiusIpAssignment":{"allOf":[{"$ref":"#/components/schemas/RadiusIpAssignmentDto"}],"description":"RADIUS IP assignment for the CPE captured at import time (static IP, default/custom pool, or dual-mode uplink). Requires the `pppoeUsername`/`pppoePassword` pair — that is what materialises the CPE this assignment is stored on. Omit for the demarcation-point default behavior; the assignment can also be set, changed, or cleared later via `PATCH /v1/subscriptions/:id`."}},"required":["externalUserId","firstName","email","phone"],"type":"object"},"AddressRequestDto":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"string"},"region":{"type":"string"},"street":{"type":"string"}},"type":"object"},"RadiusIpAssignmentDto":{"properties":{"ip":{"description":"IPv4 address to pin. Required for `STATIC_IP` and `DUAL_UPLINK`; rejected for the pool modes. Must be unique per RADIUS instance — a duplicate returns 422 `STATIC_IP_CONFLICT`.","type":"string"},"mode":{"description":"IP-assignment scenario for the RADIUS reply. `STATIC_IP` pins `ip` and suppresses the PPP profile attribute; `DEFAULT_POOL` suppresses the profile attribute so the NAS default pool applies; `CUSTOM_POOL` replies `Framed-Pool = poolName`; `DUAL_UPLINK` pins `ip` while keeping the demarcation-point profile attribute.","enum":["STATIC_IP","DEFAULT_POOL","CUSTOM_POOL","DUAL_UPLINK"],"type":"string"},"poolName":{"description":"NAS pool name to reply as `Framed-Pool`. Required for `CUSTOM_POOL`; rejected for the other modes.","type":"string"}},"required":["mode"],"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"CreateSubscriberResponseDto":{"properties":{"address":{"$ref":"#/components/schemas/AddressDto"},"assignedPackageId":{"description":"Share's internal package reference","type":"object"},"billingCycleEnd":{"description":"ISO date of billing expiry (activation)","format":"date-time","type":"object"},"billingCycleStart":{"description":"ISO date of current billing period start (activation)","format":"date-time","type":"object"},"createdAt":{"description":"Timestamp of subscriber creation in Share","format":"date-time","type":"string"},"email":{"type":"object"},"externalUserId":{"description":"Subscriber ID in the partner's platform","type":"string"},"firstName":{"type":"string"},"id":{"description":"Share internal identifier","type":"string"},"lastName":{"type":"object"},"metadata":{"description":"Arbitrary key-value metadata","type":"object"},"nextPlanId":{"description":"Queued plan ID for next billing cycle (mid-cycle change or migration)","format":"uuid","type":"object"},"nextPlanName":{"description":"Human-readable label of the queued plan","type":"object"},"packageName":{"description":"Human-readable plan label","type":"object"},"paymentStatus":{"description":"Payment status derived from the latest subscription. `null` when the subscriber has no subscription (no payment obligation) — e.g. a freshly created subscriber before any subscription exists.","enum":["active","pending","suspended","overdue"],"nullable":true,"type":"string"},"phone":{"type":"object"},"planChangeEffectiveDate":{"description":"ISO date when the queued plan change takes effect (current billing cycle end date)","format":"date-time","type":"object"},"pppoeUsername":{"description":"PPPoE username generated by Share","type":"object"},"serviceHandle":{"description":"Stable 13-digit handle derived from a subscriber-scoped sequence and the owning provider country code. Read-only and deterministic — safe to expose in support tooling and partner integrations as a stand-in for the internal UUID.","pattern":"^\\d{13}$","type":"string"}},"required":["id","serviceHandle","externalUserId","firstName","address","createdAt"],"type":"object"},"AddressDto":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"object"},"region":{"type":"object"},"street":{"type":"string"}},"required":["street","city","country"],"type":"object"}}},"paths":{"/v1/subscribers":{"post":{"description":"Creates a subscriber under the authenticated provider. Plan assignment, CPE creation, and demarcation-point selection are performed separately via `POST /v1/subscriptions`. Sending any of those fields on this endpoint returns 400.\n\nExisting PPPoE credentials may be supplied via the optional `pppoeUsername`/`pppoePassword` pair (DEV-1207) — they are stored on the CPE at import time so migration reuses them; credential rotation still lives on `/v1/subscriptions`.\n\nThe optional `radiusIpAssignment` object (DEV-1220) captures the subscriber's RADIUS IP scenario on that same CPE; it requires the PPPoE credential pair. Only the pool modes (`DEFAULT_POOL`, `CUSTOM_POOL`) are accepted at create time — `STATIC_IP` and `DUAL_UPLINK` need a demarcation point for uniqueness validation and are rejected with 400 `STATIC_MODE_REQUIRES_DEMARCATION_POINT`; set them via `PATCH /v1/subscriptions/:id` once the subscription exists. Omitted = demarcation-point default behavior. The subscriber is created first, then the assignment is applied — a rejected assignment (e.g. 422 `CPE_NOT_FOUND`) leaves the subscriber created and returns its id in the error `data.id`; retry via `PATCH /v1/subscriptions/:id`. The assignment lands on the import-time CPE, which the subscription's credentials must adopt (same `pppoeUsername`) for it to take effect — a different username strands the assignment on the unused import CPE.\n\nProvenance: pass the optional `X-Inbound-Channel` header to mark the request as `API` (default) or `BULK` (offline importer). The `SPLYNX` channel is reserved for the integrations adapter and is rejected here.\n\n**Error codes:** `NOT_ALLOWED` (400) when any of `planId`, `cpeMacAddress`, or `demarcationPointId` is sent (those fields live on `/v1/subscriptions`). See the [Error codes](../errors/error-codes.md) reference.","operationId":"SubscribersController_createSubscriber_v1","parameters":[{"description":"Ingestion-time provenance tag. `API` (default) marks an interactive partner request; `BULK` marks an offline importer batch. The `SPLYNX` value is reserved for the integrations adapter and is rejected here.","in":"header","name":"x-inbound-channel","required":false,"schema":{"enum":["API","BULK"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriberRequestDto"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/CreateSubscriberResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"The newly created subscriber."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"422":{"content":{"application/json":{"schema":{"properties":{"data":{"description":"Context for recovery — e.g. the created subscriber id when a create-time side effect is rejected after the create committed.","nullable":true,"properties":{"id":{"format":"uuid","type":"string"}},"type":"object"},"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"enum":["STATIC_IP_CONFLICT","CPE_NOT_FOUND"],"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"radiusIpAssignment rejected after the subscriber was created (codes: STATIC_IP_CONFLICT, CPE_NOT_FOUND) — `data.id` carries the created subscriber id for recovery."},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Create a subscriber","tags":["Subscribers"]}}}}
```

## Get a subscriber

> Returns a single subscriber owned by the authenticated provider.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"SubscriberResponseDto":{"properties":{"address":{"$ref":"#/components/schemas/AddressDto"},"assignedPackageId":{"description":"Share's internal package reference","type":"object"},"billingCycleEnd":{"description":"ISO date of billing expiry","format":"date-time","type":"object"},"billingCycleStart":{"description":"ISO date of current billing period start","format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"email":{"type":"object"},"externalUserId":{"description":"Subscriber ID in the partner's platform","type":"string"},"firstName":{"type":"string"},"id":{"description":"Share internal identifier","type":"string"},"lastName":{"type":"object"},"metadata":{"description":"Arbitrary key-value metadata","type":"object"},"nextPlanId":{"description":"Queued plan ID for next billing cycle (mid-cycle change or migration)","format":"uuid","type":"object"},"nextPlanName":{"description":"Human-readable label of the queued plan","type":"object"},"packageName":{"description":"Human-readable plan label","type":"object"},"paymentStatus":{"description":"Payment status aggregated across the subscriber’s live subscriptions (an ACTIVE subscription wins over PENDING/SCHEDULED). `null` when the subscriber has no subscription (no payment obligation).","enum":["active","pending","suspended","overdue"],"nullable":true,"type":"string"},"phone":{"type":"object"},"planChangeEffectiveDate":{"description":"ISO date when the queued plan change takes effect (current billing cycle end date)","format":"date-time","type":"object"},"pppoeUsername":{"description":"PPPoE username generated by Share","type":"object"},"providerId":{"description":"Owning provider (partner) id","format":"uuid","type":"string"},"providerName":{"description":"Owning provider display name (network name); null when the provider has none on file","nullable":true,"type":"object"},"serviceHandle":{"description":"Stable 13-digit handle derived from a subscriber-scoped sequence and the owning provider country code. Read-only and deterministic — safe to expose in support tooling and partner integrations as a stand-in for the internal UUID.","pattern":"^\\d{13}$","type":"string"},"updatedAt":{"format":"date-time","type":"object"}},"required":["id","providerId","serviceHandle","externalUserId","firstName","createdAt"],"type":"object"},"AddressDto":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"object"},"region":{"type":"object"},"street":{"type":"string"}},"required":["street","city","country"],"type":"object"}}},"paths":{"/v1/subscribers/{id}":{"get":{"description":"Returns a single subscriber owned by the authenticated provider.","operationId":"SubscribersController_getSubscriber_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SubscriberResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"The requested subscriber."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Get a subscriber","tags":["Subscribers"]}}}}
```

## Update a subscriber

> Updates identity fields on a subscriber (name, email, phone, address, metadata). Plan changes and credential rotation are performed via \`PATCH /v1/subscriptions/:id\`.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"UpdateSubscriberRequestDto":{"properties":{"address":{"$ref":"#/components/schemas/AddressRequestDto"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"metadata":{"description":"Arbitrary key-value metadata for the subscriber","type":"object"},"phone":{"type":"string"}},"type":"object"},"AddressRequestDto":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"string"},"region":{"type":"string"},"street":{"type":"string"}},"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"SubscriberResponseDto":{"properties":{"address":{"$ref":"#/components/schemas/AddressDto"},"assignedPackageId":{"description":"Share's internal package reference","type":"object"},"billingCycleEnd":{"description":"ISO date of billing expiry","format":"date-time","type":"object"},"billingCycleStart":{"description":"ISO date of current billing period start","format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"email":{"type":"object"},"externalUserId":{"description":"Subscriber ID in the partner's platform","type":"string"},"firstName":{"type":"string"},"id":{"description":"Share internal identifier","type":"string"},"lastName":{"type":"object"},"metadata":{"description":"Arbitrary key-value metadata","type":"object"},"nextPlanId":{"description":"Queued plan ID for next billing cycle (mid-cycle change or migration)","format":"uuid","type":"object"},"nextPlanName":{"description":"Human-readable label of the queued plan","type":"object"},"packageName":{"description":"Human-readable plan label","type":"object"},"paymentStatus":{"description":"Payment status aggregated across the subscriber’s live subscriptions (an ACTIVE subscription wins over PENDING/SCHEDULED). `null` when the subscriber has no subscription (no payment obligation).","enum":["active","pending","suspended","overdue"],"nullable":true,"type":"string"},"phone":{"type":"object"},"planChangeEffectiveDate":{"description":"ISO date when the queued plan change takes effect (current billing cycle end date)","format":"date-time","type":"object"},"pppoeUsername":{"description":"PPPoE username generated by Share","type":"object"},"providerId":{"description":"Owning provider (partner) id","format":"uuid","type":"string"},"providerName":{"description":"Owning provider display name (network name); null when the provider has none on file","nullable":true,"type":"object"},"serviceHandle":{"description":"Stable 13-digit handle derived from a subscriber-scoped sequence and the owning provider country code. Read-only and deterministic — safe to expose in support tooling and partner integrations as a stand-in for the internal UUID.","pattern":"^\\d{13}$","type":"string"},"updatedAt":{"format":"date-time","type":"object"}},"required":["id","providerId","serviceHandle","externalUserId","firstName","createdAt"],"type":"object"},"AddressDto":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"object"},"region":{"type":"object"},"street":{"type":"string"}},"required":["street","city","country"],"type":"object"}}},"paths":{"/v1/subscribers/{id}":{"put":{"description":"Updates identity fields on a subscriber (name, email, phone, address, metadata). Plan changes and credential rotation are performed via `PATCH /v1/subscriptions/:id`.","operationId":"SubscribersController_updateSubscriber_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriberRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SubscriberResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"The updated subscriber."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Update a subscriber","tags":["Subscribers"]}}}}
```

## Delete a subscriber

> Permanently removes a subscriber owned by the authenticated provider.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"SubscriberResponseDto":{"properties":{"address":{"$ref":"#/components/schemas/AddressDto"},"assignedPackageId":{"description":"Share's internal package reference","type":"object"},"billingCycleEnd":{"description":"ISO date of billing expiry","format":"date-time","type":"object"},"billingCycleStart":{"description":"ISO date of current billing period start","format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"email":{"type":"object"},"externalUserId":{"description":"Subscriber ID in the partner's platform","type":"string"},"firstName":{"type":"string"},"id":{"description":"Share internal identifier","type":"string"},"lastName":{"type":"object"},"metadata":{"description":"Arbitrary key-value metadata","type":"object"},"nextPlanId":{"description":"Queued plan ID for next billing cycle (mid-cycle change or migration)","format":"uuid","type":"object"},"nextPlanName":{"description":"Human-readable label of the queued plan","type":"object"},"packageName":{"description":"Human-readable plan label","type":"object"},"paymentStatus":{"description":"Payment status aggregated across the subscriber’s live subscriptions (an ACTIVE subscription wins over PENDING/SCHEDULED). `null` when the subscriber has no subscription (no payment obligation).","enum":["active","pending","suspended","overdue"],"nullable":true,"type":"string"},"phone":{"type":"object"},"planChangeEffectiveDate":{"description":"ISO date when the queued plan change takes effect (current billing cycle end date)","format":"date-time","type":"object"},"pppoeUsername":{"description":"PPPoE username generated by Share","type":"object"},"providerId":{"description":"Owning provider (partner) id","format":"uuid","type":"string"},"providerName":{"description":"Owning provider display name (network name); null when the provider has none on file","nullable":true,"type":"object"},"serviceHandle":{"description":"Stable 13-digit handle derived from a subscriber-scoped sequence and the owning provider country code. Read-only and deterministic — safe to expose in support tooling and partner integrations as a stand-in for the internal UUID.","pattern":"^\\d{13}$","type":"string"},"updatedAt":{"format":"date-time","type":"object"}},"required":["id","providerId","serviceHandle","externalUserId","firstName","createdAt"],"type":"object"},"AddressDto":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"postalCode":{"type":"object"},"region":{"type":"object"},"street":{"type":"string"}},"required":["street","city","country"],"type":"object"}}},"paths":{"/v1/subscribers/{id}":{"delete":{"description":"Permanently removes a subscriber owned by the authenticated provider.","operationId":"SubscribersController_deleteSubscriber_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SubscriberResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Subscriber deleted."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Delete a subscriber","tags":["Subscribers"]}}}}
```

## Deactivate a subscriber (subscriber-wide or scoped)

> Deactivates a subscriber and records a reason + free-text note on every affected subscription. Body \`subscriptionIds\` is optional — when omitted, every non-INACTIVE subscription on the subscriber is deactivated; when supplied, only the listed subscriptions are touched. Per-subscription side effects (billing cycle cancelled, subscription → INACTIVE with the recorded reason) always run on the targeted set. Subscriber-wide side effects (suspension, network access removal, suspension notification) only fire when every one of the subscriber's subscriptions is now INACTIVE — partial-scope calls that leave any subscription live keep the subscriber active.\
> \
> \*\*Error codes:\*\* \`NOT\_FOUND\` (404) when the subscriber does not exist under the authenticated provider; \`ALREADY\_INACTIVE\` (409) when the targeted set is empty (every requested subscription is already INACTIVE, or the subscriber has no subscriptions to deactivate).

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"DeactivateSubscriberRequestDto":{"properties":{"inactiveReason":{"description":"Domain reason persisted on every affected subscription. Use `ADMIN_DEACTIVATED` for the standard partner-initiated path.","enum":["GRACE_EXPIRED","ADMIN_DEACTIVATED","PLAN_REMOVED","NO_PLAN_ASSIGNED","PLAN_DISABLED","ACTIVATION_GRACE_EXPIRED"],"type":"string"},"inactiveReasonNote":{"description":"Free-text note recorded alongside `inactiveReason` for audit / support context. Max 500 chars — longer values are rejected with 400. Persisted on every affected subscription.","maxLength":500,"type":"string"},"subscriptionIds":{"description":"Optional scope: when supplied, only the listed subscriptions are deactivated and any non-listed subscription on the subscriber is left untouched. When omitted, every non-INACTIVE subscription on the subscriber is deactivated (subscriber-wide). The subscriber is suspended only when every one of the subscriber's subscriptions becomes INACTIVE.","items":{"format":"uuid","type":"string"},"type":"array"}},"required":["inactiveReason"],"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"DeactivateSubscriberResponseDto":{"properties":{"affectedSubscriptionIds":{"description":"Subscriptions that transitioned to INACTIVE on this call. Always non-empty for a 200 response (an empty target set surfaces as 409 `ALREADY_INACTIVE`).","items":{"format":"uuid","type":"string"},"type":"array"},"subscriberSuspended":{"description":"Whether the subscriber itself was suspended. True only when every one of the subscriber's subscriptions is now INACTIVE — partial-scope calls that leave any subscription live return false.","type":"boolean"},"terminal":{"description":"Terminal path taken. Currently only `DEACTIVATED` is emitted — an already-inactive call surfaces as 409 `ALREADY_INACTIVE` rather than a terminal on this response.","enum":["DEACTIVATED"],"type":"string"}},"required":["terminal","affectedSubscriptionIds","subscriberSuspended"],"type":"object"}}},"paths":{"/v1/subscribers/{id}/deactivate":{"post":{"description":"Deactivates a subscriber and records a reason + free-text note on every affected subscription. Body `subscriptionIds` is optional — when omitted, every non-INACTIVE subscription on the subscriber is deactivated; when supplied, only the listed subscriptions are touched. Per-subscription side effects (billing cycle cancelled, subscription → INACTIVE with the recorded reason) always run on the targeted set. Subscriber-wide side effects (suspension, network access removal, suspension notification) only fire when every one of the subscriber's subscriptions is now INACTIVE — partial-scope calls that leave any subscription live keep the subscriber active.\n\n**Error codes:** `NOT_FOUND` (404) when the subscriber does not exist under the authenticated provider; `ALREADY_INACTIVE` (409) when the targeted set is empty (every requested subscription is already INACTIVE, or the subscriber has no subscriptions to deactivate).","operationId":"SubscribersController_deactivateSubscriber_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateSubscriberRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/DeactivateSubscriberResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Subscriber deactivated; affected subscriptions returned."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Deactivate a subscriber (subscriber-wide or scoped)","tags":["Subscribers"]}}}}
```

## List a subscriber's settled payments + current balance

> Returns the cursor-paginated history of settled payments for a subscriber, alongside the subscriber's current ledger balance. Only \`COMPLETED\` payments appear — pending and failed attempts are filtered server-side. Amounts are ledger-truthful and include offline paybill payments. Pagination: pass \`nextCursor\` from one page as the \`cursor\` query param of the next; \`hasMore=false\` marks the last page.\
> \
> \*\*Error codes:\*\* \`NOT\_FOUND\` (404) when the subscriber does not exist under the authenticated provider.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"ApiResponseDto":{"properties":{},"type":"object"},"ListSubscriberSettledPaymentsResponseDto":{"properties":{"balance":{"description":"Subscriber's current ledger balance at request time. Positive values are credit on file; negative values are outstanding debt.","type":"number"},"currency":{"description":"Currency of `balance` (and of the item amounts).","type":"string"},"hasMore":{"description":"`true` when there is at least one more page.","type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/SubscriberSettledPaymentItemDto"},"type":"array"},"limit":{"description":"Page size actually applied (after clamping).","maximum":100,"minimum":1,"type":"number"},"nextCursor":{"description":"Cursor for the next page when more pages remain; otherwise `null`. Pass it back as the `cursor` query param.","type":"object"}},"required":["items","balance","currency","limit","hasMore"],"type":"object"},"SubscriberSettledPaymentItemDto":{"properties":{"amount":{"description":"Ledger-truthful amount — summed over the credit entries of the settled deposit posting.","minimum":0,"type":"number"},"billId":{"description":"Billing cycle id the payment settled — `null` for one-time charge / ad-hoc settlements.","type":"object"},"createdAt":{"format":"date-time","type":"string"},"currency":{"type":"string"},"dueDate":{"description":"Due date of the obligation this payment settled: the billing cycle end date when the payment closed a cycle, the one-time charge expiry when it closed a charge, `null` for ad-hoc top-ups that match neither.","format":"date-time","type":"object"},"id":{"description":"Payment identifier. Doubles as the cursor handle for the next page.","type":"string"},"ledgerTransactionId":{"description":"Linked ledger transaction id — `null` for the rare COMPLETED row without a ledger posting yet.","type":"object"},"paymentDate":{"description":"Settlement time (creation time when unknown).","format":"date-time","type":"string"},"paymentMethod":{"description":"Payment method the settlement arrived on.","enum":["CARD","BANK","MOBILE_MONEY","WALLET","CRYPTO"],"type":"string"},"planId":{"format":"uuid","type":"object"},"planName":{"type":"object"},"planType":{"type":"object"},"speed":{"description":"Display speed e.g. `\"50mbps\"`. `\"—\"` when unknown.","type":"string"},"status":{"description":"Always `COMPLETED` — this feed filters out non-settled rows on the server.","enum":["COMPLETED"],"type":"string"}},"required":["id","amount","currency","status","paymentMethod","paymentDate","createdAt","speed"],"type":"object"}}},"paths":{"/v1/subscribers/{id}/payments":{"get":{"description":"Returns the cursor-paginated history of settled payments for a subscriber, alongside the subscriber's current ledger balance. Only `COMPLETED` payments appear — pending and failed attempts are filtered server-side. Amounts are ledger-truthful and include offline paybill payments. Pagination: pass `nextCursor` from one page as the `cursor` query param of the next; `hasMore=false` marks the last page.\n\n**Error codes:** `NOT_FOUND` (404) when the subscriber does not exist under the authenticated provider.","operationId":"SubscribersController_listSettledPayments_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Cursor handle — the `nextCursor` value returned by the previous page (the last payment id of that page). Omit for the first page.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Page size. Clamped to 100.","in":"query","name":"limit","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"number"}},{"description":"Restrict the result to payments whose linked subscription is on this plan.","in":"query","name":"planId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"ISO-8601 lower bound on the payment creation time.","in":"query","name":"startDate","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"ISO-8601 upper bound on the payment creation time.","in":"query","name":"endDate","required":false,"schema":{"format":"date-time","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/ListSubscriberSettledPaymentsResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Settled payments + current balance."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"List a subscriber's settled payments + current balance","tags":["Subscribers"]}}}}
```

## Send a subscriber their paybill instructions

> Dispatches the paybill-instructions prompt to the subscriber on SMS (default) or email. Intended for re-sending payment details on demand — repeat calls always dispatch again (no deduplication against earlier sends). The response reflects whether the message was actually dispatched on the requested channel.\
> \
> \*\*Error codes:\*\* \`NOT\_FOUND\` (404) when the subscriber does not exist under the authenticated provider.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscribers are end-customers of an ISP. This module covers identity lifecycle only: create, list, get, update, delete. Plan, CPE, and credential assignment live under Subscriptions. For the full lifecycle including activation, suspension, and termination, see the Subscriber Lifecycle guide.","name":"Subscribers"}],"security":[{"X-Access-Secret":[]},{"X-Access-Id":[]}],"components":{"securitySchemes":{"X-Access-Secret":{"description":"Provider Access Secret Key (JWT)","in":"header","name":"X-Access-Secret","type":"apiKey"},"X-Access-Id":{"description":"Provider Access ID","in":"header","name":"X-Access-Id","type":"apiKey"}},"schemas":{"SendPaymentInstructionsRequestDto":{"properties":{"channel":{"default":"sms","description":"Channel to deliver the paybill prompt on. Defaults to `sms`. When omitted the endpoint always uses SMS — it does not fan out to both.","enum":["sms","email"],"type":"string"}},"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"SendPaymentInstructionsResponseDto":{"properties":{"success":{"description":"Whether the communications router actually dispatched the prompt on the requested channel. `false` indicates the router skipped the send (missing template, missing recipient address).","type":"boolean"}},"required":["success"],"type":"object"}}},"paths":{"/v1/subscribers/{id}/send-payment-instructions":{"post":{"description":"Dispatches the paybill-instructions prompt to the subscriber on SMS (default) or email. Intended for re-sending payment details on demand — repeat calls always dispatch again (no deduplication against earlier sends). The response reflects whether the message was actually dispatched on the requested channel.\n\n**Error codes:** `NOT_FOUND` (404) when the subscriber does not exist under the authenticated provider.","operationId":"SubscribersController_sendPaymentInstructions_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPaymentInstructionsRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SendPaymentInstructionsResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Communication dispatched."},"400":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"rejectionReasons":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}},"type":"object"},"type":"array"},"success":{"type":"boolean"}}}}},"description":"Validation failed"},"401":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/json":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Send a subscriber their paybill instructions","tags":["Subscribers"]}}}}
```