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 redirect ID when a visitor arrives from an affiliate link
  2. Report the transaction when the visitor completes a purchase

1. Capture the redirect ID

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

Example incoming URL:

https://yourstore.com/product/123?revclic_rid=42

You must:

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

JavaScript example

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

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

PHP example

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

2. Report a transaction

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

Recipe: basic transaction with redirect

When you have the revclic_rid from the affiliate link, pass it as redirect_id. The affiliate is automatically resolved from the redirect.

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

Recipe: basic transaction without redirect

When no redirect is available, you must provide the affiliate_id explicitly.

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

Required fields for each item:

Field Description
gtin Product identification code (EAN or UPC)
price Unit price
quantity Number of units
commission_rate Commission percentage for this item

Optional fields:

Field Description
redirect_id The redirect ID captured from the affiliate link. When provided, the affiliate is resolved automatically.
affiliate_id The affiliate ID. Required when redirect_id is not provided.
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 '{
    "redirect_id": 1,
    "basket_items": [
      {
        "gtin": "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/UPC codes — they help identify products in reports

Related endpoints