Referrals are records of when a user signs up to your app after visiting a referral link.

Once a referred user signs up to a paid plan, this is considered a "conversion". Creation and conversion are the two main events in a referral's life and the API lets you handle both programmatically from your app.

List referrals

GET https://api.refermo.co/v1/referrals/

Request parameters

None.

Response values

Pagination

  • count (int)
    Total results for this query (including other pages of results).
  • next (string)
    The URL for the next page of results, or null if there isn't one.
  • previous (string)
    The URL for the previous page of results, or null if there isn't one.

Referral data

  • id (string, 32 chars)
    The unique Refermo ID for this referral.
  • member_id (string, 32 chars)
    The unique Refermo ID for the referring member.
  • user_identifier (string)
    The unique ID for the referred user from your app.
  • created_at (unix timestamp)
  • converted_at (unix timestamp or null if referral has not converted)
  • is_converted (boolean)
    A simple boolean to see if the referral has converted.
  • coupon_code (string or null)
    The discount code created if this referral has double-sided rewards. This coupon can be applied at checkout to give the referred user a discount, based on your campaign settings.
  • subscription (dictionary or null)
    If this referral has converted, it will have been assigned the subscription which was created as it was converted. This dictionary has the same values as in the Subscription endpoint.
  • source (string, options app, api or js)
    This tells how the referral was created.
  • campaign_id (string, 8 chars)
    The unique ID for the campaign this referral was created within.
  • reward_type (string, options credit or commission)
    The type of reward created for this referral.
  • reward_amount (decimal as a string)
    The amount of each reward created for this referral.
  • reward_threshold (decimal as a string)
    The amount the referred user needs to be spend before rewards are created.
  • currency (string, 3 chars)
    The 3-character currency code used for this referral's rewards. This was copied from the referral's campaign when it was created.
  • stats (dictionary)
    Numerical stats for this referral.
  • rewards_completed (boolean)
    This shows if the referral will receive future rewards or not. For example, credit-based referrals will only have one reward, whereas a recurring commission-based referral will get ongoing rewards.
  • rewards (list)
    A list of rewards which have been created for this referral. This is a list of objects with id, reward type, amount rewarded, currency of the reward amount, the timestamp when the reward was created and the ID of the subscription payment in Paddle which triggered the reward.

Example response

HTTP 200 OK
{
  "count": 18,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "4b8024de11341839cf6cdafbd1dfaa01",
      "member_id": "c235f4c1f987260699843afeb59b3e16",
      "user_identifier": "dancustomer@gmail.com",
      "created_at": 1637123678,
      "converted_at": 1637123821,
      "is_converted": true,
      "coupon_code": "31A30BAF",
      "subscription": {
        "id": 9682864,
        "unit_price": "19.00",
        "currency": "USD",
        "status": "active",
        "email": "dancustomer@gmail.com",
        "next_bill_date": "2022-01-05",
        "last_bill_date": "2021-11-05",
        "plan": {
          "id": 665966,
          "name": "Monthly",
          "amount": "19.00",
          "currency": "USD",
          "interval": "month",
          "frequency": 1
        }
      },
      "source": "js",
      "campaign_id": "4d0e29b3",
      "reward_type": "credit",
      "reward_amount": "10.00",
      "reward_threshold": "0.00",
      "currency": "USD",
      "stats": {
        "rewards": 1,
        "credit_earned": "10.00",
        "commission_earned": "0.00",
        "currency": "USD"
      },
      "rewards_completed": true,
      "rewards": [
        {
          "id": "eeaa35bb13a70bc6834f35297ee74779",
          "type": "credit",
          "amount": "10.00",
          "currency": "USD",
          "created_at": 1638702715,
          "payment_id": 32259282
        }
      ]
    },
    ...
  ]
}

Filters

List referrals by a specific member

To get a list referrals by one of your members, use the query parameter member and provide the id of the member, like this:

GET https://api.refermo.co/v1/referrals/?member=a7ea424c3cb5e7dcdfadf3b45abc6f4e

Retrieve a referral

GET https://api.refermo.co/v1/referrals/[id]/

Request parameters

  • id
    The referral's Refermo ID.

