Automating conversion tracking via API

The Affilae API lets you create, accept, refuse or adjust your conversions from your own system, without opening the interface. It is the answer when your order volume makes manual validation too heavy.

This page describes the useful endpoints and the order in which to call them. The full technical reference is published on rest.affilae.com/reference.

Rules that apply to every call

• Every request must include the header Authorization: Bearer {YOUR_TOKEN}
• Conversion amounts, sent or received, are expressed in cents. So 100 means 1.00 EUR.
• All timestamps are in UTC.

Creating a conversion (Server-to-Server)

With Server-to-Server, you can send each order through the API instead of the postback URL. Call POST /advertiser/conversions.add with kind = tracking and the click IDs you kept.

Example:

curl -X POST https://rest.affilae.com/advertiser/conversions.add \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"kind": "tracking", "program": "5e336e000000000000000000", "rule": "5e336e000000000000000001",
       "externalId": "CMD-10245", "amount": 8990, "currency": "EUR",
       "cids": ["603ed1800000000000000000"], "ip": "185.179.113.132"}'

Responses:

• 201: the conversion is created and returned in conversion.data.
• 202 “No contributions found”: no click and no promo code can be linked, no conversion is created.
• 400: the request is refused, the message says why, for example “Conversion already exists” or “Invalid clickIDs”.

Retrieving a conversion ID

Before accepting, refusing or updating a conversion, you must know its internal Affilae ID. There are two ways to get it.

1. List your conversions

Call GET /advertiser/conversions.list to retrieve the list of your conversions.

You can filter by:

• status, with pending, accepted or refused;
• date range, with from and to;
• customer identifier, with customerId;
• external identifier, with externalId.

2. Get the details of a conversion

Call GET /advertiser/conversions.info if you already know the external ID or the customer. This endpoint returns all information about the conversion, including its internal Affilae ID. The program parameter, the program ID, is required.

Accepting or refusing a conversion

Once you have the ID, you can automate your validation decisions. A locked conversion can no longer be accepted or refused.

Accept

Call POST /advertiser/conversions.accept. The conversion is validated and marked as accepted.

Required fields:

• program, the advertiser program ID;
• id, the internal conversion ID.

Refuse

Call POST /advertiser/conversions.refuse, for example for a product return, fraud or a test order.

Required fields:

• program, the program ID;
• id, the internal conversion ID;
• reason, the reason for refusal.

Adjusting a conversion amount

If a customer returns part of an order, or a cart adjustment is needed, you can modify the amount of a conversion. Call POST /advertiser/conversions.update.

Conditions:

• the conversion must not be refused, locked or included in a payment;
• the adjusted amount must not exceed the initial amount;
• the amount must not have been modified already.

Required fields:

• id, the internal conversion ID;
• amount, the new amount in cents;
• reason, the reason for the adjustment, for example a partial cart return.

API endpoint summary

Best practices

• Maintain the mapping between your own orders, the externalId, and the Affilae IDs, to prevent duplicates.
• Store your API key securely, never share it and never include it in client-side code.
• The API enforces rate limits. Make sure your scripts handle them gracefully.
• Keep logs of your API calls, they simplify troubleshooting and support.

Need help

Our support team is available from your advertiser interface for any technical assistance.

Related articles

• Understanding conversion statuses
• Add a conversion manually
• How to automatically validate large volumes of conversions through a .csv batch-file?
• S2S – Server-to-Server
• Postback, Publisher tracking