This article will outline:

• How to automate affiliate sale validations, update transaction metadata, and monitor asynchronous job execution using the Partnerize Brand API

Index

• Step 1: Extracting Pending Conversions
• Step 2 : Auditing conversions against brand's internal system
• Step 3: Validating Statuses and Modifying Metadata
  • 3.1 Validating Conversions
  • 3.2 Modifying Conversions
• Step 4 : Monitoring Job Execution
  • 4.1 How to Track Job Status
  • 4.2 Polling Best Practices

Overview

Conversions / sales tracked in Partnerize are set to pending by default. Once your return window or internal validation period passes, brands must set conversions to approved or rejected for invoicing and partner commission payouts.

Conversion Validation Process

1. Extract: Query pending conversions via reporting endpoints
2. Audit: Cross-reference sales against your internal system
3. Modify : Send validation / modification updates via API
4. Monitor: Poll the job endpoint until processing is complete

While this article details the validation process via the Partnerize API, alternative methods are available, such as utilizing the Bulk Conversion Actions tool directly within the platform user interface.

Additionally, your account may be subject to a contractual Force Approval Period. For detailed information regarding how this period functions, where to locate the configuration within the platform, and how to request modifications, please refer to the Force Approval Period section of our Payment Settings Guide.

Step 1 : Extracting Pending Conversions

To authenticate requests, find your app_api_key and user_api_key in Partnerize under Settings → Account Settings.  Partnerize uses HTTP Basic Authentication formatted as:

https://{app_api_key}:{user_api_key}@api.partnerize.com

Use the Conversion Reporting JSON endpoint to retrieve conversions for validation :

Reporting Endpoint:  

GET /reporting/report_advertiser/campaign/{campaignID}/conversion.json

1.1 Example : Retrieve Pending Conversions via Explicit Date Range (start_date & end_date)

GET /reporting/report_advertiser/campaign/CAMP_123456/conversion.json?start_date=2026-09-01&end_date=2026-09-30&statuses%5B%5D=pending

1.2 Example : Retrieve Pending Conversions via Relative Date Range (text_date)

GET /reporting/report_advertiser/campaign/CAMP_123456/conversion.json?text_date=last+1+days&statuses%5B%5D=pending

1.3 Example : Retrieve Pending Conversions by Fulfilment Date

GET /reporting/report_advertiser/campaign/CAMP_123456/conversion.json?start_date=2026-09-01&end_date=2026-09-30&date_type=fulfilment_date&statuses%5B%5D=pending

Step 2 : Audit conversions against brand's internal system

Every conversion tracked in Partnerize includes a conversion_reference matching your internal order ID. Brands will use this to cross-reference against your internal system to prepare the conversion updates :

• If conversion has passed return window / validation checks : Set status to approved

• If conversion was returned / failed credit checks : Set status to rejected with an appropriate reason

• If conversion details were modified: Update item values and relevant metadata fields

Step 3: Validating Statuses and Modifying Metadata

To update conversion statuses (approved / rejected ) or change metadata in bulk (up to 100,000 items per request), send a POST request to following endpoint 

Update Endpoint

POST /v3/brand/campaigns/{campaignID}/conversions/bulk

3.1 Validating Conversions

Conversions can be updated using three possible references 

• conversion_reference:  Brand's own internal order ID passed into tracking conversionref parameter
• conversion_id: Partnerize's generated ID assigned to each conversion 
• conversion_item_id :  Partnerize's generated ID assigned to each individual item. Applicable when updating multiple items within the same order 

❗VALIDATION NOTE :  Conversion statuses can ONLY be updated prior to being invoiced. Once a conversion has been invoiced, its status is locked❗

3.1.1 Example Payload : Updating Status by Brand Conversion References 

{
  "conversion_references": {
    "ORD-88912": {
      "status": "approved"
    },
    "ORD-44102": {
      "status": "rejected",
      "reason": "Customer returned item"
    }
  }
}

3.1.2 Example Payload : Updating Status by Partnerize Conversion ID

{
    "conversions": {
       "111111l1": {
         "status": "approved" 
       },
       "111111l2": {
         "status": "rejected",
         reason": "Fraud"
       }
     } 
}

3.1.3 Example Payload : Updating Status by Partnerize Conversion Item ID

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

3.2 Modifying Conversions

Data for your conversions may change during its life cycle (E.g if post checkout details become available or adjustments occur - common for travel brands).  Using /conversions/bulk/  endpoint brands can modify item values , statuses or metadata points 

❗MODIFYING  NOTE : Modifying values or metadata fields automatically triggers Partnerize to replay and recalculate commissions based on your campaign rules. Please take into consideration❗

3.2.1 Example Payload : Item-Level update to item_value  and metadata  sale_item

{
  "conversion_items": {
    "111111l4118583": {
      "item_value": 350.00,
      "metadata": {
        "sale_item": "TRUE"
      }
    }
  }
}

3.2.2 Example Payload : Nested validation to approve / reject  AND Item-Level update to metadata  cabin_code /  number_passengers

{
  "conversion_items": {
    "111111l4118583": {
      "status": "rejected",
      "metadata": {
        "cabin_code": "business_class",
         "number_of_passengers": "3"
      }
    },
    "111111l4118584": {
      "status": "approved",
      "metadata": {
        "cabin_code": "economy",
        "number_of_passengers": "2"
      }
    }
  }
}

❗NOTE : Modifying DOES NOT support inserting new item rows into an existing conversion only adding / editing metadata fields ❗

Step 4 : Monitoring Job Execution

Bulk update endpoints execute asynchronously and respond with HTTP 202 Accepted, indicating that the request has been accepted for processing. The response includes a job_id that can be used to monitor execution

Job Endpoint  

GET /v3/jobs/{jobID}

Example Response v3/jobs/111111l11 :  Shows a completed bulk conversion update in which both items were processed successfully:

{
  "data": {
    "id": "111111l11",
    "created_at": "2026-10-15T14:00:00+00:00",
    "status": "complete",
    "type": "conversion_bulk_update",
    "percentage_complete": 100,
    "item_total_count": 2,
    "item_success_count": 2,
    "item_error_count": 0
  }
}

4.1 How to Track Job Status

1. Extract the job_id from the initial bulk update response
2. Send a GET request to /v3/jobs/{jobID} to retrieve the latest job status
3. If processing is ongoing, wait before polling again
4. Once the job reaches a complete status, inspect the item counts to determine the outcome
5. If errors are reported, review the available error details before deciding whether to correct and resubmit affected item

4.2 Polling Best Practices

1. Initial Delay: Wait 3–5 seconds before making the first job-status request
2. Exponential Backoff: Gradually increase polling intervals (e.g. 5s → 10s → 20s), up to a maximum of 30–60 seconds while the job is in progress.
3. Respect Rate Limits: 
   1. Monitor the API's rate-limit response headers (X-RateLimit-Remaining)
   2. If an HTTP 429 response is returned, pause according to the retry guidance provided in X-RateLimit-Retry-After

Additional Resources

• API Extracting Reports :  https://api-docs.partnerize.com/brand/#operation/Export%20Conversions 
• API Updates : https://api-docs.partnerize.com/brand/#operation/v3-conversion-bulk-update 
• API Jobs : https://api-docs.partnerize.com/brand/#operation/get_jobs 
• API Rate Limiting  :  https://api-docs.partnerize.com/brand/#section/Rate-limiting