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

# Charges

One-time charges (`OneTimeCharge`) on a subscriber: ad-hoc fees, installation fees, equipment, reconnection. Charges are subscriber-primary with an optional subscription link, and can optionally gate `D2` activation when `blocksActivation: true`. Splits are locked at creation (MVP: 100% partner / 0% Share). For monthly billing, use the Subscriptions and Billing resources.

## List one-time charges for a subscriber

> Paginated, provider-scoped list of the subscriber’s one-time charges. Sorted by \`createdAt\` descending. 404 is returned if the subscriber doesn’t belong to the caller’s provider (cross-provider IDs are not leaked).

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"One-time charges (`OneTimeCharge`) on a subscriber: ad-hoc fees, installation fees, equipment, reconnection. Charges are subscriber-primary with an optional subscription link, and can optionally gate `D2` activation when `blocksActivation: true`. Splits are locked at creation (MVP: 100% partner / 0% Share). For monthly billing, use the Subscriptions and Billing resources.","name":"Charges"}],"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"},"ChargeResponseDto":{"properties":{"amount":{"type":"number"},"blocksActivation":{"type":"boolean"},"cancelReason":{"type":"object"},"cancelledAt":{"format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"enum":["PARTNER_API","PLATFORM_ADMIN","SPLYNX_SYNC"],"type":"string"},"currency":{"type":"string"},"description":{"maxLength":140,"type":"string"},"expiresAt":{"format":"date-time","type":"object"},"id":{"format":"uuid","type":"string"},"paidAt":{"format":"date-time","type":"object"},"partnerSplitPercent":{"description":"Locked at creation","type":"number"},"shareSplitPercent":{"description":"Locked at creation","type":"number"},"status":{"enum":["PENDING","PAID","WAIVED","CANCELLED","REFUNDED","SETTLEMENT_FAILED","ARCHIVED"],"type":"string"},"subscriberId":{"format":"uuid","type":"string"},"subscriptionId":{"format":"uuid","type":"object"},"type":{"enum":["INSTALLATION","EQUIPMENT","RECONNECTION","OTHER"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"waiveReason":{"type":"object"},"waivedAt":{"format":"date-time","type":"object"},"waivedBy":{"type":"object"}},"required":["id","subscriberId","type","description","amount","currency","status","blocksActivation","shareSplitPercent","partnerSplitPercent","createdBy","createdAt","updatedAt"],"type":"object"}}},"paths":{"/v1/subscribers/{subscriberId}/charges":{"get":{"description":"Paginated, provider-scoped list of the subscriber’s one-time charges. Sorted by `createdAt` descending. 404 is returned if the subscriber doesn’t belong to the caller’s provider (cross-provider IDs are not leaked).","operationId":"ChargesController_listCharges_v1","parameters":[{"in":"path","name":"subscriberId","required":true,"schema":{"format":"uuid","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 `OneTimeCharge.status`. Omit to include every status.","in":"query","name":"status","required":false,"schema":{"enum":["PENDING","PAID","WAIVED","CANCELLED","REFUNDED","SETTLEMENT_FAILED","ARCHIVED"],"type":"string"}},{"description":"Filter by `OneTimeCharge.type` (`INSTALLATION`, `EQUIPMENT`, `RECONNECTION`, `OTHER`). Omit to include every type.","in":"query","name":"type","required":false,"schema":{"enum":["INSTALLATION","EQUIPMENT","RECONNECTION","OTHER"],"type":"string"}},{"description":"Filter to charges linked to a specific subscription. Omit to include subscriber-scoped charges (e.g. ad-hoc fees without a subscription link).","in":"query","name":"subscriptionId","required":false,"schema":{"format":"uuid","type":"string"}},{"description":"Inclusive lower bound on `createdAt` (ISO-8601).","in":"query","name":"createdAfter","required":false,"schema":{"format":"date-time","type":"string"}},{"description":"Inclusive upper bound on `createdAt` (ISO-8601).","in":"query","name":"createdBefore","required":false,"schema":{"format":"date-time","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"items":{"$ref":"#/components/schemas/ChargeResponseDto"},"type":"array"},"success":{"type":"boolean"}}}]}}},"description":"Paginated charges for this 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":"List one-time charges for a subscriber","tags":["Charges"]}}}}
```

## Create a one-time charge for a subscriber

