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, and partner program records you work with in the Fours console.

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:

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, and this reference always describes what is deployed now.
The OAuth token host, apiv2.suger.cloud Version 2 of the auth host apiv2 names the token-issuing host, not a version of the resource API. Requesting a token there and calling https://api.suger.cloud is the current, supported pairing — 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 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 [email protected].

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

Auditing

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

Buyer

  • List Buyers GET list buyers by 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

  • Search Marketplace Knowledge POST Searches the shared knowledge index covering AWS, Azure, and GCP marketplace documentation, Fours docs, and…

Metering

Notification

Offer

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

Support

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