Introduction

Last Updated: Fri Oct 10 10:20:02 EDT 2021

Using the RetailBenefits API, you can build applications that utilize the RetailBenefits infrastructure to provide a more seamless integration between your customers and their shopping experience, bring cashback shopping to new platforms, or inroduce new innovative ideas.With this guide we explain and provide code samples for many common integration use cases.

Our API is built on HTTP, is RESTful and:

Uses predictable, resource-oriented URLs.
Uses built-in HTTP capabilities for passing parameters and authentication.
Responds with standard HTTP response codes to indicate errors.
Returns JSON

To help you get started quickly we have annotated our documenation with code samples written in several popular programming languages. Use the language selector at the top right to switch between them.

Unless otherwise specified, the base URL for API endpoints is https://api.netrbx.com/v3

Versioning

When we make backwards-incompatible changes to the API, we release new versions which are exposed by change the version in the URL https://api.netrbx.com/<version>.

The current version is v3.

Rate Limiting

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/account" \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 200 OK
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 190
X-RateLimit-Reset: 1404751292

To ensure performance, stability, and availability we throttle requests to a maximum of 5,000/hr and 25,000/day. Additionally no more than 5 requests/sec are permitted, however we do accomidate bursting to 10 requests / sec. You can check the returned HTTP headers of any API requests to see your current rate limit status.

Pagination

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/products?per_page=50&page=2" \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 200 OK
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 200 OK
Link: <https://api.netrbx.com/v3/products?page=3&per_page=50>; rel="next", <https://api.netrbx.com/v3/products?page=5&per_page=50>; rel="last"
X-Records: 250

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the page parameter. If omitted the value of this parameter will default to 1. For most resources you can also set a custom page size with the per_page parameter. Maximium value for the per_page parameter is 500.

The pagination info is included in the Link header. It is important to follow these Link header values instead of constructing your own URLs

For technical reasons not all endpoints accomodate the per_page parameter.

Errors & Status Codes

The response from RetailBenefits will have HTTP response codes that will help you determine the status of the request. Our API tries to use the appropriate HTTP response code to indicate either success or the type of problem that occured.

Success Codes

Code	Description	Explanation
200	OK	The request completed as expected.
201	Created	The request completed and a new resource has been created.
204	No Content	The request completed as expected, however does not need to return a response body.
304	Not Modified	The request completed as expected, however the document has not been modified since your last request.

Error Codes

Code	Description	Explanation
400	Bad Request	Probably caused by a programmer error, such as missing a required parameter.
401	Unauthorized	Your access_token has expired or is invalid. Make sure you have provided client_id or access_token.
403	Forbidden	You do not have permission to whatever it is you’re asking for.
404	Not Found	You’re asking for someththing that doesn’t exist.
422	Unprocessable Entity	The request looks ok, but one or more parameters look a little screwy. It’s possible that you sent data in the wrong format (e.g. an array where we expected a string) or data is missing when it is required.
429	Too Many Requests	To keep reliable performance, our API limits the rate at which you can perform certain actions.
500	Internal Server Error	Something went wrong on our side, and we have been notifed. Please try again later.
503	Service Unavailable	We’re temporarially offline for maintanance. Please try again later.

Date Format

Retail Benefits returns JSON for all API calls. Since JSON does not have a built-in date type, dates are passed as strings encoded according to ISO 8601

NOTE: This format must be used for dates being passed in to the api.

Type	Format
Date	YYYY-MM-DD
Date with time	YYYY-MM-DDTHH-MM-SSZ
	YYYY-MM-DDTHH-MM-SS±HH:MM

Authentication

# With shell, you can just pass the correct header with each request
# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/account" \
  -H "Authorization:Bearer ACCESS_TOKEN"

You authenticate to the RetailBenfits API by providing an OAuth2 access_token. You can retrieve an access_token by using one of the scenarios below and passing the client_id and client_secret provided to you. This access token has one or more scopes to identify the permissions granted.

Scopes

Name	Description
public	Access to all public data (brand information).
user	Permitted to act on a users behalf (update profile, etc..).
protected	Permitted to pull all data for a benefit program.
shopping	Permitted to pull shopping related data (merchants, categories, products).

Admin Authentication

# Make sure to replace `CLIENT_ID` and `CLIENT_SECRET` with your API credentials.
curl "https://api.netrbx.com/v3/oauth/token" \
  -X POST \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d grant_type=client_credentials

{
    "access_token": "826c758269658150872c478f70c2f348c30fd7dd076d3bd55a2089efecd6a2f5",
    "token_type": "bearer",
    "expires_in": 7200,
    "scope": "public"
}

This endpoint provides an admin access token. This token is used in scenarios such as updating user information, retrieving a list of shopper transactions or for initial communication with our APIs for mobile and toolbar based implementations when a user has not yet authenticated with one of the other scenarios below.

If you were provided your client_id and client_secret for a server-side integration this token will allow access to perform most actions. If you are a vendor or a customer who was provided this client_id and client_secret for use with a mobile, toolbar, or application based implementation, some endpoints may require you to have permission to act on a shopper’s behalf. In this case a 403 response code will be returned and you will need an access_token retrieved from one of the other scenarios.

HTTP Request

POST https://api.netrbx.com/v3/oauth/token

Expected Response Code

200 - OK

Required Parameters

Parameter	Type	Description
client_id	string	The client id belonging to your application.
client_secret	string	The client secret belonging to your application.
grant_type	string	Must be `client_credentials`

User Authentication with credentials

# Make sure to replace `CLIENT_ID` and `CLIENT_SECRET` with your API credentials.
curl "https://api.netrbx.com/v3/oauth/token" \
  -X POST \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d grant_type=password \
  -d username=rbxshopper \
  -d password=C4$hB4ck!

{
    "access_token": "826c758269658150872c478f70c2f348c30fd7dd076d3bd55a2089efecd6a2f5",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "5b49d5d5cddaa390efd685254863f94ff42cdcc39753bc3b4fdfaca283492c27",
    "scope": "public,user"
}

This endpoint provides a user access token. It is commmonly used for client-side integrations such as mobile or desktop applications, toolbars, or web based thick clients (anywhere there is risk of your credentials being exposed) where you have the ability to ask the user for their credentials. Upon authentication your permissions will be elevated allowing you to act on behalf of the user you have authenticated.

HTTP Request

POST https://api.netrbx.com/v3/oauth/token

Expected Response Code

200 - OK

Required Parameters

Parameter	Type	Description
client_id	string	The client id belonging to your application.
client_secret	string	The client secret belonging to your application.
grant_type	string	Must be `password`
username	string	Username of the user wishing to authenticate.
password	string	Password of the user wishing to authenticate.

The access_token returned should be used in place of one gained from any previous tokens. Additionally the username and password of the user should not be stored, and the access_token should be used instead.

User Authentication with Facebook

# Make sure to replace `CLIENT_ID` and `CLIENT_SECRET` with your API credentials.
curl "https://api.netrbx.com/v3/oauth/token" \
  -X POST \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d grant_type=facebook_token \
  -d facebook_token=7bcc5e94bfa2e9115a4b260c89c388ec472b6dff5f1ecac72de5f1cdb4059f51

{
    "access_token": "826c758269658150872c478f70c2f348c30fd7dd076d3bd55a2089efecd6a2f5",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "5b49d5d5cddaa390efd685254863f94ff42cdcc39753bc3b4fdfaca283492c27",
    "scope": "public,user"
}

This endpoint provides a user access token. It allows you to exchange a Facebook access_token for a Retail Benefits access_token scoped to the user owning the Facebook token.

HTTP Request

POST https://api.netrbx.com/v3/oauth/token

Expected Response Code

200 - OK

Required Parameters

Parameter	Type	Description
client_id	string	The client id belonging to your application.
client_secret	string	The client secret belonging to your application.
grant_type	string	Must be `facebook_token`
facebook_token	string	Access token provided by Facebook API.

User Authentication with Google+

# Make sure to replace `CLIENT_ID` and `CLIENT_SECRET` with your API credentials.
curl "https://api.netrbx.com/v3/oauth/token" \
  -X POST \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d grant_type=googleplus_token \
  -d googleplus_token=8409b453e502cd0ae63385cc835a9a50bb3072f0f0df62728914e28510baa022

{
    "access_token": "826c758269658150872c478f70c2f348c30fd7dd076d3bd55a2089efecd6a2f5",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "5b49d5d5cddaa390efd685254863f94ff42cdcc39753bc3b4fdfaca283492c27",
    "scope": "public,user"
}

This endpoint provides a user access token. It allows you to exchange a Google+ access_token for a Retail Benefits access_token scoped to the user owning the Google+ token.

HTTP Request

POST https://api.netrbx.com/v3/oauth/token

Expected Response Code

200 - OK

Required Parameters

Parameter	Type	Description
client_id	string	The client id belonging to your application.
client_secret	string	The client secret belonging to your application.
grant_type	string	Must be `googleplus_token`
googleplus_token	string	Access token provided by Google+ API.

User Authentication with a single sign on token

# Make sure to replace `CLIENT_ID` and `CLIENT_SECRET` with your API credentials.
curl "https://api.netrbx.com/v3/oauth/token" \
  -X POST \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d grant_type=sso_token \
  -d sso_token=d81565956425ed93d779bfbe1e75e9fb6d3b8d164116c6d9ab977d974a714e35

{
    "access_token": "826c758269658150872c478f70c2f348c30fd7dd076d3bd55a2089efecd6a2f5",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "5b49d5d5cddaa390efd685254863f94ff42cdcc39753bc3b4fdfaca283492c27",
    "scope": "public,user"
}

This endpoint provides a user access token. It allows you to exchange a single sign on token for a Retail Benefits access_token scoped to the user owning the SSO token. This scenario would mostly commonly used by toolbar based integrations in which the application would read the SSO token from a cookie and pass it through the API to obtain its own authentication scoped to the user owning the SSO token.

