> 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/billing.md).

# Billing

Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.

## List bills for a subscriber

> Returns the paginated set of billing cycles for a subscriber, ordered by start date (newest first). Each \`billId\` in the response can be supplied to the invoice and receipt endpoints below.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"},"BillSummaryEntity":{"properties":{"amount":{"type":"number"},"billId":{"description":"BillingCycle ID — use as billId on invoice/receipt routes","format":"uuid","type":"string"},"createdAt":{"format":"date-time","type":"string"},"currency":{"type":"string"},"endDate":{"format":"date-time","type":"string"},"graceEndsAt":{"description":"DEV-727 — activation-grace deadline (`BillingCycle.activationGraceExpiresAt`). Null outside the activation-grace window.","format":"date-time","nullable":true,"type":"string"},"paidAt":{"description":"DEV-727 — `PaymentTransaction.completedAt` for the cycle's linked transaction. Null when no settled payment is attached.","format":"date-time","nullable":true,"type":"string"},"paymentStatus":{"enum":["PENDING","EXTERNAL","PAID","WAIVED","SETTLEMENT_FAILED"],"type":"string"},"paymentTransactionId":{"nullable":true,"type":"object"},"planId":{"format":"uuid","type":"string"},"startDate":{"format":"date-time","type":"string"},"status":{"enum":["SCHEDULED","EXTERNAL","ACTIVE","OVERDUE","SUSPENDED","COMPLETED","CANCELLED","ARCHIVED"],"type":"string"},"subscriberId":{"format":"uuid","type":"string"},"subscriptionId":{"format":"uuid","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["billId","subscriberId","subscriptionId","planId","amount","currency","status","paymentStatus","startDate","endDate","paymentTransactionId","paidAt","graceEndsAt","createdAt","updatedAt"],"type":"object"}}},"paths":{"/v1/billing/{subscriberId}":{"get":{"description":"Returns the paginated set of billing cycles for a subscriber, ordered by start date (newest first). Each `billId` in the response can be supplied to the invoice and receipt endpoints below.","operationId":"BillingController_listBills_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}},{"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":"Filter by `BillingCycle.status`. Omit to include every cycle status.","in":"query","name":"status","required":false,"schema":{"enum":["SCHEDULED","EXTERNAL","ACTIVE","OVERDUE","SUSPENDED","COMPLETED","CANCELLED","ARCHIVED"],"type":"string"}},{"description":"Filter by `BillingCycle.paymentStatus`. Omit to include every payment status.","in":"query","name":"paymentStatus","required":false,"schema":{"enum":["PENDING","EXTERNAL","PAID","WAIVED","SETTLEMENT_FAILED"],"type":"string"}},{"description":"Inclusive lower bound on `startDate` (ISO-8601).","in":"query","name":"from","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Inclusive upper bound on `startDate` (ISO-8601).","in":"query","name":"to","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"When `true`, includes billing cycles whose subscription is archived. Omit or set to `false` to see only cycles from active subscriptions.","in":"query","name":"includeArchived","required":false,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/BillSummaryEntity"},"type":"array"},"success":{"type":"boolean"}}}]}}},"description":"Paginated list of bills."},"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 bills for a subscriber","tags":["Billing"]}}}}
```

## Get an invoice

