Rewardful API: What You Can (and Can't) Build

Rewardful API: What You Can (and Can't) Build

If you're reading Rewardful's developer docs, you're probably trying to answer one question: can I build a custom affiliate dashboard, a private admin panel, or some automation on top of this instead of using Rewardful's own UI? Short answer: mostly yes, within limits worth knowing before you commit engineering time to it.

I run Referralful, an alternative built on the same general shape of API, so I've read Rewardful's docs closely enough to map out what's actually there rather than what the marketing page implies.

What the REST API exposes

Rewardful's REST API lets you programmatically manage the same resources you'd otherwise click through in its dashboard.

Resource	What it covers
Affiliates	Partner accounts, tokens, status
Campaigns	Commission structure and cookie settings
Affiliate links	Tracking URLs per affiliate
Affiliate coupons	Coupon-code-based attribution
Referrals	Lead-to-conversion tracking per visitor
Sales	Transaction records tied to a referral
Commissions	Calculated earnings per sale
Payouts	Payment batch records

Authentication is HTTP Basic Auth: your API secret goes in as the username with an empty password (curl -u YOUR_API_SECRET: https://api.getrewardful.com/v1/...). You pull the secret from Company Settings. Responses come back as JSON with UUID identifiers, ISO 8601 timestamps, and a consistent pagination object (current_page, next_page, total_pages, total_count) on every list endpoint.

The rate limit that actually matters

	Rewardful REST API
Rate limit	45 requests per 30-second window
Over-limit response	HTTP 429 with RateLimit headers showing reset time
Recommended handling	Throttle batch operations, don't hammer list endpoints in a loop

That's a fairly standard limit for a SaaS API protecting shared infrastructure, and most single-tenant dashboards won't ever hit it during normal use. It's fine for syncing a dashboard on a schedule or reacting to individual events. It's tight if you're trying to backfill years of historical referral data in one script, or building something that polls Rewardful in real time instead of relying on webhooks. Plan for pagination and delays if you're doing a bulk export.

The JavaScript API: client-side tracking

Separate from the REST API, Rewardful ships a JS snippet (rewardful.js) for client-side attribution. The core methods:

• rewardful('ready', callback) runs code once Rewardful has loaded
• rewardful('convert', { email }) matches a purchase to a Stripe customer by email, client-side
• rewardful('source', TOKEN) manually assigns a visitor to an affiliate
• Rewardful.Forms.attach() auto-injects hidden referral fields into forms

You also get read access to Rewardful.referral, Rewardful.affiliate, Rewardful.campaign, and Rewardful.coupon as data attributes, which is what lets you personalize a landing page based on which affiliate sent the visitor.

The real limitation: client-side conversion tracking via convert only works if the Stripe customer was created within the last 24 hours. If your signup flow creates a Stripe customer well before checkout completes (invoiced sales, delayed activation, annual contracts negotiated over email), that window closes before the conversion event fires, and you need server-side tracking instead.

Webhooks

Rewardful fires webhooks across seven resource types (affiliates, affiliate links, affiliate coupons, referrals, sales, commissions, and payouts), with roughly 38 distinct event types total: things like affiliate.confirmed, referral.converted, sale.refunded, commission.paid, and payout.failed. That granularity is genuinely useful. You can react to a refund the moment it happens instead of polling for it, or auto-provision access the second an affiliate is confirmed.

What's notably absent: there's no raw click-tracking resource in the REST API or webhook list. Referrals cover lead capture through conversion, not anonymous click events. If you need click-level analytics beyond what Rewardful's own dashboard reports, you're not getting it through the API as documented.

What you can actually build

• A custom affiliate-facing dashboard that pulls commission and payout data via REST instead of routing partners through Rewardful's hosted portal.
• Real-time internal alerts, in Slack or email, triggered off webhooks like commission.paid or payout.failed, so your team catches problems the moment they happen.
• A signup flow that tags new Stripe customers with affiliate attribution automatically, using the JS API's convert method.
• Reporting that joins Rewardful's referral data with your own product analytics by affiliate ID, something the native dashboard doesn't do out of the box.

What you can't (easily)

• Backfill years of historical referral data quickly. At 45 requests per 30 seconds, a large export takes real time, and you'll want retry logic for the inevitable 429s.
• Attribute conversions through the JS convert method on delayed-billing flows, since it only works if the Stripe customer record is less than 24 hours old.
• Pull raw click or impression data. The API's most granular tracking object is a referral, not a click, so pre-conversion funnel analysis has to happen somewhere else.

None of this makes the API bad. It's a genuinely complete surface for the workflows Rewardful expects you to run: manage affiliates, react to commission and payout events, and personalize pages for referred visitors. It's just not a general-purpose analytics API, and it wasn't built to be one.

Should you actually build this yourself

Building a custom dashboard or automation layer on Rewardful's API is a real option, not a hypothetical one. The resources are there, the rate limit is workable for anything short of bulk historical backfills, and webhooks cover the events most teams actually care about. The honest question is whether you need to. If Rewardful's own affiliate portal and admin dashboard already do what your team needs, a custom layer on top just adds maintenance overhead for a marginal gain. It makes more sense once you have a specific gap: a partner-facing view that doesn't match your brand, an internal alert Rewardful doesn't send by default, or a reporting join its dashboard can't do on its own.

How this compares to Referralful's API

I built Referralful's REST API to cover the same shape of resources: campaigns, affiliates, links and coupons, referrals, commissions, payouts, plus a conversions endpoint for reporting sales from non-Stripe billing systems. It uses the same HTTP Basic Auth pattern as Rewardful, API secret as the username, and we deliberately matched endpoint structure, field names, and pagination so a Rewardful integration is closer to a find-and-replace job than a rewrite. If you're comparing the two products more broadly than just the API, our Rewardful comparison covers pricing and features too, and our affiliate program software guide has the wider field if you're still shopping.

FAQ

Can I build a fully custom affiliate portal on Rewardful's API? Yes, the REST API exposes affiliates, commissions, payouts, and referrals, which covers what most custom portals need. You'll just need to design around the 45-requests-per-30-second rate limit for any bulk operations.

Does Rewardful's API support real-time click tracking? Not through the documented REST API or webhooks. The lowest-level tracked object is a referral, which represents a lead or conversion, not a raw click.

What's the rate limit on Rewardful's REST API? 45 requests per 30-second window. Exceeding it returns an HTTP 429 response with headers indicating when the limit resets.

Is Referralful's API compatible with Rewardful integrations? It's built to the same shape deliberately: same authentication pattern, similar resource names and pagination, so migrating a Rewardful integration mostly means swapping the base URL and credentials.

If you're evaluating whether to build on this instead of buying a hosted dashboard, our developer docs are open to read before you sign up for anything.