API Reference
Billing and Settlements API
Developer-authenticated billing, statements, invoices, settlement balance, ledger, batches, and payout-readiness endpoints.
SoundSync
Verified endpoints
These endpoints are route-backed in the current platform.
GET
/api/developer/billing/status
Fetch developer billing status and billing gate.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- { status } including billing_gate/billingGate.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"status": {
"type": "object",
"properties": {
"developer_id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"billing_good_standing": {
"type": "boolean"
},
"amount_due_cents": {
"type": "integer",
"minimum": 0
},
"outstanding_non_sale_charges_cents": {
"type": "integer",
"minimum": 0
},
"invoice_balance_cents": {
"type": "integer",
"minimum": 0
},
"projected_minimum_adjustment_cents": {
"type": "integer",
"minimum": 0
},
"billing_gate": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"billingGate": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/billing/payment-method
Fetch saved developer billing payment method preview.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- { payment_method }.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"payment_method": {
"type": "object",
"properties": {
"payment_method": {
"type": "object",
"properties": {
"brand": {
"type": "string"
},
"last4": {
"type": "string"
},
"exp_month": {
"type": "integer"
},
"exp_year": {
"type": "integer"
}
},
"additionalProperties": true
},
"provider": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/billing/portal-session
Create Stripe billing portal session.
- Auth
- Account Bearer JWT
- Scope
- billing.view + billing.manage and all-products workspace scope.
- Returns
- Portal session URL/metadata.
- Side effects
- Creates Stripe Billing Portal session.
- Notes
- Requires billing.view + billing.manage and all-products workspace scope because the portal can edit payment methods and billing contact information. billing.view alone permits reports, not portal session creation; missing management permission returns 403 developer_team_permission_denied. Return URL is constructed by the application. This developer-billing portal is not the customer subscription invoice-history portal, Stripe Connect onboarding or a payout request.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"provider": {
"type": "string"
},
"stripe_mode": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/billing/statements
List developer billing statements.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query limit: integer
- query offset: integer
- Returns
- statements[].
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"statements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"total_cents": {
"type": "integer",
"minimum": 0
},
"platform_fee_cents": {
"type": "integer",
"minimum": 0
},
"marketplace_fee_cents": {
"type": "integer",
"minimum": 0
},
"marketing_email_usage_cents": {
"type": "integer",
"minimum": 0
},
"marketing_email_usage_quantity": {
"type": "integer"
},
"marketing_email_included_quantity": {
"type": "integer"
},
"marketing_email_billable_quantity": {
"type": "integer"
},
"external_redemption_usage_cents": {
"type": "integer",
"minimum": 0
},
"external_redemption_usage_quantity": {
"type": "integer"
},
"external_redemption_included_quantity": {
"type": "integer"
},
"external_redemption_billable_quantity": {
"type": "integer"
},
"minimum_adjustment_cents": {
"type": "integer",
"minimum": 0
},
"line_item_summary": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"invoice": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"statement_id": {
"type": "integer",
"minimum": 1
},
"provider": {
"type": "string"
},
"provider_invoice_id": {
"type": [
"string",
"null"
]
},
"display_number": {
"type": "string"
},
"provider_label": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": "integer",
"minimum": 0
},
"statement_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"statement_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"due_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"collection_attempts": {
"type": "integer"
},
"hosted_invoice_url": {
"type": [
"string",
"null"
]
},
"invoice_pdf": {
"type": [
"string",
"null"
]
},
"line_item_summary": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"hasMore": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/billing/invoices
List developer billing invoices.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query limit: integer
- query offset: integer
- Returns
- invoices[].
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"invoices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"statement_id": {
"type": "integer",
"minimum": 1
},
"provider": {
"type": "string"
},
"provider_invoice_id": {
"type": [
"string",
"null"
]
},
"display_number": {
"type": "string"
},
"provider_label": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": "integer",
"minimum": 0
},
"statement_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"statement_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"due_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"collection_attempts": {
"type": "integer"
},
"hosted_invoice_url": {
"type": [
"string",
"null"
]
},
"invoice_pdf": {
"type": [
"string",
"null"
]
},
"line_item_summary": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"hasMore": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/billing/invoices/:invoiceId
Fetch developer billing invoice.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- { invoice }.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"invoice": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"statement_id": {
"type": "integer",
"minimum": 1
},
"provider": {
"type": "string"
},
"provider_invoice_id": {
"type": [
"string",
"null"
]
},
"display_number": {
"type": "string"
},
"provider_label": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": "integer",
"minimum": 0
},
"statement_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"statement_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"due_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"collection_attempts": {
"type": "integer"
},
"hosted_invoice_url": {
"type": [
"string",
"null"
]
},
"invoice_pdf": {
"type": [
"string",
"null"
]
},
"line_item_summary": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/billing/statements/:statementId/invoice
Fetch invoice for a statement.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- { invoice }.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"invoice": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"statement_id": {
"type": "integer",
"minimum": 1
},
"provider": {
"type": "string"
},
"provider_invoice_id": {
"type": [
"string",
"null"
]
},
"display_number": {
"type": "string"
},
"provider_label": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": "integer",
"minimum": 0
},
"statement_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"statement_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"due_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"collection_attempts": {
"type": "integer"
},
"hosted_invoice_url": {
"type": [
"string",
"null"
]
},
"invoice_pdf": {
"type": [
"string",
"null"
]
},
"line_item_summary": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/settlements/balance
Fetch settlement balance and payout account state.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- balance/account payload.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"account": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"party_type": {
"type": "string"
},
"party_id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"payout_method_status": {
"type": "string"
},
"currency": {
"type": "string"
},
"available_balance_cents": {
"type": "integer"
},
"pending_balance_cents": {
"type": "integer"
},
"lifetime_earned_cents": {
"type": "integer"
},
"lifetime_paid_cents": {
"type": "integer"
},
"lifetime_refunded_cents": {
"type": "integer"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"payout_status_refreshed": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
POST
/api/developer/settlements/connect-session
Create Stripe Connect payout onboarding/session.
- Auth
- Account Bearer JWT
- Scope
- Workspace owner only, with billing.view and all-products scope; live onboarding approval remains required.
- Request fields
- returnTo: string
- collectionFields: currently_due | eventually_due
- environment: test | live
- Returns
- Connect session URL/metadata.
- Side effects
- Creates Stripe Connect account link/session.
- Notes
- Only the workspace owner may create or resume Stripe Connect onboarding. Requires billing.view, all-products scope and server-resolved isWorkspaceOwner:true; a role name, permission list or request-body owner flag cannot substitute. Non-owners receive 403 developer_team_owner_required before provider or onboarding-approval checks. Live mode still requires the configured onboarding approval; this call cannot enable it. /earnings/connect-session and /payouts/connect-session are compatibility aliases with the same guard. Billing/Administrator reporting and payout-status refresh retain their existing billing permissions. An onboarding URL is not a transfer or proof that payouts completed; no execution flag is changed.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"returnTo": {
"type": "string"
},
"collectionFields": {
"type": "string",
"enum": [
"currently_due",
"eventually_due"
]
},
"environment": {
"type": "string",
"enum": [
"test",
"live"
]
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"provider": {
"type": "string"
},
"stripe_mode": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
Operation errors: developer_team_owner_required, developer_team_all_products_scope_required, LIVE_CONNECT_DEVELOPER_NOT_ALLOWLISTED.
GET
/api/developer/settlements/ledger
List settlement ledger.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query limit: integer
- query offset: integer
- Returns
- ledger entries.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"entries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"source_type": {
"type": "string"
},
"source_id": {
"type": "integer",
"minimum": 1
},
"source_reference": {
"type": "string"
},
"direction": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": "integer"
},
"available_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/settlements/batches
List settlement batches.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query limit: integer
- query offset: integer
- Returns
- batches[].
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"batches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"total_amount_cents": {
"type": "integer"
},
"item_count": {
"type": "integer"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"provider": {
"type": "string"
},
"provider_batch_id": {
"type": [
"string",
"null"
]
},
"approved_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"failed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/settlements/payout-readiness
Fetch payout readiness.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Returns
- payout status booleans.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"party_type": {
"type": "string"
},
"party_id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"payout_method_status": {
"type": "string"
},
"payout_ready": {
"type": "boolean"
},
"payout_blocked": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
Download billing records as CSV
GET /api/developer/billing/invoices/{invoiceId}/download.csv and /statements/{statementId}/download.csv require billing.view and all-products scope. These are private developer-billing records, not customer purchase invoices or a request to send funds. Read the text/csv body and Content-Disposition filename; a missing or unowned record returns 404.
SoundSync
Billing CSV downloads
GET
/api/developer/billing/invoices/{invoiceId}/download.csv
Download an owned developer billing invoice
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope.
- Returns
- HTTP 200: text/csv.
- Notes
- Requires billing.view and all-products scope. Downloads the owned developer-billing invoice as CSV, not a customer purchase invoice or payment receipt. Read Content-Disposition for the filename. Returns 404 BILLING_INVOICE_NOT_FOUND for an unavailable invoice.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}Documented failures: 400, 500, 503.
GET
/api/developer/billing/statements/{statementId}/download.csv
Download an owned billing statement
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope.
- Returns
- HTTP 200: text/csv.
- Notes
- Requires billing.view and all-products scope. Downloads the owned monthly billing statement as CSV, not a payout execution or confirmation of bank receipt. Read Content-Disposition for the filename. Returns 404 BILLING_STATEMENT_NOT_FOUND for an unavailable statement.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}Documented failures: 400, 500, 503.
Refresh payout status without initiating a payout
POST /api/developer/settlements/payout-status/refresh accepts environment (live or test), with supported stripeEnvironment/stripe_environment aliases. Omit it to use the configured onboarding environment. billing.view and all-products scope are required, and live setup approval is checked.
The response contains account and refreshed. refreshed:false means there was no matching Connect account or configured provider to refresh. refreshed:true means Stripe status was retrieved and local status/balances were updated, not that money was transferred. A local settlement account can be created. This is not a zero-write probe, an onboarding-link request or a switch for automatic transfers.
SoundSync
Requests and responses
POST
/api/developer/settlements/payout-status/refresh
Refresh the saved Stripe Connect payout status
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products scope; effective developer ownership. Live onboarding approval is checked.
- Request fields
- environment: live | test
- Returns
- HTTP 200: account, refreshed.
- Notes
- Uses the configured environment when omitted; stripeEnvironment and stripe_environment alias environment. Can create a local settlement account, contact Stripe and persist status/balances. refreshed:false means no matching Connect account or provider configuration, not payout completion. refreshed:true confirms a status refresh only. This does not create an onboarding link, transfer money or enable automatic execution. /earnings and /payouts mounts are compatibility aliases.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"environment": {
"enum": [
"live",
"test"
]
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"account": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"party_type": {
"type": "string"
},
"party_id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"available_balance_cents": {
"type": "integer"
},
"pending_balance_cents": {
"type": "integer"
},
"lifetime_earned_cents": {
"type": "integer"
},
"lifetime_paid_cents": {
"type": "integer"
},
"lifetime_refunded_cents": {
"type": "integer"
},
"payout_method_status": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
},
"refreshed": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
Operation errors: LIVE_CONNECT_DEVELOPER_NOT_ALLOWLISTED, STRIPE_CONNECT_ENVIRONMENT_MISMATCH.
If live payout setup needs approval
The workspace owner starts or resumes Stripe Connect onboarding. Other team roles, including Administrators and Billing users, cannot open a new onboarding link for the owner. Their permitted balance, statement and payout-status reporting remains available. If you receive developer_team_owner_required, ask the workspace owner to complete setup; changing the requested environment does not grant access.
Live Stripe Connect setup currently requires account approval. If setup or status refresh returns LIVE_CONNECT_DEVELOPER_NOT_ALLOWLISTED, contact SoundSync support with your developer account reference to request review. Do not repeatedly create test accounts or change the environment to work around this restriction. Live checkout availability and live payout onboarding are separate checks.
After approval, finish the available Stripe Connect requirements and inspect the saved live payout status. A connected destination, a status refresh or a scheduled run is not confirmation of bank receipt. This setup requirement does not change the twice-monthly schedule or the minimum 14-day hold.
Separate billing reports from payment-method management
Billing reports, invoices, statements and their CSV downloads remain available with billing.view and all-products workspace scope. Opening the developer Stripe billing portal additionally requires billing.manage because that portal can change payment methods and billing contact details.
POST /api/developer/billing/portal-session returns 403 developer_team_permission_denied when billing.manage is missing. Existing role definitions stay unchanged: a read-only billing viewer cannot use the editable portal. This is separate from owner-only Stripe Connect payout onboarding, the customer subscription portal and any transfer execution.
Follow the money through its separate reporting states
Use payout history to reconcile a batch with its transfer references, invoice offsets and saved bank-payout records. A scheduled batch, a transfer to a connected account and a bank receipt are different events. Filter history by UTC batch-creation dates and live/test scope, then follow hasMore or download all matching CSV rows.
The earnings, settlements and payouts router mounts are compatibility names for the same guarded reports. This reference uses /api/developer/settlements. Every operation requires billing.view and all-products workspace scope; request-supplied developer IDs cannot expand that workspace. Reports do not approve payouts, change financial configuration or execute refunds or recovery.
SoundSync
Choose the report and respect its coverage
| Report | Use and limits |
|---|---|
| history / history/export.csv | Batch creation-date filters, currency and live/test scope. JSON includes limited batches plus approximate uninvoiced usage for live USD; CSV streams all matching batch/transfer rows, not the uninvoiced projection. |
| summary / transfers / bank-payouts | Schedule and balance totals, transfer intents, and saved provider bank status. Reading them does not refresh Stripe or initiate payment. |
| summary-v2 | Journal/commerce summary with its returned accounting labels, currency, live/test and optional date range. Complete dates are required for optional period charges. |
| transactions-v2 / settlements-v2 / adjustments-v2 | Allocation rows with limit/offset, state, optional currency and settlement account. These list handlers do not implement environment or date filters. The latter two supply default states that a valid state query can override. |
| statements-v2 | Currently a journal_settlement_preview with statements:[] and a summary, not issued documents. Use billing statement/invoice operations for existing billing documents. |
| recovery/summary / recovery/cases / recovery/cases/{id} | Read recorded recovery state and owned case detail. Recovery reports do not implement live/test or date filtering. ready:false is unavailable coverage, not proof of zero obligations. |
| recovery/offsets / recovery/statements | Currently return empty lists, a summary and source:mor_recovery_safe_off. They do not establish that an offset was executed or a statement was issued. |
| recovery/reserve | Read existing workspace reserve records; no currency, environment, date or offset filtering. This does not introduce a routine reserve policy or create/release a hold. |
SoundSync
Payout history, transfers and recovery reports
GET
/api/developer/settlements/history
Read payout batches, transfers, bank status and uninvoiced usage
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string. Defaults to usd. Current commerce operates in USD.
- query environment: string
- query from: string. Inclusive UTC batch-creation date.
- query to: string. Inclusive UTC batch-creation date; must not precede from.
- query limit: integer
- query offset: integer
- Returns
- HTTP 200: batches, hasMore, limit, offset, currency, environment, unstatementedUsage.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Filters from/to select batch creation, not sale dates. hasMore requires the next offset page. unstatementedUsage contains approximate past usage not yet invoiced, only for live USD; it is not a newly issued invoice or collected charge. /payouts/history is an alias under the same router.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Defaults to usd. Current commerce operates in USD."
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
},
"required": false,
"description": ""
},
{
"name": "from",
"in": "query",
"schema": {
"type": "string",
"format": "date"
},
"required": false,
"description": "Inclusive UTC batch-creation date."
},
{
"name": "to",
"in": "query",
"schema": {
"type": "string",
"format": "date"
},
"required": false,
"description": "Inclusive UTC batch-creation date; must not precede from."
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"batches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"scheduled_run_date": {
"type": [
"string",
"null"
]
},
"first_sale_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"last_sale_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"internal_billing_offset": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"transfers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"status": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"reserve_cents": {
"type": [
"integer",
"string",
"null"
]
},
"adjustment_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"billing_offset": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"reference": {
"type": [
"string",
"null"
]
},
"completed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"reconciliation_required": {
"type": [
"boolean",
"null"
]
},
"bank_payment": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"arrival_date": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
},
"hasMore": {
"type": "boolean"
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"currency": {
"type": "string"
},
"environment": {
"type": "string"
},
"unstatementedUsage": {
"type": "array",
"items": {
"type": "object",
"properties": {
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"currency": {
"const": "usd"
},
"status": {
"const": "not_invoiced"
},
"approximate": {
"const": true
},
"marketing_email_quantity": {
"type": "integer"
},
"external_redemption_quantity": {
"type": "integer"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/history/export.csv
Download all matching payout-history rows
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string. Defaults to usd. Current commerce operates in USD.
- query environment: string
- query from: string. Inclusive UTC batch-creation date.
- query to: string. Inclusive UTC batch-creation date; must not precede from.
- Returns
- HTTP 200: text/csv.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Streams all matching batches in internal pages of 100; caller limit/offset do not truncate the export. Filename: soundsync-payout-history.csv. Columns are Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Transfer amount cents, Transfer status, Bank reference and Bank status. Multiple transfers produce multiple rows. CSV has no unstatementedUsage projection. A mid-stream failure can terminate the download; do not treat a partial file as complete.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Defaults to usd. Current commerce operates in USD."
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
},
"required": false,
"description": ""
},
{
"name": "from",
"in": "query",
"schema": {
"type": "string",
"format": "date"
},
"required": false,
"description": "Inclusive UTC batch-creation date."
},
{
"name": "to",
"in": "query",
"schema": {
"type": "string",
"format": "date"
},
"required": false,
"description": "Inclusive UTC batch-creation date; must not precede from."
}
]No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/summary
Read settlement, transfer and bank-payment totals with the payout schedule
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string. Defaults to usd. Current commerce operates in USD.
- query environment: string
- Returns
- HTTP 200: summary, partnerSales.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. The schedule uses the server current time; this route does not forward asOf or date-range queries. A transfer to a connected account and a bank payout are distinct states. External partner sales are separately classified estimates, not funded managed-checkout balances; partnerSales.unavailable indicates missing reporting, including test scope. Neither this read nor its returned execution-status fields enables automatic payments.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Defaults to usd. Current commerce operates in USD."
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"summary": {
"type": "object",
"properties": {
"available_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"held_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"reserved_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"approved_allocation_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"approved_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"transferred_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"failed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"bank_payout_pending_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"bank_payout_paid_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"bank_payout_failed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"currency": {
"type": "string"
},
"environment": {
"type": "string"
},
"payout_mode": {
"type": "string"
},
"automatic_payments_enabled": {
"type": "boolean"
},
"owner_transfer_execution_enabled": {
"type": "boolean"
},
"hold_days": {
"type": "integer"
},
"period_time_zone": {
"type": "string"
},
"schedule_time_zone": {
"type": "string"
},
"next_hold_release_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"next_payout_run_date": {
"type": "string"
},
"scheduled_payout_execution_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"eligible_sale_cutoff_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"previous_payout_run_date": {
"type": "string"
},
"following_payout_run_date": {
"type": "string"
},
"eligible_sales_period_start_date": {
"type": "string"
},
"eligible_sales_period_end_date": {
"type": "string"
},
"eligible_sales_period_exclusive_end_date": {
"type": "string"
}
},
"additionalProperties": true
},
"partnerSales": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/transfers
List owned payout transfer intents
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string. Defaults to usd. Current commerce operates in USD.
- query environment: string
- query limit: integer
- query offset: integer
- query status: string
- query connectAccount: string
- Returns
- HTTP 200: transfers, limit, offset, hasMore, currency, environment.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. connect_account aliases connectAccount. Queued, submitted, failed and completed records must retain their actual status. hasMore uses an extra row. Listing an intent does not approve, retry, cancel or execute it.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Defaults to usd. Current commerce operates in USD."
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 50
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "connectAccount",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"transfers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_batch_id": {
"type": [
"integer",
"string"
]
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"source_balance_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"reserve_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"adjustment_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"net_transfer_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"provider_transfer_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"hasMore": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"environment": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/transfers/{id}
Read one transfer intent owned by the current workspace
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Returns
- HTTP 200: intent.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Unknown or foreign IDs return 404 TRANSFER_INTENT_NOT_FOUND. This ID-based read does not apply currency/environment query filters; inspect the returned owned record. No transfer action is performed.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"intent": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_batch_id": {
"type": [
"integer",
"string"
]
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"source_balance_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"reserve_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"adjustment_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"net_transfer_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"provider_transfer_id": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 500, 503.
Operation errors: TRANSFER_INTENT_NOT_FOUND.
GET
/api/developer/settlements/bank-payouts
Read provider bank-payout records for the workspace
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string. Defaults to usd. Current commerce operates in USD.
- query environment: string
- query limit: integer
- query offset: integer
- Returns
- HTTP 200: payouts, limit, offset, hasMore, currency, environment.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Reports saved provider records, not a fresh Stripe lookup. pending/in_transit is not paid; an arrival estimate is not confirmed bank receipt.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Defaults to usd. Current commerce operates in USD."
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"payouts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"provider_payout_id": {
"type": "string"
},
"status": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"arrival_date": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"paid_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
},
"hasMore": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"environment": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/summary-v2
Read journal-derived earnings and optional period charges
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string. Defaults to usd. Current commerce operates in USD.
- query environment: string
- query startDate: string. Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases.
- query endDate: string. Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases.
- query includePeriodCharges: string
- Returns
- HTTP 200: summary, flags.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Reads preserve the returned accounting_label, legacy_label and revenue_math_source; a preview is not a cutover or transfer. A complete start/end range adds commerce-summary fields. includePeriodCharges=true requires that complete range and adds a period-charge report, not an invoice or collection. Returned flags are descriptive and do not change configuration.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Defaults to usd. Current commerce operates in USD."
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
},
"required": false,
"description": ""
},
{
"name": "startDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases."
},
{
"name": "endDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases."
},
{
"name": "includePeriodCharges",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"summary": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"environment": {
"type": "string"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"gross_product_revenue_before_tax_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_added_to_customer_payment_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"soundsync_fee_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_earnings_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"pending_hold_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"available_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"approved_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"sent_to_stripe_account_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"next_hold_release_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"outstanding_refund_debt_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"payout_reconciliation_required": {
"type": "boolean"
},
"revenue_math_source": {
"type": "string"
},
"accounting_label": {
"type": "string"
},
"legacy_label": {
"type": "string"
},
"tax_notice": {
"type": "string"
},
"commerce_summary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"period_charges": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"flags": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: JOURNAL_SETTLEMENT_TABLES_MISSING.
GET
/api/developer/settlements/transactions-v2
Read journal source allocations
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query limit: integer
- query offset: integer
- query currency: string
- query settlementAccountId: integer
- query state: string
- Returns
- HTTP 200: allocations, limit, offset.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. These allocation lists do not implement environment or date-range filters; do not assume summary-v2 filters apply. settlement_account_id aliases settlementAccountId. The server fixes developerId. A supplied valid state overrides the endpoint default. There is no hasMore or total field: continue offset paging until a short page. These are allocation rows, not bank-payout confirmations.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 100
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"required": false,
"description": ""
},
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "settlementAccountId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "state",
"in": "query",
"schema": {
"type": "string",
"enum": [
"pending_hold",
"held",
"dispute_hold",
"available",
"reserved_for_batch",
"approved_for_transfer",
"partially_transferred",
"transferred",
"negative_adjustment",
"reversed",
"partially_reversed",
"canceled",
"invalidated"
]
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"allocations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_account_id": {
"type": [
"integer",
"string"
]
},
"order_id": {
"type": [
"integer",
"string"
]
},
"state": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"remaining_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"allocation_basis_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"platform_share_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_excluded_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"available_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: INVALID_ALLOCATION_STATE, JOURNAL_SETTLEMENT_TABLES_MISSING.
GET
/api/developer/settlements/settlements-v2
Read allocations defaulting to approved-for-transfer state
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query limit: integer
- query offset: integer
- query currency: string
- query settlementAccountId: integer
- query state: string
- Returns
- HTTP 200: allocations, limit, offset.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. These allocation lists do not implement environment or date-range filters; do not assume summary-v2 filters apply. settlement_account_id aliases settlementAccountId. The server fixes developerId. A supplied valid state overrides the endpoint default. There is no hasMore or total field: continue offset paging until a short page. These are allocation rows, not bank-payout confirmations.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 100
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"required": false,
"description": ""
},
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "settlementAccountId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "state",
"in": "query",
"schema": {
"type": "string",
"enum": [
"pending_hold",
"held",
"dispute_hold",
"available",
"reserved_for_batch",
"approved_for_transfer",
"partially_transferred",
"transferred",
"negative_adjustment",
"reversed",
"partially_reversed",
"canceled",
"invalidated"
],
"default": "approved_for_transfer"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"allocations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_account_id": {
"type": [
"integer",
"string"
]
},
"order_id": {
"type": [
"integer",
"string"
]
},
"state": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"remaining_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"allocation_basis_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"platform_share_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_excluded_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"available_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: INVALID_ALLOCATION_STATE, JOURNAL_SETTLEMENT_TABLES_MISSING.
GET
/api/developer/settlements/adjustments-v2
Read allocations defaulting to negative-adjustment state
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query limit: integer
- query offset: integer
- query currency: string
- query settlementAccountId: integer
- query state: string
- Returns
- HTTP 200: allocations, limit, offset.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. These allocation lists do not implement environment or date-range filters; do not assume summary-v2 filters apply. settlement_account_id aliases settlementAccountId. The server fixes developerId. A supplied valid state overrides the endpoint default. There is no hasMore or total field: continue offset paging until a short page. These are allocation rows, not bank-payout confirmations.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 500,
"default": 100
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"required": false,
"description": ""
},
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "settlementAccountId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "state",
"in": "query",
"schema": {
"type": "string",
"enum": [
"pending_hold",
"held",
"dispute_hold",
"available",
"reserved_for_batch",
"approved_for_transfer",
"partially_transferred",
"transferred",
"negative_adjustment",
"reversed",
"partially_reversed",
"canceled",
"invalidated"
],
"default": "negative_adjustment"
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"allocations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_account_id": {
"type": [
"integer",
"string"
]
},
"order_id": {
"type": [
"integer",
"string"
]
},
"state": {
"type": "string"
},
"currency": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"remaining_amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"allocation_basis_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"platform_share_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_excluded_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"available_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: INVALID_ALLOCATION_STATE, JOURNAL_SETTLEMENT_TABLES_MISSING.
GET
/api/developer/settlements/statements-v2
Read the journal statement-preview envelope
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string. Defaults to usd. Current commerce operates in USD.
- query environment: string
- query startDate: string. Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases.
- query endDate: string. Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases.
- query includePeriodCharges: string
- Returns
- HTTP 200: statements, summary, source.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Currently returns statements:[] with the summary and source:journal_settlement_preview. It does not produce statement documents. Use the developer billing statement/invoice APIs for issued billing documents; preserve the preview label.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Defaults to usd. Current commerce operates in USD."
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string",
"enum": [
"live",
"test"
],
"default": "live"
},
"required": false,
"description": ""
},
{
"name": "startDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Inclusive timestamp/date; start_date, from and periodStart/period_start are aliases."
},
{
"name": "endDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Exclusive timestamp; a date-only value includes that UTC day. end_date, to and periodEnd/period_end are aliases."
},
{
"name": "includePeriodCharges",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"statements": {
"type": "array",
"maxItems": 0
},
"summary": {
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"environment": {
"type": "string"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"gross_product_revenue_before_tax_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_added_to_customer_payment_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"soundsync_fee_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_earnings_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"pending_hold_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"available_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"approved_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"sent_to_stripe_account_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"next_hold_release_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"outstanding_refund_debt_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"payout_reconciliation_required": {
"type": "boolean"
},
"revenue_math_source": {
"type": "string"
},
"accounting_label": {
"type": "string"
},
"legacy_label": {
"type": "string"
},
"tax_notice": {
"type": "string"
},
"commerce_summary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"period_charges": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"source": {
"const": "journal_settlement_preview"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: JOURNAL_SETTLEMENT_TABLES_MISSING.
GET
/api/developer/settlements/recovery/summary
Read recovery readiness, totals and current records
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string
- query status: string
- query caseType: string
- query orderId: integer
- query recoveryCaseId: integer
- query settlementAccountId: integer
- query limit: integer
- Returns
- HTTP 200: ready, flags, summary, cases, account, reserves.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Missing recovery tables return ready:false with empty records; this is unavailable coverage, not verified absence of obligations. Summary filters do not turn the limited cases/reserves lists into exhaustive exports.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "caseType",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "orderId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "recoveryCaseId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "settlementAccountId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 250,
"default": 25
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ready": {
"type": "boolean"
},
"flags": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"summary": {
"type": "object",
"properties": {
"case_count": {
"type": "integer"
},
"target_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"recovered_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"outstanding_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_reversed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"platform_reversed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"reserve_held_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"future_offset_pending_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
}
},
"additionalProperties": true
},
"cases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_account_id": {
"type": [
"integer",
"string"
]
},
"order_id": {
"type": [
"integer",
"string"
]
},
"case_type": {
"type": "string"
},
"status": {
"type": "string"
},
"provider": {
"type": "string"
},
"provider_object_type": {
"type": "string"
},
"provider_object_id": {
"type": "string"
},
"currency": {
"type": "string"
},
"developer_recovery_target_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_recovered_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_outstanding_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"requested_refund_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"refunded_customer_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"account": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"reserves": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/recovery/cases
List owned refund/dispute recovery cases
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string
- query status: string
- query caseType: string
- query orderId: integer
- query recoveryCaseId: integer
- query settlementAccountId: integer
- query limit: integer
- query offset: integer
- Returns
- HTTP 200: cases, limit, offset.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. No hasMore or total field is returned; continue until a short page. Missing required recovery tables is a service error.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "caseType",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "orderId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "recoveryCaseId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "settlementAccountId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 250,
"default": 50
},
"required": false,
"description": ""
},
{
"name": "offset",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"cases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_account_id": {
"type": [
"integer",
"string"
]
},
"order_id": {
"type": [
"integer",
"string"
]
},
"case_type": {
"type": "string"
},
"status": {
"type": "string"
},
"provider": {
"type": "string"
},
"provider_object_type": {
"type": "string"
},
"provider_object_id": {
"type": "string"
},
"currency": {
"type": "string"
},
"developer_recovery_target_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_recovered_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_outstanding_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"requested_refund_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"refunded_customer_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: MOR_RECOVERY_TABLES_MISSING.
GET
/api/developer/settlements/recovery/cases/{id}
Read one owned recovery case, components and safe action summaries
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Returns
- HTTP 200: case, components, actions.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Unknown or foreign IDs return 404 RECOVERY_CASE_NOT_FOUND. Actions expose only their safe summary fields, not private execution payloads.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"case": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"settlement_account_id": {
"type": [
"integer",
"string"
]
},
"order_id": {
"type": [
"integer",
"string"
]
},
"case_type": {
"type": "string"
},
"status": {
"type": "string"
},
"provider": {
"type": "string"
},
"provider_object_type": {
"type": "string"
},
"provider_object_id": {
"type": "string"
},
"currency": {
"type": "string"
},
"developer_recovery_target_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_recovered_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_outstanding_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"requested_refund_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"refunded_customer_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
},
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"recovery_case_id": {
"type": [
"integer",
"string"
]
},
"component_type": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"currency": {
"type": "string"
},
"responsible_party": {
"type": "string"
},
"recoverable": {
"type": "boolean"
},
"status": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"action_type": {
"type": "string"
},
"status": {
"type": "string"
},
"amount_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"currency": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 500, 503, 409.
Operation errors: RECOVERY_CASE_NOT_FOUND, MOR_RECOVERY_TABLES_MISSING.
GET
/api/developer/settlements/recovery/offsets
Read the non-executing recovery offsets envelope
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string
- query status: string
- query caseType: string
- query orderId: integer
- query recoveryCaseId: integer
- query settlementAccountId: integer
- Returns
- HTTP 200: offsets, summary, source.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Currently returns offsets:[] and source:mor_recovery_safe_off. Empty output is not evidence that recovery was executed or that all outstanding obligations were cleared.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "caseType",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "orderId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "recoveryCaseId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "settlementAccountId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"offsets": {
"type": "array",
"maxItems": 0
},
"summary": {
"type": "object",
"properties": {
"case_count": {
"type": "integer"
},
"target_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"recovered_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"outstanding_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_reversed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"platform_reversed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"reserve_held_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"future_offset_pending_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
}
},
"additionalProperties": true
},
"source": {
"const": "mor_recovery_safe_off"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/recovery/statements
Read the non-executing recovery statements envelope
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query currency: string
- query status: string
- query caseType: string
- query orderId: integer
- query recoveryCaseId: integer
- query settlementAccountId: integer
- Returns
- HTTP 200: statements, summary, source.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Recovery reports do not implement environment or date-range query filtering. Supported ID/caseType filters accept snake_case aliases. Configuration/readiness is not proof of execution. A report never initiates a refund, reversal, reserve or future-earnings offset. Currently returns statements:[] and source:mor_recovery_safe_off. Empty output is not evidence that recovery was executed or that all outstanding obligations were cleared.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "caseType",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "orderId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "recoveryCaseId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "settlementAccountId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"statements": {
"type": "array",
"maxItems": 0
},
"summary": {
"type": "object",
"properties": {
"case_count": {
"type": "integer"
},
"target_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"recovered_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"outstanding_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"tax_reversed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"platform_reversed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"reserve_held_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"future_offset_pending_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
}
},
"additionalProperties": true
},
"source": {
"const": "mor_recovery_safe_off"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503.
GET
/api/developer/settlements/recovery/reserve
Read existing workspace reserve records
- Auth
- Account Bearer JWT
- Scope
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands.
- Request fields
- query limit: integer
- Returns
- HTTP 200: reserves, limit.
- Notes
- billing.view and all-products workspace scope; the server fixes the effective developer. These are reporting reads, not payout or recovery commands. Lists saved records across the effective workspace; currency/environment/date filters and offset are not implemented here. This read does not establish a routine reserve policy, place a hold or release funds.
Request, response and error reference
Query and header parameters
[
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 250,
"default": 50
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"reserves": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"string"
]
},
"developer_id": {
"type": [
"integer",
"string"
]
},
"held_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"released_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"currency": {
"type": "string"
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}
},
"limit": {
"type": "integer"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: MOR_RECOVERY_TABLES_MISSING.
SoundSync
Read and reconcile before taking action
Read payout history and download matching rows
curl --fail-with-body -sS --get "$SOUNDSYNC_API_BASE/api/developer/settlements/history" \
-H "Authorization: Bearer $DEVELOPER_TOKEN" \
--data-urlencode "currency=usd" --data-urlencode "environment=live" \
--data-urlencode "from=2026-10-01" --data-urlencode "to=2026-10-15" \
--data-urlencode "limit=20" --data-urlencode "offset=0"
curl --fail-with-body -sS --get "$SOUNDSYNC_API_BASE/api/developer/settlements/history/export.csv" \
-H "Authorization: Bearer $DEVELOPER_TOKEN" \
--data-urlencode "currency=usd" --data-urlencode "environment=live" \
--data-urlencode "from=2026-10-01" --data-urlencode "to=2026-10-15"SoundSync