> Partner-initiated one-time obligation (installation, equipment, reconnection, ad-hoc). Subscriber-primary; subscription link is optional. Splits are locked at creation (MVP: 100% partner / 0% Share). When \`blocksActivation: true\` and the linked subscription is PENDING, the charge gates D2 activation until paid, waived, or cancelled. Coerced to \`false\` if the linked subscription is already ACTIVE.\
> \
> Idempotency: pass \`Idempotency-Key\` (UUID) header. Duplicate POSTs with the same key for the same subscriber return the original charge without re-emitting events.\
> \
> \*\*Error codes:\*\* \`subscriber\_terminal\` (400), \`subscription\_mismatch\` (400), \`invalid\_expires\_at\` (400). See the \[Error codes]\(../errors/error-codes.md) reference.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"One-time charges (`OneTimeCharge`) on a subscriber: ad-hoc fees, installation fees, equipment, reconnection. Charges are subscriber-primary with an optional subscription link, and can optionally gate `D2` activation when `blocksActivation: true`. Splits are locked at creation (MVP: 100% partner / 0% Share). For monthly billing, use the Subscriptions and Billing resources.","name":"Charges"}],"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":{"CreateChargeRequestDto":{"properties":{"amount":{"description":"Charge amount, in `currency` minor units / decimals","type":"number"},"blocksActivation":{"default":false,"description":"When `true` and the linked subscription is PENDING, this charge gates D2 activation until it transitions to PAID, WAIVED, or CANCELLED. Coerced to `false` (with a warning log) when the linked subscription is already ACTIVE — there is nothing to gate. Ignored when no `subscriptionId` is provided.","type":"boolean"},"currency":{"description":"ISO-4217 currency code","type":"string"},"description":{"description":"Free-text description; surfaces in subscriber SMS + receipts","maxLength":140,"type":"string"},"expiresAt":{"description":"Optional ISO-8601 expiry. PENDING charges past this timestamp are auto-cancelled by a separate cron (post-MVP). Must be in the future.","format":"date-time","type":"string"},"subscriptionId":{"description":"Optional link to a subscription. When set, the charge belongs to that specific service period; otherwise it's a subscriber-level obligation that survives subscription churn.","format":"uuid","type":"string"},"type":{"description":"Type of charge","enum":["INSTALLATION","EQUIPMENT","RECONNECTION","OTHER"],"type":"string"}},"required":["type","description","amount","currency"],"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"ChargeResponseDto":{"properties":{"amount":{"type":"number"},"blocksActivation":{"type":"boolean"},"cancelReason":{"type":"object"},"cancelledAt":{"format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"enum":["PARTNER_API","PLATFORM_ADMIN","SPLYNX_SYNC"],"type":"string"},"currency":{"type":"string"},"description":{"maxLength":140,"type":"string"},"expiresAt":{"format":"date-time","type":"object"},"id":{"format":"uuid","type":"string"},"paidAt":{"format":"date-time","type":"object"},"partnerSplitPercent":{"description":"Locked at creation","type":"number"},"shareSplitPercent":{"description":"Locked at creation","type":"number"},"status":{"enum":["PENDING","PAID","WAIVED","CANCELLED","REFUNDED","SETTLEMENT_FAILED","ARCHIVED"],"type":"string"},"subscriberId":{"format":"uuid","type":"string"},"subscriptionId":{"format":"uuid","type":"object"},"type":{"enum":["INSTALLATION","EQUIPMENT","RECONNECTION","OTHER"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"waiveReason":{"type":"object"},"waivedAt":{"format":"date-time","type":"object"},"waivedBy":{"type":"object"}},"required":["id","subscriberId","type","description","amount","currency","status","blocksActivation","shareSplitPercent","partnerSplitPercent","createdBy","createdAt","updatedAt"],"type":"object"}}},"paths":{"/v1/subscribers/{subscriberId}/charges":{"post":{"description":"Partner-initiated one-time obligation (installation, equipment, reconnection, ad-hoc). Subscriber-primary; subscription link is optional. Splits are locked at creation (MVP: 100% partner / 0% Share). When `blocksActivation: true` and the linked subscription is PENDING, the charge gates D2 activation until paid, waived, or cancelled. Coerced to `false` if the linked subscription is already ACTIVE.\n\nIdempotency: pass `Idempotency-Key` (UUID) header. Duplicate POSTs with the same key for the same subscriber return the original charge without re-emitting events.\n\n**Error codes:** `subscriber_terminal` (400), `subscription_mismatch` (400), `invalid_expires_at` (400). See the [Error codes](../errors/error-codes.md) reference.","operationId":"ChargesController_createCharge_v1","parameters":[{"in":"path","name":"subscriberId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Client-generated UUID. Duplicate POSTs with the same key for the same target resource return the original response without re-emitting downstream events. Keep ≤ 255 chars.\n\nExample: `9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d`.","in":"header","name":"idempotency-key","required":false,"schema":{"format":"uuid","maxLength":255,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChargeRequestDto"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/ChargeResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Charge created successfully"},"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":"Create a one-time charge for a subscriber","tags":["Charges"]}}}}
```