HTTP Request

POST https://api.netrbx.com/v3/oauth/token

Expected Response Code

200 - OK

Required Parameters

Parameter	Type	Description
client_id	string	The client id belonging to your application.
client_secret	string	The client secret belonging to your application.
grant_type	string	Must be `sso_token`
sso_token	string	Single sign on token.

Refreshing an access_token

# Make sure to replace `CLIENT_ID` and `CLIENT_SECRET` with your API credentials.
curl "https://api.netrbx.com/v3/oauth/token" \
  -X POST \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d grant_type=refresh_token \
  -d refresh_token=5b49d5d5cddaa390efd685254863f94ff42cdcc39753bc3b4fdfaca283492c27

{
    "access_token": "826c758269658150872c478f70c2f348c30fd7dd076d3bd55a2089efecd6a2f5",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "5b49d5d5cddaa390efd685254863f94ff42cdcc39753bc3b4fdfaca283492c27",
    "scope": "public,user"
}

This scenario is to obtain a new access_token when your existing token has expired. When granted an access_token its lifetime is provided in the responses as expires_in and refresh_token will be provided along with it. You may store and use this refresh_token to gain another access_token without prompting the user for their credentials again.

HTTP Request

POST https://api.netrbx.com/v3/oauth/token

Expected Response Code

200 - OK

Required Parameters

Parameter	Type	Description
client_id	string	The client id belonging to your application.
client_secret	string	The client secret belonging to your application.
grant_type	string	Must be `refresh_token`
refresh_token	string	Refresh token provided when the initial access_token was returned.

Account

Show Account

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/account"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1,
    "email": "user@example.com",
    "first_name":"Pat",
    "last_name":"Shopper",
    "country_code": "US",
    "referral_code": "username",
    "referral_url": "https://example.com/username",
    "custom_identifier": 789,
    "customer_parent_identifier": 234,
    "customer_referrer_identifier": 456,
    "custom_role": "member",
    "weekly_deals":true,
    "shopping_reminder":true,
    "monthly_balance":true,
    "monthly_payment":false,
    "rewards_problem":true,
    "subscription_level":"not_subscribed",
    "active":true,
    "cashback":
    {
      "total": 323.45,
      "pending": 23.21,
      "paid": 300.24,
      "next_payment_date": "2014-12-12",
      "next_payment_amount": 17.34
    }
  }
]

This endpoint retrieves account information for the current user.

HTTP Request

GET https://api.netrbx.com/v3/account

Expected Response Code

200 - OK

Parameters

None

Update Account

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/account"
  -X PUT \
  -H "Authorization:Bearer ACCESS_TOKEN"
  -d email="abc@def.com" \
  -d password="123456"

[
  {
    "id": 1,
    "email": "abc@def.com",
    "first_name":"Pat",
    "last_name":"Shopper",
    "country_code": "US",
    "referral_code": "username",
    "referral_url": "https://example.com/username",
    "custom_identifier": 789,
    "customer_parent_identifier": 234,
    "customer_referrer_identifier": 456,
    "custom_role": "member",
    "weekly_deals":true,
    "shopping_reminder":true,
    "monthly_balance":true,
    "monthly_payment":false,
    "rewards_problem":true,
    "subscription_level":"annual",
    "active":true,
    "cashback":
    {
      "total": 323.45,
      "pending": 23.21,
      "paid": 300.24,
      "next_payment_date": "2014-12-12",
      "next_payment_amount": 17.34
    }
  }
]

This endpoint is used to update profile information for the current user. The response will include all fields in the user profile, other than the password, including those updated by the call to this endpoint.

If a value other than true or false is provided for any of the email preferences (e.g. weekly_deals), that parameter will remain unchanged.

HTTP Request

PUT https://api.netrbx.com/v3/account

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
email	string	“”	User’s contact email address
first_name	string	“”	User’s first name
last_name	string	“”	User’s last name
password	string	“”	Password for the user.
country_code	string	“”	User’s primary country.
referral_code	string	“”	Code to be used when this user refers another and as url stub (http://example.com/u/).
referrer	string	“”	Referral code given to this user by another user.
custom_identifier	string	“”	Unique identifier for this user (usually your primary key).
custom_parent_identifier	string	“”	Identifier of parent record (usually your foreign key).
custom_referrer_identifier	string	“”	Identifier of user referring this user (must match custom_identifier).
custom_role	string	“”	Role of this user (mostly used for affiliate management).
weekly_deals	boolean	“”	Whether to receive emails for weekly deals.
shopping_reminder	boolean	“”	Whether to receive emails for shopping reminders
monthly_balance	boolean	“”	Whether to receive emails for monthly balance.
monthly_payment	boolean	“”	Whether to receive emails for monthly payments.
rewards_problem	boolean	“”	Whether to receive emails for problems with their rewards.
reset_password_on_login	boolean	“”	Whether to notify user to reset their password on their next sign in.

Activity

List all Activity

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/activity"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 12,
    "merchant_id": 123,
    "merchant_name":"Best Buy",
    "activity_date":"2014-09-12",
    "sale_amount": 5.32,
    "travel": false,
    "days_to_report": 4,
    "eligible_for_inquiry": false,
    "created_at":"2014-09-12T20:26:49.893Z"
  },
  {
    "id": 13,
    "merchant_id": 123,
    "merchant_name":"Target",
    "activity_date":"2014-09-10",
    "sale_amount": nil,
    "travel": true,
    "days_to_report": 4,
    "eligible_for_inquiry": false,
    "created_at":"2014-09-10T20:26:49.893Z"
  }
]

This endpoint retrieves records of visits to merchants by the current user. Records are listed in reverse chronological order.

HTTP Request

GET https://api.netrbx.com/v3/activity

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Maximum number of results to return per page

NOTE: This endpoint requires the use of a user access_token

Cashback

List all Cashback

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/cashback"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 9325,
    "tracking_id": "2v6558d43733d18feav2",
    "merchant_name": "Best Buy",
    "purchase_date": "2014-05-12",
    "cashback_amount": 3.45,
    "purchase_amount": 221.56,
    "available_date": "2014-09-21",
    "payment_date": "",
    "payment_amount": 0,
    "status": "pending",
    "settlement_type":"commission",
    "created_at":"2014-05-12T20:26:49.893Z"
  },
  {
    "id": 4362,
    "tracking_id": "2v6558d43733d18feav2",
    "merchant_name": "Target",
    "purchase_date": "2014-03-02",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "2014-07-01",
    "payment_amount": 25.43,
    "status": "paid",
    "settlement_type":"commission",
    "created_at":"2014-03-02T20:26:49.893Z"
  }
]

This endpoint retrieves all cashback activity for the current user. If there is no current user, no records will be returned. Records are sorted chronologically with newest records appearing first. If the value of the status field is pending, then the payment_date field will be blank and the payment_amount field will be zero.

If the status parameter is left blank, or given a value other than paid, pending or earned then all activity is returned. paid returns all records which have already been paid. pending returns all records which have not yet been paid. earned returns all pending records included in the next projected payment.

HTTP Request

GET https://api.netrbx.com/v3/cashback

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
status	string	“”	One of pending, paid or earned.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Maximum number of results to return per page

NOTE: This endpoint requires the use of a user access_token

Parameter	Type	Default	Description
root	boolean	false	Whether to only return top level (root) categories.

Custom Offers

List custom offers

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/custom_offers"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": "1",
    "name": "Coffee Party",
    "description": "All varieties of beans",
    "start_date": "2014-04-04",
    "end_date": "2014-07-04",
    "featured": true,
    "images": {
      "featured": "http://logo.com/logo.png",
      "standard": "http://logo.com/logo.png"
    }
  },
  {
    "id": "2",
    "name": "Ice Cream Party",
    "description": "All varieties of flavors",
    "start_date": "2014-04-04",
    "end_date": "2014-07-04",
    "featured": false,
    "images": {
      "featured": "http://logo.com/logo.png",
      "standard": "http://logo.com/logo.png"
    }
  }
]

Optional Parameters

Parameter	Type	Default	Description
featured	boolean	“”	Whether to include offers that are featured.

This endpoint retrieves all custom offers matching a scoped benefit program

HTTP Request

GET https://api.netrbx.com/v3/custom_offers

Expected Response Code

200 - OK

Link for custom offer

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/custom_offers/<id>/link"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": "1",
    "name": "Coffee Party",
    "description": "All varieties of beans",
    "tracking_url": "https://target.com",
    "start_date": "2014-04-04",
    "end_date": "2014-07-04",
    "featured": true,
    "images": {
      "featured": "http://logo.com/logo.png",
      "standard": "http://logo.com/logo.png"
    }
  },
]

HTTP Request

GET https://api.netrbx.com/v3/custom_offers/<id>/link

Expected Response Code

200 - OK

Disbursements

A Disbursement is a collection of payments sent to either a benefit program or an individual user. An aggregate disbursement contains many payments. An individual disbursement contains only one.

List disbursements

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/disbursements"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
 {
   "id": 4362,
   "amount": 234.34,
   "date": "2014-06-21",
   "status": "confirmed",
   "type": "aggregate",
   "payments_count": 97,
   "user_id": null,
   "details": "http://s3.amazon.com/disbursement_4362.csv.gz",
   "processed": true
 },
 {
   "id": 2943,
   "amount": 345.35,
   "date": "2014-07-21",
   "status": "sent",
   "type": "individual",
   "payments_count": 1,
   "user_id": 234,
   "details": "http://s3.amazon.com/disbursement_2943.csv.gz",
   "processed": false
 },
 {
   "id": 20934,
   "amount": 35.35,
   "date": "2014-07-01",
   "status": "failed",
   "type": "individual",
   "payments_count": 1,
   "user_id": null,
   "details": "http://s3.amazon.com/disbursement_20934.csv.gz",
   "processed": true
 }
]

