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

# Revenue Tracking API

> Documentation for Linkrunner Revenue Tracking API

<Note>
  Revenue data is only stored and displayed for attributed users. The user must have been registered via the `.signup` function in one of the [SDKs](/sdk/flutter#user-registration) for their payment data to appear on Linkrunner. To attribute a test user, follow the [Integration Testing](/testing/integration-testing) guide. You can verify your events are being captured on the [Events Settings](https://dashboard.linkrunner.io/dashboard/settings/events) page.
</Note>

## Base URL

```
https://api.linkrunner.io/api/v1
```

## Authentication

Generate your server code from [https://dashboard.linkrunner.io/settings?s=data-apis](https://dashboard.linkrunner.io/settings?p_id=4\&s=data-apis)

In the request header add the below attribute:

```
linkrunner-key: YOUR-SERVER-KEY
```

## Capture payment

```
POST: /capture-payment
```

### Request Body

```json theme={null}
{
  "user_id": "666",
  "payment_id": "ABC", // optional but recommended
  "amount": 25096, // Send amount in one currency only
  "type": "FIRST_PAYMENT", // optional
  // "type": "SECOND_PAYMENT", // optional
  "status": "PAYMENT_COMPLETED" // optional
}
```

**NOTE:** If you accept payments in multiple currencies convert them to one currency before calling the API.

**Deduplication:** We perform idempotent deduplication using a combination of `type` and `payment_id`. For each unique combination of payment type and payment ID, only one record will be created. If you send multiple requests with the same `type` and `payment_id` combination, only the first will be recorded and subsequent ones will be ignored. To ensure proper deduplication, always provide a unique `payment_id` for each transaction of a given type.

### Payment types

* **FIRST\_PAYMENT**: User's first payment
* **SECOND\_PAYMENT**: User's second payment
* **WALLET\_TOPUP**: Adding funds to a wallet
* **FUNDS\_WITHDRAWAL**: Withdrawing funds
* **SUBSCRIPTION\_CREATED**: Subscription started
* **SUBSCRIPTION\_RENEWED**: Subscription renewed
* **ONE\_TIME**: One-time payment
* **RECURRING**: Recurring payment
* **DEFAULT**: Generic/unspecified payment type

If `type` is omitted, it defaults to **DEFAULT**.

### Payment status

* **PAYMENT\_INITIATED**: Payment has been initiated
* **PAYMENT\_COMPLETED**: Payment completed successfully
* **PAYMENT\_FAILED**: Payment attempt failed
* **PAYMENT\_CANCELLED**: Payment was cancelled

If `status` is omitted, it defaults to **PAYMENT\_COMPLETED**.

### Responses

1. **201** Payment captured
2. **401** Invalid server key

## Remove captured payment

```
POST: /remove-payment
```

### Request Body

```json theme={null}
{
  "user_id": "666",
  "payment_id": "ABC"
}
```

**NOTE:** `user_id` or `payment_id` is required in order to remove a payment entry. If you pass `user_id`, all the payments attributed to that user will be removed!

### Responses

1. **200** Payment entry/entries deleted
2. **400** No payment found with the given payment id or user id
3. **401** Invalid server key

## Meta Ecommerce Events

If you are tracking `Purchase` events to sync with Meta Catalog Sales, **you must first map the purchase event with the standard commerce event in the Linkrunner Dashboard** before sending it.

*Note: Any Payment event you send should be mapped with **Purchase** for Commerce Event Manager. For example, map **FIRST\_PAYMENT** with **Purchase** or **DEFAULT** with **Purchase**.*

While you can include any custom attributes in the `event_data` object, Meta requires specific fields for ecommerce events to correctly attribute catalog sales. Your `event_data` object should include the following fields:

For comprehensive details on each field requirement, refer to our [Meta Commerce Manager](/ecommerce-manager/meta-commerce-manager#understanding-event_data) documentation.

```json theme={null}
{
  "user_id": "666",
  "payment_id": "ABC",
  "amount": 25096,
  "type": "DEFAULT", // Event is mapped with the Purchase in the Linkrunner Meta Integration Settings
  "status": "PAYMENT_COMPLETED",
  "event_data": {
    "content_ids": ["whshct4mwc"],
    "contents": [
      {
        "id": "whshct4mwc",
        "quantity": 2,
        "item_price": 1000
      }
    ],
    "content_type": "product",
    "currency": "INR",
    "value": 2000.0,
    "num_items": 2,
    "order_id": "order_id_1234"
  }
}
```

*Note: In the example above, the `type` field is omitted from the request body, which means it defaults to **DEFAULT**. Ensure this default payment type is properly mapped with **Purchase** in your Linkrunner dashboard.*

To verify your events are being correctly received by Meta, please follow our [Testing Ecommerce Events](/ecommerce-manager/meta-commerce-manager#testing-ecommerce-events) guide.