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.
Choose the supported partner path
Reseller relationships, product assignments and reporting are separate from custom order fulfillment. Custom Partner API credentials, external-order submission, manual license issue, serial allocation and fulfillment webhooks require activation by SoundSync. These custom fulfillment operations are not currently enabled by default.
An approved WooCommerce connection has its own authorization, mapping and activation checks. Native affiliate and collaborator programs are separate again; the custom fulfillment setting does not switch those programs off. Historical records remain subject to their normal account permissions. Contact SoundSync before planning a custom fulfillment integration.
SoundSync
Verified external Partner API endpoints
These routes require scoped partner API keys and per-category rate limits.
/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
}
/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
}
/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.
- Notes
- Custom fulfillment requires SoundSync activation. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED without issuing access. Test credentials normally validate only: test_mode:true and would_fulfill:true are not actual fulfillment; inspect fulfillment_event_created and item statuses. Real test fulfillment requires its separate enabled capability. External processing fees are not covered by SoundSync.
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"
},
"label": {
"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"
},
"test_mode": {
"type": "boolean"
},
"would_fulfill": {
"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"
},
"reseller_sku": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"type": "string"
},
"license": {
"type": [
"object",
"null"
],
"properties": {
"serial": {
"type": "string"
},
"status": {
"type": "string"
},
"redemption_status": {
"type": "string"
}
},
"additionalProperties": true,
"description": "Private serial access when issued; null for validation-only test results."
},
"entitlement": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"claim_url": {
"type": [
"string",
"null"
],
"description": "Private customer claim URL when issued; never log or publish it."
},
"commercial_model": {
"type": "string"
},
"wholesale_rate_cents": {
"type": "integer",
"minimum": 0
},
"commission_rate_bps": {
"type": "integer",
"minimum": 0
},
"developer_revenue_share_bps": {
"type": "integer",
"minimum": 0
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
Documented failures: 400, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/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"
},
"label": {
"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"
},
"test_mode": {
"type": "boolean"
},
"would_fulfill": {
"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"
},
"reseller_sku": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"type": "string"
},
"license": {
"type": [
"object",
"null"
],
"properties": {
"serial": {
"type": "string"
},
"status": {
"type": "string"
},
"redemption_status": {
"type": "string"
}
},
"additionalProperties": true,
"description": "Private serial access when issued; null for validation-only test results."
},
"entitlement": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
}
},
"additionalProperties": true
},
"claim_url": {
"type": [
"string",
"null"
],
"description": "Private customer claim URL when issued; never log or publish it."
},
"commercial_model": {
"type": "string"
},
"wholesale_rate_cents": {
"type": "integer",
"minimum": 0
},
"commission_rate_bps": {
"type": "integer",
"minimum": 0
},
"developer_revenue_share_bps": {
"type": "integer",
"minimum": 0
},
"expected_payable_cents": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}
/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.
- Notes
- Custom fulfillment activation is required. Disabled availability returns 410 PARTNER_FULFILLMENT_DISABLED. Reporting an external refund is not a SoundSync-managed provider refund.
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, 401, 403, 404, 409, 410, 429, 500, 503.
Operation errors: PARTNER_FULFILLMENT_DISABLED.
/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
}
/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 -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 approximately two-week wait after the assigned sales period, 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. |
Handle fulfillment availability before retrying
Custom fulfillment can return 410 PARTNER_FULFILLMENT_DISABLED before any order or license is issued. Do not retry with a new external order ID to bypass this response. Confirm activation with SoundSync, keep a stable Idempotency-Key and use the environment and relationship assigned to the integration. Read-only access and approved WooCommerce fulfillment follow their separate contracts.
SoundSync