This endpoint returns records for disbursements for the current benefit program ending with the current date or the given end date. By default this endpoint retrieves the last 30 days of disbursements. Otherwise it uses the given start date.

Possible values for the status field in the return data are pending, sent, failed and confirmed. Possible values for the type field in the return data are individual and aggregate. Aggregate disbursements collect several payments.

The payments_count field is the number of payments collected into the disbursement.

The user_id field will be blank for disbursements sent to the benefit program. Otherwise it is the system id for the user to which the disbursement was sent.

The details field provides the uri for a compressed csv file containing information about payments contained in the disbursement.

HTTP Request

GET https://api.netrbx.com/v3/disbursements

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
benefit_program	string	“”	If true, returns only disbursements for the benefit program. If false, returns only user disbursements. By default returns all disbursements.
user_ids	string	“”	Comma separated list of user ids for which to retrieve disbursements. By default returns all disbursements.
start_date	string		Date from which to begin including disbursements. By default returns all disbursements. See the Date Format page.
end_date	string		Date up to which to include disbursements. By default returns all disbursements. See the Date Format page.
status	string	sent,confirmed	If provided (pending,failed,sent,confirmed) will return only disbursements in those statuses by default it returns sent and confirmed only.
processed	boolean	false	If false, returns only disbursements that have not been flagged as processed.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page.

NOTE: This endpoint requires the use of an admin access_token

Retrieve a set of disbursements

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/disbursements/1234,5678"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
 {
   "id": 1234,
   "amount": 234.34,
   "date": "2014-06-21",
   "status": "confirmed",
   "type": "aggregate",
   "user_id": null,
   "payments_count": 97,
   "details": "http://s3.amazon.com/disbursement_1234.csv.gz",
   "processed": true
 },
 {
   "id": 5678,
   "amount": 345.35,
   "date": "2014-07-21",
   "status": "sent",
   "type": "individual",
   "payments_count": 1,
   "user_id": 234,
   "details": "http://s3.amazon.com/disbursement_5678.csv.gz",
   "processed": false
 }
]

This endpoint retrieves a set of disbursements corresponding to the id’s sent in. If any of the provided id’s are not found, records for those id’s will not be included in the response. This will be the only indication that an error has occurred.

Note that the :ids field in the request must be replaced by a comma-separated list of id values for disbursements in the server system.

HTTP Request

GET https://api.netrbx.com/v3/disbursements/:ids

Expected Response Code

200 - OK

Optional Parameters

None.

NOTE: This endpoint requires the use of an admin access_token

Process a disbursement

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/disbursements/1234/process"
  -X PUT \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint sets the “processed” field on the disbursement to true.

Note that the :id field in the request must be replaced with the id value for the disbursement in the server system.

HTTP Request

PUT https://api.netrbx.com/v3/disbursements/:id/process

Expected Response Code

204 - No Content

Possible Error Code

404 - Not Found: The disbursement corresponding to the provided id was not found.

Parameters

None.

Unprocess a disbursement

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/disbursements/1234/unprocess"
  -X PUT \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint sets the “processed” field on the disbursement to false.

Note that the :id field in the request must be replaced with the id value for the disbursement in the server system.

HTTP Request

PUT https://api.netrbx.com/v3/disbursements/:id/unprocess

Expected Response Code

204 - No Content

Possible Error Code

404 - Not Found: The disbursement corresponding to the provided id was not found.

Parameters

None.

Downloads

Retrieve all downloads

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/downloads"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -d start_date=2014-06-07 \
  -d end_date=2014-08-09 \
  -d page=3 \
  -d per_page=100"

[
 {
   "custom_identifier": "abcd",
   "download_date": "2014-06-21T12:11Z",
   "id": 4362,
   "ip_address": "192.168.0.0",
   "os": "Android",
   "platform": "Firefox Extension",
   "user_agent": "Mozilla/5.0 (Windows NT 6.0; WOW64; rv:37.0) Gecko/20100101 Firefox/37.0",
   "user_id": 7234
 },
 {
   "custom_identifier": "abcd",
   "download_date": "2014-06-22T12:11Z",
   "id": 4927,
   "ip_address": "192.168.0.0",
   "os": "Android",
   "platform": "Android",
   "user_agent": "Mozilla/5.0 (Windows NT 6.0; WOW64; rv:37.0) Gecko/20100101 Firefox/37.0",
   "user_id": 9234
 }
]

This endpoint returns records of users downloading toolbars or mobile applications.

The id field is unique to the record. It may be used to reconcile duplicate records.

The user_id field refers to the user who visited the merchant. The custom_identifier field is taken from this user. More information for this user is available at the users endpoint.

Time value for the download_date field is in UTC.

Possible values for the platform field are: Android, Chrome Extension, Firefox Extension, IE Extension, iOS, and Safari Extension.

HTTP Request

GET https://api.netrbx.com/v3/downloads

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
start_date	string	“”	Date from which to begin including download records. By default returns all download records. See the Date Format page.
end_date	string	“”	Date up to which to include download records. By default returns all download records. See the Date Format page.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page.

NOTE: This endpoint requires the use of an admin access_token

Inquiries

List all inquiries

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/inquiries"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1234,
    "user_id": 1234,
    "status": "denied",
    "inquiry_type": "missing",
    "order_number": "XYZ123458",
    "purchase_amount": 121.5,
    "shopper_description": "denied - not last click XYZ123458",
    "travel_date": "2018-05-24",
    "agreed_to_terms": true,
    "link": {
      "id": 1234,
      "order_number": 1234,
      "sale_amount": "0.0",
      "visit_id": 1234,
      "shopper_commission_amount": "0.0"
    },
    "merchant": {
      "id": 1234,
      "name": "Acme LLC"
    }
  }
]

This endpoint retrieves all inquiries for the current user. Inquiry statuses include pending, processing, approved and denied.

HTTP Request

GET https://api.netrbx.com/v3/inquiries

Expected Response Code

200 - OK

Retrieve a set of existing inquiries

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/inquiries/<ids - comma separated>"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1234,
    "user_id": 1234,
    "status": "denied",
    "inquiry_type": "missing",
    "order_number": "XYZ123458",
    "purchase_amount": 121.5,
    "shopper_description": "denied - not last click XYZ123458",
    "travel_date": "2018-05-24",
    "agreed_to_terms": true,
    "link": {
      "id": 1234,
      "order_number": 1234,
      "sale_amount": "0.0",
      "visit_id": 1234,
      "shopper_commission_amount": "0.0"
    },
    "merchant": {
      "id": 1234,
      "name": "Acme LLC"
    }
  }
]

This endpoint retrieves a set of inquiries corresponding to the id’s sent in. If any of the provided id’s are not found, records for those id’s will not be included in the response. This will be the only indication that an error has occurred.

HTTP Request

GET https://api.netrbx.com/v3/inquiries/<ids - comma separated>

Expected Response Code

200 - OK

Optional Parameters

None.

Create an Inquiry

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/inquiries"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -d merchant_id=3408 \
  -d order_number=C13489 \
  -d link_id=1234 \
  -d shopper_description="order confirmation email" \
  -d agreed_to_terms=true \
  -d purchase_amount= 25.32 \
  -d travel_date="2018-05-24"

[
  {
    "id": 1234,
    "user_id": 1234,
    "status": "denied",
    "inquiry_type": "missing",
    "order_number": "C13489",
    "purchase_amount": 25.32,
    "shopper_description": "denied - not last click XYZ123458",
    "travel_date": "2018-05-24",
    "agreed_to_terms": true,
    "link": {
      "id": 1234,
      "order_number": 1234,
      "sale_amount": "0.0",
      "visit_id": 1234,
      "shopper_commission_amount": "0.0"
    },
    "merchant": {
      "id": 1234,
      "name": "Acme LLC"
    }
  }
]

This endpoint is used for creating a new inquiry for the current user.

HTTP Request

POST https://api.netrbx.com/v3/inquiries

Expected Response Code

201 - Created

Required Parameters

Parameter	Type	Required	Description
merchant_id	Integer	True	Merchant involved in the purchase.
order_number	String	True	Order / Confirmation number provided at checkout or on receipt.
order_total	Float	True	Total amount given to merchant, including tax and shipping.
purchase_amount	Float	True	The purchase amount for the item.
shopper_description	String	True	The shopper description (contents of confirmation email.
agreed_to_terms	Boolean	True	Were the terms agreed to or not.
status	String	True	Status of the inquiry one of pending, approved, denied.
link_id	Integer	True	Link that was clicked.
travel_date	Date	False	Date of travel.

Keywords

List Keywords

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.rbx.com/v3/keywords"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "name": "Target"
  },
  {
    "name": "Tartan"
  }
]

This endpoint returns a list of keywords starting with the given search parameter. It returns all keywords when no search parameter is provided.

HTTP Request

GET https://api.netrbx.com/v3/keywords

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
search	string	“”	Case-insensitive characters used to match the beginning of a keyword

Links

Retrieve all links

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/links"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -d start_date=2014-06-07 \
  -d end_date=2014-08-09 \
  -d page=3 \
  -d per_page=100"

[
 {
   "clicked_date": "2014-06-21T12:11Z",
   "converted_date": "2014-06-21T18:11Z",
   "custom_identifier": "abcd",
   "id": 4362,
   "ip_address": "192.168.0.0",
   "merchant_id": 2344,
   "merchant_name":"Big Box",
   "os": "Android",
   "platform": "mobile",
   "program_commission_amount": 0.12,
   "referrer_commission_amount": 0.12,
   "sale_amount": 12.34,
   "shopper_commission_amount": 0.23,
   "user_agent": "Mozilla/5.0 (Windows NT 6.0; WOW64; rv:37.0) Gecko/20100101 Firefox/37.0",
   "user_id": 7234,
   "days_to_report": 4,
   "eligible_for_inquiry": false
 },
 {
   "clicked_date": "2014-06-22T12:11Z",
   "converted_date": "",
   "custom_identifier": "abcd",
   "id": 4927,
   "ip_address": "192.168.0.0",
   "merchant_id": 2234,
   "merchant_name":"Big Box",
   "os": "Android",
   "platform": "web",
   "program_commission_amount": 0, 
   "referrer_commission_amount": 0, 
   "sale_amount": 0, 
   "shopper_commission_amount": 0, 
   "user_agent": "Mozilla/5.0 (Windows NT 6.0; WOW64; rv:37.0) Gecko/20100101 Firefox/37.0",
   "user_id": 9234,
   "days_to_report": 4,
   "eligible_for_inquiry": false
 }
]

