Revclic
Guides

Integration guide

This guide explains how to integrate Revclic into your e-commerce platform. For complete endpoint specifications, see the API Reference.

Overview

The integration consists of two steps:

  1. Capture the tracking ID when a visitor arrives from an affiliate link
  2. Report the transaction when the visitor completes a purchase

1. Capture the tracking ID

When a shopper clicks an affiliate link, they are redirected to your website with a revclic_id parameter in the URL.

Example incoming URL:

https://yourstore.com/product/123?revclic_id=3B01WYNUGO1R4G20

You must:

  • Extract the revclic_id from the URL
  • Store it in a cookie or session for the duration of the visit

JavaScript example

// extract revclic_id from URL and store in cookie
const urlParams = new URLSearchParams(window.location.search);
const revclicId = urlParams.get('revclic_id');

if (revclicId) {
  document.cookie = `revclic_id=${revclicId}; max-age=2592000; path=/`; // 30 days
}

PHP example

// extract revclic_id from URL and store in session
if (isset($_GET['revclic_id'])) {
    $_SESSION['revclic_id'] = $_GET['revclic_id'];
}

2. Report a transaction

After a successful purchase, send the transaction to Revclic using the Create Transaction endpoint.

Recipe: basic transaction

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_id": "3B01WYNUGO1R4G20",
    "basket_items": [
      {
        "ean": "1234567890123",
        "name": "Laptop Stand",
        "price": 49.99,
        "quantity": 2,
        "commission_rate": 10.0
      }
    ]
  }'

Required fields for each item:

Field Description
ean Product EAN code
price Unit price
quantity Number of units
commission_rate Commission percentage for this item

Optional fields:

Field Description
tracking_id The revclic_id captured from the affiliate link
name Product name (for display purposes)
status Initial item status: pending (default), accepted, or rejected

Recipe: transaction with pre-accepted items

If your return policy does not apply (e.g. digital goods, non-refundable orders), you can report items as already accepted at creation time. This skips the validation window and the commission is included in the next invoice immediately.

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_id": "3B01WYNUGO1R4G20",
    "basket_items": [
      {
        "ean": "9876543210987",
        "name": "Digital License",
        "price": 19.99,
        "quantity": 1,
        "commission_rate": 15.0,
        "status": "accepted"
      }
    ]
  }'

3. Validate or reject items

You have 3 months to review each item. Use the Update Transaction endpoint to change item statuses.

Recipe: update a single item

Update a specific item by its ID:

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 123, "status": "accepted" }
    ]
  }'

Recipe: reject a returned item

If the customer returns an item:

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 456, "status": "rejected" }
    ]
  }'

Recipe: update multiple items at once

You can update several items in a single request:

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 123, "status": "accepted" },
      { "id": 456, "status": "rejected" }
    ]
  }'

Item statuses:

Status Meaning
pending Awaiting validation (default)
accepted Commission confirmed
rejected No commission (returned, cancelled, invalid)

Item validation rules

  • Each item must include its id (returned when the transaction was created)
  • You can only update the status field
  • You can update one item, several items, or all items in a single request
  • Items not reviewed within 3 months are automatically accepted
  • Commission is only calculated for accepted items

Understanding the status field

Every transaction includes a read-only status field that is computed automatically from its basket item statuses. It cannot be set directly on the transaction.

Value Condition
pending At least one item is still pending
accepted All items are accepted, or a mix of accepted and rejected
rejected All items are rejected

The transaction status is recalculated every time an item status changes.

Understanding the reward field

Every transaction includes a read-only reward field that reflects the billing and payout lifecycle of the commission. It is managed automatically by Revclic and cannot be set manually.

Value Meaning
pending Commission is waiting for the validation window to close and an invoice to be generated
to_be_paid An invoice has been generated and is awaiting merchant payment
paid The merchant has paid the invoice — the commission is now due to the affiliate
complete The affiliate payout has been issued

The reward value progresses through these stages in order and can only move forward.

Best practices

  • Report transactions promptly — send them as soon as the order is confirmed
  • Store the tracking ID reliably — use server-side sessions or secure cookies
  • Validate items regularly — don't wait for auto-acceptance
  • Use meaningful EAN codes — they help identify products in reports

Related endpoints