Skip to content
SoundSyncAudio software platform

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.

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.
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.

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"
    },
    "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
}
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.
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.

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.

TermCurrent verified meaning
DeveloperSoundSync account that owns products and relationships.
Partner/resellerExternal relationship that can receive assigned products, use scoped API keys, fulfill external orders, and receive webhooks.
AffiliateNative 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.
CustomerBuyer/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.