This endpoint returns records of users clicking links to visit merchants. A link is converted when the record of a purchase associated with the merchant visit is received by the system.

The id field is unique to the record. It may be used to reconcile duplicate records, or to track when a link has been converted.

The merchant_id field refers to the merchant visited. The merchant_name field is taken from this merchant. More information for this merchant is available at the merchants endpoint.

The user_id field refers to the user who visited the merchant. The custom_identifier field is taken from this user. More information for this user is available at the users endpoint.

Time values for the clicked_date and converted_date fields are in UTC.

If the link has not been converted, the converted_date is left blank, and the *_amount fields are zero.

Possible values for the platform field are: web, mobile, and toolbar.

HTTP Request

GET https://api.netrbx.com/v3/links

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
user_ids	string	“”	Comma separated list of user ids for which to retrieve links. By default returns all links.
start_date	string	“”	Date from which to begin including links. By default returns all links. See the Date Format page.
end_date	string	“”	Date up to which to include links. By default returns all links. See the Date Format page.
converted	boolean	“”	If false, returns only links that have not been converted. If true, returns only those links that have been converted. Otherwise returns all links.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page.

NOTE: This endpoint requires the use of an admin access_token

Create a link

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/links"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -d link_type=share \
  -d linkable_type=Merchant \
  -d linkable_id=1234 \
  -d source="SearchResult"

[
  {
    "id": 1,
    "short_code": "X3d7Hq",
    "url": "https://example.com/X3d7Hq",
    "source": "SearchResult",
    "merchant_id": 1234
  }
]

This endpoint is used for creating a new link. A link provides a shortened, trackable url to an object, e.g. a merchant, product or offer. The url can then be used by a shopper to refer someone else to that object. It then allows the system to track the referral to the shopper. The url can also be used as a tracking id for associating the visit to an object to the shopper.

On success, the response contains the id, short_code and url for the newly created link. On failure, the endpoint returns a description of the error.

HTTP Request

POST https://api.netrbx.com/v3/links

Expected Response Code

201 - Created

Possible Error Code

422 - Unprocessable Entity: link_type, linkable_type or linkable_id fields are blank or contain unrecognized values.

Required Parameters

Parameter	Type	Description
link_type	string	Purpose of the link. Allowed values are share and purchase.
linkable_type	string	Type of object referred to by the link. Possible values are Merchant, Offer and Product.
linkable_id	string	Id of the object referred to by the link.
source	string	Location of link placement for example (Merchant Details, Search Results, Email etc..) used for analytics

Optional Parameters

Parameter	Type	Description
interstitial	boolean	Whether an interstitial screen should be displayed. Implementations that display their own should not use this parameter as the default value is false.

NOTE: This endpoint requires the use of a user access_token

Merchants

List all merchants

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/merchants?url[]=http://acme.com&url[]=http://daliatros.com"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "android_tracking": false,
    "cashback_high": 4.1, 
    "cashback_type": "percentage",
    "cashback_active": true,
    "cashback_varies": true,
    "countries": ["US", "UK"],
    "description": "lorem ipsum dolor sit amet",
    "favorite": false,
    "favorite_offers_count": 1,
    "featured": true,
    "id": 1234,
    "ios_tracking": true,
    "logo_url": "http://www.acmellc.com/logo.png",
    "name": "Acme LLC",
    "offers_count": 12,
    "status": "active",
    "terms_and_conditions": "lorem ipsum dolor sit amet",
    "url": "http://www.acmellc.com"
  }, 
  {
    "android_tracking": false,
    "cashback_high": 4.3,
    "cashback_type": "flat_rate",
    "cashback_active": true,
    "cashback_varies": false,
    "countries": ["US"],
    "description": "lorem ipsum dolor sit amet",
    "favorite": false,
    "favorite_offers_count": 0,
    "featured": false,
    "id": 2345,
    "ios_tracking": true,
    "logo_url": "http://www.daliatros.com/logo.png",
    "name": "Daliatros",
    "offers_count": 3,
    "status": "active",
    "terms_and_conditions": "lorem ipsum dolor sit amet",
    "url": "http://www.daliatros.com"
  } 
]

This endpoint retrieves all merchants. If the provided access token corresponds to a current user, the list does not include merchants blocked for that user.

The cashback_type has two possible values: percentage, and flat_rate. The cashback_active field shows whether the user has visited this merchant within the last hour. The cashback_varies field shows whether the merchant has different cashback quantities depending on the type of item purchased.

If there is no current user, the favorite parameter is ignored.

For the featured, favorite and with_favorite_offers parameters, if no value is provided, then all merchants are included in the response; false returns merchants who do not meet the criteria and true returns merchants who fit the criteria.

Results are ordered alphabetically by name by default, and by relevancy when search param has been provided.

HTTP Request

GET https://api.netrbx.com/v3/merchants

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
category_id	integer		Limits results to merchants in the given category
featured	boolean	“”	Restricts records returned to those marked as featured. See note above.
favorite	boolean	“”	Restricts records returned to those marked as favorite. See note above.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page
search	string	“”	Terms to use for search of merchants
url	array	“”	Url(s) of merchants to search by
status	string	“active”	Restricts records returned to those with the specified status. Possible values are active and deleted.
with_favorite_offers	boolean	“”	Restricts records to those which do or do not have offers favorited by the current user. See note above.

Retrieve a set of existing merchants

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/merchants/1234"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "android_tracking": false,
    "cashback_high": 4.3,
    "cashback_type": "percentage",
    "cashback_active": true,
    "cashback_varies": false,
    "country_codes": ["US","UK"],
    "description": "lorem ipsum dolor sit amet",
    "favorite": true,
    "favorite_offers_count": 0,
    "featured": false,
    "id": 1234,
    "ios_tracking": true,
    "logo_url": "http://www.acmellc.com/logo.png",
    "name": "Acme LLC",
    "offers_count": 3,
    "status": "active",
    "terms_and_conditions": "lorem ipsum dolor sit amet",
    "url": "http://www.acmellc.com"
  } 
]

This endpoint retrieves a set of merchants corresponding to the id’s sent in. If any of the provided id’s are not found, records for those id’s will not be included in the response. This will be the only indication that an error has occurred.

Note that the :ids field in the request must be replaced by a comma-separated list of id values for merchants in the server system.

HTTP Request

GET https://api.netrbx.com/v3/merchants/:ids

Expected Response Code

200 - OK

Optional Parameters

None.

Block a merchant

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/merchants/23456/block"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint blocks display of a merchant for the current user.

Note that the :id field in the request must be replaced with the id value for the merchant in the server system.

HTTP Request

POST https://api.netrbx.com/v3/merchants/:id/block

Expected Response Code

204 - No Content

Possible Error Code

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The merchant corresponding to the provided id was not found.

Parameters

None.

Unblock a merchant

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/merchants/23456/unblock"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint unblocks display of a merchant for the current user.

Note that the :id field in the request must be replaced with the id value for the merchant in the server system.

HTTP Request

POST https://api.netrbx.com/v3/merchants/:id/unblock

Expected Response Code

204 - No Content

Possible Error Code

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The merchant corresponding to the provided id was not found.

Parameters

None.

Favorite a merchant

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/merchants/23456/favorite"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint sets a merchant as a favorite for the current user.

Note that the :id field in the request must be replaced with the id value for the merchant in the server system.

HTTP Request

POST https://api.netrbx.com/v3/merchants/:id/favorite

Expected Response Code

204 - No Content

Possible Error Code

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The merchant corresponding to the provided id was not found.

Parameters

None.

Unfavorite a merchant

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/merchants/23456/unfavorite"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint unsets a merchant as a favorite for the current user.

Note that the :id field in the request must be replaced with the id value for the merchant in the server system.

HTTP Request

POST https://api.netrbx.com/v3/merchants/:id/unfavorite

Expected Response Code

204 - No Content

Possible Error Code

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The merchant corresponding to the provided id was not found.

Parameters

None.

Notifications

List User Notifications

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/notifications"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 2,
    "title": "Save at Walmart",
    "content": "Save at Walmart",
    "platform": "toolbar",
    "data": {
      "m": [
        1847
      ],
      "t": 1
    },
    "created_at": "2017-04-23T16:10:47.394Z",
    "expires": "2017-05-03T16:10:47.393Z"
  }
]

This endpoint retrieves a list of notifications for the current user.

HTTP Request

GET https://api.netrbx.com/v3/notifications

Optional Parameters

Parameter	Type	Default	Description
last_seen_id	integer		Limits results to those with an id greater than the provided id
last_seen	date		Limits results to those created after provided date.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page

Offer Types

Get Offer Types

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/offer_types"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": "92839",
    "name": "Free Shipping"
  },
  {
    "id": "28348",
    "name": "Discount"
  }, 
]

This endpoint retrieves a list of offer types.

HTTP Request

GET https://api.netrbx.com/v3/offer_types

Expected Response Code

200 - OK

Optional Parameters

None

Offers

