API Reference
Orders, Refunds, and Disputes API
Developer purchase reporting, whole-product checkout refunds, dispute visibility, and separate partner external reversals.
SoundSync
Verified endpoints
These endpoints are route-backed in the current platform.
GET
/api/developer/analytics/revenue/activity
List developer revenue/order activity shown in analytics.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query range: string
- query startDate: string. Custom start; start/from aliases are accepted.
- query endDate: string. Custom end; end/to aliases are accepted.
- query productId: integer
- query currency: string
- query environment: string
- query includeResellers: boolean
- query tab: string
- Returns
- Activity rows for orders, refunds, product activity, and revenue context.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
- Notes
- Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings.
Request, response and error reference
Query and header parameters
[
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"today",
"7d",
"30d",
"90d",
"current_month",
"previous_month"
]
},
"required": false,
"description": ""
},
{
"name": "startDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Custom start; start/from aliases are accepted."
},
{
"name": "endDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Custom end; end/to aliases are accepted."
},
{
"name": "productId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "includeResellers",
"in": "query",
"schema": {
"type": "boolean"
},
"required": false,
"description": ""
},
{
"name": "tab",
"in": "query",
"schema": {
"type": "string",
"enum": [
"overview",
"commerce",
"products",
"customers",
"marketing",
"engagement",
"retention",
"technical"
]
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"range": {
"type": "string"
},
"start_date": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"end_date": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"currency": {
"type": "string"
},
"environment": {
"type": "string"
},
"limit": {
"type": "integer"
},
"activity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"source": {
"type": "string"
},
"source_id": {
"type": "integer",
"minimum": 1
},
"occurred_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"amount_cents": {
"type": [
"integer",
"null"
]
},
"currency": {
"type": [
"string",
"null"
]
},
"product": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
},
"additionalProperties": true
},
"status": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"backend_gaps": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/analytics/overview
Return developer analytics overview including commerce KPIs.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query range: string
- query startDate: string. Custom start; start/from aliases are accepted.
- query endDate: string. Custom end; end/to aliases are accepted.
- query productId: integer
- query currency: string
- query environment: string
- query includeResellers: boolean
- query tab: string
- Returns
- Summary cards, timeline, products, orders, downloads, activations, marketplace, promotions, subscriptions, and exported field parity.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
- Notes
- Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings.
Request, response and error reference
Query and header parameters
[
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"today",
"7d",
"30d",
"90d",
"current_month",
"previous_month"
]
},
"required": false,
"description": ""
},
{
"name": "startDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Custom start; start/from aliases are accepted."
},
{
"name": "endDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Custom end; end/to aliases are accepted."
},
{
"name": "productId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "includeResellers",
"in": "query",
"schema": {
"type": "boolean"
},
"required": false,
"description": ""
},
{
"name": "tab",
"in": "query",
"schema": {
"type": "string",
"enum": [
"overview",
"commerce",
"products",
"customers",
"marketing",
"engagement",
"retention",
"technical"
]
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"dateRange": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"comparisonRange": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"currency": {
"type": "string"
},
"environment": {
"type": "string"
},
"activeTab": {
"type": "string"
},
"availableTabs": {
"type": "array",
"items": {
"type": "string"
}
},
"productFilter": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"unavailableSections": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"kpis": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"currentMonthCharges": {
"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"
},
"monthly_minimum_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
},
"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
},
"external_redemptions": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"marketing_emails": {
"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
},
"includeResellerSales": {
"type": "boolean"
},
"resellerDataUnavailable": {
"type": "boolean"
},
"resellerEstimatesIncomplete": {
"type": "boolean"
},
"topProducts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product": {
"type": "string"
},
"revenueCents": {
"type": "integer"
},
"orders": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"recentActivity": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"created_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
"additionalProperties": true
}
},
"engagementSummary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"customerGeography": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"revenueTimeSeries": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"trafficOverview": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"retentionSummary": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"technicalHealth": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"customerBehavior": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
},
"insights": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"raw": {
"type": "object",
"additionalProperties": true,
"description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
}
},
"additionalProperties": true
}Documented failures: 400, 500, 503.
GET
/api/developer/analytics/overview/export.csv
Export developer analytics overview as CSV.
- Auth
- Account Bearer JWT
- Scope
- Authenticated developer workspace; the route permission and assigned-product scope are enforced server-side.
- Request fields
- query range: string
- query startDate: string. Custom start; start/from aliases are accepted.
- query endDate: string. Custom end; end/to aliases are accepted.
- query productId: integer
- query currency: string
- query environment: string
- query includeResellers: boolean
- query tab: string
- Returns
- text/csv developer analytics export.
- Side effects
- Retrieves the authorized resource; any preparation or event recording is described in the operation notes.
- Notes
- Keep date, product, currency and live/test scope aligned. Missing measurements are not certified zeroes; imported external amounts are not automatically funded managed-sale earnings.
Request, response and error reference
Query and header parameters
[
{
"name": "range",
"in": "query",
"schema": {
"type": "string",
"enum": [
"today",
"7d",
"30d",
"90d",
"current_month",
"previous_month"
]
},
"required": false,
"description": ""
},
{
"name": "startDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Custom start; start/from aliases are accepted."
},
{
"name": "endDate",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": "Custom end; end/to aliases are accepted."
},
{
"name": "productId",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false,
"description": ""
},
{
"name": "currency",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "environment",
"in": "query",
"schema": {
"type": "string"
},
"required": false,
"description": ""
},
{
"name": "includeResellers",
"in": "query",
"schema": {
"type": "boolean"
},
"required": false,
"description": ""
},
{
"name": "tab",
"in": "query",
"schema": {
"type": "string",
"enum": [
"overview",
"commerce",
"products",
"customers",
"marketing",
"engagement",
"retention",
"technical"
]
},
"required": false,
"description": ""
}
]No request body fields are read by this operation.
HTTP 200 response (text/csv)
{
"type": "string",
"format": "binary"
}Documented failures: 400, 500, 503.
POST
/api/partner/v1/orders/:externalOrderId/refund
Partner-facing external-order refund/reversal route.
- Auth
- Relationship-scoped partner API key
- Scope
- Use the authentication and resource scope specified for this operation.
- Request fields
- reason: string
- Returns
- Refund/revocation response for partner-visible fulfillment.
- Side effects
- Applies partner refund/revoke behavior and logs API request.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"reason": {
"type": "string"
}
},
"additionalProperties": true
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"status": {
"type": "string"
},
"code": {
"type": "string"
},
"external_order_id": {
"type": "string"
},
"idempotent_replay": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 403, 404, 409.
SoundSync
Order states
Use these states when building support/reporting UI.
| State | Meaning | Access rule | Recovery |
|---|---|---|---|
| paid | Payment completed or free claim completed. | Sale ledger entries created; settlement/journal allocation may be created when enabled. | Active entitlements and downloads allowed. |
| refunded | Full refund or reversal recorded. | Negative/refund ledger and recovery/settlement adjustments may apply. | Downloads blocked when entitlement becomes inactive. |
| partially_refunded | Some whole products have been refunded while others remain, or a separately reconciled provider partial refund exists. Not permission for arbitrary developer refund amounts. | Partial negative adjustment may apply. | Download behavior follows entitlement state. |
| disputed | Dispute/chargeback event recorded. | Recovery/reserve/provisional accounting may apply. | Downloads follow entitlement state. |
| failed | Payment failed before durable checkout completion. | No sale ledger entitlement grant. | No protected downloads. |
| canceled | Checkout canceled or order canceled before access grant. | No sale ledger entitlement grant unless another source exists. | No protected downloads. |
| migrated | Historical/imported order record. Product catalog migration is supported, but importing product drafts does not transfer historical payments, customer accounts, or recurring billing authority. | Migration ledger depends on import path. | Downloads follow entitlement state. |
SoundSync
Developer checkout refunds
Current route and service contracts. Examples below are illustrative; live provider outcomes and client-host testing are separate checks.
GET
/api/developer/purchases/:orderId/refund
Preview eligibility and the original refund breakdown.
- Auth
- Account Bearer JWT
- Scope
- Owned purchase and every affected product; refunds.create is required for preview and confirmation.
- Request fields
- query itemIds: string
- Returns
- Eligible preview with snapshot, availableItems, deadline, confirmationToken, and any unavailableReason; an existing blocking operation can return eligible:false.
- Side effects
- Retrieves the authorized resource. Operation-specific notes identify preparation or referral recording where applicable.
- Notes
- Developer JWT, refunds.create permission, and scope over every affected product are required. No payment is initiated.
Request, response and error reference
Query and header parameters
[
{
"name": "itemIds",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
}
]HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"eligible": {
"type": "boolean"
},
"unavailableReason": {
"type": [
"string",
"null"
]
},
"confirmationToken": {
"type": "string"
},
"deadline": {
"type": "string"
},
"snapshot": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"availableItems": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true
}
},
"itemSelectionUnavailableReason": {
"type": [
"string",
"null"
]
},
"operation": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 503.
POST
/api/developer/purchases/:orderId/refund
Confirm the current preview and request the refund.
- Auth
- Account Bearer JWT
- Scope
- Owned purchase and every affected product; refunds.create is required for preview and confirmation.
- Request fields
- confirm: true (required)
- confirmationToken: string (required)
- reason: string (required)
- itemIds: array
- Returns
- 202 with operation. Track its state; acceptance is not provider completion.
- Side effects
- Confirm the current preview and request the refund. Review the confirmation and retry requirements before repeating the request.
- Notes
- Do not send amount, amountCents, or items. Custom amount requests are rejected. The original capture must be eligible and the selected items must remain unrefunded.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"confirm": {
"const": true
},
"confirmationToken": {
"type": "string"
},
"reason": {
"type": "string",
"minLength": 3,
"maxLength": 1000
},
"itemIds": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer",
"minimum": 1
}
}
},
"required": [
"confirm",
"confirmationToken",
"reason"
],
"additionalProperties": false
}HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"operation": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": true
}Documented failures: 400, 403, 404, 409, 503.