> ## Documentation Index
> Fetch the complete documentation index at: https://developers.tapfiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server-to-server tracking

> Track conversions and customers from your backend with postback requests.

Postbacks let your server report sales and sign-ups directly, without code in the browser. Use them when the purchase happens in your backend, in an app, or on a platform where you can't run tapfiliate.js.

Each postback is a single `GET` or `POST` request. Authenticate it with your API key in the `X-Api-Key` header, as described in [Authentication](/authentication).

| Action | Endpoint |
| - | - |
| Create a conversion | `https://api.tapfiliate.com/1.7/pb/con/c/` |
| Update a conversion | `https://api.tapfiliate.com/1.7/pb/con/u/` |
| Create a customer | `https://api.tapfiliate.com/1.7/pb/cus/c/` |
| Update a customer | `https://api.tapfiliate.com/1.7/pb/cus/u/` |

## Who referred the visitor

To attribute a conversion or customer, send one of these. If you send several, the first one in this list wins:

1. `coupon` — the affiliate's coupon code.
2. `click_id` — the click ID, if you stored it when the visitor arrived.
3. `referral_code` — the affiliate's referral code, the value of `ref=` in their link.
4. `asset_id` and `source_id` — from the affiliate's link.

## Create a conversion

<CodeGroup>
  ```bash POST theme={null}
  curl -X POST https://api.tapfiliate.com/1.7/pb/con/c/ \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "referral_code": "janejameson",
      "external_id": "ORD005",
      "amount": 100
    }'
  ```

  ```bash GET theme={null}
  curl "https://api.tapfiliate.com/1.7/pb/con/c/?referral_code=janejameson&external_id=ORD005&amount=100" \
    -H "X-Api-Key: YOUR_API_KEY"
  ```
</CodeGroup>

| Parameter | Description |
| - | - |
| `external_id` | Required. A unique ID for this conversion, such as your order ID. |
| `amount` | The conversion amount. Commissions are calculated from it. |
| `currency` | Three-letter ISO currency code. The program currency is used if omitted. |
| `customer_id` | Your ID of the customer. Used for recurring and lifetime commissions, depending on your program settings. |
| `meta_data` | Extra data to store with the conversion, as an object. |
| `user_agent` | The visitor's user agent, for statistics and fraud detection. |
| `ip` | The visitor's IP address, for fraud detection. |

A successful request returns `200` with the created conversion:

```json theme={null}
{
  "id": "cv_Ma5Z-kgUwHqoWUz9vE",
  "external_id": "ORD005",
  "amount": 100.0,
  "created_at": "2023-03-15T08:51:10+00:00",
  "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" },
  "affiliate": { "id": "u_JaN3-J0n", "firstname": "Jane", "lastname": "Jameson" },
  "commissions": [
    { "id": "cm_FlC2mbDUM-o52U3NQj", "amount": 10.0, "currency": "USD", "commission_type": "standard", "approved": null }
  ]
}
```

## Update a conversion

Approve or disapprove a conversion, or correct its amount, by its `external_id`. Commission amounts are recalculated.

```bash theme={null}
curl -X POST https://api.tapfiliate.com/1.7/pb/con/u/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ORD005",
    "status": "disapproved",
    "amount": 100
  }'
```

| Parameter | Description |
| - | - |
| `external_id` | Required. The ID of the conversion to update. |
| `status` | `approved` or `disapproved`. |
| `amount` | The new conversion amount. |
| `meta_data` | Extra data to store with the conversion. |

## Create a customer

Track a sign-up before the first payment. Later conversions with the same `customer_id` are attributed to the same affiliate.

```bash theme={null}
curl -X POST https://api.tapfiliate.com/1.7/pb/cus/c/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_code": "janejameson",
    "customer_id": "USER1234",
    "status": "trial"
  }'
```

| Parameter | Description |
| - | - |
| `customer_id` | Required. Your ID of the customer, unique per customer. |
| `status` | Initial status: `new` (default), `trial` or `lead`. |
| `meta_data` | Extra data to store with the customer. |
| `user_agent` | The visitor's user agent. |
| `ip` | The visitor's IP address. |

## Update a customer

```bash theme={null}
curl -X POST https://api.tapfiliate.com/1.7/pb/cus/u/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "USER1234",
    "meta_data": { "plan": "pro" }
  }'
```

## Passing affiliate data through

Affiliates can add `tm_` parameters to their links, for example `?tm_foo=bar&tm_baz=qux`. To keep this data, read the parameters from the landing URL and send them as `meta_data`, here `{ "foo": "bar", "baz": "qux" }`.

<Note>
  Track a test conversion before you launch your program to check the whole flow.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.