Home
About us
Apply now

Introduction

Welcome to the Rulrr Developer's Documentation and API Reference.

Before you begin

If you haven't already, submit your application form to become an official Rulrr Integrated Partner and start offering your customers the benefits of automated digital advertising. Applications will be reviewed within up to 7 business days, in case they're approved you'll receive a unique client ID and client secret, that will be needed to successfully create any type of request.

The Rulrr API enables the integration of various Point of Sale (POS) systems with Rulrr's automated marketing engine. By connecting their POS to Rulrr, store owners can create targeted ad campaigns for their specific customer base and measure the effectiveness of these campaigns.

The user experience

The user journey process involves the following steps:

  1. The user initiates the integration process in the Rulrr app by selecting a client application that integrates with the Rulrr oAuth flow. (Create Campaign > POS Integration) 

  2. The application will present instructions to perform on the client application side.

  3. The user follows up on the instructions and initiates the Rulrr-Connect feature on their client application.

The OAuth flow

The integration process involves the following steps:

  1. POS requests the Integration Token passing the client ID and client secret (provided by Rulrr) in params. Rulrr creates an integration entity in the database with this token and status “pending”, and returns an access token to the POS

  2. POS sends a periodic request checking the integration status, passing client ID, client Secret and Integration Token in params. Waits for status `finished` in order to fetch access token.

  3. POS displays an IFrame with the website connect.rulrr.com. It must contain:

    • integration_token passed as a parameter

    • client_id passed as a parameter

  4. The user completes the account verification and integration preferences form on the IFrame and when completed, the Integration Status should change to ‘finished’.

  5. POS detects a status change (via periodic fetch) and sends a request to retrieve created access and refresh tokens. This endpoint will return tokens only once!

  6. The client application then has access to the following endpoints, Update store profile, Send customers list and Send single order.

Click here to view the documentation of the OAuth Endpoints (Rulrr Connect).

Requirements and limitations

  • Authorization codes returned by the authorization URL web page expire after 15 minutes. An authorization code can only be used once.

  • Access tokens expire after 365 days. To maintain access, you must generate a new access token using the refresh token received with the original authorization. 

  • Refresh tokens obtained using the code flow do not expire. If you lose a refresh token, you must repeat the full authorization flow to obtain a new access token and refresh token. A refresh token only becomes invalid when the client application's access has been completely revoked.