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
Environment | URL |
---|---|
Sandbox | https://api.sandbox.cleeng.com/3.1 |
Production | https://api.cleeng.com/3.1 |
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
ETag
Response HeaderHeader | Type | Required? | Description |
---|---|---|---|
| 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
If-Match
Request HeaderHeader | Type | Required? | Description |
---|---|---|---|
If-Match | string | optional | The 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
If-None-Match
Request HeaderHeader | Type | Required? | Description |
---|---|---|---|
If-None-Match | string | optional | The 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 newETag
.
Conditional Request Response Codes
204
No Content
204
No Content- Returned for conditional requests with
If-Match
header - No content if no changes were made.
412
Precondition Failed
412
Precondition Failed- Returned when a precondition header (
If-Match
) is not met. - Example:
If-Match
value doesn’t match the currentETag
→ someone else updated the resource.
304
Not Modified
304
Not Modified- Returned for a
GET
request withIf-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.