List all offers

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/offers"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": "34623",
    "name": "Free Shipping on orders over $50",
    "restriction": "",
    "merchant_id": "28938934",
    "merchant_name": "Target",
    "logo_url": "http://logo.com/logo.png",
    "start_date": "2014-04-04",
    "end_date": "2014-07-04",
    "code": "X43U8R",
    "featured": true,
    "favorite": false,
    "status": "enabled",
    "categories":
    [
      {
        "id": "298347",
        "name": "Clothing"
      }
    ],
    "offer_types":
    [
      {
        "id": "8435",
        "name": "Free Shipping"
      }
    ]
  },
  {
    "id": "83723",
    "name": "$10 off any order over $500",
    "restriction": "Limited time only",
    "merchant_id": "9348034",
    "merchant_name": "Target",
    "logo_url": "http://logo.com/logo.png",
    "start_date": "2014-05-05",
    "end_date": "ongoing",
    "code": "",
    "featured": false,
    "favorite": false,
    "status": "enabled",
    "categories":
    [
      {
        "id": "93843",
        "name": "Outdoors"
      },
      {
        "id": "298347",
        "name": "Clothing"
      }
    ],
    "offer_types":
    [
      {
        "id": "8435",
        "name": "Discount"
      },
      {
        "id": "23934",
        "name": "Promotional"
      }
    ]
  }
]

This endpoint retrieves all offers matching given parameters. For the expiring_soon type this means offers expiring within one day.

If there is no current user, the favorite parameter is ignored. For the featured and favorite parameters, if no value is provided, then all offers are included in the response; false returns offers which do not meet the criteria and true returns offers which fit the criteria.

HTTP Request

GET https://api.netrbx.com/v3/offers

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
category_id	integer		Limits results to offers for the given category
expires	string	“”	One of day, week or month. Does not return offers already expired.
enabled	boolean	true	Whether to return enabled offers.
featured	boolean		Whether to include offers that are featured.
favorite	boolean		Whether to include favorite offers.
merchant_id	integer		Limits results to offers for the given merchant
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Maximum number of results to return per page
search	string	“”	Terms to use for search of offers

Retrieve a set of existing offers

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/offers/34623,83723"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": "34623",
    "name": "Free Shipping on orders over $50",
    "restriction": "",
    "merchant_id": "28938934",
    "merchant_name": "Target",
    "logo_url": "http://logo.com/logo.png",
    "start_date": "2014-04-04",
    "end_date": "2014-07-04",
    "code": "X43U8R",
    "featured": true,
    "favorite": false,
    "status": "enabled",
    "categories":
    [
      {
        "id": "298347",
        "name": "Clothing"
      }
    ],
    "offer_types":
    [
      {
        "id": "8435",
        "name": "Free Shipping"
      }
    ]
  },
  {
    "id": "83723",
    "name": "$10 off any order over $500",
    "restriction" : "New Customers Only",
    "merchant_id": "9348034",
    "merchant_name": "Target",
    "logo_url": "http://logo.com/logo.png",
    "start_date": "2014-05-05",
    "end_date": "ongoing",
    "code": "",
    "featured": false,
    "favorite": false,
    "status": "enabled",
    "categories":
    [
      {
        "id": "93843",
        "name": "Outdoors"
      },
      {
        "id": "298347",
        "name": "Clothing"
      }
    ],
    "offer_types":
    [
      {
        "id": "8435",
        "name": "Discount"
      },
      {
        "id": "23934",
        "name": "Promotional"
      }
    ]
  }
]

This endpoint retrieves a set of offers corresponding to the id’s sent in. If any of the provided id’s are not found, records for those id’s will not be included in the response. This will be the only indication that an error has occurred.

If an id corresponds to a disabled offer, the record for that offer will not be returned.

Note that the :ids field in the request must be replaced by a comma-separated list of id values for offers in the server system.

HTTP Request

GET https://api.netrbx.com/v3/offers/:ids

Expected Response Code

200 - OK

Optional Parameters

None.

Favorite an offer

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/offers/23456/favorite"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint sets an offer as a favorite for the current user.

Note that the :id field in the request must be replaced with the id value for the offer in the server system.

HTTP Request

POST https://api.netrbx.com/v3/offers/:id/favorite

Expected Response Code

204 - No Content

Possible Error Code

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The offer corresponding to the provided id was not found.

Parameters

None.

Unfavorite an offer

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/offers/23456/unfavorite"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint unsets an offer as a favorite for the current user.

Note that the :id field in the request must be replaced with the id value for the offer in the server system.

HTTP Request

POST https://api.netrbx.com/v3/offers/:id/unfavorite

Expected Response Code

204 - No Content

Possible Error Code

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The offer corresponding to the provided id was not found.

Parameters

None.

Payments

Payments are a collection of settlements payable to a user or benefit program. Payments are aggregated into disbursements which are distributed to a benefit program or user.

List payments

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/payments"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 4362,
    "user_id": null,
    "custom_identifier": null,
    "custom_parent_identifier": null,
    "payment_date": "2014-03-02",
    "payment_amount": 121.34,
    "sales_amount": 1453.98,
    "sales_count": 532,
    "status": "pending",
    "disbursement_date": "",
    "disbursement_id": null,
    "processed": true
  },
  {
    "id": 3092,
    "user_id": 832,
    "custom_identifier": 789,
    "custom_parent_identifier": 234,
    "payment_date": "2014-03-02",
    "payment_amount": 21.34,
    "sales_amount": 453.98,
    "sales_count": 53,
    "status": "sent",
    "disbursement_date": "2014-03-15",
    "disbursement_id": 234,
    "processed": true
  }
]

This endpoint returns a summary of payments made to either the benefit program or users in the benefit program. Payment records end with the current date or the given end date. By default this endpoint retrieves the last 30 days of payments. Otherwise it uses the given start date.

The sales_amount is the sum of the price of all purchases the transactions for which are included in the payment. Similarly, the sales_count field is the number of transactions included in the payment. Note that some merchants may provide a separate transaction for each line item in a purchase. The sales_count may also include transactions representing the return of a purchased item to a merchant.

The user_id, custom_identifier and custom_parent_identifier fields will be null for payments to the benefit program. Otherwise they are the values from system record of the user receiving the payment.

The status field is pending for payments not yet associated with a disbursement. Otherwise it is the status of the disbursement associated with the payment.

The disbursement_date and disbursement_id fields are null for payments not associated with a disbursement. Otherwise they are the date of the disbursement and system identifier with which the payment is associated.

HTTP Request

GET https://api.netrbx.com/v3/payments

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
benefit_program	string	“”	If true, returns only payments for the benefit program. If false, returns only user payments. By default returns all payments.
user_ids	string	“”	Comma separated list of user ids for which to retrieve payments. By default returns all payments.
start_date	string		Purchase date from which to begin including payments. By default returns all payments. See the Date Format page.
end_date	string		Purchase date up to which to include payments. By default returns all payments. See the Date Format page.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page.

NOTE: This endpoint requires the use of an admin access_token

Retrieve a set of payments

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/payments/1234,5678"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1234,
    "user_id": null,
    "custom_identifier": null,
    "custom_parent_identifier": null,
    "payment_date": "2014-03-02",
    "payment_amount": 121.34,
    "sales_amount": 1453.98,
    "sales_count": 532,
    "status": "failed",
    "disbursement_date": "2014-03-15",
    "disbursement_id": 123,
    "processed": true
  },
  {
    "id": 5678,
    "user_id": 832,
    "custom_identifier": 789,
    "custom_parent_identifier": 234,
    "payment_date": "2014-03-02",
    "payment_amount": 21.34,
    "sales_amount": 453.98,
    "sales_count": 53,
    "status": "confirmed",
    "disbursement_date": "2014-03-15",
    "disbursement_id": 234,
    "processed": true
  }
]

This endpoint retrieves a set of payments corresponding to the id’s sent in. If any of the provided id’s are not found, records for those id’s will not be included in the response. This will be the only indication that an error has occurred.

Note that the :ids field in the request must be replaced by a comma-separated list of id values for payments in the server system.

HTTP Request

GET https://api.netrbx.com/v3/payments/:ids

Expected Response Code

200 - OK

Optional Parameters

None.

NOTE: This endpoint requires the use of an admin access_token

Places

List All Places

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/places"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "merchant_id": 239004,
    "distance": 200,
    "lat": -94.324,
    "lon": 103.53
  },
  {
    "merchant_id": 392847,
    "distance": 900,
    "lat": -94.114,
    "lon": 103.934
  }
]

This endpoint returns a list of places, each of which corresponds to a merchant. The list includes all places within the given distance parameter from the location specified in the lat_lon parameter.

The distance value returned is in meters.

HTTP Request

GET https://api.netrbx.com/v3/places

Expected Response Code

200 - OK

Mandatory Parameters

Parameter	Type	Description
lat_lon	string	Comma-separated values for latitude and longitude for where to begin search.

Optional Parameters

Parameter	Type	Default	Description
distance	float	500	Radius in meters from given latitude and longitude to use for search.
merchant_id	string	“”	Restrict places returned to those for the specified merchant.

Products

List all products

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/products"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": "34623",
    "name": "iPhone 5S",
    "image_url": "http://www.apple.com/store/images/iphone_5s",
    "merchant_count": "1",
    "price_min": "299.99",
    "price_max": "299.99",
    "favorite": "true",
    "merchants": 
    [
      {
        "id": "34623-1234",
        "name": "Best Buy",
        "logo_url": "http://www.bestbuy.com/logo",
        "merchant_id": "639823",
        "url": "http://www.bestbuy.com/products/iphone_5s",
        "retail_price": "499.99",
        "price": "299.99",
        "cash_back_price":"290.99",
        "cash_back": "3%"
      }
    ]
  }, 
  {
    "id": "83948",
    "name": "Kellogs Corn Flakes",
    "image_url": "http://www.kellogs.com/store/images/corn_flakes",
    "merchant_count": "2",
    "price_min": "3.99",
    "price_max": "4.39",
    "favorite": "false"
  }
]

This endpoint retrieves all products.

If there is no current user, the favorite parameter is ignored. For both the featured and favorite parameters, if no value is provided, then all products are included in the response; false returns products who do not meet the criteria and true returns products who fit the criteria.

