Fours API Reference

The Fours API is Fours' public REST API: it lets your own systems manage the products, offers, entitlements, buyers, usage metering, co-sell opportunities, funding applications, partners and partner training you work with in the Fours console, read your revenue records, and query your analytics and save charts and dashboards from it.

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

Revenue, analytics and partner relationship management (PRM) operations use /ai/org/{orgId}/revenue/…, /ai/org/{orgId}/analytics/… and /ai/org/{orgId}/prm/… on the same API host. Keep the /ai prefix when calling these endpoints.

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://api.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'

Revenue and analytics operations require a bearer token. PRM operations also accept a legacy API key sent as Authorization: Key <api-key>. 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, PUT and PATCH operations send JSON.
  • Versioning: see Versioning and compatibility below — the resource API is unversioned, and apiv2 is an older name for the same 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. A few endpoints, such as analytics queries, answer 429 while too many requests of the same kind are already running; retry after a short wait.
  • 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:

WhatVersioned?What it means for you
The resource API, https://api.suger.cloud Unversioned and rolling There is no version segment in the path and no version header. There is one live contract. This reference is built from the API's latest source rather than from the release running in production, so a new or changed operation can appear here, and a withdrawn one disappear, shortly before the live API changes.
The older host name apiv2.suger.cloud Not a version: the same host as api.suger.cloud apiv2 is an older name for the same host and keeps working; it is not a version of the resource API. Use api.suger.cloud to request a token and to call https://api.suger.cloud — see API Access.
This OpenAPI document (info.version 1.0) The document's own release number It identifies the specification file, not the API. Do not branch client behavior on it.

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. Fours avoids these on the public surface; when an operation is renamed, merged into another or withdrawn, its documentation page is removed and the old URL redirects to the operation that replaces it, or to this reference when none does. 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 renamed, merged or withdrawn are removed from this reference, and their old documentation URLs redirect to the operation that replaces them, or 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:

All operations

Every operation has its own page at /api/<operation>/ — open one below or from the sidebar — with its parameters, request body and responses, a runnable request, and an example response. Each page also has a Markdown version at /api/<operation>.md for agents and LLMs.

API

Analytics

Auditing

  • Query Auditing Events GET Query auditing events with filtering, sorting, and pagination using CRUD query language.

Buyer

  • List Buyers GET List buyers under the given organization with pagination and optional filters.
  • Create Buyer POST create a new buyer for Stripe or Adyen under the given organization.
  • Query Buyers GET Query buyers with filtering, sorting, and pagination using CRUD query language.
  • Get Buyer GET get buyer by the given organization and buyer id.
  • Update Buyer PATCH update buyer by the given organization and buyer id.
  • List Buyer's Wallets GET list all wallets of a buyer.
  • Create Credit Wallet POST create a new credit wallet for the buyer.
  • Update Credit Wallet PATCH update startTime or expireTime of the wallet.
  • Delete Buyer Wallet DELETE delete a wallet of the buyer, if it's a payment method, sync to payment provider too.
  • Close Credit Wallet PATCH Close the given credit wallet, if it's a payment method, sync to payment provider too.
  • Set Buyer Default Wallet PATCH set a payment method wallet as buyer's default wallet.

Contact

Cosell

Entitlement

Funding

Metering

Notification

Offer

  • Create or Update Draft Offer POST Create a new draft offer or update the existing draft offer.
  • List Offers GET List offers under the given organization with pagination and optional filter.
  • Create Offer POST Create a private offer under the given organization.
  • Query Offers GET Query offers with filtering, sorting, and pagination using CRUD query language.
  • Get Offer GET Get the offer by the given offer ID.
  • Delete Offer DELETE The offer is soft deleted (marked as DELETED status) in Fours service.
  • Cancel Offer POST Only the offer with status = "PENDING_ACCEPTANCE", "PENDING_CANCEL", "ACTIVE" or "USED" is allowed to cancel.
  • Get Offer EULA GET Get the EULA file of the given offer ID.
  • Extend Offer Expiry Date POST Only the offer with status = "PENDING_ACCEPTANCE", "EXPIRED", "ACCEPTED" or "UPDATE_FAILED" is allowed to…
  • Update Offer Meta Info PATCH Update the meta info of the given offer.
  • Notify Offer Contacts POST Send offer notifications to the given contact ids.
  • Get Offer PDF GET Render the offer's current terms (parties, dates, pricing, payment terms, marketplace details) as a shareable…
  • Update Offer Pricing (Unified Format) PATCH Add new usage dimensions or update existing dimension rates (at negotiated rates) on a released AWS private…
  • Get Offer Reseller EULA GET Get the Reseller EULA file of the given offer ID.
  • Sync Offer POST Sync the given offer from its partner.
  • Get Offer by External ID GET Get the offer by the given offer external ID.

OfferSet

  • List Offer Sets GET List offer sets under the given organization with filtering, sorting, and pagination using CRUD query…
  • Create Offer Set POST Create a new offer set under the given organization.
  • Get Offer Set GET Get the offer set by the given offer set ID.

Operation

Organization

Partner Relationship Management

Product

Report

Revenue

  • List revenue record details by partner GET Returns the raw billing rows a marketplace partner reported for this organization, as a page with the total…
  • Query Revenue Records GET Returns this organization's revenue records as a page, with the total count alongside them, so page_size=1…
  • Total Revenue, Grouped POST Totals this organization's revenue in the database and returns the grouped amounts, answering "how much" in…
  • List Cash Disbursements GET Returns this organization's cash disbursement rows as a page, with the total count and a summary alongside…
  • List Accounts Receivable Invoices GET Returns this organization's accounts receivable invoices as a page, newest issue date first, with the total…
  • List Credit Memos GET Returns this organization's credit memos as a page, with the total count alongside them: issued credit memos…

Support

Training

Spotted something wrong or out of date on this page? Tell us and we'll correct it.