> 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/guides/onboard-a-subscriber.md).

# Onboard a subscriber

Walkthrough for end-to-end subscriber onboarding: collect customer details, create the subscriber, attach a subscription, and let the activation machinery (RADIUS provisioning, first invoice) take over.

This guide also doubles as the writing template for "embed an OpenAPI operation inside a tutorial" — the operation block below is rendered directly from the live spec at [`openapi/share-api.json`](https://github.com/Share-Internet/share-api/blob/main/docs-site/openapi/share-api.json).

## Flow at a glance

```mermaid
sequenceDiagram
  Partner->>Share: POST /v1/subscribers
  Share-->>Partner: 201 with subscriber id sub_...
  Partner->>Share: POST /v1/subscriptions with subscriberId, planId, demarcationPointId
  Share-->>Partner: 201 with subscription id sbn_..., status PENDING
  Note over Share: First-payment collection drives the PENDING to ACTIVE transition.
  Partner->>Share: Push payment (or wait for the customer to pay via paybill)
  Share-->>Partner: payment.completed webhook
  Note over Share: Subscription is now ACTIVE, RADIUS credentials provisioned.
```

## Step 1 — Create the subscriber

The first call records the customer's identity. No plan or network state is attached yet — that happens on the next step.

> The block above is GitBook's native OpenAPI operation embed. Update the decorator in `apps/api/src/v1/subscribers/subscribers.controller.ts`, run `npm run docs:openapi`, commit the refreshed `share-api.json`, and this page re-renders automatically on the next sync.

## Step 2 — Attach a subscription

Pick the plan and the demarcation point. The subscription is created in `PENDING` until the first payment lands.

```bash
curl -sS https://api.share.inc/v1/subscriptions \
  -X POST \
  -H "X-Access-Id: <your-access-id>" \
  -H "X-Access-Secret: <your-access-secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "subscriberId": "sub_01HXYZ...",
    "planId": "pln_01HABC...",
    "demarcationPointId": "dmp_01HDEF..."
  }'
```

## Step 3 — Let activation happen

Once the first payment is collected (via STK push or partner-side collection), Share emits a `payment.completed` webhook and the subscription transitions to `ACTIVE`. RADIUS credentials are provisioned in the same hop.

See [Webhooks → Event catalog](/webhooks/event-catalog.md) for the full event list and payload shapes.

## Cleanup / cancellation

To cancel mid-cycle, `DELETE /v1/subscriptions/{id}` — the customer finishes the current paid cycle and is then suspended. Hard-deletion of a subscriber is intentionally not supported via the public API.