The number of records returned per page will vary between 10 and 30. We are using several sources for product lookup and cannot predict how the results will overlap. The total number of records shown in the header is also an estimate. The total number of pages should be accurate.

If there is only one merchant selling the item, then merchant detail information will be included in the data returned. The structure for this data is identical for that used in the detail view described below.

HTTP Request

GET https://api.netrbx.com/v3/products

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
featured	boolean		Whether to include products that are featured.
favorite	boolean		Whether to include favorite products.
page	integer	1	Page number of results to retrieve. Min value is 1.
search	string	“”	Terms to use for search of products
ean	string		EAN for a barcode search

Retrieve a set of existing products

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/products/34623,83948"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": "34623",
    "name": "iPhone 5S",
    "description": "The latest iPhone from Apple",
    "image_url": "http://www.apple.com/store/images/iphone_5s",
    "merchant_count": "2",
    "price_min": "289.99",
    "price_max": "299.99",
    "favorite": true,
    "merchants": 
    [
      {
        "id": "34623-1234",
        "name": "Best Buy",
        "logo_url": "http://www.bestbuy.com/logo",
        "merchant_id": "639823",
        "url": "http://www.bestbuy.com/products/iphone_5s",
        "retail_price": "499.99",
        "price": "299.99",
        "cash_back_price":"290.99",
        "cash_back": "3%"
      },
      {
        "id": "34623-2345",
        "name": "Target",
        "logo_url": "http://www.target.com/logo",
        "merchant_id": "834793",
        "url": "http://www.target.com/products/iphone_5s",
        "retail_price": "439.99",
        "price": "289.99",
        "cash_back_price": "275.49",
        "cash_back": "5%"
      }
    ]
  }, 
  {
    "id": "83948",
    "name": "Kellogs Corn Flakes",
    "description": "The classic breakfast cereal from Kellogs",
    "image_url": "http://www.kellogs.com/store/images/corn_flakes",
    "merchant_count": "2",
    "price_min": "3.99",
    "price_max": "4.39",
    "favorite": false,
    "merchants": 
    [
      {
        "id": "83948-1234",
        "name": "Amazon",
        "logo_url": "http://www.amazon.com/logo",
        "merchant_id": "183729",
        "url": "http://www.amazon.com/products/kellogs_corn_flakes",
        "retail_price": "5.99",
        "price": "3.99",
        "cash_back_price": "3.99",
        "cash_back": "0%"
      },
      {
        "id": "83948-2345",
        "name": "Target",
        "logo_url": "http://www.target.com/logo",
        "merchant_id": "834793",
        "url": "http://www.target.com/products/kellogs_corn_flakes",
        "retail_price": "7.39",
        "price": "4.39",
        "cash_back_price":"4.17",
        "cash_back": "5%"
      }
    ]
  }
]

This endpoint retrieves a set of products corresponding to the id’s sent in. If any of the provided id’s are not found, records for those id’s will not be included in the response. This will be the only indication that an error has occurred.

Note that the :ids field in the request must be replaced by a comma-separated list of id values for products in the server system.

HTTP Request

GET https://api.netrbx.com/v3/products/:ids

Expected Response Code

200 - OK

Optional Parameters

None.

Favorite a product

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/products/23456/favorite"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint sets a product as a favorite for the current user.

Note that the :id field in the request must be replaced with the id value for the product in the server system.

HTTP Request

POST https://api.netrbx.com/v3/products/:id/favorite

Expected Response Code

204 - No Content

Possible Error Codes

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The product corresponding to the provided id was not found.

Parameters

None.

Unfavorite a product

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/products/23456/unfavorite"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -i

HTTP/1.1 204 No Content
Date: Mon, 07 Jul 2014 14:59:39 GMT
Status: 204 No Content

This endpoint unsets a produt as a favorite for the current user.

Note that the :id field in the request must be replaced with the id value for the product in the server system.

HTTP Request

POST https://api.netrbx.com/v3/products/:id/unfavorite

Expected Response Code

204 - No Content

Possible Error Codes

401 - Unauthorized: This endpoint is only available when a user has logged in.

404 - Not Found: The product corresponding to the provided id was not found.

Parameters

None.

Regions

List All Regions

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/regions"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"


[
  {
    "geohash": "87z9qp", 
    "bounding_box": {
      "top_left": {
        "lat": 21.3519287109375, 
        "lon": -157.939453125
      },
      "bottom_right": {
        "lat": 21.357421875, 
        "lon": -157.928466796875 
      }
    },
    "center": {
      "lat": 21.35467529296875, 
      "lon": -157.9339599609375
    }, 
    "radius": 645.9081458320728, 
    "place_count": 1
  }
]

This endpoint returns a list of regions containing one or more places. The list includes all regions within the given distance parameter from the location specified in the lat_lon parameter.

The distance and radius values returned are in meters.

HTTP Request

GET https://api.netrbx.com/v3/regions

Expected Response Code

200 - OK

Mandatory Parameters

Parameter	Type	Description
lat_lon	string	Comma-separated values for latitude and longitude for where to begin search.

Optional Parameters

Parameter	Type	Default	Description
distance	float	500	Radius in meters from given latitude and longitude to use for search.

Search Engines

List search engines

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/search_engines"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "uri": "search.yahoo.com",
    "uri_pattern": "search\\.yahoo\\.com\/search.*",
    "container_selector": "#web ol li",
    "link_selector": ".res h3 a",
    "link_pattern": "=(https?:\/\/.+?)\/\/"
  }
]

This endpoint returns a list of search engines recognized by the application.

HTTP Request

GET https://api.netrbx.com/v3/search_engines

Expected Response Code

200 - OK

Optional Parameters

None

Searches

Retrieve previous searches

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/searches"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 2341,
    "name": "iPhone 5s",
    "type": "products"
  },
  {
    "id": 4311,
    "name": "Target",
    "type": "merchants"
  }
]

This endpoint returns a list of previous searches performed by the current user.

HTTP Request

GET https://api.netrbx.com/v3/searches

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
type	string	“”	Type of search to filter can be one of (products, merchants, or offers).
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page.

NOTE: This endpoint requires the use of a user access_token

Settlements

Settlements are commmissions and referral bonuses earned from merchants either from purchase transactions or other merchant events. They are aggregated into payments based on their meeting thresholds for payment amount or wait period.

List settlements

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/settlements"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 4362,
    "tracking_id": "2v6558d43733d18feav2",
    "user_id": null,
    "custom_identifier": null,
    "custom_parent_identifier": null,
    "purchase_user_id": null,
    "purchase_custom_identifier": null,
    "purchase_custom_parent_identifier": null,
    "merchant_name": "Target",
    "purchase_date": "2014-03-02",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "",
    "payment_amount": 0.0,
    "payment_id": null,
    "disbursement_id": null,
    "status": "pending",
    "settlement_type":"commission",
    "created_at":"2014-03-07T20:26:49.893Z"
  },
  {
    "id": 5362,
    "tracking_id": "2v6558d43733d18feav2",
    "user_id": null,
    "custom_identifier": null,
    "custom_parent_identifier": null,
    "purchase_user_id": null,
    "purchase_custom_identifier": null,
    "purchase_custom_parent_identifier": null,
    "merchant_name": "Walmart",
    "purchase_date": "2014-03-12",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "2014-07-01",
    "payment_amount": 25.43,
    "payment_id": 231,
    "disbursement_id": 132,
    "status": "paid",
    "settlement_type":"referral",
    "created_at":"2014-03-12T20:26:49.893Z"
  },
  {
    "id": 4362,
    "tracking_id": "2v603913c2745bf7b7v2",
    "user_id": 234,
    "custom_identifier": 789,
    "custom_parent_identifier": 234,
    "purchase_user_id": 234,
    "purchase_custom_identifier": 789,
    "purchase_custom_parent_identifier": 234,
    "merchant_name": "Target",
    "purchase_date": "2014-03-02",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "",
    "payment_amount": 0.0,
    "payment_id": null,
    "disbursement_id": null,
    "status": "pending",
    "settlement_type":"commission",
    "created_at":"2014-03-03T20:26:49.893Z"
  },
  {
    "id": 5362,
    "tracking_id": "2vcf00206640b4417cv2",
    "user_id": 234,
    "custom_identifier": 789,
    "custom_parent_identifier": 234,
    "purchase_user_id": 234,
    "purchase_custom_identifier": 789,
    "purchase_custom_parent_identifier": 234,
    "merchant_name": "Walmart",
    "purchase_date": "2014-03-12",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "2014-07-01",
    "payment_amount": 25.43,
    "payment_id": 332,
    "disbursement_id": 112,
    "status": "paid",
    "settlement_type":"commission",
    "created_at":"2014-03-12T20:26:49.893Z"
  },
  {
    "id": 4362,
    "tracking_id": "2v95f8a20099a81369v2",
    "user_id": 2934,
    "custom_identifier": 7891,
    "custom_parent_identifier": 1234,
    "purchase_user_id": 2934,
    "purchase_custom_identifier": 7891,
    "purchase_custom_parent_identifier": 1234,
    "merchant_name": "Target",
    "purchase_date": "2014-03-02",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "",
    "payment_amount": 0.0,
    "payment_id": null,
    "disbursement_id": null,
    "status": "pending",
    "settlement_type":"commission",
    "created_at":"2014-03-02T20:26:49.893Z"
  },
  {
    "id": 5362,
    "tracking_id": "2vaa03565047a924eev2",
    "user_id": 2934,
    "custom_identifier": 7891,
    "custom_parent_identifier": 1234,
    "purchase_user_id": 1234,
    "purchase_custom_identifier": 3456,
    "purchase_custom_parent_identifier": 2345,
    "merchant_name": "Walmart",
    "purchase_date": "2014-03-12",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "2014-07-01",
    "payment_amount": 25.43,
    "payment_id": 521,
    "disbursement_id": 432,
    "status": "paid",
    "settlement_type":"referral",
    "created_at":"2014-03-12T20:26:49.893Z"
  }
]