## Get a one-time charge by ID

> Provider-scoped fetch. Returns 404 if the charge does not exist, does not belong to the URL’s \`subscriberId\`, or the subscriber does not belong to the caller’s provider.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"One-time charges (`OneTimeCharge`) on a subscriber: ad-hoc fees, installation fees, equipment, reconnection. Charges are subscriber-primary with an optional subscription link, and can optionally gate `D2` activation when `blocksActivation: true`. Splits are locked at creation (MVP: 100% partner / 0% Share). For monthly billing, use the Subscriptions and Billing resources.","name":"Charges"}],"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"},"ChargeResponseDto":{"properties":{"amount":{"type":"number"},"blocksActivation":{"type":"boolean"},"cancelReason":{"type":"object"},"cancelledAt":{"format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"enum":["PARTNER_API","PLATFORM_ADMIN","SPLYNX_SYNC"],"type":"string"},"currency":{"type":"string"},"description":{"maxLength":140,"type":"string"},"expiresAt":{"format":"date-time","type":"object"},"id":{"format":"uuid","type":"string"},"paidAt":{"format":"date-time","type":"object"},"partnerSplitPercent":{"description":"Locked at creation","type":"number"},"shareSplitPercent":{"description":"Locked at creation","type":"number"},"status":{"enum":["PENDING","PAID","WAIVED","CANCELLED","REFUNDED","SETTLEMENT_FAILED","ARCHIVED"],"type":"string"},"subscriberId":{"format":"uuid","type":"string"},"subscriptionId":{"format":"uuid","type":"object"},"type":{"enum":["INSTALLATION","EQUIPMENT","RECONNECTION","OTHER"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"waiveReason":{"type":"object"},"waivedAt":{"format":"date-time","type":"object"},"waivedBy":{"type":"object"}},"required":["id","subscriberId","type","description","amount","currency","status","blocksActivation","shareSplitPercent","partnerSplitPercent","createdBy","createdAt","updatedAt"],"type":"object"}}},"paths":{"/v1/subscribers/{subscriberId}/charges/{chargeId}":{"get":{"description":"Provider-scoped fetch. Returns 404 if the charge does not exist, does not belong to the URL’s `subscriberId`, or the subscriber does not belong to the caller’s provider.","operationId":"ChargesController_getCharge_v1","parameters":[{"in":"path","name":"subscriberId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"chargeId","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/ChargeResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Charge returned successfully"},"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 one-time charge by ID","tags":["Charges"]}}}}
```

## Cancel a PENDING one-time charge

