Tracking API
Track Sale
Record an attributed sale and create the partner commission from your backend
Call this endpoint from your server after a payment succeeds to record the conversion and trigger commission creation.
The tax, currency and conversion rules below apply to API sales recorded from this time. Sales recorded earlier keep their existing pricing.
Endpoint
POST https://api.affitor.com/api/v1/track/sale
Authorization: Bearer YOUR_PROGRAM_API_KEY
Content-Type: application/jsonAuthentication
All requests require a program API key sent as a Bearer token in the Authorization header. The API key is found in your program settings in the Affitor dashboard.
Authorization: Bearer YOUR_PROGRAM_API_KEYRequest Fields
Your unique payment identifier. Used for duplicate detection; re-sending the same value returns 409.
Sale amount in the smallest currency unit (e.g. cents for USD). Must be a positive integer.
The tax included in amount_cents, in the same unit. Used to calculate the pre-tax commission basis: amount_cents - tax_cents. If provided and not null, it must be an integer from 0 to amount_cents, inclusive. Otherwise, the API returns 400 invalid_request with the message tax_cents must be an integer between 0 and amount_cents. If omitted or null, the whole amount is the basis.
Your internal customer/user ID. It matches a key already stored on a customer in your program, for example by a server-verified lead or an attributed Stripe payment. By default a browser signup() alone records a provisional lead, which does not store the key, so send a matching click_id as well when the key has not been stored. At least one of customer_key or click_id must match an existing customer record.
The Affitor click ID (affitor_click_id cookie value). Used as fallback attribution when customer_key is not provided.
A supported ISO 4217 currency code. Defaults to USD. Codes without a numeric minor unit are unsupported, as are BOV, CHE, CHW, COU, MXV, USN, UYI, UYW, VED and XAD. An unsupported code returns 422 unsupported_currency before creating a sale, commission or fee.
"payment" (default) or "subscription".
paymentsubscriptionArbitrary line-item detail to store with the sale record.
true if this is a recurring billing charge. Defaults to false.
Your subscription identifier, stored with the sale. Affitor does not use it to find the customer or to calculate the commission: send each renewal as its own sale, with its own transaction_id.
"monthly", "quarterly", or "annual".
monthlyquarterlyannualYour product identifier. Used for per-product commission policy matching.
When the payment happened, as ISO 8601 with an offset (for example 2026-10-16T09:30:00Z), no more than 30 days old and at most 5 minutes in the future. Stored for reporting only: commissions, attribution windows and hold periods still use the time Affitor receives the call.
Your payment provider. Stored for reporting.
stripepolardodopaddlelemonsqueezycreemsepaypayosapipayx402otherThe provider's own payment id (1 to 255 characters). Stored for reporting; duplicate detection still uses transaction_id.
false records a test sale, the same as additional_data.test_mode: true. true or omitted does not force a live sale: additional_data.test_mode: true or a test API key still records a test sale.
Minor units and conversion
Despite its name, amount_cents uses the currency's minor unit, not always hundredths. Use the same unit for tax_cents.
| Currency | Decimal places | Sale amount | amount_cents |
|---|---|---|---|
| USD | 2 | USD 49.00 | 4900 |
| VND | 0 | VND 490,000 | 490000 |
| JPY | 0 | JPY 490,000 | 490000 |
| BHD | 3 | BHD 1.234 | 1234 |
| KWD | 3 | KWD 1.234 | 1234 |
For a supported non-USD currency, Affitor converts the pre-tax basis to USD using a stored daily rate dated on the UTC day it receives the sale or within the preceding seven days. USD uses a rate of 1. occurred_at does not change that rate-selection day. The sale record keeps the original currency, total, tax and pre-tax amount alongside its pricing result.
Within that window, Affitor chooses the newest day with a quote or hold for that currency. On that day, it uses the primary source; the secondary source is considered only when the primary source has no entry for the currency. A held or invalid entry from the selected source blocks fallback to the other source and to an older day.
If no usable rate is selected, an otherwise accepted sale is kept unpriced. That sale is kept with money_status: "fx_pending" and no commission or platform fee. It is not automatically priced later. Do not resend it: its transaction_id is already recorded, so another call returns 409 duplicate_transaction.
Request Body Example
curl -X POST https://api.affitor.com/api/v1/track/sale \
-H "Authorization: Bearer YOUR_PROGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "txn_abc123",
"customer_key": "usr_9876",
"amount_cents": 4900,
"tax_cents": 400,
"currency": "USD",
"sale_type": "payment"
}'The USD example sends a total of 4900 minor units, including 400 of tax. The commission basis is 4500 minor units (USD 45.00).
Subscription example
{
"transaction_id": "inv_sub_001",
"customer_key": "usr_9876",
"amount_cents": 4900,
"currency": "USD",
"sale_type": "subscription",
"is_recurring": true,
"subscription_id": "sub_stripe_xyz",
"subscription_interval": "monthly",
"product_id": "prod_pro_plan"
}Response
{
"success": true,
"sale_id": 42,
"commission_id": 17,
"message": "Sale tracked successfully"
}| Field | Type | Description |
|---|---|---|
success | boolean | true on success. |
sale_id | integer or null | ID of the created sale event record; null when the attribution window expired. |
commission_id | integer or null | ID of the created commission record; null when the attribution window expired or the sale was kept unpriced. |
message | string | Human-readable confirmation, when present. |
money_status | string | fx_pending in the unpriced response above. |
Re-sending the same transaction_id returns 409 Conflict with error.code duplicate_transaction and your program's earlier sale id in error.details.sale_id, or null when the earlier sale belongs to another program. Affitor does not create a duplicate sale, so you can safely retry on network failure. Retry a 500 the same way, with the same transaction_id: a 500 does not prove that nothing was recorded. A retry can fail again with 500; one that reaches the duplicate check answers 409 with your program's sale_id if an earlier attempt recorded the sale, so the sale is not recorded twice.
A 409 response with a sale_id means your program already recorded this sale. Do not retry a 409; treat it as a successful prior call and continue your payment flow normally. A 409 with sale_id: null means another program already used this transaction_id, so nothing was recorded for your program.
Error Responses
Most errors use the platform envelope { "data": null, "error": { "status", "name", "message", "details", "code" } }. A retired API key and rate limiting use the typed envelope { "error": { "code", "message", ... } }. Either way, branch on error.code; the message text may change.
| Status | error.code | When |
|---|---|---|
400 | invalid_request | transaction_id missing or not a string; amount_cents not a positive integer; a supplied non-null tax_cents not an integer from zero to the amount; an invalid occurred_at, provider, provider_payment_id or livemode |
400 | no_attribution | Neither customer_key nor click_id resolved a customer, the customer belongs to another program, or no partner relationship was found |
401 | unauthorized | Missing or malformed Authorization header, or the API key does not match any active program |
401 | api_key_rotation_required | A retired API key (the body also carries hint and docs_url) |
409 | duplicate_transaction | transaction_id already recorded; error.details.sale_id is your program's earlier sale id, or null when it belongs to another program |
422 | unsupported_currency | currency is not supported; no sale, commission or fee is created |
429 | rate_limited | Too many requests; wait retry_after_seconds |
500 | internal_error | The sale could not be recorded, or the server could not confirm that it was. Retry with the same transaction_id |
Test Mode
Send additional_data.test_mode: true (or livemode: false) to create a test sale event without creating a live commission. The API key is still required but transaction_id and amount_cents are optional in test mode. From the time above, a supplied currency and amount must follow the same supported-code, minor-unit and tax rules.
{
"additional_data": {
"test_mode": true
}
}Test mode response:
{
"success": true,
"message": "Test sale event tracked successfully",
"data": {
"eventId": 12,
"programId": 3,
"test_mode": true
}
}