This endpoint returns records for settlements for the current benefit program ending with the current date or the given end date. By default this endpoint retrieves the last 30 days of settlements. Otherwise it uses the given start date.

Possible values for the settlement_type field in the return data are commission and referral.

The status field is paid for settlements associated with a payment. Otherwise it is pending and the payment_date, payment_amount and payment_id fields are empty.

HTTP Request

GET https://api.netrbx.com/v3/settlements

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
benefit_program	string	“”	If true, returns only settlements for the benefit program. If false, returns only user settlements. By default returns all settlements.
user_ids	string	“”	Comma separated list of user ids for which to retrieve settlements. By default returns all settlements.
payment_ids	string	“”	Comma separated list of payment ids for which to retrieve settlements. Data will include only those settlements associated with the given payment ids. By default returns all settlements.
disbursement_ids	string	“”	Comma separated list of disbursement ids for which to retrieve settlements. Data will include only those settlements associated with the given disbursement ids. By default returns all settlements.
settlement_type	string	“”	Type of settlement (commission or referral). Defaults to all settlement types
purchase_start_date	string		Purchase date from which to begin including settlements. By default returns all settlements. See the Date Format page.
purchase_end_date	string		Purchase date up to which to include settlements. By default returns all settlements. See the Date Format page.
start_date	string		Created date from which to begin including settlements. By default returns all settlements. See the Date Format page.
end_date	string		Created date up to which to include settlements. By default returns all settlements. See the Date Format page.
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page.

NOTE: This endpoint requires the use of an admin access_token

Retrieve a set of settlements

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/settlements/1234,5678"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1234,
    "tracking_id": "2v6558d43733d18feav2",
    "user_id": null,
    "custom_identifier": null,
    "custom_parent_identifier": null,
    "purchase_user_id": null,
    "purchase_custom_identifier": null,
    "purchase_custom_parent_identifier": null,
    "merchant_name": "Target",
    "purchase_date": "2014-03-02",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "",
    "payment_amount": 0.0,
    "payment_id": null,
    "status": "pending",
    "settlement_type":"commission",
    "created_at":"2014-03-02T20:26:49.893Z"
  },
  {
    "id": 5678,
    "tracking_id": "2v6558d43733d18feav2",
    "user_id": "123",
    "custom_identifier": 7891,
    "custom_parent_identifier": 1234,
    "purchase_user_id": 123,
    "purchase_custom_identifier": 7891,
    "purchase_custom_parent_identifier": 1234,
    "merchant_name": "Walmart",
    "purchase_date": "2014-03-12",
    "cashback_amount": 2.34,
    "purchase_amount": 453.98,
    "available_date": "2014-06-21",
    "payment_date": "2014-07-01",
    "payment_amount": 25.43,
    "payment_id": 231,
    "disbursement_id": 132,
    "status": "paid",
    "settlement_type":"referral",
    "created_at":"2014-03-12T20:26:49.893Z"
  }
]

This endpoint retrieves a set of settlements corresponding to the id’s sent in. If any of the provided id’s are not found, records for those id’s will not be included in the response. This will be the only indication that an error has occurred.

Note that the :ids field in the request must be replaced by a comma-separated list of id values for settlements in the server system.

HTTP Request

GET https://api.netrbx.com/v3/settlements/:ids

Expected Response Code

200 - OK

Optional Parameters

None.

NOTE: This endpoint requires the use of an admin access_token

Updates

List available updates

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/updates"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -d "last_updated=2014-07-06T23:22:00Z"

{
  "merchants_categories":  "http://s3.amazon.com/benefit_program_merchants_categories.sqlite3",
  "cache_file_timestamp": "2014-09-26 01:26",
  "contact_email": "support@retailbenefits.com",
  "contact_phone": "800-555-1212",
  "privacy_url": "https://demo.netrbx.com/privacy",
  "terms_conditions_url": "https://demo.netrbx.com/terms_conditions",
  "refer_conditions_url": "https://demo.netrbx.com/refer_conditions",
  "geolocation":
  {
    "place_radius": 50,
    "region_radius": 3218,
    "search_radius": 500,
    "min_distance_between_notifications": 500,
    "min_time_between_notifications": 900
  }
}

This endpoint retrieves urls and data including an update file for cached merchants and categories, terms and conditions, privacy statement, a contact email, and geolocation parameters .

For the last_updated parameter, please note the date format as described in the introduction. URL in the response for merchants and categories will refer to a complete set of data if the last_updated parameter is more than a day old, or a set of updates otherwise.

If the last_updated parameter is not provided, the URL in the response will refer to a complete set of data.

The cache file will contain three tables: One for merchant data, one for merchant category data, and a join table matching these.

Also note that the country_codes field in the merchant record is a comma-separated list of country codes.

The cache_file_timestamp field is the timestamp (UTC) of the file referred to by the merchants_categories field.

For the geolocation parameters, distance values for search_radius and min_distance_between_notifications are in meters (6.21x10^-4 miles). The time value for min_time_between_notifications is in seconds.

HTTP Request

GET https://api.netrbx.com/v3/updates

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Description
last_updated	datetime	Date and time of last retrieval of updates.

Users

Users endpoint is to to be used for bulk access by benefit program integrations, except in the instance of creating users. All client side implementations that wish to update the current user should make use of the /account endpoint.

List Users

# Make sure to replace `ACCESS_TOKEN` with your admin access_token.
curl "https://api.netrbx.com/v3/users"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1,
    "email": "user@example.com",
    "first_name":"Pat",
    "last_name":"Shopper",
    "country_code": "US",
    "referral_code": "username",
    "referral_url": "https://example.com/username",
    "custom_identifier": "789",
    "custom_parent_identifier": "234",
    "custom_referrer_identifier": "456",
    "custom_role": "member",
    "weekly_deals":true,
    "shopping_reminder":true,
    "monthly_balance":true,
    "monthly_payment":false,
    "rewards_problem":true,
    "subscription_level":"annual",
    "active":true,
    "last_sign_in_date":"2015-05-29T20:26:49.893Z",
    "last_request_date":"2015-05-29T20:26:49.893Z",
    "ios_installation_date":"2015-05-29T20:26:49.893Z",
    "android_installation_date":"",
    "toolbar_installation_date":"",
    "created_at":"2015-05-29T20:26:49.893Z",
    "cashback":
    {
      "total": 323.45,
      "pending": 23.21,
      "paid": 300.24,
      "next_payment_date": "2014-12-12",
      "next_payment_amount": 17.34
    }
  }
]

This endpoint retrieves a list of user account information. It returns all users when no parameters provided.

HTTP Request

GET https://api.netrbx.com/v3/users

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
custom_identifiers	string	“”	Comma-separated list of users for whom are included in the list.
custom_role	string	“”	Name of role of users whose records are to be returned.
email	string	“”	Email address of user whose record is to be returned
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page

NOTE: This endpoint requires the use of an admin access_token

Show User

# Make sure to replace `ACCESS_TOKEN` with your admin access_token.
curl "https://api.netrbx.com/v3/users/23456"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1,
    "email": "user@example.com",
    "first_name":"Pat",
    "last_name":"Shopper",
    "country_code": "US",
    "referral_code": "username",
    "referral_url": "https://example.com/username",
    "custom_identifier": "789",
    "custom_parent_identifier": "234",
    "custom_referrer_identifier": "456",
    "custom_role": "member",
    "weekly_deals":true,
    "shopping_reminder":true,
    "monthly_balance":true,
    "monthly_payment":false,
    "rewards_problem":true,
    "subscription_level":"annual",
    "active":true,
    "last_sign_in_date":"2015-05-29T20:26:49.893Z",
    "last_request_date":"2015-05-29T20:26:49.893Z",
    "ios_installation_date":"2015-05-29T20:26:49.893Z",
    "android_installation_date":"",
    "toolbar_installation_date":"",
    "created_at":"2015-05-29T20:26:49.893Z",
    "cashback":
    {
      "total": 323.45,
      "pending": 23.21,
      "paid": 300.24,
      "next_payment_date": "2014-12-12",
      "next_payment_amount": 17.34
    }
  }
]

This endpoint retrieves account information for the user with specified id.

Note that the :id field in the request must be replaced with the id value for the user in the server system.

HTTP Request

GET https://api.netrbx.com/v3/users/:id

Expected Response Code

200 - OK

Parameters

None

NOTE: This endpoint requires the use of an admin access_token

Update User

# Make sure to replace `ACCESS_TOKEN` with your admin access_token.
curl "https://api.netrbx.com/v3/users/23456"
  -X PUT \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1,
    "email": "abc@def.com",
    "first_name":"Pat",
    "last_name":"Shopper",
    "country_code": "US",
    "referral_code": "username",
    "referral_url": "https://example.com/username",
    "custom_identifier": "789",
    "custom_parent_identifier": "234",
    "custom_referrer_identifier": "456",
    "custom_role": "member",
    "weekly_deals":true,
    "shopping_reminder":true,
    "monthly_balance":true,
    "monthly_payment":false,
    "rewards_problem":true,
    "subscription_level":"annual",
    "active":true,
    "last_sign_in_date":"2015-05-29T20:26:49.893Z",
    "last_request_date":"2015-05-29T20:26:49.893Z",
    "ios_installation_date":"2015-05-29T20:26:49.893Z",
    "android_installation_date":"",
    "toolbar_installation_date":"",
    "created_at":"2015-05-29T20:26:49.893Z",
    "cashback":
    {
      "total": 323.45,
      "pending": 23.21,
      "paid": 300.24,
      "next_payment_date": "2014-12-12",
      "next_payment_amount": 17.34
    }
  }
]

This endpoint is used to update profile information for the current user.

The response will include all fields in the user profile, other than the password, including those updated by the call to this endpoint.

