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
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- date range/filter query
- Returns
- Activity rows for orders, refunds, product activity, and revenue context.
- Side effects
- None for read endpoints unless noted.
GET
/api/developer/analytics/overview
Return developer analytics overview including commerce KPIs.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- date range query
- Returns
- Summary cards, timeline, products, orders, downloads, activations, marketplace, promotions, subscriptions, and exported field parity.
- Side effects
- None for read endpoints unless noted.
GET
/api/developer/analytics/overview/export.csv
Export developer analytics overview as CSV.
- Auth
- Developer JWT.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Developer JWT
- date range query
- Returns
- text/csv developer analytics export.
- Side effects
- None for read endpoints unless noted.
POST
/api/partner/v1/orders/:externalOrderId/refund
Partner-facing external-order refund/reversal route.
- Auth
- Scoped partner API key with licenses:revoke behavior.
- Scope
- Developer-owned or public storefront/marketplace scope as noted.
- Request fields
- Partner API key
- externalOrderId
- reason/metadata body
- Returns
- Refund/revocation response for partner-visible fulfillment.
- Side effects
- Applies partner refund/revoke behavior and logs API request.
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 | Legacy/import record type; no assisted migration service is currently offered. | 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
- Developer Bearer JWT; refunds.create and product scope.
- Scope
- Authenticated account, workspace, relationship, and product ownership checks apply.
- Request fields
- orderId path
- Optional itemIds query: comma-separated whole order-item IDs
- Returns
- Eligible preview with snapshot, availableItems, deadline, confirmationToken, and any unavailableReason; an existing blocking operation can return eligible:false.
- Side effects
- Read-only unless the operation explicitly records referral activity.
- Notes
- Developer JWT, refunds.create permission, and scope over every affected product are required. No payment is initiated.
POST
/api/developer/purchases/:orderId/refund
Confirm the current preview and request the refund.
- Auth
- Developer Bearer JWT; refunds.create and product scope.
- Scope
- Authenticated account, workspace, relationship, and product ownership checks apply.
- Request fields
- orderId path
- confirm:true
- confirmationToken from the latest preview
- reason: 3-1000 characters
- Optional itemIds: whole order-item IDs matching the preview
- Returns
- 202 with operation. Track its state; acceptance is not provider completion.
- Side effects
- Performs the described operation; review confirmation and retry requirements.
- 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.