Automating conversion tracking via API

Objective : Automatically accept/refuse conversions and adjust transaction amounts.

Before you begin automating your conversion management, ensure you have the following:

• Your Advertiser API Key (Authentication Token).
• API Base URL: https://rest.affilae.dev4.kaizen-developments.com
• API Documentation: Access Reference here

Technical Requirements

All requests must include the following header:

• Authorization: Bearer {YOUR_TOKEN}

Important Notes:

• Amounts: All amounts sent or received are expressed in cents (e.g., "100" = 1.00 €).
• Dates: All timestamps are in UTC.

---

1. Retrieving a Conversion ID

Before performing any action (accepting, refusing, or updating), you must identify the internal Affilae ID of the conversion. There are two ways to do this:

• List Conversions: Use the endpoint GET /advertiser/conversions.list to retrieve a list. You can filter by status (pending, accepted, refused), date range (from, to), customerId, or externalId.
• Get Conversion Details: Use GET /advertiser/conversions.info if you already know the external ID or the client ID. This returns all information, including the internal Affilae ID.

---

2. Accepting or Refusing a Conversion

Once you have the ID, you can automate validation decisions.

• Accept a Conversion: Use POST /advertiser/conversions.accept to validate a conversion.
  • Required fields: program (Program ID), id (Internal Conversion ID).
• Refuse a Conversion: Use POST /advertiser/conversions.refuse (e.g., for product returns, fraud, or tests).
  • Required fields: program (Program ID), id (Internal Conversion ID), reason (Reason for refusal).

---

3. Adjusting a Conversion Amount (Partial Returns)

If a customer returns part of an order or a cart adjustment is needed, you can modify the amount of a pending conversion.

Use POST /advertiser/conversions.update.

• Conditions:
  • The conversion must be in “pending” status.
  • The adjusted amount must be lower than the initial amount.
• Required fields: id, amount (in cents), reason.

---

API Endpoint Summary

• List conversions: GET /advertiser/conversions.list
• Get conversion info: GET /advertiser/conversions.info
• Accept conversion: POST /advertiser/conversions.accept
• Refuse conversion: POST /advertiser/conversions.refuse
• Adjust amount: POST /advertiser/conversions.update

---

Best Practices

• Mapping: Maintain a link between your internal order IDs (externalId) and Affilae IDs to prevent duplicates.
• Security: Store your API key securely; never share it or include it in client-side code.
• Testing: Run tests on a small volume of conversions before full deployment.
• Rate Limits: The API enforces rate limits. Ensure your scripts handle these limits gracefully.
• Logging: Keep logs of your API calls to simplify troubleshooting and support.

Need help? Our support team is available via your advertiser interface for any technical assistance.