Getting Started With Core API

Core API (API 3.1) is designed for Server-to-Server integrations. It uses a publisher token for authentication and provides additional functionality such as:

  • Subscribing to webhook topics
  • Dunning action settings
  • Listing subscriptions and users
  • Externally-managed subscriptions synchronization.

Core API is used to provide additional flexibility for publishers who want to leverage their backend services to integrate with Cleeng


Authentication

This API requires a header with publisher token.

{
 "X-Publisher-Token": "your_publisher_token" 
}

Conditional Requests

To ensure data integrity, especially on resources that may be updated by multiple sources, our API uses conditional requests. This prevents you from accidentally overwriting changes made by another process. The workflow is implemented using the ETag and If-Match headers.

📘

Note: This mechanism is currently enabled on selected endpoints within the Offer API.

ETag Response Header

Header

Type

Required?

Description

ETag

string

optional

Used for versioning. The current version of the resource.

An ETag is a unique identifier representing the current version of the resource. When the resource changes, the ETag also changes.

ETag header is returned in a response with the version on selected offer endpoints only if you use the If-Match or If-None-Match header in a request.

If-Match Request Header

HeaderTypeRequired?Description
If-MatchstringoptionalThe version of resource that you want to change.

When modifying or deleting a resource (PUT, POST, PATCH, DELETE), you should include the If-Match header with the ETag value you last received.

If-Match header is optional - when not sent it should always overwrite an offer.

When the If-Match version matches, the offer should be modified. If there are no changes in the resource, 204 HTTP code should be returned.

Error handling

When the If-Match version doesn’t match (the provided If-Match value does not match the current resource’s ETag), an endpoint should respond with 412 HTTP code.

If-None-Match Request Header

HeaderTypeRequired?Description
If-None-MatchstringoptionalThe version of resource that you want to compare against the version that you have cached.

The If-None-Match header is used for read (GET) operations.

Caching / conditional GET:

You can send the last known ETag in an If-None-Match header.

  • If the resource has not changed, the server returns 304 Not Modified with no body, allowing you to use its cached copy.
  • If the resource has changed, the server returns the full resource with 200 OK and the new ETag.

Conditional Request Response Codes

204 No Content

  • Returned for conditional requests with If-Match header
  • No content if no changes were made.

412 Precondition Failed

  • Returned when a precondition header (If-Match) is not met.
  • Example: If-Match value doesn’t match the current ETag → someone else updated the resource.

304 Not Modified

  • Returned for a GET request with If-None-Match when the resource has not changed.
  • No body is sent - you should use its cached version.

Summary: When to Use Which

  • Use If-Match when updating or deleting, to ensure you only modify the version you last retrieved.
  • Use If-None-Match when reading, to avoid unnecessary data transfer or accidental duplicates.