Integration Endpoints

A POS is connected to a Rulrr store with a short, one-time 6-digit pairing code. There is no client-secret exchange: the merchant reserves a code in the Rulrr app, your terminal redeems it once, and you receive a durable access token for that store.

The flow

1. The merchant picks your POS in the Rulrr app. This reserves a 6-digit code bound to their store, sets the store's POS type to your integration, and holds the reservation for 72 hours.
2. The merchant reads the code to your terminal (typed in at setup).
3. Your terminal redeems the code once with POST /v1/auth/integration/pair.
4. You store the returned access token and use it as Authorization: Bearer {accessToken} on every Integration Endpoint (see Authenticating requests).

Redeem the code promptly. It is valid for 72 hours from reservation and can only be redeemed while it is still reserved.

Redeem the pairing code

POST /v1/auth/integration/pair
Host: rest.rulrr.com
Content-Type: application/json

{ "code": 428913 }

code is the 6-digit number the merchant read to you (sent as a JSON number).

Response 200

{
  "access_token": "…",
  "storeId": "…",
  "posType": "your-pos"
}

Errors

Redeem once. After a successful pair the code is consumed. Persist the access_token securely on the terminal; if you ever lose it or the store is unpaired, the merchant reserves a new code and you pair again to receive a fresh token.

Once a store has been paired to your POS (see Onboarding & pairing), you hold a durable access token scoped to that single connected store. Every Integration Endpoint is authorised with that token.

Base URL

All endpoints are served from:

https://rest.rulrr.com

under the /v1 base path. The /v1 prefix is required; a path sent without it returns 403.

How to authenticate

Send the access token in the Authorization header as a Bearer token:

POST /v1/orders
Host: rest.rulrr.com
Authorization: Bearer {accessToken}
Content-Type: application/json

The access token identifies the connected store; you do not send any client id or secret on these data endpoints. Keep the token in the header, never in the URL.

Legacy fallback. Older partners may still pass the token as an ?access_token={accessToken} query parameter. It stays accepted for backward compatibility, but new integrations should use the Authorization: Bearer header and keep the token out of the URL.

Token validity

• Access tokens are durable: they do not expire on a fixed schedule and stay valid while the store connection is active.
• A missing, malformed, or revoked token returns 403 (see Errors).
• If a store is unpaired and paired again, a new access token is issued; discard the old one.

What the token can do

An access token grants the connected store the ability to:

Each is documented in the following sections. All endpoints are served under https://rest.rulrr.com/v1.

Conventions

• Money is expressed in the minor unit of the currency (e.g. agorot for ILS, cents for USD) as a string, together with an ISO currency code (e.g. "ILS", "USD"). 2400 in ILS is 24.00 shekels.
• Timestamps are ISO-8601 and should carry an explicit timezone offset (e.g. 2026-06-28T14:03:00+03:00).
• Content type for request bodies is application/json.

Create or update the profile of the connected store — its name, address, contact details and currency. Keeping this current improves ad localisation and receipt accuracy.

PUT /v1/stores?access_token={accessToken}
Content-Type: application/json

Request body

{
  "storeName": "Bridge Street Bakery",
  "storeAddress": "120 Bridge Street",
  "storeCity": "Austin",
  "storeState": "TX",
  "storeCountryCode": "US",
  "storePostalCode": "78701",
  "storePhoneNumber": "+1-512-555-0142",
  "storeCurrency": "USD"
}

Response 200

{
  "store": {
    "id": "…",
    "name": "Bridge Street Bakery",
    "phoneNumber": "+1-512-555-0142",
    "address": {
      "addressLine": "120 Bridge Street",
      "city": "Austin",
      "state": "TX",
      "country": "US",
      "postalCode": "78701"
    },
    "currency": "USD"
  }
}

Errors

See Errors for the shared error model.

Send the store's customer list so Rulrr can build targeted and look-alike audiences for campaigns. This is the foundation of initial targeting: the better the customer data, the stronger the audiences Rulrr can create on the ad networks.

Because customer lists can be large, the upload is a two-step, pre-signed URL process — you never post the list to the API directly.

Step 1 — Request an upload URL

GET /v1/customers?access_token={accessToken}

Response 200

{ "uploadUrl": "https://…s3…/customers/…?X-Amz-Signature=…" }

The uploadUrl is a short-lived, pre-signed URL that accepts a single file upload.

Step 2 — Upload the customers file

PUT the customer records as JSON to the uploadUrl returned above. Each record should contain whatever identifiers you have; email and phone are the most valuable for matching.

[
  {
    "firstName": "Dana",
    "lastName": "Levy",
    "email": "dana@example.com",
    "phoneNumber": "+15125550101",
    "city": "Austin",
    "countryCode": "US"
  },
  {
    "firstName": "Sam",
    "lastName": "Cohen",
    "email": "sam@example.com",
    "phoneNumber": "+15125550102"
  }
]

Rulrr ingests the file, de-duplicates customers (by email, falling back to phone), and uses the result to seed audiences. Re-send the list periodically to keep audiences fresh; ingestion is idempotent, so re-uploading the same customers will not create duplicates.

Field guidance

Errors

Privacy. Only send customer data you are permitted to share for advertising. Rulrr uses it to create and measure audiences on the merchant's behalf.

Send each completed order (transaction) so Rulrr can measure conversions and attribute revenue to campaigns. This is how the merchant sees real sales impact, and how Rulrr distinguishes new vs. returning customers. A closed order with a customer phone number also drives the e-receipt.

POST /v1/orders
Host: rest.rulrr.com
Authorization: Bearer {accessToken}
Content-Type: application/json

Request body