> Returns a single invoice for a subscriber bill.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"},"InvoiceEntity":{"properties":{"amount":{"type":"number"},"billId":{"format":"uuid","type":"string"},"currency":{"type":"string"},"description":{"type":"string"},"dueDate":{"description":"Due-by date. Always populated for BillingCycle invoices; nullable for OneTimeCharge invoices (DEV-827) — `OneTimeCharge.expiresAt` is optional on the schema.","format":"date-time","nullable":true,"type":"string"},"issuedAt":{"format":"date-time","type":"string"},"items":{"items":{"$ref":"#/components/schemas/InvoiceItemEntity"},"type":"array"},"split":{"allOf":[{"$ref":"#/components/schemas/BillingSplitEntity"}],"description":"Revenue split breakdown for the cycle. Null when the cycle has no split policy stamped.","nullable":true,"type":"object"},"status":{"type":"string"},"subscriberId":{"format":"uuid","type":"string"}},"required":["billId","subscriberId","amount","currency","status","issuedAt","dueDate","description","items","split"],"type":"object"},"InvoiceItemEntity":{"properties":{"description":{"type":"string"},"quantity":{"type":"number"},"total":{"type":"number"},"unitPrice":{"type":"number"}},"required":["description","quantity","unitPrice","total"],"type":"object"},"BillingSplitEntity":{"properties":{"partnerAmount":{"type":"number"},"partnerPercent":{"description":"Partner (ISP) percentage (0-100)","type":"number"},"shareAmount":{"type":"number"},"sharePercent":{"description":"Share platform percentage (0-100)","type":"number"}},"required":["sharePercent","partnerPercent","shareAmount","partnerAmount"],"type":"object"}}},"paths":{"/v1/billing/{subscriberId}/invoice/{billId}":{"get":{"description":"Returns a single invoice for a subscriber bill.","operationId":"BillingController_getInvoice_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}},{"description":"Bill identifier (UUID).","in":"path","name":"billId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/InvoiceEntity"},"success":{"type":"boolean"}}}]}}},"description":"The requested invoice."},"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 an invoice","tags":["Billing"]}}}}
```

## Download an invoice as PDF

> Returns the rendered invoice as a downloadable PDF document.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"}}},"paths":{"/v1/billing/{subscriberId}/invoice/{billId}/pdf":{"get":{"description":"Returns the rendered invoice as a downloadable PDF document.","operationId":"BillingController_getInvoicePdf_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}},{"description":"Bill identifier (UUID).","in":"path","name":"billId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/pdf":{}},"description":"PDF invoice binary."},"400":{"content":{"application/pdf":{"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/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Download an invoice as PDF","tags":["Billing"]}}}}
```

## Email the invoice PDF to the subscriber

> Renders the invoice PDF and dispatches it to the subscriber by email. Delivery is asynchronous — the response confirms the email was enqueued, not that it reached the recipient.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"},"SendPdfResponseDto":{"properties":{"delivered":{"description":"True once the email has been enqueued for delivery. Final delivery state is reported separately by the communications service.","type":"boolean"},"messageId":{"description":"Provider message identifier, when available synchronously. Absent for asynchronous deliveries.","nullable":true,"type":"string"}},"required":["delivered"],"type":"object"}}},"paths":{"/v1/billing/{subscriberId}/invoice/{billId}/pdf/send":{"post":{"description":"Renders the invoice PDF and dispatches it to the subscriber by email. Delivery is asynchronous — the response confirms the email was enqueued, not that it reached the recipient.","operationId":"BillingController_sendInvoicePdf_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}},{"description":"Bill identifier (UUID).","in":"path","name":"billId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SendPdfResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Invoice email enqueued for delivery."},"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":"Email the invoice PDF to the subscriber","tags":["Billing"]}}}}
```

## Get a receipt

> Returns the receipt for a settled subscriber bill.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"},"ReceiptEntity":{"properties":{"amount":{"type":"number"},"billId":{"format":"uuid","type":"string"},"currency":{"type":"string"},"paidAt":{"format":"date-time","type":"string"},"paymentMethod":{"type":"string"},"receiptId":{"format":"uuid","type":"string"},"split":{"allOf":[{"$ref":"#/components/schemas/BillingSplitEntity"}],"description":"Revenue split breakdown for the cycle. Null when the cycle has no split policy stamped.","nullable":true,"type":"object"},"subscriberId":{"format":"uuid","type":"string"},"transactionReference":{"type":"string"}},"required":["receiptId","billId","subscriberId","amount","currency","paidAt","paymentMethod","transactionReference","split"],"type":"object"},"BillingSplitEntity":{"properties":{"partnerAmount":{"type":"number"},"partnerPercent":{"description":"Partner (ISP) percentage (0-100)","type":"number"},"shareAmount":{"type":"number"},"sharePercent":{"description":"Share platform percentage (0-100)","type":"number"}},"required":["sharePercent","partnerPercent","shareAmount","partnerAmount"],"type":"object"}}},"paths":{"/v1/billing/{subscriberId}/receipt/{billId}":{"get":{"description":"Returns the receipt for a settled subscriber bill.","operationId":"BillingController_getReceipt_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}},{"description":"Bill identifier (UUID).","in":"path","name":"billId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/ReceiptEntity"},"success":{"type":"boolean"}}}]}}},"description":"The requested receipt."},"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 receipt","tags":["Billing"]}}}}
```

