---
id: "api-reference/track-sale"
type: "doc"
url: "https://affitor.com/docs/api-reference/track-sale"
kind: "reference"
updated: "2026-11-08"
---
# 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.

<Callout type="info" title="Sales recorded from November 5, 2026 (16:00 UTC)">
  The tax, currency and conversion rules below apply to API sales recorded from this time. Sales recorded earlier keep their existing pricing.
</Callout>

## Endpoint

```
POST https://api.affitor.com/api/v1/track/sale
Authorization: Bearer YOUR_PROGRAM_API_KEY
Content-Type: application/json
```

---

## Authentication

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_KEY
```

---

## Request Fields

<ParamList>
  <ParamField name="transaction_id" type="string" required>
    Your unique payment identifier. Used for duplicate detection; re-sending the same value returns 409.
  </ParamField>
  <ParamField name="amount_cents" type="integer" required>
    Sale amount in the smallest currency unit (e.g. cents for USD). Must be a positive integer.
  </ParamField>
  <ParamField name="tax_cents" type="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.
  </ParamField>
  <ParamField name="customer_key" type="string" requirement="conditional">
    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.
  </ParamField>
  <ParamField name="click_id" type="string" requirement="conditional">
    The Affitor click ID (`affitor_click_id` cookie value). Used as fallback attribution when `customer_key` is not provided.
  </ParamField>
  <ParamField name="currency" type="string">
    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.
  </ParamField>
  <ParamField name="sale_type" type="string" enum={["payment", "subscription"]}>
    `"payment"` (default) or `"subscription"`.
  </ParamField>
  <ParamField name="line_items" type="object">
    Arbitrary line-item detail to store with the sale record.
  </ParamField>
  <ParamField name="is_recurring" type="boolean">
    `true` if this is a recurring billing charge. Defaults to `false`.
  </ParamField>
  <ParamField name="subscription_id" type="string">
    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`.
  </ParamField>
  <ParamField name="subscription_interval" type="string" enum={["monthly", "quarterly", "annual"]}>
    `"monthly"`, `"quarterly"`, or `"annual"`.
  </ParamField>
  <ParamField name="product_id" type="string">
    Your product identifier. Used for per-product commission policy matching.
  </ParamField>
  <ParamField name="occurred_at" type="string">
    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.
  </ParamField>
  <ParamField name="provider" type="string" enum={["stripe", "polar", "dodo", "paddle", "lemonsqueezy", "creem", "sepay", "payos", "apipay", "x402", "other"]}>
    Your payment provider. Stored for reporting.
  </ParamField>
  <ParamField name="provider_payment_id" type="string">
    The provider's own payment id (1 to 255 characters). Stored for reporting; duplicate detection still uses `transaction_id`.
  </ParamField>
  <ParamField name="livemode" type="boolean">
    `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.
  </ParamField>
</ParamList>

---

## 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

<CodeGroup items={[
  {
    label: "cURL",
    lang: "bash",
    code: `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"
  }'`
  },
  {
    label: "Node.js",
    lang: "javascript",
    code: `const res = await fetch('https://api.affitor.com/api/v1/track/sale', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_PROGRAM_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transaction_id: 'txn_abc123',
    customer_key: 'usr_9876',
    amount_cents: 4900,
    tax_cents: 400,
    currency: 'USD',
    sale_type: 'payment',
  }),
});
const data = await res.json();`
  },
  {
    label: "Python",
    lang: "python",
    code: `import requests

response = requests.post(
    'https://api.affitor.com/api/v1/track/sale',
    headers={
        'Authorization': 'Bearer YOUR_PROGRAM_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'transaction_id': 'txn_abc123',
        'customer_key': 'usr_9876',
        'amount_cents': 4900,
        'tax_cents': 400,
        'currency': 'USD',
        'sale_type': 'payment',
    },
)
data = response.json()`
  },
]} />

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

```json
{
  "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

<ResponseTabs items={[
  {
    status: 200,
    label: "200 Attributed",
    code: `{
  "success": true,
  "sale_id": 42,
  "commission_id": 17,
  "message": "Sale tracked successfully"
}`
  },
  {
    status: 200,
    label: "200 Unpriced",
    code: `{
  "success": true,
  "sale_id": 42,
  "commission_id": null,
  "money_status": "fx_pending"
}`
  },
  {
    status: 200,
    label: "200 Window Expired",
    code: `{
  "success": true,
  "attributed": false,
  "reason": "attribution_window_expired",
  "click_age_days": 75,
  "window_days": 60,
  "sale_id": null,
  "commission_id": null
}`
  },
  {
    status: 409,
    label: "409 Duplicate",
    code: `{
  "data": null,
  "error": {
    "status": 409,
    "name": "ConflictError",
    "message": "Duplicate transaction_id. This sale has already been recorded.",
    "details": { "sale_id": 42 },
    "code": "duplicate_transaction"
  }
}`
  },
]} />

| 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. |

<Callout type="info" title="Idempotency">
  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.
</Callout>

<Callout type="warning" title="409 is not an error">
  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.
</Callout>

---

## Error Responses

Most errors use the [platform envelope](/docs/api-reference/errors#the-platform-envelope) `{ "data": null, "error": { "status", "name", "message", "details", "code" } }`. A retired API key and rate limiting use the [typed envelope](/docs/api-reference/errors#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.

```json
{
  "additional_data": {
    "test_mode": true
  }
}
```

Test mode response:

```json
{
  "success": true,
  "message": "Test sale event tracked successfully",
  "data": {
    "eventId": 12,
    "programId": 3,
    "test_mode": true
  }
}
```

---

## Related

- [Lead Tracking (Signup)](/docs/brand/tracking/lead-tracking-signup/)
- [Tracking Overview](/docs/brand/tracking/tracking-overview/)
- [Testing Integration](/docs/brand/tracking/testing-integration/)
