__________________________________________________________________________________________________________________

This article will review:

• The process to follow when implementing automated validations via the Partnerize API
• The API endpoints to use and sample POST arrays
• Links to supporting supporting documentation

__________________________________________________________________________________________________________________

Index

• Overview
• Implementation Steps

Overview

Transactions that track within the Partnerize platform must be validated before they can be invoiced and commission is subsequently paid to partners.  It is the responsibility of the brand to ensure that all tracked transactions are validated.  There are numerous ways in which a transaction can be validated, but the recommended approach to this would be for the brand to automate their validations process via the Partnerize API.  This gives the following benefits:

• Reduces time spent manually validating transactions
• Ensures that the Partnerize system is in sync with the brand's own back end systems, in terms of transactions statuses
• Validations can be ran at whichever frequency is required by the brand (i.e. daily, weekly, monthly)

Implementation Steps

A conversion in the Partnerize system is tracked in a pending status by default, when the conversion call is first sent to Partnerize at point of sale. The conversionref parameter in the tracking method (pixel or server to server conversion call) should be populated with the reference with which the brand wishes to validate. This should be the booking ID/Order reference/Order ID.

Brands would then need to extract a pending conversion report from the Partnerize API, cross reference the conversion reference with the order references in their own system and establish which conversions should be approved/rejected.

API Call to extract pending orders:

Conversion (basket) level:

https://{app_api_key}:{user_api_key}@api.partnerize.com/reporting/report_advertiser/campaign/{campaign_id}/conversion.{format}?start_date={YYYY-MM-DD hh:mm:ss}&end_date={YYYY-MM-DD hh:mm:ss}&statuses%5B%5D=pending 

Conversion item level: 

https://{app_api_key}:{user_api_key}@api.partnerize.com​/reporting/e​xport/​​export/​conversion_item.csv?​s​tart_date={YYYY-MM-DD hh:mm:ss}&end_date={YYYY-MM-DD hh:mm:ss}​&campaign_id={campaign_id}​&statuses%5B%5D=pending 

__________________________________________________________________________________________________________________

❗NOTE:

• The 'app_api_key' and 'user_api_key' will need to be obtained via the Partnerize platform for the brand's network.  These can be found below:
  • Application API Key (Settings > Account Settings > User Application Key)
  • User API Key (Settings > Account Settings > User API Key)
• Format : Please substitute with either json or xml depending on the required format
• The dynamic 'text_date' functionality can also be used for both endpoints, as an alternative to 'start_date' and 'end_date', for example:
  • text_date=last+7+days

__________________________________________________________________________________________________________________

Conversion validation process:

Once the brand has all of conversions which need to be approved/rejected, the following endpoint can be used to update the conversion status and, where applicable, add an optional reject reason to any rejected conversions.  To approve/reject, one of three different IDs can be used:

• conversionref:
  • This would typically be the brand's own internal transaction ID/order ID
• conversion_id:
  • The Partnerize-generated ID assigned to each conversion when a transaction hits the tracking servers
• conversion_item_id
  • The Partnerize-generated ID assigned to each conversion item when a transaction hits the tracking servers

__________________________________________________________________________________________________________________

❗NOTE:

• To perform item level validation (i.e. where a basket contains multiple items of differing statuses), this validation MUST be performed using the Partnerize conversion_item_id.

__________________________________________________________________________________________________________________

API endpoint to use to validation transactions:​

https://XXXXXXX:YYYYYYY@api.partnerize.com​/v3/brand/campaigns/{campaignID}/conversions/bulk​

Sample conversion API approval POST body (using conversion_reference):

{
    "conversion_references": {
       "AUTO-5de90e8ccdc106.23934624": {
          "status": "approved" 
       },
       "AUTO-0de90e8adec106.23934947": { 
          "status": "approved",
       }
    } 
}

Sample conversion API approval POST body (using conversion_id):

{
    "conversions": {
       "111111l1": {
         "status": "approved" 
       },
       "111111l2": {
         "status": "approved",
       }
     } 
}

Sample conversion API approval POST body (using conversion_item_id):

{
  "conversion_items": {
    "111111l3": {
      "status": "approved" 
    },
    "111111l4": {
      "status": "approved",
    }
  } 
}

Sample conversion API rejection POST body (using conversion_reference):

{
    "conversion_references": {
       "AUTO-5de90e8ccdc106.23934624": {
          "status": "rejected" 
       },
       "AUTO-0de90e8adec106.23934947": { 
          "status": "rejected",
          "reason": "cancelled order" }
    } 
}

Sample conversion API rejection POST body (using conversion_id):

{
  "conversions": {
    "111111l1": {
      "status": "rejected" 
    },
    "111111l2": {
      "status": "rejected",
      "reason": "cancelled order" 
    }
   } 
}

Sample conversion API POST body - approvals and rejections (using conversion_item_id):

{
  "conversion_items": {
    "111111l3": {
      "status": "approved" 
    },
    "111111l4": {
      "status": "rejected",
      "reason": "cancelled order" 
    }
  } 
}

API endpoint documentation:

https://api-docs.partnerize.com/brand/#tag/Campaign-Conversions