When to use this vs a webhook integration

If you use Stripe, Paddle, LemonSqueezy, Gumroad, or GoPay, you should set up the webhook integration from the Integration Hub in your dashboard. It's automatic, real-time, and handles refunds.

Use this API endpoint when:

• You use a payment processor we don't natively support
• You want to backfill historical conversions
• You're building a custom integration (e.g. conversions from offline sales, enterprise contracts, or a custom checkout)

Step 1 — Generate an API key

Go to /merchant/api-keys and generate an Ultimate-plan key (write access is required to create conversions). Copy it — you'll only see the full key once.

Step 2 — Verify affiliate and campaign IDs

You need the campaignId of the campaign to attribute the sale to, and the affiliateId of the affiliate who referred it. Both must be active (the affiliate must be approved for the campaign, not rejected).

Fetch them via the API if you don't have them cached:

# List campaigns
curl https://linkjolt.io/api/v1/campaigns \
  -H "Authorization: Bearer lj_pk_your_key"

# List affiliates in a campaign
curl "https://linkjolt.io/api/v1/affiliates?campaignId=camp_abc" \
  -H "Authorization: Bearer lj_pk_your_key"

Step 3 — Create the conversion

POST to /api/v1/conversions with the sale amount. Commission is calculated automatically based on your campaign settings (including tiered commissions if enabled).

curl https://linkjolt.io/api/v1/conversions \
  -X POST \
  -H "Authorization: Bearer lj_pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "camp_abc",
    "affiliateId": "aff_xyz",
    "amount": 99.00,
    "orderId": "invoice-2026-001",
    "clickId": "click_123",
    "customerEmail": "customer@example.com"
  }'

Fields explained

• campaignId (required) — which campaign to attribute to
• affiliateId (required) — the affiliate who referred the sale
• amount (required) — sale amount in dollars (not cents)
• orderId (recommended) — unique per-sale ID. If provided and you re-send the same value, we return 409 to prevent duplicates
• clickId (optional) — the LinkJolt click ID if you have it. Enables fraud detection.
• customerEmail (optional) — enables self-referral fraud detection when combined with clickId

Step 4 — Handle the response

Success: 201 Created with the new conversion record.

{
  "data": {
    "id": "conv_abc123",
    "campaignId": "camp_abc",
    "affiliateId": "aff_xyz",
    "amount": 99.00,
    "commission": 19.80,
    "currency": "usd",
    "status": "pending",
    "orderId": "invoice-2026-001",
    "conversionType": "one_time",
    "createdAt": "2026-04-15T10:30:00Z"
  }
}

Common error responses:

• 400 affiliate_not_approved — the affiliate is rejected or pending for that campaign
• 403 insufficient_permissions — you're using a Pro (read-only) key, not Ultimate
• 403 earnings_limit_reached — your merchant account hit the plan's monthly earnings cap
• 404 not_found — campaign doesn't belong to you
• 409 duplicate — orderId already used
• 429 rate_limit_exceeded — slow down (300 req/min on Ultimate)

Security notes

The endpoint runs the same security checks as webhook handlers:

• Plan earnings limit enforcement
• Rejected affiliate block
• Self-referral fraud detection (when clickId + customerEmail are supplied)

Conversions created via the API are tagged source: 'api' in the database, so you can distinguish them from webhook-created conversions in reports.

Next

Set up outbound webhooks to get notified when the status of conversions changes (pending → approved → paid).

Full reference: POST /api/v1/conversions