> Transitions the charge from \`PENDING\` to \`CANCELLED\`, stamping \`cancelledAt = now()\` and \`cancelReason = body.reason\`.\
> \
> Returns 409 \`CHARGE\_NOT\_CANCELLABLE\` if \`status != PENDING\`. Returns 404 if the charge does not exist, is not owned by the URL’s \`subscriberId\`, or the subscriber is owned by a different provider.\
> \
> No cascade onto linked \`Installation\`: if this charge is the one linked to a \`PENDING\_PAYMENT\` \`Installation\` (\`installation.oneTimeChargeId == chargeId\`), that Installation is left as-is. Orphan cleanup is intentionally out of scope; partners should also reconcile the Installation via the installations endpoints.\
> \
> \*\*Error codes:\*\* \`CHARGE\_NOT\_CANCELLABLE\` (409) — the charge is not in \`PENDING\` status (already paid, waived, refunded, or cancelled). See the \[Error codes]\(../errors/error-codes.md) reference.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"One-time charges (`OneTimeCharge`) on a subscriber: ad-hoc fees, installation fees, equipment, reconnection. Charges are subscriber-primary with an optional subscription link, and can optionally gate `D2` activation when `blocksActivation: true`. Splits are locked at creation (MVP: 100% partner / 0% Share). For monthly billing, use the Subscriptions and Billing resources.","name":"Charges"}],"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":{"CancelChargeRequestDto":{"properties":{"reason":{"description":"Operator-supplied reason for the cancellation. Stored on `OneTimeCharge.cancelReason` for audit + partner-side reconciliation.","maxLength":280,"type":"string"}},"required":["reason"],"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"ChargeResponseDto":{"properties":{"amount":{"type":"number"},"blocksActivation":{"type":"boolean"},"cancelReason":{"type":"object"},"cancelledAt":{"format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"enum":["PARTNER_API","PLATFORM_ADMIN","SPLYNX_SYNC"],"type":"string"},"currency":{"type":"string"},"description":{"maxLength":140,"type":"string"},"expiresAt":{"format":"date-time","type":"object"},"id":{"format":"uuid","type":"string"},"paidAt":{"format":"date-time","type":"object"},"partnerSplitPercent":{"description":"Locked at creation","type":"number"},"shareSplitPercent":{"description":"Locked at creation","type":"number"},"status":{"enum":["PENDING","PAID","WAIVED","CANCELLED","REFUNDED","SETTLEMENT_FAILED","ARCHIVED"],"type":"string"},"subscriberId":{"format":"uuid","type":"string"},"subscriptionId":{"format":"uuid","type":"object"},"type":{"enum":["INSTALLATION","EQUIPMENT","RECONNECTION","OTHER"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"waiveReason":{"type":"object"},"waivedAt":{"format":"date-time","type":"object"},"waivedBy":{"type":"object"}},"required":["id","subscriberId","type","description","amount","currency","status","blocksActivation","shareSplitPercent","partnerSplitPercent","createdBy","createdAt","updatedAt"],"type":"object"}}},"paths":{"/v1/subscribers/{subscriberId}/charges/{chargeId}/cancel":{"post":{"description":"Transitions the charge from `PENDING` to `CANCELLED`, stamping `cancelledAt = now()` and `cancelReason = body.reason`.\n\nReturns 409 `CHARGE_NOT_CANCELLABLE` if `status != PENDING`. Returns 404 if the charge does not exist, is not owned by the URL’s `subscriberId`, or the subscriber is owned by a different provider.\n\nNo cascade onto linked `Installation`: if this charge is the one linked to a `PENDING_PAYMENT` `Installation` (`installation.oneTimeChargeId == chargeId`), that Installation is left as-is. Orphan cleanup is intentionally out of scope; partners should also reconcile the Installation via the installations endpoints.\n\n**Error codes:** `CHARGE_NOT_CANCELLABLE` (409) — the charge is not in `PENDING` status (already paid, waived, refunded, or cancelled). See the [Error codes](../errors/error-codes.md) reference.","operationId":"ChargesController_cancelCharge_v1","parameters":[{"in":"path","name":"subscriberId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"chargeId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelChargeRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/ChargeResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Charge cancelled successfully"},"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":"Cancel a PENDING one-time charge","tags":["Charges"]}}}}
```

## Waive a PENDING one-time charge

