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 — Create Invoice
• GET /api/v1/service/billing/invoices/{invoice_id} — Get Invoice
• POST /api/v1/service/billing/invoices/{invoice_id}/collect — Collect Payment
• POST /api/v1/service/billing/invoices/{invoice_id}/refund — Refund Invoice
• POST /api/v1/service/billing/invoices/{invoice_id}/void — Void Invoice
• GET /api/v1/service/billing/payouts — List Payouts
• 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}