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.
/api/developer/billing/status
Fetch developer billing status and billing gate.
- Auth
- Account Bearer session token
- 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.
- Notes
- The HTTP response wraps the billing object in status; status.status is the account state string. service_active distinguishes production activation from saved setup. configured_monthly_* describes the agreed option, while monthly_* can be zero before activation. Full Store uses a minimum adjustment, not a second subscription charge; fixed options use their separate service fee. hold_days is an approximate legacy display field: use payout_window_policy and assigned Eastern sales periods rather than computing a rolling release date from it.
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
},
"service_option": {
"type": "string",
"enum": [
"full_store",
"licensing_hosting",
"licensing_only"
]
},
"service_option_name": {
"type": "string"
},
"service_active": {
"type": "boolean"
},
"monthly_minimum_cents": {
"type": "integer",
"minimum": 0
},
"monthly_service_fee_cents": {
"type": "integer",
"minimum": 0
},
"configured_monthly_minimum_cents": {
"type": "integer",
"minimum": 0
},
"configured_monthly_service_fee_cents": {
"type": "integer",
"minimum": 0
},
"storage_allowance_bytes": {
"type": "integer",
"minimum": 0,
"description": "Bytes, not GB. Current service allowances use decimal GB."
},
"hosting_included": {
"type": "boolean"
},
"checkout_included": {
"type": "boolean"
},
"minimum_qualifying_basis": {
"type": "string",
"enum": [
"sales_fees",
"soundsync_charges"
]
},
"minimum_qualifying_activity_cents": {
"type": "integer",
"minimum": 0
},
"projected_service_fee_cents": {
"type": "integer",
"minimum": 0
},
"billing_cycle": {
"type": "object",
"properties": {
"cadence": {
"const": "calendar_month"
},
"payout_run_days": {
"type": "array",
"items": {
"type": "integer",
"enum": [
1,
15
]
}
},
"hold_days": {
"type": "integer",
"minimum": 0
},
"hold_is_approximate": {
"type": "boolean"
},
"payout_window_policy": {
"type": "string"
},
"period_strategy": {
"type": "string"
}
},
"additionalProperties": true
},
"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."
},
"current_month_charges": {
"type": "object",
"properties": {
"range": {
"type": "string"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"currency": {
"type": "string"
},
"service_option": {
"type": "string",
"enum": [
"full_store",
"licensing_hosting",
"licensing_only"
]
},
"service_option_name": {
"type": "string"
},
"service_active": {
"type": "boolean"
},
"monthly_minimum_cents": {
"type": "integer",
"minimum": 0
},
"monthly_service_fee_cents": {
"type": "integer",
"minimum": 0
},
"configured_monthly_minimum_cents": {
"type": "integer",
"minimum": 0
},
"configured_monthly_service_fee_cents": {
"type": "integer",
"minimum": 0
},
"storage_allowance_bytes": {
"type": "integer",
"minimum": 0,
"description": "Bytes, not GB. Current service allowances use decimal GB."
},
"hosting_included": {
"type": "boolean"
},
"checkout_included": {
"type": "boolean"
},
"minimum_qualifying_basis": {
"type": "string",
"enum": [
"sales_fees",
"soundsync_charges"
]
},
"minimum_qualifying_activity_cents": {
"type": "integer",
"minimum": 0
},
"service_policy_version": {
"type": "string"
},
"developer_service_fee_cents": {
"type": "integer",
"minimum": 0
},
"unledgered_service_fee_cents": {
"type": "integer",
"minimum": 0
},
"platform_fees_from_direct_sales_cents": {
"type": "integer",
"minimum": 0
},
"marketplace_fees_cents": {
"type": "integer",
"minimum": 0
},
"marketing_email_charges_cents": {
"type": "integer",
"minimum": 0
},
"redemption_overage_charges_cents": {
"type": "integer",
"minimum": 0
},
"minimum_adjustment_cents": {
"type": "integer",
"minimum": 0
},
"provider_processing_fees_cents": {
"type": "integer",
"minimum": 0
},
"soundsync_charges_cents": {
"type": "integer",
"minimum": 0
},
"pre_minimum_total_cents": {
"type": "integer",
"minimum": 0
},
"billable_activity_cents": {
"type": "integer",
"minimum": 0
},
"current_total_if_billed_today_cents": {
"type": "integer",
"minimum": 0
},
"marketing_emails": {
"type": "object",
"properties": {
"sent_this_month": {
"type": "integer",
"minimum": 0
},
"included": {
"type": "integer",
"minimum": 0
},
"monthly_included": {
"type": "integer",
"minimum": 0
},
"prior_month_quantity": {
"type": "integer",
"minimum": 0
},
"month_to_date_quantity": {
"type": "integer",
"minimum": 0
},
"remaining_included": {
"type": "integer",
"minimum": 0
},
"billable": {
"type": "integer",
"minimum": 0
},
"charge_cents": {
"type": "integer",
"minimum": 0
},
"rate_cents_per_1000": {
"type": [
"integer",
"null"
]
},
"current_rate_cents_per_1000": {
"type": "integer",
"minimum": 0
},
"pricing_basis": {
"type": "string"
}
},
"additionalProperties": true
},
"external_redemptions": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
}
},
"additionalProperties": true
},
"current_balance_cents": {
"type": "integer",
"minimum": 0
},
"can_activate_storage": {
"type": "boolean"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 500, 503.
/api/developer/billing/payment-method
Fetch saved developer billing payment method preview.
- Auth
- Account Bearer session token
- 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.
/api/developer/billing/portal-session
Create Stripe billing portal session.
- Auth
- Account Bearer session token
- 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.
/api/developer/billing/statements
List developer billing statements.
- Auth
- Account Bearer session token
- 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
},
"payment_processing_fee_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.
/api/developer/billing/invoices
List developer billing invoices.
- Auth
- Account Bearer session token
- 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.
/api/developer/billing/invoices/:invoiceId
Fetch developer billing invoice.
- Auth
- Account Bearer session token
- 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.
/api/developer/billing/statements/:statementId/invoice
Fetch invoice for a statement.
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/balance
Fetch settlement balance and payout account state.
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products workspace scope; effective developer ownership.
- Request fields
- query currency: string
- query environment: value
- Returns
- balance/account payload.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
- Notes
- Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string",
"default": "usd"
}
},
{
"name": "environment",
"in": "query",
"schema": {
"enum": [
"live",
"test"
],
"default": "live"
}
}
]
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.
/api/developer/settlements/connect-session
Create Stripe Connect payout onboarding/session.
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products workspace scope; effective developer ownership. Workspace owner only for this setup operation.
- 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.
/api/developer/settlements/ledger
List settlement ledger.
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products workspace scope; effective developer ownership.
- 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.
/api/developer/settlements/batches
List settlement batches.
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products workspace scope; effective developer ownership.
- 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.
/api/developer/settlements/payout-readiness
Fetch payout readiness.
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products workspace scope; effective developer ownership.
- Request fields
- query currency: string
- query environment: value
- Returns
- payout status booleans.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
- Notes
- Can initialize a local settlement account, recalculate balances and refresh a configured Stripe Connect account. Not a zero-write uptime probe. payout_ready is an account/destination status, not approval to send, a guaranteed net amount or confirmed bank receipt. No transfer or automatic-execution setting is changed.
Request, response and error reference
Query and header parameters
[
{
"name": "currency",
"in": "query",
"schema": {
"type": "string",
"default": "usd"
}
},
{
"name": "environment",
"in": "query",
"schema": {
"enum": [
"live",
"test"
],
"default": "live"
}
}
]
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
/api/developer/billing/invoices/{invoiceId}/download.csv
Download an owned developer billing invoice
- Auth
- Account Bearer session token
- 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.
/api/developer/billing/statements/{statementId}/download.csv
Download an owned billing statement
- Auth
- Account Bearer session token
- 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
/api/developer/settlements/payout-status/refresh
Refresh the saved Stripe Connect payout status
- Auth
- Account Bearer session token
- Scope
- billing.view and all-products workspace scope; effective developer ownership.
- 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.
Complete the available payout setup
The workspace owner starts or resumes provider onboarding. Other team roles keep their permitted reporting access, not the owner's destination authority. Eligible onboarded Stripe destinations follow their current provider requirements. PayPal Payouts is approved; select and verify an eligible USD PayPal destination or complete the supported Stripe route.
An account restriction, unsupported country or incomplete provider requirement can prevent payment. Resolve the actual saved readiness requirement or contact support. Do not change business country or the environment to bypass a restriction.
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
/api/developer/settlements/history
Read payout batches, transfers, bank status and uninvoiced usage
- Auth
- Account Bearer session token
- 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, pendingFeeAdjustmentCents.
- 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. Transfer payout_fee records distinguish the original deduction, actual provider fee, prior adjustment, estimated cross-border component and FX quote/settlement. Pending or unclaimed payment is not bank receipt; unreserved fee adjustments can change a later payout.
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
},
"provider": {
"type": "string"
},
"payout_fee": {
"anyOf": [
{
"type": "object",
"properties": {
"feeCents": {
"type": "integer",
"minimum": 0
},
"actualFeeCents": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
},
"adjustmentCents": {
"type": "integer"
},
"differenceCents": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
"feeComponents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"basis": {
"type": "string"
},
"amountCents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
},
"crossBorderEstimated": {
"type": "boolean"
},
"crossBorderFeeCents": {
"type": "integer",
"minimum": 0
},
"crossBorderEstimateBasisPoints": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
},
"fx": {
"anyOf": [
{
"type": "object",
"properties": {
"currency": {
"type": "string"
},
"localNetMinor": {
"type": "integer",
"minimum": 0
},
"actualLocalNetMinor": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
},
"conversionFeeCents": {
"type": "integer",
"minimum": 0
},
"actualExchangeRate": {
"type": "string"
},
"quote": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"exchangeRate": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"settlementVerified": {
"type": "boolean"
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"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
}
},
"pendingFeeAdjustmentCents": {
"type": "integer"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 500, 503.
/api/developer/settlements/history/export.csv
Download all matching payout-history rows
- Auth
- Account Bearer session token
- 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. The 28 columns, in order, are: Batch, Currency, First sale UTC, Last sale UTC, Scheduled run, Batch earnings cents, Batch status, Invoice offset cents, Transfer reference, Net payout cents, Transfer status, Bank reference, Bank status, Original payout fee deduction cents, Actual payout fee cents, Prior fee adjustment cents, Fee status, Cross-border fee estimated, Cross-border estimate cents included, Cross-border estimate basis points, Quoted FX cost USD cents, Recorded exchange rate, Local payout currency, Recorded local net minor units, FX quote expiry UTC, Conversion status, Fee difference cents, Reconciliation status. Net payout cents is the recorded transfer amount, not gross sale proceeds or guaranteed bank receipt. Actual fee and reconciliation fields can be unavailable until the provider record exists; an empty value is not a confirmed zero. Quoted FX cost is already included in its quoted conversion, not an instruction to subtract it twice. Cross-border estimate cents included is already part of the original deduction. Current accounting is USD; Recorded local net minor units instead uses Local payout currency. Conversion status is confirmed only for a verified settlement, expired_quote for an expired or imminent-expiry quote, unavailable for missing/invalid quote expiry, and quoted for a quote outside that expiry boundary. No FX record leaves this column empty. 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.
/api/developer/settlements/summary
Read settlement, transfer and bank-payment totals with the payout schedule
- Auth
- Account Bearer session token
- 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, payoutForecast, payoutFeePreview.
- 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. The summary selects the upcoming payout run, not the oldest unpaid run used by owner payment preparation. available_cents belongs to that selected sales period; held_cents can include unpaid earnings outside it or on hold. owed_cents covers the scoped unpaid balance across periods and is not the forecast net or permission to send. unresolved_source_entries/cents identify historical entries without complete order/environment evidence, excluded from confirmed payable totals. payoutForecast is an estimate for the selected Eastern period, not payout eligibility or permission to send: readyToSend is always false. It keeps known sales/usage visible while processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null. A negative net produces amountDueCents rather than a negative transfer. payoutFeePreview can have basis:period_forecast and forecastOnly:true; it is not a completed payment. 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. payoutFeePreview is a read-only projection or prepared amount, not payment execution. The next-run estimate can include recorded earnings that mature by that run. USD accounting, local payout currency, quoted FX cost, estimated provider fees and bank receipt are separate facts. feeComponents preserve each provider component basis and USD-cent amount; actualFeeCents and signed differenceCents are supplied when reconciliation records are available.
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."
},
"owed_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"source_model": {
"type": "string",
"enum": [
"journal",
"legacy"
]
},
"unresolved_source_entries": {
"type": "integer"
},
"unresolved_source_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"accounting_adjustment_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",
"description": "Nominal wait in days. Fixed half-month windows govern eligibility, including short February; this is not an exact rolling hold."
},
"payout_window_policy": {
"type": "string"
},
"hold_is_approximate": {
"type": "boolean"
},
"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."
},
"payoutForecast": {
"type": "object",
"properties": {
"version": {
"const": "payout-period-forecast-v1"
},
"currency": {
"type": "string"
},
"available": {
"type": "boolean"
},
"processingKnown": {
"type": "boolean"
},
"pendingProcessingCount": {
"type": "integer"
},
"salesCents": {
"type": [
"integer",
"null"
]
},
"salesFeeCents": {
"type": [
"integer",
"null"
]
},
"earningsBeforeUsageCents": {
"type": [
"integer",
"null"
]
},
"marketingEmailCents": {
"type": [
"integer",
"null"
]
},
"redemptionCents": {
"type": [
"integer",
"null"
]
},
"minimumCents": {
"type": [
"integer",
"null"
]
},
"serviceCents": {
"type": [
"integer",
"null"
]
},
"knownProcessingCents": {
"type": [
"integer",
"null"
]
},
"processingCents": {
"type": [
"integer",
"null"
]
},
"totalNonSaleCents": {
"type": [
"integer",
"null"
]
},
"netBeforePayoutFeesCents": {
"type": [
"integer",
"null"
]
},
"totalDeductionsBeforePayoutFeeCents": {
"type": [
"integer",
"null"
]
},
"amountDueCents": {
"type": [
"integer",
"null"
]
},
"minimumBasis": {
"type": [
"string",
"null"
]
},
"readyToSend": {
"const": false
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"runDate": {
"type": "string",
"format": "date"
},
"charges": {
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"marketing_email_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"redemption_overage_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"minimum_adjustment_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_service_fee_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"provider_processing_fees_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"non_sale_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"minimum_qualifying_basis": {
"type": [
"string",
"null"
]
},
"marketing_emails": {
"type": "object",
"properties": {
"quantity": {
"type": "integer"
},
"billable": {
"type": "integer"
},
"free_used": {
"type": "integer"
},
"free_limit": {
"type": "integer"
},
"free_used_in_period": {
"type": "integer"
},
"allowance_months": {
"type": "integer"
},
"rate_cents_per_1000": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
},
"external_redemptions": {
"type": "object",
"properties": {
"quantity": {
"type": "integer"
},
"billable": {
"type": "integer"
},
"free_used": {
"type": "integer"
},
"free_limit": {
"type": "integer"
},
"free_used_in_period": {
"type": "integer"
},
"allowance_months": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"feePreview": {
"type": "object",
"properties": {
"basis": {
"const": "period_forecast"
},
"projected": {
"type": "boolean"
},
"forecastOnly": {
"type": "boolean"
},
"status": {
"type": "string"
},
"grossCents": {
"type": [
"integer",
"null"
]
},
"netCents": {
"type": [
"integer",
"null"
]
},
"feeCents": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": "string"
},
"provider": {
"type": "string"
},
"country": {
"type": [
"string",
"null"
]
},
"businessCountry": {
"type": [
"string",
"null"
]
},
"payoutCurrency": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"payoutFeePreview": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"waiting",
"setup_required",
"unavailable",
"prepared",
"calculated",
"estimated"
]
},
"message": {
"type": "string"
},
"currency": {
"const": "usd"
},
"provider": {
"type": "string",
"enum": [
"stripe",
"paypal"
]
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"businessCountry": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"payoutCurrency": {
"type": "string"
},
"estimated": {
"type": "boolean"
},
"projected": {
"type": "boolean"
},
"basis": {
"type": "string"
},
"runDate": {
"type": "string"
},
"eligibleAt": {
"type": "string",
"format": "date-time"
},
"transferIntentId": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[1-9][0-9]*$"
}
]
},
"grossCents": {
"type": "integer",
"minimum": 0
},
"billingOffsetCents": {
"type": "integer",
"minimum": 0
},
"adjustmentCents": {
"type": "integer"
},
"roundingCarryCents": {
"type": "integer",
"minimum": 0
},
"feeCents": {
"type": "integer",
"minimum": 0
},
"netCents": {
"type": "integer",
"minimum": 0
},
"transferFeeCents": {
"type": "integer",
"minimum": 0
},
"crossBorderFeeCents": {
"type": "integer",
"minimum": 0
},
"monthlyFeeCents": {
"type": "integer",
"minimum": 0
},
"settlementFeeCents": {
"type": "integer",
"minimum": 0
},
"feeComponents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"basis": {
"type": "string"
},
"amountCents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
},
"conversionFeeCents": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
},
"recipientConversionIncluded": {
"type": "boolean"
},
"monthlyFeePeriod": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"localNetMinor": {
"type": "integer",
"minimum": 0
},
"exchangeRate": {
"type": "string"
},
"totalDeveloperFeeCents": {
"type": "integer",
"minimum": 0
},
"netUsdEquivalentCents": {
"type": "integer",
"minimum": 0
},
"fxFeeTreatment": {
"type": "string"
},
"fxQuoteExpiresAt": {
"type": "string",
"format": "date-time"
},
"fxSettled": {
"type": "boolean"
},
"crossBorderEstimated": {
"type": "boolean"
},
"crossBorderEstimateBasisPoints": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
]
},
"actualFeeCents": {
"type": "integer",
"minimum": 0
},
"differenceCents": {
"type": "integer"
},
"feeReconciled": {
"type": "boolean"
},
"reconciliationStatus": {
"type": "string"
},
"feeDisclosure": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"calculation": {
"type": "string"
},
"period_start": {
"type": "string"
},
"period_end": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 500, 503.
/api/developer/settlements/transfers
List owned payout transfer intents
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/transfers/{id}
Read one transfer intent owned by the current workspace
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/bank-payouts
Read provider bank-payout records for the workspace
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/summary-v2
Read journal-derived earnings and optional period charges
- Auth
- Account Bearer session token
- 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 Eastern calendar 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 Eastern calendar 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",
"properties": {
"available": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"marketing_email_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"redemption_overage_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"minimum_adjustment_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_service_fee_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"provider_processing_fees_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"non_sale_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"minimum_qualifying_basis": {
"type": [
"string",
"null"
]
},
"marketing_emails": {
"type": "object",
"properties": {
"quantity": {
"type": "integer"
},
"billable": {
"type": "integer"
},
"free_used": {
"type": "integer"
},
"free_limit": {
"type": "integer"
},
"free_used_in_period": {
"type": "integer"
},
"allowance_months": {
"type": "integer"
},
"rate_cents_per_1000": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
},
"external_redemptions": {
"type": "object",
"properties": {
"quantity": {
"type": "integer"
},
"billable": {
"type": "integer"
},
"free_used": {
"type": "integer"
},
"free_limit": {
"type": "integer"
},
"free_used_in_period": {
"type": "integer"
},
"allowance_months": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"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.
/api/developer/settlements/transactions-v2
Read journal source allocations
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/settlements-v2
Read allocations defaulting to approved-for-transfer state
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/adjustments-v2
Read allocations defaulting to negative-adjustment state
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/statements-v2
Read the journal statement-preview envelope
- Auth
- Account Bearer session token
- 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 Eastern calendar 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 Eastern calendar 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",
"properties": {
"available": {
"type": "boolean"
},
"currency": {
"type": "string"
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"marketing_email_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"redemption_overage_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"minimum_adjustment_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"developer_service_fee_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"provider_processing_fees_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"non_sale_charges_cents": {
"type": [
"integer",
"string"
],
"description": "Integer cents; PostgreSQL bigint totals can be serialized as decimal strings."
},
"minimum_qualifying_basis": {
"type": [
"string",
"null"
]
},
"marketing_emails": {
"type": "object",
"properties": {
"quantity": {
"type": "integer"
},
"billable": {
"type": "integer"
},
"free_used": {
"type": "integer"
},
"free_limit": {
"type": "integer"
},
"free_used_in_period": {
"type": "integer"
},
"allowance_months": {
"type": "integer"
},
"rate_cents_per_1000": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
},
"external_redemptions": {
"type": "object",
"properties": {
"quantity": {
"type": "integer"
},
"billable": {
"type": "integer"
},
"free_used": {
"type": "integer"
},
"free_limit": {
"type": "integer"
},
"free_used_in_period": {
"type": "integer"
},
"allowance_months": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"source": {
"const": "journal_settlement_preview"
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 500, 503, 409.
Operation errors: JOURNAL_SETTLEMENT_TABLES_MISSING.
/api/developer/settlements/recovery/summary
Read recovery readiness, totals and current records
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/recovery/cases
List owned refund/dispute recovery cases
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/recovery/cases/{id}
Read one owned recovery case, components and safe action summaries
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/recovery/offsets
Read the non-executing recovery offsets envelope
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/recovery/statements
Read the non-executing recovery statements envelope
- Auth
- Account Bearer session token
- 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.
/api/developer/settlements/recovery/reserve
Read existing workspace reserve records
- Auth
- Account Bearer session token
- 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
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
Interpret the payout fee fields
| Field | Meaning |
|---|---|
| feeComponents | Itemized provider components, each with id, kind, basis and amountCents in USD cents. Preserve the declared basis; do not substitute local bank minor units. |
| settlementFeeCents / crossBorderFeeCents | Separate fee components where the supported route supplies them. crossBorderEstimated and crossBorderEstimateBasisPoints identify an estimate, not a universal final tariff. |
| actualFeeCents / differenceCents | Available provider reconciliation records. A positive or negative difference can produce a later credit or deduction; a preview without these fields has not established the actual fee. |
| conversionFeeCents / exchangeRate | Read with fxFeeTreatment and the quoted settlement currency. Conversion already included in the exchange rate must not be charged a second time. |
| basis / period_start / period_end | Read-only calculation context where supplied. A period projection or prepared estimate is not payment execution or bank receipt. |
Read the selected service before interpreting a charge
GET /api/developer/billing/status returns an object inside status. Read status.service_option, status.service_active, configured_monthly_service_fee_cents, configured_monthly_minimum_cents, hosting_included, checkout_included and storage_allowance_bytes. The nested status.status is the billing-account state string, not another response wrapper.
A configured $20 fixed fee can coexist with monthly_service_fee_cents:0 before production activation. A Full Store minimum is not an extra $20 subscription. Historical service policy and current effective pricing can differ; do not reprice an older statement from today's option list.
SoundSync
Activate the selected hosting service
/api/developer/billing/activate-storage
Confirm current monthly pricing and activate production storage
- Auth
- Account Bearer session token
- Scope
- billing.view + billing.manage, all-products scope and the actual workspace owner.
- Request fields
- confirmMonthlyPricing: true (required)
- Returns
- HTTP 200: service.
- Notes
- Requires billing.view + billing.manage, all-products scope and the actual workspace owner. Send confirmMonthlyPricing:true. The selected service must include hosting; billing and a saved payment method are verified before first activation. Already active services return their current agreement. Starts the existing monthly service pricing, not an immediate card charge, upload, publication or payout. Does not change a role or financial execution flag.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"confirmMonthlyPricing": {
"const": true
}
},
"required": [
"confirmMonthlyPricing"
],
"additionalProperties": true
}
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"service": {
"type": "object",
"properties": {
"id": {
"type": "string",
"enum": [
"full_store",
"licensing_hosting",
"licensing_only"
]
},
"name": {
"type": "string"
},
"price": {
"type": "string"
},
"priceDetail": {
"type": "string"
},
"description": {
"type": "string"
},
"monthlyFeeCents": {
"type": "integer",
"minimum": 0
},
"monthlyMinimumCents": {
"type": "integer",
"minimum": 0
},
"saleFeeBps": {
"type": "integer",
"minimum": 0
},
"minimumBasis": {
"type": "string",
"enum": [
"sales_fees",
"soundsync_charges"
],
"description": "Use the effective agreement. Older agreements retain their prior minimum basis until the recorded transition."
},
"hosting": {
"type": "boolean"
},
"checkout": {
"type": "boolean"
},
"storageBytes": {
"type": "integer",
"minimum": 0,
"description": "Bytes, not GB. Current service allowances use decimal GB."
},
"storageLabel": {
"type": "string"
},
"features": {
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"type": "boolean"
},
"selected": {
"type": "boolean"
},
"legacy": {
"type": "boolean"
},
"agreementId": {
"type": [
"integer",
"string",
"null"
],
"minimum": 1,
"pattern": "^[1-9][0-9]*$",
"description": "PostgreSQL bigserial may serialize as a decimal string. Preserve the identifier without numeric coercion; null means no agreement."
},
"policyVersion": {
"type": "string"
},
"activatedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"effectiveFrom": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 402, 403, 409, 500, 503.
Operation errors: MONTHLY_PRICING_CONFIRMATION_REQUIRED, SERVICE_OPTION_OWNER_REQUIRED, DEVELOPER_SERVICE_OPTION_REQUIRED, DEVELOPER_SERVICE_OPTION_CAPABILITY_REQUIRED, DEVELOPER_COST_PAYMENT_METHOD_REQUIRED, DEVELOPER_COST_BILLING_RESTRICTED, DEVELOPER_COST_BILLING_UNAVAILABLE, DEVELOPER_COST_FUNDING_UNAVAILABLE.
Interpret the current minimum basis and processing amounts
status.minimum_qualifying_basis is sales_fees for the current agreement or soundsync_charges for a preserved older agreement. minimum_qualifying_activity_cents is the recorded qualifying amount, not the advertised sales rate multiplied over old orders. Read current_month_charges.provider_processing_fees_cents separately from soundsync_charges_cents. Statement payment_processing_fee_cents is the provider pass-through, not SoundSync revenue.
POST /api/developer/billing/activate-storage requires confirmMonthlyPricing:true and actual owner authority. A returned active agreement starts the monthly service policy but does not collect an immediate payment. can_activate_storage is a display capability, not permission to bypass the route guards.
Read forecast completeness separately from payout readiness
The payout summary includes payoutForecast and payoutFeePreview. payoutForecast.available describes calculation completeness, while readyToSend remains false. processingKnown:false leaves processingCents, totalNonSaleCents and netBeforePayoutFeesCents null and reports pendingProcessingCount. Independently confirmed sales and usage can still be shown; an unavailable amount is not a confirmed zero.
If sales or charge inputs are incomplete, available:false can leave individual forecast amounts and feePreview.grossCents null. The preview can report status:unavailable; processing_pending means the calculation inputs are complete but actual processing-fee evidence is still pending. Use the current preview message and provider rather than substituting an older prepared-period quote.
A payoutFeePreview with basis:period_forecast and forecastOnly:true is an estimate, not execution authority. Forecasted net is before payout-provider fees and can be negative, with amountDueCents showing the estimated debt. The same meanings apply to the payout-summary alias.
Interpret free and paid usage in a payout period
payoutForecast.charges and journal summary period_charges include marketing_emails and external_redemptions. quantity and billable describe units in the selected period; billable is not the number of paid email blocks. free_used is the monthly allowance consumed through the period end, including earlier usage in those months. free_used_in_period is only the included portion consumed inside the selected range.
free_limit sums the monthly allowances for allowance_months. A range spanning two months can show 2,000 included emails, not a larger single-month allowance. rate_cents_per_1000 can be null for mixed recorded rates. Older statement snapshots may lack these counters; missing counts are unavailable, not zero.
Read the payout summary in its selected period
GET /api/developer/settlements/summary and its /payouts/summary alias select the upcoming run from server time, not the oldest unpaid period used by owner payment preparation. available_cents belongs to that run; held_cents can include other unpaid periods and specific holds. owed_cents covers the scoped unpaid balance across periods, not the forecast net after charges.
unresolved_source_entries and unresolved_source_cents identify historical records without complete order and payment-environment evidence. They are excluded from confirmed payable totals until reconciled. source_model identifies journal or legacy accounting; the response does not switch the source or authorize payment.
Choose one payout reporting mount consistently
The earnings, settlements and payouts mounts use the same guarded router. The exact operation map below includes its nested /payouts and /earnings compatibility suffixes. Prefer /api/developer/settlements with the shortest listed suffix for new clients. A compatibility name does not change the request, response, workspace, filters, status or side effects.
All routes require billing.view and all-products scope. Connect onboarding, payout destination changes and payout-email verification also require the actual workspace owner. Payout-status refresh retains its separate reporting access and configured live/test approval checks; a teammate cannot gain owner onboarding access by changing the URL.
Balance and payout-readiness reads can initialize a local settlement account, recalculate balances or refresh configured provider status. They do not execute payments, but are not guaranteed zero-write uptime probes. payout_ready is not transfer approval or bank receipt. Use each report's actual filters: summary-v2 date filters do not automatically apply to allocation, recovery or ID-detail routes.
SoundSync
Payout reporting and setup compatibility operation map
| Method | Compatibility path | Contract or result |
|---|---|---|
| GET | /api/developer/settlements/payouts/history | GET /api/developer/settlements/history |
| GET | /api/developer/settlements/payouts/history/export.csv | GET /api/developer/settlements/history/export.csv |
| GET | /api/developer/settlements/payouts/summary | GET /api/developer/settlements/summary |
| GET | /api/developer/settlements/payouts/transfers | GET /api/developer/settlements/transfers |
| GET | /api/developer/settlements/payouts/transfers/{id} | GET /api/developer/settlements/transfers/{id} |
| GET | /api/developer/settlements/payouts/bank-payouts | GET /api/developer/settlements/bank-payouts |
| GET | /api/developer/settlements/earnings/summary-v2 | GET /api/developer/settlements/summary-v2 |
| GET | /api/developer/settlements/earnings/transactions-v2 | GET /api/developer/settlements/transactions-v2 |
| GET | /api/developer/settlements/earnings/settlements-v2 | GET /api/developer/settlements/settlements-v2 |
| GET | /api/developer/settlements/earnings/adjustments-v2 | GET /api/developer/settlements/adjustments-v2 |
| GET | /api/developer/settlements/earnings/statements-v2 | GET /api/developer/settlements/statements-v2 |
| GET | /api/developer/settlements/earnings/recovery/summary | GET /api/developer/settlements/recovery/summary |
| GET | /api/developer/settlements/earnings/recovery/cases | GET /api/developer/settlements/recovery/cases |
| GET | /api/developer/settlements/earnings/recovery/cases/{id} | GET /api/developer/settlements/recovery/cases/{id} |
| GET | /api/developer/settlements/earnings/recovery/offsets | GET /api/developer/settlements/recovery/offsets |
| GET | /api/developer/settlements/earnings/recovery/reserve | GET /api/developer/settlements/recovery/reserve |
| GET | /api/developer/settlements/earnings/recovery/statements | GET /api/developer/settlements/recovery/statements |
| GET | /api/developer/earnings/balance | GET /api/developer/settlements/balance |
| GET | /api/developer/earnings/ledger | GET /api/developer/settlements/ledger |
| GET | /api/developer/earnings/batches | GET /api/developer/settlements/batches |
| GET | /api/developer/earnings/payout-readiness | GET /api/developer/settlements/payout-readiness |
| POST | /api/developer/earnings/connect-session | POST /api/developer/settlements/connect-session |
| POST | /api/developer/earnings/payout-status/refresh | POST /api/developer/settlements/payout-status/refresh |
| POST | /api/developer/earnings/payout-method | POST /api/developer/settlements/payout-method |
| POST | /api/developer/earnings/payout-email/send-code | POST /api/developer/settlements/payout-email/send-code |
| POST | /api/developer/earnings/payout-email/verify | POST /api/developer/settlements/payout-email/verify |
| GET | /api/developer/earnings/history | GET /api/developer/settlements/history |
| GET | /api/developer/earnings/payouts/history | GET /api/developer/settlements/history |
| GET | /api/developer/earnings/history/export.csv | GET /api/developer/settlements/history/export.csv |
| GET | /api/developer/earnings/payouts/history/export.csv | GET /api/developer/settlements/history/export.csv |
| GET | /api/developer/earnings/summary | GET /api/developer/settlements/summary |
| GET | /api/developer/earnings/payouts/summary | GET /api/developer/settlements/summary |
| GET | /api/developer/earnings/transfers | GET /api/developer/settlements/transfers |
| GET | /api/developer/earnings/payouts/transfers | GET /api/developer/settlements/transfers |
| GET | /api/developer/earnings/transfers/{id} | GET /api/developer/settlements/transfers/{id} |
| GET | /api/developer/earnings/payouts/transfers/{id} | GET /api/developer/settlements/transfers/{id} |
| GET | /api/developer/earnings/bank-payouts | GET /api/developer/settlements/bank-payouts |
| GET | /api/developer/earnings/payouts/bank-payouts | GET /api/developer/settlements/bank-payouts |
| GET | /api/developer/earnings/summary-v2 | GET /api/developer/settlements/summary-v2 |
| GET | /api/developer/earnings/earnings/summary-v2 | GET /api/developer/settlements/summary-v2 |
| GET | /api/developer/earnings/transactions-v2 | GET /api/developer/settlements/transactions-v2 |
| GET | /api/developer/earnings/earnings/transactions-v2 | GET /api/developer/settlements/transactions-v2 |
| GET | /api/developer/earnings/settlements-v2 | GET /api/developer/settlements/settlements-v2 |
| GET | /api/developer/earnings/earnings/settlements-v2 | GET /api/developer/settlements/settlements-v2 |
| GET | /api/developer/earnings/adjustments-v2 | GET /api/developer/settlements/adjustments-v2 |
| GET | /api/developer/earnings/earnings/adjustments-v2 | GET /api/developer/settlements/adjustments-v2 |
| GET | /api/developer/earnings/statements-v2 | GET /api/developer/settlements/statements-v2 |
| GET | /api/developer/earnings/earnings/statements-v2 | GET /api/developer/settlements/statements-v2 |
| GET | /api/developer/earnings/recovery/summary | GET /api/developer/settlements/recovery/summary |
| GET | /api/developer/earnings/earnings/recovery/summary | GET /api/developer/settlements/recovery/summary |
| GET | /api/developer/earnings/recovery/cases | GET /api/developer/settlements/recovery/cases |
| GET | /api/developer/earnings/earnings/recovery/cases | GET /api/developer/settlements/recovery/cases |
| GET | /api/developer/earnings/recovery/cases/{id} | GET /api/developer/settlements/recovery/cases/{id} |
| GET | /api/developer/earnings/earnings/recovery/cases/{id} | GET /api/developer/settlements/recovery/cases/{id} |
| GET | /api/developer/earnings/recovery/offsets | GET /api/developer/settlements/recovery/offsets |
| GET | /api/developer/earnings/earnings/recovery/offsets | GET /api/developer/settlements/recovery/offsets |
| GET | /api/developer/earnings/recovery/reserve | GET /api/developer/settlements/recovery/reserve |
| GET | /api/developer/earnings/earnings/recovery/reserve | GET /api/developer/settlements/recovery/reserve |
| GET | /api/developer/earnings/recovery/statements | GET /api/developer/settlements/recovery/statements |
| GET | /api/developer/earnings/earnings/recovery/statements | GET /api/developer/settlements/recovery/statements |
| GET | /api/developer/payouts/balance | GET /api/developer/settlements/balance |
| GET | /api/developer/payouts/ledger | GET /api/developer/settlements/ledger |
| GET | /api/developer/payouts/batches | GET /api/developer/settlements/batches |
| GET | /api/developer/payouts/payout-readiness | GET /api/developer/settlements/payout-readiness |
| POST | /api/developer/payouts/connect-session | POST /api/developer/settlements/connect-session |
| POST | /api/developer/payouts/payout-status/refresh | POST /api/developer/settlements/payout-status/refresh |
| POST | /api/developer/payouts/payout-method | POST /api/developer/settlements/payout-method |
| POST | /api/developer/payouts/payout-email/send-code | POST /api/developer/settlements/payout-email/send-code |
| POST | /api/developer/payouts/payout-email/verify | POST /api/developer/settlements/payout-email/verify |
| GET | /api/developer/payouts/history | GET /api/developer/settlements/history |
| GET | /api/developer/payouts/payouts/history | GET /api/developer/settlements/history |
| GET | /api/developer/payouts/history/export.csv | GET /api/developer/settlements/history/export.csv |
| GET | /api/developer/payouts/payouts/history/export.csv | GET /api/developer/settlements/history/export.csv |
| GET | /api/developer/payouts/summary | GET /api/developer/settlements/summary |
| GET | /api/developer/payouts/payouts/summary | GET /api/developer/settlements/summary |
| GET | /api/developer/payouts/transfers | GET /api/developer/settlements/transfers |
| GET | /api/developer/payouts/payouts/transfers | GET /api/developer/settlements/transfers |
| GET | /api/developer/payouts/transfers/{id} | GET /api/developer/settlements/transfers/{id} |
| GET | /api/developer/payouts/payouts/transfers/{id} | GET /api/developer/settlements/transfers/{id} |
| GET | /api/developer/payouts/bank-payouts | GET /api/developer/settlements/bank-payouts |
| GET | /api/developer/payouts/payouts/bank-payouts | GET /api/developer/settlements/bank-payouts |
| GET | /api/developer/payouts/summary-v2 | GET /api/developer/settlements/summary-v2 |
| GET | /api/developer/payouts/earnings/summary-v2 | GET /api/developer/settlements/summary-v2 |
| GET | /api/developer/payouts/transactions-v2 | GET /api/developer/settlements/transactions-v2 |
| GET | /api/developer/payouts/earnings/transactions-v2 | GET /api/developer/settlements/transactions-v2 |
| GET | /api/developer/payouts/settlements-v2 | GET /api/developer/settlements/settlements-v2 |
| GET | /api/developer/payouts/earnings/settlements-v2 | GET /api/developer/settlements/settlements-v2 |
| GET | /api/developer/payouts/adjustments-v2 | GET /api/developer/settlements/adjustments-v2 |
| GET | /api/developer/payouts/earnings/adjustments-v2 | GET /api/developer/settlements/adjustments-v2 |
| GET | /api/developer/payouts/statements-v2 | GET /api/developer/settlements/statements-v2 |
| GET | /api/developer/payouts/earnings/statements-v2 | GET /api/developer/settlements/statements-v2 |
| GET | /api/developer/payouts/recovery/summary | GET /api/developer/settlements/recovery/summary |
| GET | /api/developer/payouts/earnings/recovery/summary | GET /api/developer/settlements/recovery/summary |
| GET | /api/developer/payouts/recovery/cases | GET /api/developer/settlements/recovery/cases |
| GET | /api/developer/payouts/earnings/recovery/cases | GET /api/developer/settlements/recovery/cases |
| GET | /api/developer/payouts/recovery/cases/{id} | GET /api/developer/settlements/recovery/cases/{id} |
| GET | /api/developer/payouts/earnings/recovery/cases/{id} | GET /api/developer/settlements/recovery/cases/{id} |
| GET | /api/developer/payouts/recovery/offsets | GET /api/developer/settlements/recovery/offsets |
| GET | /api/developer/payouts/earnings/recovery/offsets | GET /api/developer/settlements/recovery/offsets |
| GET | /api/developer/payouts/recovery/reserve | GET /api/developer/settlements/recovery/reserve |
| GET | /api/developer/payouts/earnings/recovery/reserve | GET /api/developer/settlements/recovery/reserve |
| GET | /api/developer/payouts/recovery/statements | GET /api/developer/settlements/recovery/statements |
| GET | /api/developer/payouts/earnings/recovery/statements | GET /api/developer/settlements/recovery/statements |
Preserve the meaning of preview and recovery responses
statements-v2 currently returns statements:[] with a journal_settlement_preview summary. Recovery offsets and statements likewise return their documented empty arrays with mor_recovery_safe_off. These are not newly issued statement documents, proof of completed recovery or permission to transfer. Historical entries and returned configuration fields must retain their recorded meanings.
Payout history, a transfer to a connected account and a provider bank payout remain separate records. External partner estimates are not funded managed-checkout earnings. Reports and aliases do not change the payout schedule, fee policy, automatic transfers or automatic reversals.
Use the current payout-history CSV
The private export has 28 ordered columns, not the earlier 13-column layout. Net payout cents is the transfer amount. Additional columns retain the original payout fee, actual provider fee, prior adjustment, fee state, included cross-border estimate, FX quote cost, exchange rate, destination currency, local minor-unit amount, quote expiry and reconciliation state. Read the CSV header rather than assigning columns by an older position.
An empty actual-fee value is unavailable, not a confirmed zero. Cross-border estimate cents included is already part of the original deduction; quoted FX cost is already reflected in the quoted conversion. Do not subtract either component twice. Conversion status can be quoted, expired_quote, confirmed or unavailable; no FX record leaves the column empty. A missing or invalid expiry must not be labeled as a valid quote. Confirmed conversion is separate from confirmed bank receipt.
SoundSync