{
  "orderId": "POS-10293",
  "orderPrice": "4200",
  "orderCurrency": "USD",
  "createdAt": "2026-06-28T14:03:00-05:00",
  "customerFirstName": "Dana",
  "customerLastName": "Levy",
  "customerPhoneNumber": "+15125550101",
  "customerEmail": "dana@example.com",
  "orderDetails": {
    "orderStatus": "CLOSED",
    "orderType": "dine-in",
    "orderItems": [
      { "itemId": "SKU-1", "itemName": "Sourdough", "itemPrice": "1200", "itemQuantity": 2, "itemTax": "0" }
    ],
    "orderPayments": [
      { "paymentType": "card", "paymentId": "pay_1", "paymentSum": "4200", "paymentCardType": "visa", "paymentLast4": "4242" }
    ]
  }
}

Example: a parking session

Rulrr treats a parking session as an order like any other. Put the plate, entry/exit times, duration and tariff in orderDetails (it is pass-through, so vendor-specific keys are kept), price the session in the currency's minor unit, and set orderStatus to CLOSED when the driver has paid on exit. Include the phone number to issue the e-receipt.

{
  "orderId": "PARK-558120",
  "orderPrice": "2400",
  "orderCurrency": "ILS",
  "createdAt": "2026-06-28T16:45:00+03:00",
  "customerPhoneNumber": "+972521234567",
  "orderDetails": {
    "orderStatus": "CLOSED",
    "orderType": "parking",
    "orderItems": [
      {
        "itemId": "PARK",
        "itemName": "Parking, bay B-42",
        "itemPrice": "2400",
        "itemQuantity": 1,
        "itemTax": "0",
        "plate": "12-345-67",
        "entryTime": "2026-06-28T14:05:00+03:00",
        "exitTime": "2026-06-28T16:45:00+03:00",
        "durationMinutes": 160,
        "tariff": "Standard daytime"
      }
    ],
    "orderPayments": [
      { "paymentType": "card", "paymentId": "pay_88213", "paymentSum": "2400", "paymentCardType": "visa", "paymentLast4": "4242" }
    ]
  }
}

Here orderPrice "2400" in ILS is 24.00 shekels for a 160-minute stay (14:05 to 16:45, +03:00). The driver receives an SMS receipt at https://share.rulrr.com/inv/PARK-558120.

What Rulrr does with an order

1. Resolves the customer from the provided name/email/phone (creating or updating the consumer record), so the order is tied to a person.
2. Records the order against the store, classifying the conversion as new, returning, organic, or anonymous. This powers conversion stats and revenue attribution.
3. Issues an e-receipt by SMS when the store's receipts flag is on and the order is CLOSED with a customer phone number (see E-receipts).

Response 200

{ "statusCode": 200 }

Errors

Send orders continuously. Streaming every closed transaction (not just a daily batch) gives the most accurate, near-real-time conversion measurement, and issues each e-receipt at the moment of sale.

Rulrr can send the customer a hosted e-receipt by SMS at checkout. E-receipts delight customers and strengthen the merchant's customer and consent data. This section covers reading the store's settings and how the receipt is issued and viewed.

Read store settings

Check whether e-receipts are enabled for the connected store.

GET /v1/stores
Host: rest.rulrr.com
Authorization: Bearer {accessToken}

Response 200

{ "greenInvoices": true }

greenInvoices is the store's receipts flag. It is a per-store enablement the merchant turns on during onboarding. When true, the integration should offer the e-receipt step at the point of sale (prompt for the customer's phone number). When false, no e-receipt is issued no matter what you send.

How e-receipts are issued

An e-receipt is issued automatically by Rulrr when all of the following hold for an order sent via POST /v1/orders:

• the store has its receipts flag on (greenInvoices: true), and
• the order's orderDetails.orderStatus is CLOSED, and
• the order includes a customer phone number.

When those hold, Rulrr sends the customer an SMS linking to a hosted receipt at:

https://share.rulrr.com/inv/{orderId}

{orderId} is your own order id, the orderId you sent on POST /v1/orders. The customer opens the link to view an itemised receipt with the store details, line items and payments.

Nothing extra is required on your side to issue the receipt: send the closed order with a phone number to a receipts-enabled store and Rulrr handles the SMS and the hosted page. The vendor's order call is the same whether or not the store has receipts on.

Point-of-sale prompt (recommended)

If your terminal supports it, prompt the cashier for the customer's phone number at checkout so the e-receipt can be sent. If the customer opts in and enters a valid number, you can offer the SMS receipt in place of, or alongside, the printed one.

Read an order (backs the hosted receipt)

The hosted receipt page reads the order via:

GET /v1/orders?orderId={orderId}
Host: rest.rulrr.com
Authorization: Bearer {accessToken}

This returns the order with its line items, payments and store snapshot for display. It is gated: the store must have the receipts flag on, the order must be CLOSED, and it must carry a customer with a phone number, otherwise it returns 403/404.

Most integrations never call GET /v1/orders directly; it backs the hosted e-receipt page and is documented here for completeness. To offer the receipt to the customer, just link them to https://share.rulrr.com/inv/{orderId}.

Integration Endpoints use standard HTTP status codes. A non-2xx response indicates the request was not applied.

Handling guidance

• 400 — fix the request; do not retry unchanged. Validate required fields and money/timestamp

formats (minor units as strings; ISO-8601 timestamps).

• 403 — refresh your access token (see Tokens & lifecycle); if it still fails,

the integration may have been revoked — re-run the OAuth flow.

• 404 / 410 — the resource is missing or already used; do not retry blindly.
• 500 — retry with exponential backoff. If it persists, contact

Developer Support.

Idempotency

• Orders are keyed by your orderId — re-sending the same orderId updates the existing order

rather than creating a duplicate, so retries are safe.

• Customer uploads are de-duplicated on ingest (by email, then phone), so re-uploading is safe.