Welcome to the Rewardful Developer documentation! We're excited to see what you build 🙂

Our developer documentation is organized into several categories. Which category applies to you depends upon how you wish to integrate with Rewardful. If you're unsure where to start, send us a chat message or email [email protected] — we'll be happy to help!

REST API

Programmatically manage resources within your Rewardful account.

Webhooks

Receive notifications to your own app (or Zapier) about events that occur within your Rewardful account.

The Rewardful API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

All API requests require authentication with , similar to how Stripe authenticates. Provide your API Secret as the basic auth username value. You do not need to provide a password.

Be sure to replace YOUR_API_SECRET with your actual API Secret. For example, if your API secret was ABC123, the curl command to fetch all affiliates would be:

Your API Secret can be found on the page.

Contact us as soon as possible if you believe your API Secret has been compromised so we can rotate it for you.

Request and Response Formats

Rewardful will provide a JSON-based REST API through which merchants can create affiliate accounts and fetch data for reporting. Endpoints accept request bodies and return responses.

Rewardful uses for primary keys (IDs) for all resources. If you plan to store Rewardful IDs in your database, make sure to use a column type (string, UUID, etc) appropriate for your database engine.

Dates and times in the Rewardful API are represented as formatted strings.

Errors

Missing or invalid authorization will return a 401 Unauthorized JSON response:

Requesting a nonexistent object will return a 404 Not Found JSON response:

Passing invalid data to a create/update endpoint will return a 422 Unprocessable Entity JSON response:

Pagination

API endpoints that return a list of objects include pagination, unless noted otherwise. The data structure has two root objects:

The `pagination` object

Example

This example demonstrates the pagination for a collection of 150 objects in total, split into 3 pages of 50 objects per page:

Expanding objects

Many objects allow you to request additional information as an expanded response by using the expand request parameter. You can use expand to expand a single type of object, or expand[] to expand multiple types of objects.

The documentation for each endpoint will list which objects are expandable (if any) for that endpoint.

For example, to expand an affiliate you would prepend this query string parameter to the request URL:

To expand both affiliate and sale objects, prepend this query string parameter to the request URL:

Rate limits

The Rewardful REST API uses rate limiting to help maximize its uptime and stability. Users who send many requests in quick succession may see error responses that show up as HTTP status code 429. These 429 responses will include which you can use to gracefully handle failures and retry requests when your quota resets.

In most cases the API rate limit is 45 requests per 30 second window. Please treat these limits as absolute maximums and do not generate unnecessary load.

If you plan to run a batch script (such as programmatically creating many affiliates via API), please throttle your API usage by adding sleep/delay mechanisms to your script. We may reduce limits at any time to prevent abuse.

Request

To receive webhook events, you must add a webhook endpoint to your Rewardful account. You can add, edit, or remove endpoints from the Webhooks page in your Rewardful dashboard.

And endpoint is simply a URL on your application that Rewardful will send data to when an event occurs.

An example endpoint: http://app.example.com/webhooks/rewardful

Your endpoint must be capable of receiving and processing JSON data sent from Rewardful's servers.

Rewardful's remote script loads asynchronously to make it as performant and reliable as possible. You can use our asynchronous JavaScript API to perform client-side conversion tracking as well as execute functions when Rewardful has initialized.

Add the JavaScript tag + snippet

To add support for our asynchronous JavaScript API, place this code snippet onto every page of your website, ideally in the <head> tag:

This code will add a rewardful function to the page, which can be immediately called and passed instructions that Rewardful will execute once loaded. The general format of these method calls is rewardful(methodName, arg1, arg2, arg3, ...)

It's important for this snippet to appear in your HTML before any calls to the rewardful function. To make it simple, we recommend adding it immediately before the script tag that loads the remote Rewardful script from in the setup instructions. Your final Step #1 snippet should look something like this:

Client-Side Conversion Tracking

Rewardful's JavaScript API allows you to track conversions with frontend code only — no backend code is required. This can make integrating Rewardful much simpler, and enables you to use Rewardful in scenarios where you're unable to modify backend/server code, such as when using a hosted platform to sell your products.

To track a conversion client-side, use the "convert" function, and pass the customer's email address using the email parameter. This code should appear on your thank-you or receipt page (or whatever page your customers are taken to immediately after purchase).

For example:

This code will search for the most recently created customer with the email address "[email protected]" in your Stripe account. If the customer exists and the Rewardful cookie is present (i.e. this visitor is a referral), Rewardful with associate the customer with the affiliate.

Note: this code only performs network requests if the current website visitor is a referral. If the visitor arrived on your website through another channel, the convert function does nothing.

Requirements

In order to use Client-Side Conversion Tracking there are a few prerequisites:

1. Your Stripe account must be connected to Rewardful with .

2. Your platform creates Stripe Customers within your Stripe account when a purchase is made.

3. You are able to add client-side code snippets to your website & receipt/thank-you page, and access the customer's email address on these pages.

Executing code when Rewardful loads

In some cases you might want to execute code once Rewardful has fully loaded and performed any tracking/network requests.

Pass a callback function to the ready handler to have it executed when Rewardful has fully loaded. This function always executes, whether the current visitor is a referral or not. For example:

If you only want code to run if the current visitor is a referral, you can check the Rewardful.referral property:

Calls to rewardful are queued and executed in order once Rewardful has loaded. This means you can queue up multiple functions, and even call rewardful if Rewardful is loaded (which effectively calls the underlying function immediately). For example:

Specify traffic source

It's possible to force the current visitor to be attributed to an affiliate even if the visitor didn't arrive through an affiliate link. This is useful for creating landing pages with friendly URLs for a partner promotion, or for creating URLs that are easier to share verbally (i.e. on podcasts).

Example: instead of example.com/?via=bond007 you could create a page at example.com/bond and include the snippet below to ensure all visitors to this page get attributed to James Bond:

It's important to note that this operation overwrites any existing referral for the visitor that's stored in the cookie. Continuing our example above, if the visitor first arrived through example.com/?via=batman but then went on to visit example.com/bond (where the code above is executed) then James Bond would ultimately get credited for the conversion.

Preloading a referral ID

Normally Rewardful will look for the ?via=token query string parameter when attributing a visit to an affiliate. When the via parameter is present and valid, a new referral will be created for the affiliate and the referral ID stored in the cookie as .

However, there may be situations where you want to preload a specific referral ID into the cookie. This can be done by adding a ?referral=<UUID> parameter to the URL:

When a user browses to this URL, the existing referral with ID bffa8b94-b25a-45a4-97a0-1c8ecb8018b0 will be loaded into the cookie. (This is actually how ).

An example of when this is relevant is when the checkout process is embedded within an iframe. If the parent URL and iframe URL both have a via parameter then two referrals will be created (one for each window) which artificially inflates visitor stats.

In this scenario, the parent window can check for an existing referral ID and pass it to the iframe by adding a referral=<UUID>parameter to the iframe URL before inserting the iframe into the DOM:

This will ensure the iframe is using the same referral ID as the parent window and will prevent double-tracking visitors. If using the approach above to insert your checkout iframe, ensure you have a fallback plan in case Rewardful never loads. See for more information.

Attributes

Referral

Rewardful.referral will return the Referral ID of the current visitor if they were referred, for example: "98288128-0d5f-45a9-88b3-ef95b229f798"

If the current visitor was not referred by a Rewardful affiliate, Rewardful.referral will return an empty string: ""

Affiliate

Rewardful.affiliate will return some information about who sent you a referral, for example:

You might want to use this for personalizing your website based on who the affiliate was:

Rewardful.affiliate returns false if there is no affiliate, i.e. the current visitor was not referred.

Campaign

Rewardful.campaign will return the ID and name of the campaign the affiliate is associated with:

Coupon Details

If you've , the coupon object will be available through Rewardful.coupon. The attributes correspond directly to the in Stripe.

For example, a 25% discount that repeats for 12 months might look like:

And a one-time $25 USD discount might look like:

We recommend checking for the coupon's existence before attempting to access it's attributes, for example:

Methods

Attaching to forms

On page load Rewardful will automatically inject a hidden input into forms with a data-rewardful attribute. This makes it simple to get the referral ID sent to your server along with the rest of the data from your signup or payment form.

For example, your signup form might look something like this:

If the current visitor came to your site through an affiliate link, Rewardful will detect the data-rewardful attribute and automatically insert a hidden input named referral with the unique click ID (UUID) as the value. For example:

When the form is submitted, the POST data sent to your server will include the referral parameter, along with the rest of the customer data. You can extract this value ($_POST['referral'] in PHP, params[:referral] in Rails, etc) and add it to the Stripe customer's metadata or save it in your own database for future use.

Manually attaching to forms

If your form is dynamically added to the page (, a single-page app or a modal) you'll need to manually tell Rewardful to attach to these forms after they have been added to the DOM.

To attach to all forms present in the DOM with the data-rewardful attribute, you can call Rewardful.Forms.attach()

Turbolinks example:

If your form appears inside a :

Attaching to specific forms

If you'd like to manually attach the hidden referral input into a specific form, you can do so with Rewardful.Forms.add(formElement), for example:

This can be useful in circumstances where you cannot easily modify the source code of the form tag (for example, using a CMS or hosted service) and are unable to add the data-rewardful attribute.

