OAuth Integration

The Rulrr OAuth API lets an integration partner connect a merchant's system to Rulrr so that the merchant can run automated, targeted advertising and measure its impact on real sales.

A partner is most commonly a Point-of-Sale (POS) system, but the same flow applies to any source of customer and transaction data — reservation systems, delivery platforms, e-commerce backends, or a Customer Data Platform (CDP). Throughout this guide we say "partner" to mean any such system; POS is simply the most common case today.

What the integration enables

Once a merchant connects a partner to their Rulrr account, the partner can:

• Keep the store profile in sync — name, address, currency and contact details.
• Send the customer list — so Rulrr can build targeted and look-alike audiences for campaigns.
• Send orders (transactions) — so Rulrr can measure conversions and attribute revenue to campaigns.
• *(Optional)* offer e-receipts by SMS at the point of sale.

How it works at a glance

The integration is a server-to-server OAuth-style handshake combined with a short, hosted consent screen the merchant completes in their browser:

1. The partner's backend asks Rulrr for an integration token using its client_id / client_secret.
2. The partner sends the merchant to connect.rulrr.com, passing that integration token.
3. The merchant signs in, chooses which Rulrr profile/store to connect, and confirms.
4. The partner exchanges the (now *finished*) integration token for an access token and refresh token.
5. The partner calls the Integration Endpoints with the access token.

The next sections walk through each step with exact endpoints, parameters and responses.

Becoming a partner

Integration credentials are issued by Rulrr. To become an official Rulrr Integrated Partner, submit the partner application; once approved you receive a unique client_id and client_secret, required to create any request in this flow. If you already operate your own OAuth server and want a deeper, bi-directional integration, contact us through Developer Support.

Base URL. All endpoints below are served under the API base path /v1 (for example POST /v1/auth/integration). Use the environment base URL provided to you with your credentials.

The end-to-end connection has four server-side calls around one hosted consent screen. All parameters in this flow are passed as query parameters.

Partner backend            Rulrr                         Merchant browser
     │                       │                                  │
  1. │── POST /v1/auth/integration ─────────▶│  create token (status: pending)
     │◀────────────── { integrationToken } ──│
     │                       │                                  │
  2. │── redirect merchant ─────────────────────────────────▶  connect.rulrr.com
     │                       │                            sign in, pick profile, confirm
     │                       │◀── connectLegacyPos ──────────── (status: finished)
     │                       │                                  │
  3. │── GET /v1/auth/integration (poll) ───▶│  status: pending | finished | cancelled
     │◀──────────────────── { status } ──────│
     │                       │                                  │
  4. │── GET /v1/auth/integration/token ────▶│  one-time issue of access + refresh tokens
     │◀── { accessToken, refreshToken, expiration } ─────────────────────────┘

Step 1 — Create the integration token

Identifies the partner and starts a pending integration.

POST /v1/auth/integration?client_id={client_id}&client_secret={client_secret}

Response 200

{ "integrationToken": "a1b2c3…" }

The token is created with status pending and expires after 1 hour.

Errors: 403 invalid client_id/client_secret, 400 malformed request.

Step 2 — Send the merchant to Rulrr-Connect

Open the hosted consent screen in a browser/IFrame, passing the integration token and your client id:

https://connect.rulrr.com/?client_id={client_id}&integration_token={integrationToken}

The merchant signs in, chooses the Rulrr profile (and, when relevant, a specific store) to connect, sets their preferences, and confirms. On confirmation, Rulrr marks the integration finished. See The Rulrr-Connect screen for what the merchant sees.

Step 3 — Check the integration status

Poll until the status becomes finished (the merchant has confirmed) — or stops being pending.

GET /v1/auth/integration?client_id={client_id}&client_secret={client_secret}&integration_token={integrationToken}

Response 200

{ "status": "pending" }   // → "finished" once confirmed, or "cancelled" if expired/declined

Errors: 403 invalid credentials, 404 unknown integration_token.

Step 4 — Exchange for access & refresh tokens

Call only when status is finished. This returns the tokens once — store them securely.

GET /v1/auth/integration/token?client_id={client_id}&client_secret={client_secret}&integration_token={integrationToken}

Response 200

{
  "accessToken": "…",
  "refreshToken": "…",
  "expiration": "2027-06-28T12:00:00.000Z"
}

