LogoLogo
REST APIWebhooksHelp Center →
  • Introduction
  • JavaScript API
    • Overview
  • REST API
    • Overview
    • Campaigns
      • The campaign object
      • List campaigns
      • Create campaign
      • Retrieve campaign
      • Update campaign
    • Affiliates
      • The affiliate object
      • List affiliates
      • Create affiliate
      • Retrieve affiliate
      • Update affiliate
      • Magic Link (SSO)
    • Affiliate Links
      • The affiliate link object
      • List affiliate links
      • Create affiliate link
      • Retrieve affiliate link
      • Update affiliate link
    • Affiliate Coupons
      • The affiliate coupon object
      • List affiliate coupons
      • Create affiliate coupon
      • Retrieve affiliate coupon
    • Referrals
      • The referral object
      • List referrals
    • Commissions
      • The commission object
      • List commissions
      • Retrieve commission
      • Update commission
      • Delete commission
    • Payouts
      • The payout object
      • List payouts
      • Retrieve a payout
      • Mark a payout as paid
  • Webhooks
    • Overview
    • Endpoints
    • Requests
    • Event types
    • Signed webhooks
  • Links
    • Help Center
    • Sign up
    • Login
    • Learn more about Rewardful
Powered by GitBook
On this page
  • Authentication
  • Request and Response Formats
  • Errors
  • Pagination
  • The `pagination` object
  • Example
  • Expanding objects
  • Rate limits

Was this helpful?

Export as PDF
  1. REST API

Overview

Introduction to Rewardful's REST API

PreviousOverviewNextCampaigns

Last updated 8 months ago

Was this helpful?

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

We highly recommend checking out , a desktop app that makes testing API requests and responses a breeze 👍

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.

curl https://api.getrewardful.com/v1/affiliates/7B016217-18AF-44DD-A30C-0DE0C1534D2A \
  -u YOUR_API_SECRET:

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:

curl --request GET \
  --url https://api.getrewardful.com/v1/affiliates \
  -u ABC123:

Your API Secret can be found on the page.

Keep your API Secret safe!

Your API Secret grants full access to your Rewardful account. Do not:

  • Share your API Secret with third parties

  • Commit your API Secret to version control (i.e. Git)

  • Share your API Secret over email or chat

  • Send your API Secret to the web browser in HTML or JavaScript

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

Errors

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

{  "error": "Invalid API Secret." }

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

{  "error": "Affiliate not found: " }

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

{
  "error": "Could not create affiliate.",
  "details": ["Email can't be blank"]
}

Pagination

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

Key

Description

pagination

Pagination data, such as current/next/previous page numbers, counts, etc.

data

An array of objects returned for the specified page number.

The `pagination` object

Key

Description

previous_page

Previous page number. Will be null if there's no previous page.

current_page

Current page number.

next_page

Next page number. Will be null if there's no next page.

count

The number of objects on this page.

limit

The requested number of objects per page.

total_pages

The total number of pages.

total_count

The total number of objects returned across all pages.

Example

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

{
  "pagination": {
    "previous_page": 1,
    "current_page": 2,
    "next_page": 3,
    "count": 50,
    "limit": 50,
    "total_pages": 3,
    "total_count": 150
  },
  "data": [
    // Array of objects
  ]
}

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:

?expand=affiliate

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

?expand[]=affiliate&expand=sale

Rate limits

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.

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.

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.

REST
form-encoded
JSON-encoded
Insomnia
HTTP Basic Auth
Company Settings
form-encoded
JSON-encoded
UUID strings
ISO 8601
RateLimit header fields