---
title: Service-to-platform billing
path: reference/api/service-billing
status: published
---

# Service-to-platform billing

**7 endpoints** in this group. All paths are prefixed with `/api/v1`.

## Endpoints in this group

- [`POST /api/v1/service/billing/invoices`](#post-api-v1-service-billing-invoices) — Create Invoice
- [`GET /api/v1/service/billing/invoices/{invoice_id}`](#get-api-v1-service-billing-invoices-invoice-id) — Get Invoice
- [`POST /api/v1/service/billing/invoices/{invoice_id}/collect`](#post-api-v1-service-billing-invoices-invoice-id-collect) — Collect Payment
- [`POST /api/v1/service/billing/invoices/{invoice_id}/refund`](#post-api-v1-service-billing-invoices-invoice-id-refund) — Refund Invoice
- [`POST /api/v1/service/billing/invoices/{invoice_id}/void`](#post-api-v1-service-billing-invoices-invoice-id-void) — Void Invoice
- [`GET /api/v1/service/billing/payouts`](#get-api-v1-service-billing-payouts) — List Payouts
- [`GET /api/v1/service/billing/subscriptions`](#get-api-v1-service-billing-subscriptions) — List Subscriptions

---

### POST `/api/v1/service/billing/invoices` — Create Invoice {#post-api-v1-service-billing-invoices}

Create an invoice from an external service.

**Parameters**:

- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Body**: `CreateExternalInvoiceRequest` — {`tenant_id`, `partner_id`, `source_service`, `currency` + 4 more}


**Responses**:

- `201` — Successful Response. Returns: `ApiResponse_ExternalInvoiceResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/service/billing/invoices/{invoice_id}` — Get Invoice {#get-api-v1-service-billing-invoices-invoice-id}

Get an externally-created invoice with revenue splits.

**Parameters**:

- `invoice_id` (path, string, required)
- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_ExternalInvoiceResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/service/billing/invoices/{invoice_id}/collect` — Collect Payment {#post-api-v1-service-billing-invoices-invoice-id-collect}

Trigger payment collection for an invoice.

**Parameters**:

- `invoice_id` (path, string, required)
- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Body**: `CollectInvoiceRequest` | null


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_ExternalInvoiceResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/service/billing/invoices/{invoice_id}/refund` — Refund Invoice {#post-api-v1-service-billing-invoices-invoice-id-refund}

Refund a paid invoice (full or partial).

**Parameters**:

- `invoice_id` (path, string, required)
- `source_service` (query, string, required)
- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Body**: `RefundInvoiceRequest` — {`amount_cents`, `reason`}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_RefundResultResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/service/billing/invoices/{invoice_id}/void` — Void Invoice {#post-api-v1-service-billing-invoices-invoice-id-void}

Void a draft or sent invoice.

**Parameters**:

- `invoice_id` (path, string, required)
- `source_service` (query, string, required)
- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_ExternalInvoiceResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/service/billing/payouts` — List Payouts {#get-api-v1-service-billing-payouts}

List revenue splits (payout records) for a service.

**Parameters**:

- `source_service` (query, string, required)
- `seller_id` (query, string, optional)
- `payout_status` (query, string, optional)
- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_PayoutSummaryResponse__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/service/billing/subscriptions` — List Subscriptions {#get-api-v1-service-billing-subscriptions}

List marketplace subscriptions created by a service.

**Parameters**:

- `source_service` (query, string, required)
- `tenant_id` (query, string, optional)
- `status` (query, string, optional)
- `x-scaicontrol-key` (header, string, optional)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_MarketplaceSubscriptionResponse__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}