Errors: 400 integration not finished / missing target, 403 invalid credentials, 404 unknown integration_token, 410 token already exchanged (tokens are returned only once).

The partner is now connected and can call the Integration Endpoints with the access token. See Tokens & lifecycle for expiry and refresh.

connect.rulrr.com is Rulrr's hosted consent experience. It is where the merchant authorises the connection — the partner never handles Rulrr credentials. Open it in a browser window or an embedded IFrame, passing the two required parameters from Step 2.

https://connect.rulrr.com/?client_id={client_id}&integration_token={integration_token}

Both parameters are required and validated on load; an invalid or expired link shows an error state.

What the merchant does

1. Sign in. The merchant logs in with their Rulrr account (email + password). Authentication is

handled by Rulrr — the partner never sees these credentials.

1. Choose where to connect. The merchant selects either:
2. an existing profile (a new store is created under it for this integration), or
3. an existing store that was added manually (it is updated to use this integration).
4. Set preferences. If the integration supports it, the merchant can enable e-receipts

(SMS receipts at checkout). This option only appears when the integration is configured for it.

1. Confirm. Confirming finalises the connection. Rulrr sets the integration status to

finished, recording the chosen profile/store and preferences against the integration token.

After confirmation the merchant sees a success screen and can return to the partner application. The partner detects the change by polling Step 3 and then performs the token exchange.

Notes for partners

• The consent screen is the only place the merchant authenticates — keep your redirect/IFrame

pointed at connect.rulrr.com and never collect Rulrr passwords yourself.

• Pass the same integration_token you created in Step 1; it ties the consent to your pending

integration and is single-use.

• If the merchant abandons the screen or the 1-hour token window lapses, the integration becomes

cancelled — create a fresh integration token and start again.

The flow involves three credentials: the short-lived integration token, and the long-lived access token + refresh token issued at the end.

Integration token

• Created by POST /v1/auth/integration.
• Carries a status: pending → finished (merchant confirmed) or cancelled (expired/declined).
• Expires 1 hour after creation. An expired token is treated as cancelled.
• Single-use for exchange: once exchanged for access/refresh tokens it cannot be exchanged again

(a second attempt returns 410).

Access token

• Returned by GET /v1/auth/integration/token.
• Valid for 1 year.
• Sent on every Partner Endpoint request (as the access_token query

parameter).

Refresh token

• Returned alongside the access token, once.
• Does not expire on its own — it only becomes invalid if the integration's access is revoked.
• Use it to mint a new access token before (or after) the current one expires.

Refreshing the access token

POST /v1/auth/token?client_id={client_id}&client_secret={client_secret}&code={refreshToken}&grant_type=refresh_token

Response 200

{ "accessToken": "…", "expiration": "2027-06-29T12:00:00.000Z" }

Errors: 400 wrong/absent grant_type, 403 invalid credentials or unknown refresh token.

Lifecycle summary

Lost your refresh token? Because it is returned only once, if you lose both tokens you must run the full authorisation flow again to reconnect.

A quick reference for the constraints that govern the integration flow.

Credentials

• Every request in the OAuth flow requires your client_id and client_secret, issued by

Rulrr on partner approval. Keep the secret server-side; never embed it in client apps.

Timeouts & lifetimes

Status values

The integration token moves through exactly these states:

• pending — created; waiting for the merchant to confirm on connect.rulrr.com.
• finished — merchant confirmed; ready to exchange for access/refresh tokens.
• cancelled — expired (past the 1-hour window) or declined.

Operational guidance

• Poll, don't hammer. Check the integration status on a sensible interval (e.g. every few

seconds) while the merchant completes the consent screen, and stop once it is finished or cancelled.

• Store tokens securely. The access and refresh tokens grant write access to the connected

store's profile, customers and orders. Treat them like passwords.

• Handle expiry proactively. Refresh the access token before it lapses using the refresh token;

there is no downtime if you refresh ahead of the 1-year expiry.

• Re-authorise on revocation. If access is revoked, the refresh token stops working — start the

full flow again.

Getting help

For partner onboarding, custom OAuth-to-OAuth integrations, or anything not covered here, reach Developer Support and leave your details — our integrations team will follow up.