> Marks the charge as comped — transitions \`PENDING → WAIVED\`, stamping \`waivedAt = now()\`, \`waivedBy = caller's providerId\`, and \`waiveReason = body.reason\` (optional). Sibling of the private-api flat route \`POST /v1/charges/:id/waive\`.\
> \
> Returns 409 \`CHARGE\_NOT\_WAIVABLE\` if \`status != PENDING\`. Returns 404 if the subscriber is owned by a different provider (\`{ field: 'subscriberId', code: 'NOT\_FOUND' }\`) or the charge does not exist under the URL’s \`subscriberId\` (\`{ field: 'id', code: 'NOT\_FOUND' }\`) — cross-tenant ids are never leaked.\
> \
> Installation cascade (Gate A): waiving a \`blocksActivation\` charge linked to a non-terminal \`Installation\` advances it exactly as a paid charge would — \`Installation.status → AWAITING\_INSTALLATION\`, \`installation\_paid\` pushed to the BSS, scheduling task created, install-window CPE provisioned (DEV-880/DEV-891). Non-blocking charges and charges with no linked installation waive row-only.\
> \
> \*\*Error codes:\*\* \`CHARGE\_NOT\_WAIVABLE\` (409) — the charge is not in \`PENDING\` status (already paid, waived, refunded, or cancelled). See the \[Error codes]\(../errors/error-codes.md) reference.

```json
{"openapi":"3.0.0","info":{"title":"Share API","version":"1.0"},"tags":[{"description":"One-time charges (`OneTimeCharge`) on a subscriber: ad-hoc fees, installation fees, equipment, reconnection. Charges are subscriber-primary with an optional subscription link, and can optionally gate `D2` activation when `blocksActivation: true`. Splits are locked at creation (MVP: 100% partner / 0% Share). For monthly billing, use the Subscriptions and Billing resources.","name":"Charges"}],"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":{"WaiveChargeRequestDto":{"properties":{"reason":{"description":"Optional reason for the waiver. Stored on `OneTimeCharge.waiveReason` for audit and partner reconciliation.","maxLength":280,"type":"string"}},"type":"object"},"ApiResponseDto":{"properties":{},"type":"object"},"ChargeResponseDto":{"properties":{"amount":{"type":"number"},"blocksActivation":{"type":"boolean"},"cancelReason":{"type":"object"},"cancelledAt":{"format":"date-time","type":"object"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"enum":["PARTNER_API","PLATFORM_ADMIN","SPLYNX_SYNC"],"type":"string"},"currency":{"type":"string"},"description":{"maxLength":140,"type":"string"},"expiresAt":{"format":"date-time","type":"object"},"id":{"format":"uuid","type":"string"},"paidAt":{"format":"date-time","type":"object"},"partnerSplitPercent":{"description":"Locked at creation","type":"number"},"shareSplitPercent":{"description":"Locked at creation","type":"number"},"status":{"enum":["PENDING","PAID","WAIVED","CANCELLED","REFUNDED","SETTLEMENT_FAILED","ARCHIVED"],"type":"string"},"subscriberId":{"format":"uuid","type":"string"},"subscriptionId":{"format":"uuid","type":"object"},"type":{"enum":["INSTALLATION","EQUIPMENT","RECONNECTION","OTHER"],"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"waiveReason":{"type":"object"},"waivedAt":{"format":"date-time","type":"object"},"waivedBy":{"type":"object"}},"required":["id","subscriberId","type","description","amount","currency","status","blocksActivation","shareSplitPercent","partnerSplitPercent","createdBy","createdAt","updatedAt"],"type":"object"}}},"paths":{"/v1/subscribers/{subscriberId}/charges/{chargeId}/waive":{"post":{"description":"Marks the charge as comped — transitions `PENDING → WAIVED`, stamping `waivedAt = now()`, `waivedBy = caller's providerId`, and `waiveReason = body.reason` (optional). Sibling of the private-api flat route `POST /v1/charges/:id/waive`.\n\nReturns 409 `CHARGE_NOT_WAIVABLE` if `status != PENDING`. Returns 404 if the subscriber is owned by a different provider (`{ field: 'subscriberId', code: 'NOT_FOUND' }`) or the charge does not exist under the URL’s `subscriberId` (`{ field: 'id', code: 'NOT_FOUND' }`) — cross-tenant ids are never leaked.\n\nInstallation cascade (Gate A): waiving a `blocksActivation` charge linked to a non-terminal `Installation` advances it exactly as a paid charge would — `Installation.status → AWAITING_INSTALLATION`, `installation_paid` pushed to the BSS, scheduling task created, install-window CPE provisioned (DEV-880/DEV-891). Non-blocking charges and charges with no linked installation waive row-only.\n\n**Error codes:** `CHARGE_NOT_WAIVABLE` (409) — the charge is not in `PENDING` status (already paid, waived, refunded, or cancelled). See the [Error codes](../errors/error-codes.md) reference.","operationId":"ChargesController_waiveCharge_v1","parameters":[{"in":"path","name":"subscriberId","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"chargeId","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaiveChargeRequestDto"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/ChargeResponseDto"},"success":{"type":"boolean"}}}]}}},"description":"Charge waived successfully"},"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":"Waive a PENDING one-time charge","tags":["Charges"]}}}}
```