API Reference
Reseller, Affiliate, and Partner APIs
Verified external Partner API behavior, scopes, idempotency, order/license endpoints, relationship terminology, and currently documented partner webhook routes.
SoundSync
Verified external Partner API endpoints
These routes require scoped partner API keys and per-category rate limits.
GET
/api/partner/v1/products
List products assigned to the authenticated partner relationship.
- Auth
- Relationship-scoped partner API key
- Scope
- Partner relationship and products:read scope.
- Request fields
- Authorization partner API key
- products:read scope
- Returns
- products[].
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sku": {
"type": [
"string",
"null"
]
},
"soundsync_sku": {
"type": [
"string",
"null"
]
},
"product_id": {
"type": "integer",
"minimum": 1
},
"title": {
"type": "string"
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"short_description": {
"type": "string"
},
"description": {
"type": "string"
},
"currency": {
"type": "string"
},
"authorized": {
"type": "boolean"
},
"license_fulfillment": {
"type": "string"
},
"msrp_cents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"suggested_sale_price_cents": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
GET
/api/partner/v1/products/:sku
Fetch one partner-visible product by SKU.
- Auth
- Relationship-scoped partner API key
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Request fields
- partner API key
- products:read scope
- sku path parameter
- Returns
- product.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"product": {
"type": "object",
"properties": {
"sku": {
"type": [
"string",
"null"
]
},
"soundsync_sku": {
"type": [
"string",
"null"
]
},
"product_id": {
"type": "integer",
"minimum": 1
},
"title": {
"type": "string"
},
"developer_id": {
"type": "integer",
"minimum": 1
},
"short_description": {
"type": "string"
},
"description": {
"type": "string"
},
"currency": {
"type": "string"
},
"authorized": {
"type": "boolean"
},
"license_fulfillment": {
"type": "string"
},
"msrp_cents": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"suggested_sale_price_cents": {
"type": [
"integer",
"null"
],
"minimum": 0
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
POST
/api/partner/v1/orders
Create/fulfill an external partner order.
- Auth
- Relationship-scoped partner API key
- Scope
- Partner relationship and orders:write or sales:write scope.
- Request fields
- header Idempotency-Key: string (required)
- external_order_id: string
- externalOrderId: string
- customer_email: string
- customerEmail: string
- purchased_at: string
- purchasedAt: string
- items: array (required)
- Returns
- 201 order fulfillment payload, or 200 idempotent replay/duplicate external order.
- Side effects
- Creates external order, serial/license fulfillment, audit log, webhook event order.fulfilled, notifications, and idempotency record.
Request, response and error reference
Query and header parameters
[
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": ""
}
]Request (application/json)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://www.soundsync.dev/contracts/partner-api.schema.json",
"title": "Partner external order",
"type": "object",
"properties": {
"external_order_id": {
"type": "string"
},
"externalOrderId": {
"type": "string"
},
"customer_email": {
"type": "string",
"format": "email"
},
"customerEmail": {
"type": "string",
"format": "email"
},
"purchased_at": {
"type": "string",
"format": "date-time"
},
"purchasedAt": {
"type": "string",
"format": "date-time"
},
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "integer",
"minimum": 1
},
"productId": {
"type": "integer",
"minimum": 1
},
"reseller_sku": {
"type": "string",
"minLength": 1
},
"resellerSku": {
"type": "string",
"minLength": 1
},
"sku": {
"type": "string",
"minLength": 1
},
"quantity": {
"type": "integer",
"minimum": 1,
"default": 1
},
"unit_reported_price_cents": {
"type": "integer",
"minimum": 0
}
},
"anyOf": [
{
"required": [
"product_id"
]
},
{
"required": [
"productId"
]
},
{
"required": [
"reseller_sku"
]
},
{
"required": [
"resellerSku"
]
},
{
"required": [
"sku"
]
}
]
}
}
},
"allOf": [
{
"anyOf": [
{
"required": [
"external_order_id"
]
},
{
"required": [
"externalOrderId"
]
}
]
},
{
"anyOf": [
{
"required": [
"customer_email"
]
},
{
"required": [
"customerEmail"
]
}
]
},
{
"anyOf": [
{
"required": [
"purchased_at"
]
},
{
"required": [
"purchasedAt"
]
}
]
}
],
"required": [
"items"
],
"additionalProperties": true
}HTTP 201 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"soundsync_order_id": {
"type": "string"
},
"external_order_id": {
"type": "string"
},
"relationship_id": {
"type": "string"
},
"source": {
"type": "string"
},
"financial_classification": {
"type": "string"
},
"soundsync_checkout_fee_cents": {
"type": "integer",
"minimum": 0
},
"reported_total_paid_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string"
},
"verification_status": {
"type": "string"
},
"fulfillment_event_created": {
"type": "boolean"
},
"idempotent_replay": {
"type": "boolean"
},
"duplicate_external_order": {
"type": "boolean"
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"null"
]
},
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"fulfillment_status": {
"type": "string"
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 403, 404, 409.
GET
/api/partner/v1/orders/:externalOrderId
Look up an external partner order by partner external ID.
- Auth
- Relationship-scoped partner API key
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Request fields
- partner API key
- orders:read scope
- Returns
- Order fulfillment payload.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"soundsync_order_id": {
"type": "string"
},
"external_order_id": {
"type": "string"
},
"relationship_id": {
"type": "string"
},
"source": {
"type": "string"
},
"financial_classification": {
"type": "string"
},
"soundsync_checkout_fee_cents": {
"type": "integer",
"minimum": 0
},
"reported_total_paid_cents": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string"
},
"verification_status": {
"type": "string"
},
"fulfillment_event_created": {
"type": "boolean"
},
"idempotent_replay": {
"type": "boolean"
},
"duplicate_external_order": {
"type": "boolean"
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": [
"integer",
"null"
]
},
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"product_id": {
"type": "integer",
"minimum": 1
},
"product_name": {
"type": "string"
},
"fulfillment_status": {
"type": "string"
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
POST
/api/partner/v1/orders/:externalOrderId/refund
Record partner refund/reversal effects for an external order.
- Auth
- Relationship-scoped partner API key
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Request fields
- reason: string
- Returns
- Refund/revocation response.
- Side effects
- Applies refund/revoke behavior and logs the 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.
GET
/api/partner/v1/licenses/:serial
Fetch partner-visible license status.
- Auth
- Relationship-scoped partner API key
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Request fields
- partner API key
- licenses:read scope
- serial path parameter
- Returns
- license.
- Side effects
- None for GET endpoints unless noted.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"license": {
"type": "object",
"properties": {
"serial": {
"type": "string"
},
"status": {
"type": "string"
},
"revoked": {
"type": "boolean"
},
"product_id": {
"type": "integer",
"minimum": 1
},
"external_order_id": {
"type": "string"
},
"customer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
POST
/api/partner/v1/licenses/:serial/revoke
Revoke a partner-visible license/serial.
- Auth
- Relationship-scoped partner API key
- Scope
- Public, customer-token, developer-user, or scoped partner API surface as noted.
- Request fields
- reason: string
- Returns
- Revocation payload.
- Side effects
- Revokes partner-visible license according to partner service policy.
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"
},
"serial": {
"type": "string"
},
"external_order_id": {
"type": "string"
}
},
"additionalProperties": true
}Documented failures: 400, 403, 404, 409.
SoundSync
Create external order
Use an Idempotency-Key so retries do not duplicate fulfillment.
curl
curl -sS -X POST "$SOUNDSYNC_API_BASE/api/partner/v1/orders" \
-H "Authorization: Bearer $PARTNER_API_KEY" \
-H "Idempotency-Key: demo-order-2048" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"DEMO-2048","customer_email":"customer@example.com","purchased_at":"2026-10-17T12:00:00Z","currency":"usd","total_paid_cents":4900,"items":[{"sku":"YOUR_ASSIGNED_RESELLER_SKU","quantity":1,"unit_reported_price_cents":4900}]}'SoundSync
Terminology boundary
Current implementation terminology is intentionally documented as-is.
| Term | Current verified meaning |
|---|---|
| Developer | SoundSync account that owns products and relationships. |
| Partner/reseller | External relationship that can receive assigned products, use scoped API keys, fulfill external orders, and receive webhooks. |
| Affiliate | Native referral programs use accepted product agreements, attribution, original sale allocations, and payouts on the 1st and 15th after the minimum 14-day hold, on the same schedule as developers and collaborators. See the separate Affiliate and Collaborator API; partner resale credentials do not grant program-management or customer-table access. |
| Customer | Buyer/end user who receives entitlements, serials, library access, and downloads. |
SoundSync