Response values

  • id (string, 32 chars)
    The unique Refermo ID for this referral.
  • member_id (string, 32 chars)
    The unique Refermo ID for the referring member.
  • user_identifier (string)
    The unique ID for the referred user from your app.
  • created_at (unix timestamp)
  • converted_at (unix timestamp or null if referral has not converted)
  • is_converted (boolean)
    A simple boolean to see if the referral has converted.
  • coupon_code (string or null)
    The discount code created if this referral has double-sided rewards. This coupon can be applied at checkout to give the referred user a discount, based on your campaign settings.
  • subscription (dictionary or null)
    If this referral has converted, it will have been assigned the subscription which was created as it was converted. This dictionary has the same values as in the Subscription endpoint.
  • source (string, options app, api or js)
    This tells how the referral was created.
  • campaign_id (string, 8 chars)
    The unique ID for the campaign this referral was created within.
  • reward_type (string, options credit or commission)
    The type of reward created for this referral.
  • reward_amount (decimal as a string)
    The amount of each reward created for this referral.
  • reward_threshold (decimal as a string)
    The amount the referred user needs to be spend before rewards are created.
  • currency (string, 3 chars)
    The 3-character currency code used for this referral's rewards. This was copied from the referral's campaign when it was created.
  • stats (dictionary)
    Numerical stats for this referral.
  • rewards_completed (boolean)
    This shows if the referral will receive future rewards or not. For example, credit-based referrals will only have one reward, whereas a recurring commission-based referral will get ongoing rewards.
  • rewards (list)
    A list of rewards which have been created for this referral. This is a list of objects with id, reward type, amount rewarded, currency of the reward amount, the timestamp when the reward was created and the ID of the subscription payment in Paddle which triggered the reward.

Example response

HTTP 200 OK
{
  "id": "4b8024de11341839cf6cdafbd1dfaa01",
  "member_id": "c235f4c1f987260699843afeb59b3e16",
  "user_identifier": "dancustomer@gmail.com",
  "created_at": 1637123678,
  "converted_at": 1637123821,
  "is_converted": true,
  "coupon_code": "31A30BAF",
  "subscription": {
    "id": 9682864,
    "unit_price": "19.00",
    "currency": "USD",
    "status": "active",
    "email": "dancustomer@gmail.com",
    "next_bill_date": "2022-01-05",
    "last_bill_date": "2021-11-05",
    "plan": {
      "id": 665966,
      "name": "Monthly",
      "amount": "19.00",
      "currency": "USD",
      "interval": "month",
      "frequency": 1
    }
  },
  "source": "js",
  "campaign_id": "4d0e29b3",
  "reward_type": "credit",
  "reward_amount": "10.00",
  "reward_threshold": "0.00",
  "currency": "USD",
  "stats": {
    "rewards": 1,
    "credit_earned": "10.00",
    "commission_earned": "0.00",
    "currency": "USD"
  },
  "rewards_completed": true,
  "rewards": [
    {
      "id": "eeaa35bb13a70bc6834f35297ee74779",
      "type": "credit",
      "amount": "10.00",
      "currency": "USD",
      "created_at": 1638702715,
      "payment_id": 32259282
    }
  ]
}

Errors

If a member cannot be found, the endpoint will return a HTTP 404 response with an error message.

HTTP 404 Not Found
{
  "detail": "Not found."
}

Retrieve a referral by user identifier

You may want to get details of a referral for one of your app's users, rather than by an ID.

In this case, use the /v1/referrals/user/[user_identifier]/ endpoint.

The response data and errors are exactly the same as the standard /v1/referrals/[id]/ endpoint.

Create a referral

POST https://api.refermo.co/v1/referrals/

Creating a referral in essence means recording a new sign up that has occured after someone has visited a referral link.

The easiest way to record referrals is with the Javascript API, but you can also create them with this API.

Note: If you call this endpoint with the exact same data, the existing matching referral will be returned; the system will never create duplicate referrals for a pair of user identifier and member code.

Request parameters

  • None