## Download a receipt as PDF

> Returns the rendered receipt as a downloadable PDF document.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"}}},"paths":{"/v1/billing/{subscriberId}/receipt/{billId}/pdf":{"get":{"description":"Returns the rendered receipt as a downloadable PDF document.","operationId":"BillingController_getReceiptPdf_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}},{"description":"Bill identifier (UUID).","in":"path","name":"billId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/pdf":{}},"description":"PDF receipt binary."},"400":{"content":{"application/pdf":{"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/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Unauthorized — missing or invalid credentials"},"403":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Forbidden — insufficient permissions"},"404":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Resource not found"},"408":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Request timeout"},"500":{"content":{"application/pdf":{"schema":{"properties":{"error":{"type":"string"},"success":{"type":"boolean"}}}}},"description":"Internal server error"}},"summary":"Download a receipt as PDF","tags":["Billing"]}}}}
```

## Email the receipt PDF to the subscriber

> Renders the receipt PDF and dispatches it to the subscriber by email. Delivery is asynchronous — the response confirms the email was enqueued, not that it reached the recipient.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"},"SendPdfResponseDto":{"properties":{"delivered":{"description":"True once the email has been enqueued for delivery. Final delivery state is reported separately by the communications service.","type":"boolean"},"messageId":{"description":"Provider message identifier, when available synchronously. Absent for asynchronous deliveries.","nullable":true,"type":"string"}},"required":["delivered"],"type":"object"}}},"paths":{"/v1/billing/{subscriberId}/receipt/{billId}/pdf/send":{"post":{"description":"Renders the receipt PDF and dispatches it to the subscriber by email. Delivery is asynchronous — the response confirms the email was enqueued, not that it reached the recipient.","operationId":"BillingController_sendReceiptPdf_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}},{"description":"Bill identifier (UUID).","in":"path","name":"billId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/SendPdfResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Receipt email enqueued for delivery."},"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":"Email the receipt PDF to the subscriber","tags":["Billing"]}}}}
```

## Get subscriber billing status

> Returns the current billing-cycle and payment status for a subscriber.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"Subscriber billing surface: list bills (`BillingCycle`s), fetch invoice/receipt records, download PDF artefacts, and trigger PDF email delivery. Each `billId` maps to a `BillingCycle` row whose lifecycle is described in the Billing cycles concept guide. Settlement, split execution, and treasury reconciliation are internal — only the customer-facing artefacts are exposed here.","name":"Billing"}],"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"},"BillingStatusEntity":{"properties":{"balance":{"type":"number"},"currency":{"type":"string"},"currentPlanId":{"format":"uuid","nullable":true,"type":"object"},"lastPaymentDate":{"nullable":true,"type":"object"},"nextBillingDate":{"nullable":true,"type":"object"},"status":{"type":"string"},"subscriberId":{"format":"uuid","type":"string"}},"required":["subscriberId","status","currentPlanId","balance","currency","nextBillingDate","lastPaymentDate"],"type":"object"}}},"paths":{"/v1/billing/{subscriberId}/status":{"get":{"description":"Returns the current billing-cycle and payment status for a subscriber.","operationId":"BillingController_getBillingStatus_v1","parameters":[{"description":"Subscriber identifier (UUID).","in":"path","name":"subscriberId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/BillingStatusEntity"},"success":{"type":"boolean"}}}]}}},"description":"Current billing status for the 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 subscriber billing status","tags":["Billing"]}}}}
```