API Reference

The Refuel REST API is organized around standard HTTP methods. All request and response bodies use JSON. Amounts are in cents (integer).

Base URL: https://api.refuel.dev

Authentication: Most endpoints require a JWT token in the Authorization: Bearer header. Conversion tracking uses the x-api-key header with your secret key.

Authentication

Magic-link based passwordless authentication for companies and affiliates.

POST/auth/magic-link

Send a magic link to the user's email address. The link expires after 15 minutes.

Request Body

Field	Type	Required	Description
email	string	Yes	User's email address
type	string	Yes	"company" or "affiliate"

Response

{
  "success": true,
  "data": {
    "message": "Magic link sent. Check your email."
  }
}

Example

curl -X POST https://api.refuel.dev/auth/magic-link \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "type": "company" }'

POST/auth/verify

Verify a magic link token and receive a JWT for authenticated requests.

Request Body

Field	Type	Required	Description
token	string	Yes	Token from the magic link URL

Response

{
  "success": true,
  "data": {
    "token": "eyJhbGci...",
    "userId": "cmp_abc123",
    "role": "company",
    "email": "you@example.com"
  }
}

Example

curl -X POST https://api.refuel.dev/auth/verify \
  -H "Content-Type: application/json" \
  -d '{ "token": "your_magic_link_token" }'

Companies

POST/companies/register

Register a new company. Returns API keys and the embed snippet. This endpoint is public and does not require authentication.

Request Body

Field	Type	Required	Description
name	string	Yes	Company name (1-255 chars)
domain	string	Yes	Company website domain
email	string	Yes	Owner's email address
commissionRate	number	No	Commission rate 0.01-1.0 (default: 0.10)

Response

{
  "success": true,
  "data": {
    "id": "cmp_abc123",
    "apiKey": "sk_live_...",
    "publishableKey": "pk_live_...",
    "embedSnippet": "<script src=\"https://sdk.refuel.dev/v1.js\" data-key=\"pk_live_...\" async></script>"
  }
}

Example

curl -X POST https://api.refuel.dev/companies/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Store",
    "domain": "https://acme.com",
    "email": "you@acme.com",
    "commissionRate": 0.10
  }'

GET/companies/dashboard

Get company dashboard overview: revenue, commissions, affiliate count, conversion rate, and top affiliates.

Auth: Bearer JWT (company)

Query Parameters

Parameter	Type	Description
days	number	Lookback period in days (default: 30)

Response

{
  "success": true,
  "data": {
    "totalRevenue": 150000,
    "totalCommissionPaid": 15000,
    "affiliateCount": 42,
    "conversionRate": 3.25,
    "totalClicks": 1200,
    "totalConversions": 39,
    "topAffiliates": [...],
    "periodDays": 30
  }
}

Example

curl https://api.refuel.dev/companies/dashboard?days=30 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET/companies/settings

Get current company settings including API keys, commission rate, payout config, and widget config.

Auth: Bearer JWT (company)

Response

{
  "success": true,
  "data": {
    "id": "cmp_abc123",
    "name": "Acme Store",
    "domain": "https://acme.com",
    "apiKey": "sk_live_...",
    "publishableKey": "pk_live_...",
    "commissionRate": 0.10,
    "attributionWindow": 30,
    "payoutSchedule": "monthly",
    "payoutMinimum": 5000,
    "widgetConfig": { "position": "bottom-right" },
    "status": "active"
  }
}

Example

curl https://api.refuel.dev/companies/settings \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

PUT/companies/settings

Update company program settings. All fields are optional; only provided fields are updated.

Auth: Bearer JWT (company)

Request Body

Field	Type	Required	Description
commissionRate	number	No	Commission rate 0.01-1.0
attributionWindow	number	No	Attribution window in days (1-90)
payoutSchedule	string	No	"weekly", "biweekly", or "monthly"
payoutMinimum	number	No	Minimum payout in cents (1000-50000)
widgetConfig	object	No	Widget display settings

Response

{
  "success": true,
  "data": {
    "id": "cmp_abc123",
    "commissionRate": 0.15,
    "attributionWindow": 30,
    "payoutSchedule": "monthly",
    "payoutMinimum": 5000,
    "widgetConfig": { "position": "bottom-right", "accentColor": "#F0A500" }
  }
}

Example

curl -X PUT https://api.refuel.dev/companies/settings \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "commissionRate": 0.15, "payoutSchedule": "biweekly" }'

GET/companies/analytics

Detailed analytics with daily click/conversion breakdown, traffic sources, top landing pages, and revenue by day of week.

Auth: Bearer JWT (company)