Request values

  • user_identifier (string) required
    A unique identifier for this user in your app. It could be a user ID, username or email address. This value should be something that never changes in your app.
  • member_code (string) required
    The referring member's referral code. This is the same code from your referral links (yourdomain.com/?via=CODE) so you need to have access to this somehow when you create a referral.
    When using the Javascript API, this code is stored—and can therefore be accessed—in the browser as a cookie called refermo-ref.

Example request

POST
{
    "user_identifier": "dan@gmail.com",
    "member_code": "4QE39VDA"
}

Response values

  • id (string, 32 chars)
    The unique Refermo ID for this referral.
  • member_id (string, 32 chars)
    The unique Refermo ID for the referring member.
  • user_identifier (string)
    The unique ID for the referred user from your app.
  • created_at (unix timestamp)
  • converted_at (unix timestamp or null if referral has not converted)
    This will always be null for brand new referrals.
  • is_converted (boolean)
    A simple boolean to see if the referral has converted.
  • coupon_code (string or null)
    The discount code created if this referral has double-sided rewards. This coupon can be applied at checkout to give the referred user a discount, based on your campaign settings, so you can save this locally and display it when this referred user checks out.
  • subscription (dictionary or null)
    If this referral has converted, it will have been assigned the subscription which was created as it was converted. This dictionary has the same values as in the Subscription endpoint.
  • source (string, options app, api or js)
    This tells how the referral was created.
  • campaign_id (string, 8 chars)
    The unique ID for the campaign this referral was created within.
  • reward_type (string, options credit or commission)
    The type of reward created for this referral.
  • reward_amount (decimal as a string)
    The amount of each reward created for this referral.
  • reward_threshold (decimal as a string)
    The amount the referred user needs to be spend before rewards are created.
  • currency (string, 3 chars)
    The 3-character currency code used for this referral's rewards. This was copied from the referral's campaign when it was created.
  • stats (dictionary)
    Numerical stats for this referral.
  • rewards_completed (boolean)
    This shows if the referral will receive future rewards or not.
  • rewards (list)
    A list of rewards which have been created for this referral. This will be empty for brand new referrals.

Example response

HTTP 200 OK
{
  "id": "7e762faceb019337db56c408b54798bd",
  "member_id": "44dc4d920bcfe2d3183ae33bc0f9b4ed",
  "user_identifier": "testingapi@gmail.com",
  "created_at": 1641215449,
  "converted_at": null,
  "is_converted": false,
  "discount_code": null,
  "subscription": null,
  "source": "api",
  "campaign_id": "1ba89be6",
  "reward_type": "credit",
  "reward_amount": "10.00",
  "reward_threshold": "0.00",
  "currency": "USD",
  "stats": {
    "rewards": 0,
    "credit_earned": "0.00",
    "commission_earned": "0.00",
    "currency": "USD"
  },
  "rewards_completed": false,
  "rewards": []
}

Errors

If you forget to include one of the two required values, you will get a HTTP 400 response. 

HTTP 400 Bad Request
{
    "user_identifier": [
        "This field is required."
    ]
}

You'll also get an error response if a member cannot be found with the provided referral code.

HTTP 400 Bad Request
{
    "member_code": [
        "Member with code WRONGCODE was not found."
    ]
}

Update a referral

This endpoint is not available. Once created, referrals cannot be edited.

To record a referral conversion, use the conversion endpoint below.

Record a conversion

POST https://api.refermo.co/referrals/[id]/conversion/

Once a referral has been created (a new user signed up via a referral link), you need to tell Refermo when the user "converts" (when they start a paid subscription). This action triggers rewards for your referrers.

You need to provide either a checkout_id or subscription_id for each conversion, both of which are values from Paddle. This ties the conversion to a Paddle subscription, which allows Refermo to create referral rewards.

Request parameters

  • id
    The referral's ID returned from Refermo.signup() or the API.

Request values

Example request

POST
{
    "checkout_id": "110012887-chre607875daf76-a4bac0859a",
}

Delete a referral

DELETE https://api.refermo.co/v1/referrals/[id]/

Request parameters

  • id
    The referral's ID returned from Refermo.signup() or the API.

Response values

None.

Example response

HTTP 204 No Content