Distributor API v2

Distributor API v2 is the default contract for every new marketplace and distribution integration. You provision MSP and customer organizations, manage marketplace licenses, and pull usage and billing data for your own invoicing. Its production base path is /api/distributor/v2.

The partner-based Distributor API v1 remains available as a compatibility contract for Synaxon and other existing v1 integrations. Both versions run in parallel; existing v1 integrations do not need to migrate.

The provisioning model

The hierarchy is organization-centric:

Distributor
  -> MSP organization
      -> Customer organization

There is no partner resource in v2. In v2, MSPs and customers are both normal SMAO organizations, distinguished by a type field:

• msp — the MSP's own SMAO organization.
• customer — a customer organization below an MSP, linked to it by parentOrganizationId.

Both are created through the same endpoint, POST /organizations. Every organization you create carries your own identifier in externalOrganizationId; duplicates are rejected with 409, which makes retries safe to reconcile.

GET /organizations/tree returns the full hierarchy — MSPs with their direct customer children. It intentionally contains no usage data; usage stays on the usage endpoints.

Licenses

Marketplace licenses drive the lifecycle. A license is owned by an MSP organization and has one of three states:

The rules:

• An MSP organization is created together with its purchased license.
• A customer organization must be created with an already available externalLicenseId owned by its parent MSP.
• Disabling an assigned license blocks the assigned organization (status: "blocked", with blockedReason typically "license_disabled").
• Reassigning a license to an organization releases that organization's previous license back to available.
• Deleting a customer releases its license.
• Deleting an MSP is allowed only after all its customer organizations are deleted (409 ORGANIZATION_HAS_CHILDREN otherwise).

Licenses are managed per MSP via PATCH /organizations/{organizationId}/licenses (upsert) and PATCH /organizations/{organizationId}/license (reassign).

Integration mode: polling only

Start with the quickstart for the full provision-to-billing flow.

API reference

The endpoint reference below is generated from the v2 OpenAPI spec. Each endpoint page includes an interactive playground. The raw spec is at api.smao.ai/api/distributor-docs/v2/openapi.yaml.