Query Parameters

Parameter	Type	Description
days	number	Lookback period in days (default: 30)

Response

{
  "success": true,
  "data": {
    "daily": [{ "date": "2026-03-01", "clicks": 45, "conversions": 3, "revenue": 12000 }],
    "trafficSources": [{ "source": "twitter", "count": 120 }],
    "topPages": [{ "page": "/pricing", "clicks": 89 }],
    "revenueByDay": [{ "dayOfWeek": 1, "revenue": 34000 }],
    "periodDays": 30
  }
}

Example

curl https://api.refuel.dev/companies/analytics?days=30 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET/companies/conversions

List conversions with fraud flags. Supports filtering by status and pagination.

Auth: Bearer JWT (company)

Query Parameters

Parameter	Type	Description
status	string	Filter: "pending", "approved", or "rejected"
page	number	Page number (default: 1)
perPage	number	Results per page (default: 20)

Response

{
  "success": true,
  "data": [{
    "id": "conv_xyz",
    "orderId": "order_123",
    "orderValue": 9999,
    "commissionAmount": 1000,
    "status": "pending",
    "fraudFlags": [],
    "createdAt": "2026-03-30T10:00:00Z"
  }],
  "meta": { "page": 1, "perPage": 20, "total": 156 },
  "statusCounts": { "pending": 5, "approved": 140, "rejected": 11 }
}

Example

curl "https://api.refuel.dev/companies/conversions?status=pending&page=1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

PATCH/companies/conversions/:id

Approve or reject a flagged conversion. Only conversions with status "pending" can be updated.

Auth: Bearer JWT (company)

Request Body

Field	Type	Required	Description
action	string	Yes	"approve" or "reject"

Response

{
  "success": true,
  "data": { "id": "conv_xyz", "status": "approved" }
}

Example

curl -X PATCH https://api.refuel.dev/companies/conversions/conv_xyz \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "approve" }'

POST/companies/rotate-key

Rotate the company's secret API key. The old key is immediately invalidated.

Auth: Bearer JWT (company)

Response

{
  "success": true,
  "data": { "apiKey": "sk_live_new_key_here" }
}

Example

curl -X POST https://api.refuel.dev/companies/rotate-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST/companies/pause

Toggle company program between active and paused. Paused programs stop tracking new clicks.

Auth: Bearer JWT (company)

Response

{
  "success": true,
  "data": { "status": "paused" }
}

Example

curl -X POST https://api.refuel.dev/companies/pause \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Affiliates

Affiliate dashboard, link management, earnings tracking, and profile settings.

GET/affiliates/dashboard

Affiliate overview with earnings, active programs, stats, and recent payouts.

Auth: Bearer JWT (affiliate)

Query Parameters

Parameter	Type	Description
days	number	Lookback period in days (default: 30)

Response

{
  "success": true,
  "data": {
    "affiliate": { "id": "aff_abc", "email": "aff@example.com", "name": "Jane", "tier": "standard", "status": "active" },
    "stats": {
      "periodEarnings": 5000,
      "periodConversions": 12,
      "pendingPayout": 3500,
      "lifetimeEarnings": 45000,
      "totalClicks": 890,
      "activePrograms": 3
    },
    "programs": [...],
    "recentPayouts": [...]
  }
}

Example

curl https://api.refuel.dev/affiliates/dashboard?days=30 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET/affiliates/links

List all affiliate links with click/conversion stats. Supports pagination.

Auth: Bearer JWT (affiliate)

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
perPage	number	Results per page (default: 20)

Response

{
  "success": true,
  "data": [{
    "id": "link_abc",
    "code": "abc123",
    "targetUrl": "https://acme.com",
    "clicks": 150,
    "conversions": 8,
    "revenue": 42000,
    "status": "active",
    "companyName": "Acme Store",
    "commissionRate": 0.10
  }],
  "meta": { "page": 1, "perPage": 20, "total": 5 }
}

Example

curl "https://api.refuel.dev/affiliates/links?page=1&perPage=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET/affiliates/earnings

Earnings breakdown by day and by company over the specified period.

Auth: Bearer JWT (affiliate)

Query Parameters

Parameter	Type	Description
days	number	Lookback period in days (default: 30)

Response

{
  "success": true,
  "data": {
    "dailyEarnings": [{ "date": "2026-03-01", "earned": 500, "count": 2 }],
    "byCompany": [{ "companyId": "cmp_abc", "companyName": "Acme", "earned": 3000, "count": 8 }],
    "periodDays": 30
  }
}

Example

curl https://api.refuel.dev/affiliates/earnings?days=30 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET/affiliates/settings

