Getting started

This guide walks through the shortest path from zero to a recorded conversion: create an account, configure a campaign, generate an API key, send a POST /api/v1/conversions/postback request.

If you already have an account and an API key, skip to Send a conversion.

1. Create a merchant account

Sign up at app.refcampaign.com. You'll receive a verification email; once confirmed, the dashboard prompts you to create your first campaign.

A campaign is the unit affiliates join. Each campaign has its own commission rate, attribution window, and tracking URL. For testing, the defaults are fine.

2. Generate an API key

In the dashboard:

1. Open Settings → API keys.
2. Click Create API key, give it a name (e.g. local-dev).
3. Copy the token. You'll only see it once — store it in a secret manager or a local .env.

The token is an opaque Bearer key prefixed rc_live_ (or rc_test_ in test mode). You'll send it on every API request as:

Authorization: Bearer <YOUR_TOKEN>

3. Choose an attribution input

A conversion should point to an attribution signal. In production, the SDK or tracking URL captures click/session data automatically. For this API quickstart, use a known affiliate code from your campaign and pass it directly as affiliateCode.

4. Send a conversion

Now record a conversion against that affiliate code.

curl -X POST https://app.refcampaign.com/api/v1/conversions/postback \
  -H "Authorization: Bearer $REFCAMPAIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ord_001",
    "conversionType": "SALE",
    "affiliateCode": "affiliate-1",
    "amount": 4990,
    "currency": "EUR"
  }'

A successful response returns 200 with the conversion and commission details:

{
  "success": true,
  "data": {
    "success": true,
    "conversionId": "cnv_01HABCDEFG...",
    "commissionId": "cmm_01HABCDEFG...",
    "commissionAmount": 499
  },
  "meta": {
    "timestamp": "2026-05-03T10:23:11.000Z"
  }
}

The conversion lands in PENDING status. The merchant approves it (or sets up auto-approval rules), at which point a commission is generated for the affiliate.

5. What's next

• Use the SDK instead of curl: the @refcampaign/sdk package handles click + identify automatically from a JS frontend.
• Server-to-server postback: if you already capture conversions in your own backend (webhooks from Stripe, PayPal, etc.), see postback integration.
• Browse the full API: every endpoint, request schema, and response shape is in the API reference. Try requests live with the playground.

Common pitfalls

• 401 Unauthorized — the Authorization header is missing or malformed. Confirm Bearer (with the trailing space) and the full token.
• 400 VALIDATION_FAILED on currency — currency must be a 3-letter ISO 4217 code (EUR, USD, GBP). Lowercase works; symbols and full names don't.
• Conversion not attributed — either the affiliateCode is wrong, sessionId doesn't match a recent click, or the click is older than the campaign's attribution window. Pass customerEmailHash (SHA-256 hex of lowercased email) as a fallback.