Troubleshooting

If you're running into issues with your JavaScript integration it's possible to inspect the data stored in the Rewardful cookie using the Rewardful._cookie attribute.

Here's an example of the data structure returned by Rewardful._cookie:

Request

Examples

List all campaigns

Response

Rewardful can send webhook events to endpoints that notify your application any time an event happens in your account.

A common example is to receive a webhook when an affiliate signs up, which allows you to subscribe that affiliate to an email campaign in an external email service provider.

Webhooks can also be used to connect Rewardful with . To see an example of how to do this, see our screencast.

Request

Request

Request

Request

Request

Request

Optional parameters

Expandable objects

Examples

List all payouts

List all payouts with data for the associated affiliate and commissions

List payouts for a specific affiliate

List payouts that have been marked as paid

List payouts that are either due or pending

Attributes

{
  "id": "f46a912b-08bc-4332-8771-c857e11ad9dd",
  "url": "https://www.demo.com:8081/?via=luke",
  "token": "luke",
  "visitors": 10,
  "leads": 5,
  "conversions": 3,
  "affiliate_id": "aaac9869-4242-4db9-afb1-f3518ef627c5"
}

Attributes

Request

Request

Request

Parameters

Example

Response

Conversion states

A referral has three distinct conversion states:

Request

Optional parameters

*Filtering by email or stripe_customer_id will return a list with one (or zero) items.

Expandable objects

Examples

List all affiliates

List all affiliates and expand campaign data

List all affiliates and expand campaign and links data

Filter list of affiliates by campaign

Filter list of affiliates by email address

Request

Example

Response

Webhook data is sent as JSON in the POST request body to your configured endpoints.

The JSON payload has three root keys:

1. object represents the object that triggered the event (an affiliate, campaign, conversion, commission, etc.). The object's JSON structure will be identical to the structure returned by the REST API endpoints for that object type.

2. event contains metadata about the webhook event.

3. request contains metadata about this specific request to your endpoint.

Example payload

Webhook payloads sent to your endpoint contain these top-level items:

Below is an example of the JSON that would be posted to your endpoint for the affiliate.confirmed event, i.e. when an affiliate has successfully confirmed their email address.

Responses, Errors, and Retries

When your endpoint receives and successfully processes a webhook event, your web server should return a 200 response code.

If a webhook fails, Rewardful will continue to attempt delivery over the next 3 days using exponential backoff. This means if the failures continue, we'll wait longer and longer between retries, before finally giving up after 3 days.

Each webhook request sent by Rewardful includes a unique signature that can be used to verify the authenticity of the request. You can use this to confirm that the webhook request is legitimate and not an attacker attempting to spoof your endpoint.

Rewardful generates signatures using a hash-based message authentication code (HMAC) with SHA-256. The signature is generated by hashing your endpoint's Signing Secret with the webhook request body. You can view your endpoint's Signing Secret from the page in your Rewardful dashboard.

The signature is contained in the HTTP header X-Rewardful-Signature. You can verify the signature by hashing your Signing Secret with the request body, then comparing the result with X-Rewardful-Signature. If they match, it means the request is legitimate.

Here are some examples of how you can verify the signature in a few frameworks and programming languages.

Ruby on Rails

PHP

Django

Updates the specified affiliate by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Request

Use this endpoint to generate a secure, one-time URL that you can display to affiliates or redirect them to in order to have them automatically logged into their Rewardful dashboard without requiring them to provide their email and password.

Links expire after one minute and cannot be used more than once. Generating a new magic link will invalidate all previous magic links for that affiliate, even if they haven't been used.

Usage

Request

Request

This endpoint allows merchants to create new campaigns on demand by providing a set of the most common parameters used

Request

Parameters

Example

Response

Request

Parameters

Example

Response

This is a list of all the types of events we currently send. When configuring your webhook, you must select the types of events you'd like to receive to your endpoint. To minimize load on your server, we recommend selecting only the event types you actually need.

See Webhook Requests for a full example of the data structure posted to your endpoint.

Affiliates

The object key for these events will describe an object.

Affiliate Links

The object key for these events will describe an object.

Affiliate Coupons

The object key for these events will describe an object.

Referrals

The object key for these events will describe a referral object.

Sales

The object key for these events will describe a sale object.

Commissions

The object key for these events will describe a object.

Payouts

The object key for these events will describe a object.

Example

Attributes

This endpoint allows merchants to create affiliates on demand.

Both normal affiliates and customer referrers can be created through this endpoint. To create a customer referrer, simply pass the stripe_customer_id parameter that indicates the Stripe Customer that should receive account credits as rewards.