Get affiliate profile including Stripe Connect status.

Auth: Bearer JWT (affiliate)

Response

{
  "success": true,
  "data": {
    "id": "aff_abc",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "tier": "standard",
    "stripeConnectId": "acct_..."
  }
}

Example

curl https://api.refuel.dev/affiliates/settings \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

PUT/affiliates/settings

Update affiliate profile (currently supports name updates).

Auth: Bearer JWT (affiliate)

Request Body

Field	Type	Required	Description
name	string	No	Display name (1-255 chars)

Response

{
  "success": true,
  "data": { "id": "aff_abc", "name": "Jane Doe", "email": "jane@example.com" }
}

Example

curl -X PUT https://api.refuel.dev/affiliates/settings \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe" }'

SDK / Links

Public endpoints used by the embeddable SDK for widget configuration and link creation.

GET/sdk/config/:publishableKey

Returns widget configuration for the embeddable SDK. Called on every page load by the JS snippet.

Response

{
  "success": true,
  "data": {
    "companyId": "cmp_abc123",
    "companyName": "Acme Store",
    "commissionRate": 0.10,
    "widget": {
      "position": "bottom-right",
      "accentColor": "#1A6B3C",
      "buttonText": "Earn with us"
    }
  }
}

Example

curl https://api.refuel.dev/sdk/config/pk_your_publishable_key

POST/sdk/links

Create an affiliate link from the widget. Auto-creates the affiliate account if the email is new. Returns an existing link if one already exists for the same affiliate + company + URL.

Request Body

Field	Type	Required	Description
email	string	Yes	Affiliate's email address
targetUrl	string	Yes	URL the affiliate wants to promote
publishableKey	string	Yes	Company's publishable key

Response

{
  "success": true,
  "data": {
    "linkId": "link_abc",
    "code": "abc123",
    "url": "https://acme.com?ref=abc123",
    "commissionRate": 0.10
  }
}

Example

curl -X POST https://api.refuel.dev/sdk/links \
  -H "Content-Type: application/json" \
  -d '{
    "email": "affiliate@example.com",
    "targetUrl": "https://acme.com/product",
    "publishableKey": "pk_your_key"
  }'

Tracking / Conversions

Click tracking and conversion recording endpoints used by the SDK and your backend.

POST/track/click

Record a click event. Called automatically by the SDK when a user lands on a page with a ?ref=CODE parameter. Includes rate limiting (max clicks per IP per hour) and IP hashing for privacy.

Request Body

Field	Type	Required	Description
code	string	Yes	Affiliate link code
landingPage	string	Yes	Full URL of the landing page
referrer	string	No	HTTP referrer URL
fingerprint	string	No	Browser fingerprint hash
utmSource	string	No	UTM source parameter
utmMedium	string	No	UTM medium parameter
utmCampaign	string	No	UTM campaign parameter

Response

{
  "success": true,
  "data": { "tracked": true }
}

Example

curl -X POST https://api.refuel.dev/track/click \
  -H "Content-Type: application/json" \
  -d '{
    "code": "abc123",
    "landingPage": "https://acme.com/pricing",
    "referrer": "https://twitter.com",
    "utmSource": "twitter"
  }'

POST/track/conversion

Record a conversion event. Called from your backend when a purchase occurs. Authenticated via x-api-key header. Automatically calculates commission split, runs fraud detection, and attributes the conversion to the most recent click within the attribution window.

Auth: x-api-key: sk_...

Request Body

Field	Type	Required	Description
orderId	string	Yes	Your unique order identifier
orderValue	integer	Yes	Order value in cents (e.g. 9999 = $99.99)
currency	string	No	ISO currency code (default: "USD")
affiliateCode	string	Yes	Affiliate link code from the ?ref= parameter
metadata	object	No	Arbitrary key-value metadata

Response

{
  "success": true,
  "data": {
    "conversionId": "conv_xyz",
    "commissionAmount": 1000,
    "affiliatePayout": 800,
    "status": "approved",
    "fraudScore": 0.05
  }
}

Example

curl -X POST https://api.refuel.dev/track/conversion \
  -H "x-api-key: sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_12345",
    "orderValue": 9999,
    "currency": "USD",
    "affiliateCode": "abc123"
  }'

Error Responses

All error responses follow a consistent format with an error code and human-readable message.

Error response formatjson

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input"
  }
}

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Request body failed validation
401	UNAUTHORIZED	Missing or invalid authentication
404	NOT_FOUND	Resource not found
409	DUPLICATE	Resource already exists
409	ALREADY_RESOLVED	Conversion already approved/rejected