The Partnac REST API allows you to securely track clicks and conversions from your backend server, sync historical data, issue refunds, and update conversion states. Because it is server-to-server, it is completely immune to ad-blockers and browser privacy restrictions.
Authentication
All Tracking API requests must be authenticated using your Partnac Secret API Key. Pass your key in the Authorization header as a Bearer token.
- Authorization: Bearer YOUR_PARTNAC_SECRET_KEY
All requests must have the Content-Type: application/json header.
1. Track a Conversion
The most common use case for the API is registering a new conversion, such as a paid subscription, sale, or lead.
Endpoint: POST /v1/tracking/conversions
Request Body
Field | Type | Required | Description |
partnership_code | string | Yes | The unique referral/coupon code of the partner. |
unique_id | string | Yes | Your system's unique identifier (e.g., Order ID). Prevents duplicate tracking. |
conversion_type | string | Yes | sale, lead, referral, subscription, custom. |
amount | float | Yes | The monetary value. Use 0 for free signups or leads. |
campaign_id | string | No | Specific campaign ID (Partnac infers this from the partnership code if omitted). |
session_id | string | No | The click_id stored in the user's browser cookie (used to link the conversion back to the original click). |
metadata | object | No | A flexible JSON object for context (see below). |
Special Metadata Keys: Partnac extracts the following keys from metadata if provided:
- currency: Defaults to USD.
- customer_id: Essential for tracking lifetime value and recurring subscriptions. Must be the same throught the customer lifecycle.
- coupon_code: The discount code applied at checkout.
- ip_address & user_agent: Strongly recommended for fraud prevention.
- country, city, region: For geolocation insights.
Example Request
- curl -X POST https://api.partnac.com/v1/tracking/conversions \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "partnership_code": "PARTNER_REF_123",
- "unique_id": "order_10045",
- "conversion_type": "sale",
- "amount": 99.00,
- "metadata": {
- "currency": "USD",
- "customer_id": "cus_987654",
- "ip_address": "192.168.1.1",
- "user_agent": "Mozilla/5.0..."
- }
- }'
2. Refund a Conversion
If a customer refunds an order or disputes a charge, you can notify Partnac to automatically adjust or reverse the partner's earned commissions.
Endpoint: POST /v1/tracking/conversions/:id/refund (Note: :id must be the same unique_id used during sales conversion tracking)
Request Body
Field | Type | Required | Description |
amount | float | No | The amount to refund. If omitted, Partnac processes a full refund. |
reason | string | No | Why the refund occurred (e.g., fraud, customer_request). |
| external_refund_id | string | No | Your system's refund transaction ID. |
reverse_paid_earnings | bool | No | Defaults to true. If true, Partnac will deduct the refunded commission from the partner's future balance if they have already been paid. |
3. Update a Conversion
Used if you need to retroactively change the value of a conversion (e.g., an order was modified or upsold post-purchase).
Endpoint: PATCH /v1/tracking/conversions/:id
Request Body
Field | Type | Required | Description |
amount | float | No | The new total value of the conversion. |
unique_id | string | No | Your system's unique identifier (e.g., Order ID). Must be the same unique_id used during sales conversion tracking |
metadata | object | No | Merge new metadata into the conversion data. |
recalculate_commissions | bool | No | If true, Partnac will recalculate the partner's commission based on the new amount.
|
4. Track a Click (S2S)
While clicks are usually tracked via tracker.js, you can manually record a click if you handle redirects purely on your backend.
Endpoint: POST /v1/tracking/clicks
Request Body
Field | Type | Required | Description |
| partnership_code | string | Yes | The affiliate's code used by the user. |
click_url | string | Yes | The URL the user landed on. |
referrer_url | string | No | The URL the user came from. |
screen_width | int | No | The user's screen width |
ip_address | string | No | The user's ip address |
5. Retrieve Tracking Data
You can extract raw data from Partnac for your own reporting or data warehouses.
List Conversions: GET /v1/tracking/conversions
List Clicks: GET /v1/tracking/clicks
Query Parameters
- limit: Number of records to return (Default 20, Max 100).
- offset: Pagination offset.
- campaign_id: Filter by a specific campaign.
- partnership_id: Filter by a specific partner.
Example Request:
Related Articles
Welcome to Partnac: A Quick Start Guide for Brands
Welcome to Partnac. You're here because you want to grow your brand through partnerships, whether that's affiliate marketing, influencer collaborations, or creator partnerships. This guide will get you up and running in the next 15 minutes. Partnac ...
Understanding Partnac's Partnership Models
Not all partnerships are created equal. On Partnac, you can run different types of campaigns depending on your goals, budget, and what you're trying to achieve. Understanding these models helps you choose the right approach and set up campaigns that ...
Integrating Partnac Tracking into Your Website
The foundation of any successful partner program on Partnac is accurate tracking. The Partnac tracking script (tracker.js) seamlessly attributes clicks to the right partners and tracks when those clicks result in a conversion, such as a signup, ...
How Partner Payouts Work on Partnac
Partnac ensures secure and transparent financial interactions between brands and partners using a built-in escrow system. When a brand initiates a campaign or accepts an application, funds are securely held to guarantee payment upon successful ...
Setting Up Conversion Tracking (Pixels and Postbacks)
While the standard Partnac JavaScript tracker (tracker.js) is the recommended method for most websites, some scenarios require a different approach. If you need to track backend subscription renewals, integrate with a CRM, or operate in environments ...