If a value other than true or false is provided for any of the email preferences (e.g. weekly_deals), that field will remain unchanged.

If a value other than “not_subscribed”, “monthly” or “annual” is provided for the subscription_level parameter, that field will remain unchanged.

The active parameter sets whether the user is considered to be active in the system. Note that there is no delete action for this endpoint.

Note that the :id field in the request must be replaced with the id value for the user in the server system.

HTTP Request

PUT https://api.netrbx.com/v3/users/:id

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
email	string	“”	User’s contact email address
first_name	string	“”	User’s first name
last_name	string	“”	User’s last name
password	string	“”	Password for the user.
country_code	string	“”	User’s primary country.
referral_code	string	“”	Code to be used when this user refers another and as url stub (http://example.com/u/).
referrer	string	“”	Referral code given to this user by another user.
custom_identifier	string	“”	Unique identifier for this user (usually your primary key).
custom_parent_identifier	string	“”	Identifier of parent record (usually your foreign key).
custom_referrer_identifier	string	“”	Identifier of user referring this user (must match custom_identifier).
custom_role	string	“”	Role of this user (mostly used for affiliate management).
weekly_deals	boolean	true	Whether to receive emails for weekly deals.
shopping_reminder	boolean	true	Whether to receive emails for shopping reminders
monthly_balance	boolean	true	Whether to receive emails for monthly balance.
monthly_payment	boolean	true	Whether to receive emails for monthly payments.
rewards_problem	boolean	true	Whether to receive emails for problems with their rewards.
subscription_level	string	“not_subscribed”	Possible values are “not_subscribed”, “monthly” and “annual”
active	boolean	true	Whether the user is active in the system
reset_password_on_login	boolean	false	Whether to notify user to reset their password on their next sign in.

NOTE: This endpoint requires the use of an admin access_token

Create a user

# Make sure to replace `ACCESS_TOKEN` with your admin access_token.
curl "https://api.netrbx.com/v3/users"
  -X POST \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -d email=user@example.com \
  -d password=P455w0rd!

[
  {
    "id": 1,
    "email": "user@example.com",
    "first_name":"Pat",
    "last_name":"Shopper",
    "country_code": "US",
    "referral_code": "username",
    "referral_url": "https://example.com/username",
    "custom_identifier": "789",
    "custom_parent_identifier": "234",
    "custom_referrer_identifier": "456",
    "custom_role": "member",
    "weekly_deals":true,
    "shopping_reminder":true,
    "monthly_balance":true,
    "monthly_payment":true,
    "rewards_problem":true,
    "subscription_level":"annual",
    "active":true,
    "last_sign_in_date":"",
    "last_request_date":"",
    "ios_installation_date":"",
    "android_installation_date":"",
    "toolbar_installation_date":"",
    "created_at":"2015-05-29T20:26:49.893Z",
    "cashback":
    {
      "total": 0,
      "pending": 0,
      "paid": 0,
      "next_payment_date": "",
      "next_payment_amount": 0,
    }
  }
]

This endpoint is used for creating a new user. On success, the response contains the id and email for the newly created user. On failure, the endpoint returns a description of the error.

If a value other than true or false is provided for any of the email preferences (e.g. weekly_deals), that field will remain unchanged.

If a value other than “not_subscribed”, “monthly” or “annual” is provided for the subscription_level parameter, that field will remain unchanged.

The welcome_email parameter determines whether a welcome email is sent to the newly created user. The value true means that an email will be sent; false means it is not sent. If the parameter is either left empty or not included, then the setting from the current benefit program is used to decide whether to send the welcome email.

HTTP Request

POST https://api.netrbx.com/v3/users

Expected Response Code

201 - Created

Possible Error Code

422 - Unprocessable Entity: Email or password fields are blank, or another user with the same email is already in the system.

Required Parameters

Parameter	Type	Description
email	string	User’s contact email address
password	string	Password for the user.

Optional Parameters

Parameter	Type	Default	Description
first_name	string	“”	User’s first name
last_name	string	“”	User’s last name
country_code	string	“”	User’s primary country
referral_code	string	“”	Code to be used when this user refers another and as url stub (http://example.com/u/).
referrer	string	“”	Referral code given to this user by another.
custom_identifier	string	“”	Unique identifier for this user (usually your primary key).
custom_parent_identifier	string	“”	Identifier of parent record (usually your foreign key).
custom_referrer_identifier	string	“”	Identifier of user referring this user (must match custom_identifier).
custom_role	string	“”	Role of this user (mostly used for affiliate management).
weekly_deals	boolean	true	Whether to receive emails for weekly deals.
shopping_reminder	boolean	true	Whether to receive emails for shopping reminders
monthly_balance	boolean	true	Whether to receive emails for monthly balance.
monthly_payment	boolean	true	Whether to receive emails for monthly payments.
rewards_problem	boolean	true	Whether to receive emails for problems with their rewards.
subscription_level	string	“not_subscribed”	Possible values are “not_subscribed”, “monthly” and “annual”
welcome_email	boolean	true	Whether to send a welcome email after the user is created. Default is what is set on the benefit program.
reset_password_on_login	boolean	false	Whether to notify user to reset their password on their next sign in.

List referrals

# Make sure to replace `ACCESS_TOKEN` with your user access_token.
curl "https://api.netrbx.com/v3/users/23456/referrals"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1,
    "email": "user@example.com",
    "accepted_date": "2014-06-21"
  },
  {
    "id": 2,
    "email": "user2@example.com",
    "accepted_date": "2014-09-10"
  }
]

This endpoint retrieves all referrals for the specified user.

Note that the :id field in the request must be replaced with the id value for the user in the server system.

HTTP Request

GET https://api.netrbx.com/v3/users/:id/referrals

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
page	integer	1	Page number of results to retrieve.
per_page	integer	25	Number of results to return per page

NOTE: This endpoint requires the use of a user access_token

Generate a User SSO Token

# Make sure to replace `ACCESS_TOKEN` with your admin access_token.
curl "https://api.netrbx.com/v3/users/23456/sso_token"
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

{
  "id": 23456,
  "access_token": "1cb2d5226e3ffba32372ff7923504e9c6e9192be48fb6252fc44519d0f7e78a8"
  "expires_in" : 7200,
}

This endpoint generates an SSO token for use with the Single Sign-On Endpoint for the Retail Benefits website. This allows external websites to link to their Retail Benefits site and sign in a user without the user having to provide additional credentials.

Note that the :id field in the request must be replaced with the id value for the user in the server system. The id field in the response will match that of the field in the request if the query succeeds.

The expires_in field in the response is the number of seconds before the returned token expires.

Note also that the Single Sign-On endpoint is not part of the API. It will be of the form https://<subdomain>.<domain>.com/sso/:sso_token?redirect_url=:redirect_url. If the request format is html, the user corresponding to the token will be logged in and redirected to their root page. If the token passed in does not correspond to a user in the system, or if the token has expired, the user will be directed to the sign in page.

HTTP Request

GET https://api.netrbx.com/v3/users/:id/sso_token

Expected Response Code

200 - OK

Possible Error Code

404 - Not Found: A user corresponding to the given id was not found in the database.

NOTE: This endpoint requires the use of an admin access_token

Help

List FAQ’s

Returns a list of FAQ’s.

HTTP Request

GET https://api.netrbx.com/v3/faq

Expected Response Code

200 - OK

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/help/faq" \
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1234,
    "topic": {
      "name": "Getting Started",
      "id": 1234
    },
    "title": "The title for this FAQ.",
    "body": "The body for this FAQ."
  }
]

List topics

Returns a list of help topics.

HTTP Request

GET https://api.netrbx.com/v3/topics

Expected Response Code

200 - OK

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/help/topics" \
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "id": 1234,
    "name": "Getting Started",
  },
]

List articles

Retuns a list of help articles.

HTTP Request

GET https://api.netrbx.com/v3/articles

Expected Response Code

200 - OK

Optional Parameters

Parameter	Type	Default	Description
q	String	None	Query for articles
topic_id	Integer	None	The help topic to filter for.
article_type	String	None	Filter for article by type one of “guide” or “faq”.

# Make sure to replace `ACCESS_TOKEN` with your access_token.
curl "https://api.netrbx.com/v3/help/articles" \
  -X GET \
  -H "Authorization:Bearer ACCESS_TOKEN"

[
  {
    "article_type": "guide",
    "id": 1234,
    "topic": {
      "name": "The help topic name.",
      "id": 493536493
    },
    "title": "The article title.",
    "body": "The article body."
  },
]

Introduction

Versioning

Rate Limiting

Pagination

Errors & Status Codes

Success Codes

Error Codes

Date Format

Authentication

Scopes

Admin Authentication

HTTP Request

Expected Response Code

Required Parameters

User Authentication with credentials

HTTP Request

Expected Response Code

Required Parameters

User Authentication with Facebook

HTTP Request

Expected Response Code

Required Parameters

User Authentication with Google+

HTTP Request

Expected Response Code

Required Parameters

User Authentication with a single sign on token

HTTP Request

Expected Response Code

Required Parameters

Refreshing an access_token

HTTP Request

Expected Response Code

Required Parameters

Account

Show Account

HTTP Request

Expected Response Code

Parameters

Update Account

HTTP Request

Expected Response Code

Optional Parameters

Activity

List all Activity

HTTP Request

Expected Response Code

Optional Parameters

Cashback

List all Cashback

HTTP Request

Expected Response Code

Optional Parameters

Categories

Get Categories

HTTP Request

Expected Response Code

Optional Parameters

Custom Offers

List custom offers

Optional Parameters

HTTP Request

Expected Response Code

Link for custom offer

HTTP Request

Expected Response Code

Disbursements

List disbursements

HTTP Request

Expected Response Code

Optional Parameters

Retrieve a set of disbursements

HTTP Request

Expected Response Code

Optional Parameters

Process a disbursement

HTTP Request

Expected Response Code

Possible Error Code

Parameters