Skip to content

Revenue Tracking API ​

Documentation for Linkrunner Revenue Tracking API

Revenue is stored for all users, including organic ones. Payments from users with no matching click are stored without campaign attribution. Each request must identify the user with user_id or install_instance_id. You can verify your events are being captured on the Events page.

Use Test Custom Events and Payments to verify event classification, payment fields, and deduplication.

Base URL ​

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

Authentication ​

Generate your server code from https://dashboard.linkrunner.io/settings?s=data-apis

In the request header add the below attribute:

linkrunner-key: YOUR-SERVER-KEY

Capture payment ​

POST: /capture-payment

Request Body ​

json
{
  "user_id": "666",
  "payment_id": "ABC", // required, must be unique for each transaction
  "amount": 25096, // Send amount in one currency only
  "type": "FIRST_PAYMENT", // optional
  // "type": "SECOND_PAYMENT", // optional
  "status": "PAYMENT_COMPLETED", // optional
  "source": "app" // optional: "app" (default) or "web"
}

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.

End-user IP address ​

These calls come from your server, so Linkrunner never sends your server's IP to ad networks as the user's IP. By default it sends the device IP captured when the app was installed. If you know the IP of the user's device at the time of the payment, pass it as client_ip_address. Linkrunner forwards it to ad networks (for example Meta client_ip_address) to improve matching.

  • Send only the device's public IP. Private, loopback and link-local addresses are ignored.
  • Leave it out if you don't have it. Linkrunner then uses the install-time device IP.

Website payments ​

If the payment comes from a user of your website rather than your app, send "source": "web". Your website must be tracked with the Web SDK, and the payment then shows up on the Web Events page instead of the app dashboards. Leave source out, or send app, for app users. Existing integrations do not need to change.

json
{
  "user_id": "user_12345",
  "payment_id": "ORDER-1001",
  "amount": 499,
  "currency": "INR",
  "type": "FIRST_PAYMENT",
  "status": "PAYMENT_COMPLETED",
  "source": "web"
}
  • Identify the user with user_id. Use the same ID your website passes to lr.identify. install_instance_id does not apply to website users, so user_id is required.
  • Status decides how it counts. A PAYMENT_COMPLETED payment is recorded as a purchase event, the same event the Web SDK sends with lr.track('purchase', …), and counts as a purchase and revenue. Other statuses are recorded as payment_initiated, payment_failed, or payment_cancelled and do not count as revenue.
  • Stored details. amount, currency, payment_id, type, and status are added to the event's event_data, together with any event_data you send. The amount is stored as both amount and value, so a value in your event_data is replaced.
  • Attribution. Linkrunner credits the payment to the channel and campaign of that user's latest visit recorded by the Web SDK in the last 90 days. If the Web SDK has not recorded a visit from that user, the payment shows as Direct.
  • No deduplication. Unlike app payments, every website payment request is stored, including retries with the same type and payment_id. Avoid resending a payment that was already accepted.
  • Send each purchase from one place. If your website also calls lr.track('purchase', …) for the same order, the purchase is counted twice. Track it either in the browser or from your backend, not both.

Responses ​

  1. 201 Payment captured. For app payments, sending the same type and payment_id again also returns 201, and Linkrunner counts that payment once.
  2. 400 source is not app or web, or source is web and user_id is missing or website tracking is not enabled for the project
  3. 401 Invalid server key

Sample Response ​

json
{
  "msg": "Payment capture request received!",
  "status": 201,
  "processing_id": "0b7e4d2c-81a5-4f3e-9c6d-5a2f1e8b3d47",
  "data": {
    "message": "Payment capture request received!"
  }
}

processing_id identifies this request. Log it on your side and share it with Linkrunner support if a payment does not show up.

Remove captured payment ​

POST: /remove-payment

Request Body ​

json
{
  "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 documentation.

json
{
  "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 guide.

Need help? Contact support@linkrunner.io.

Need help? Contact support@linkrunner.io