Suger API Reference

CRUD operations on a set of resources, including organizations, products, offers, entitlements, usage record groups for meterting, etc.

Base URL: https://api.suger.cloud. Most endpoints are scoped to an organization under /org/{orgId}/…, and request and response bodies are JSON (application/json).

Authentication

The API uses the OAuth 2.0 client-credentials flow. Create an OAuth App to get a client ID and secret, exchange them for a short-lived (1 hour) bearer token, then send it on every request as Authorization: Bearer <token>.

curl -X POST 'https://apiv2.suger.cloud/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'resource=https://api.suger.cloud'

See API Access for the full token exchange, caching, rotation, and permissions.

Conventions

• Pagination: list endpoints commonly accept limit and offset query parameters.
• Errors: the API uses standard HTTP status codes; 4xx and 5xx responses return a JSON body describing the problem.
• Request bodies: GET and DELETE operations never take a body — pass every input as a path or query parameter. POST and PATCH operations send JSON.
• Versioning: see Versioning and compatibility below — the resource API is unversioned, and apiv2 is the OAuth host, not an API version.
• Rate limits: authenticated endpoints are not rate limited per request. Usage is bounded by your organization's service quotas instead.
• Idempotency: a few operations protect you from a duplicate on retry, each in its own way:
  • POST /org/{orgId}/offer is de-duplicated for 60 seconds — a repeat call with an identical body from the same caller returns the original response rather than creating a second offer.
  • POST /org/{orgId}/entitlement/{entitlementId}/usageRecordGroup de-duplicates on the id you supply, for 15 days; reporting the same id again is rejected rather than billed twice.
  • The PRM invitation endpoints refuse a second invitation to a recipient who already has one pending, with 409 and no second email.
  Every other mutating endpoint is not de-duplicated — a retry whose first outcome you did not observe can create a second record, so read the resource back before retrying.

Versioning and compatibility

Three different "versions" appear around this API, and only one of them describes the resource contract. This is the whole policy:

What counts as a breaking change. Removing an operation or a response field, renaming either, narrowing an accepted value, or making an optional request field required. Suger avoids these on the public surface; when an operation is withdrawn, its documentation page is removed and the old URL redirects to this reference. Additive changes — a new operation, a new optional request field, a new field in a response, or a new value in an existing enumeration — can ship at any time, so parse responses leniently and ignore fields you do not recognize.

Every operation listed here is currently supported — the reference carries no deprecated operations. Operations that have been withdrawn are removed from this reference, and their old documentation URLs redirect here. If you need advance notice before an operation you depend on changes, contact support@suger.io.

Endpoint groups

Endpoints are organized into the following groups:

• API
• Auditing
• Buyer
• Contact
• Cosell
• Entitlement
• Knowledge Search
• Metering
• Notification
• Offer
• OfferSet
• Operation
• Organization
• Partner Relationship Management
• Product
• Report
• Revenue
• Support

All operations

Every operation has a static page at /api/<operation>/ and a Markdown version at /api/<operation>.md, each with a runnable request and response example.

Using the reference

Explore every endpoint in the interactive reference below. Each operation also has a static page at /api/<operation>/ and a Markdown version at /api/<operation>.md for agents and LLMs.