Reports API

The reports API lets a script or a BI tool read your kitchen's report numbers as JSON. For example, a Google Apps Script can read last night's numbers into a KPI dashboard.

The API only reads. It cannot change anything in Rinvy. The numbers are the same numbers that the Reports page shows.

Create an API key

  1. Go to Kitchen Settings, open the Integrations section and choose the API keys tab.

  2. Under Automation API keys, type a name for the key, for example "KPI dashboard".
  3. Tick Read reports. Leave the other boxes empty if the tool only reads.
  4. Press Create key.
  5. Press Copy key and paste it into your tool. Then press Done.

The Automation API keys form with the name "KPI dashboard" typed and Read reports ticked, above the Create key button

Read a report

Send a GET request to an address that starts with:

https://api.rinvy.app/api/v1/reports/

Put the key in the Authorization header as Bearer <your key>. Rinvy refuses a key in the address (?api_key=).

Most reports take a date range: startDate and endDate, as YYYY-MM-DD in your kitchen's timezone. Both days are included. A range can be up to 366 days.

ReportWhat it returns
food-cost/theoretical?startDate&endDateFor each day, the recipe cost of what sold and the menu price of what sold, and the food cost %. Days with no sales show hasSales: false.
food-cost/headlineThe food cost % your Home tile shows: the actual % between two counts at least a week of sales apart, the theoretical % for the same counts, and the two count days. When there is no actual figure, actualPct is null and unavailableReason says why (for example period-too-short or missing-sales-days).
food-cost/actual?startDate&endDateActual food cost between the first and the last completed count in the range: beginning and ending inventory, purchases, cost of goods sold, net sales and the theoretical %. Add limit and offset to page the product list (50 by default). periodDays is the number of sales days between the two counts.
inventory-value?startDate&endDateThe inventory value at each completed count in the range.
purchases?startDate&endDateThe amount received each day, in total and by supplier. Credits and returns are taken off.
waste?startDate&endDateThe waste cost for each day, and the waste cost by reason for the whole range.
variance?startDate&endDateTheoretical usage against actual usage for each product. Needs the Pro plan.
sales?startDate&endDateNet sales and units sold for each day. A day uses your POS sales when they have a money figure, and your typed net sales otherwise, as the Food Cost report does.
usage?startDate&endDateWhat each product used in the range, and its cost.
alerts/priceThe open price change alerts.
alerts/stockout-riskThe open stockout risk alerts.
alerts/food-costMenu items whose food cost is above their target.
alerts/inventory-healthOpen findings from the inventory health check after a count.
alerts/expirationLots that expire soon.

To get waste by reason for one day, send that day as both startDate and endDate.

For a food cost tile on a dashboard, use food-cost/headline. Use food-cost/actual for a statement between the counts of a range you choose. Two counts a day apart give one day of usage against one day of sales, and that number swings widely.

The response

A successful request returns 200:

{
  "ok": true,
  "kitchen": {
    "id": "…",
    "name": "R Town Pizza",
    "timezone": "America/Los_Angeles",
    "currency": "USD"
  },
  "data": { … }
}

kitchen tells you which kitchen the key reads, so one dashboard can hold several kitchens. data holds the report. Money is in the kitchen's currency.

A refused request returns "ok": false and an error that says what to fix.

StatusMeaning
400A date is missing or wrong, the end is before the start, or the range is longer than 366 days.
401The key is missing, wrong, revoked, or sent in the address instead of the header.
403The key can't read reports, or your plan doesn't include this report.
404The report name is wrong. The error lists the reports.
429Too many requests. A key can read 120 reports an hour.
500Something went wrong in Rinvy. Try again later.

Google Sheets example

The Google Apps Script below reads yesterday's purchases and waste for each kitchen and adds one row per kitchen to a tab named KPIs.

  1. In your Google Sheet, open Extensions → Apps Script.
  2. Paste the script below and put one key per kitchen in RINVY_KEYS.
  3. Run readKpis once and approve the permissions it asks for.
  4. To run it every night, open Triggers (the clock icon), add a trigger for readKpis, and pick a daily time-driven schedule.

const RINVY_KEYS = ['rk_live_KITCHEN_ONE', 'rk_live_KITCHEN_TWO'];
const RINVY_URL = 'https://api.rinvy.app/api/v1/reports/';

function rinvy(key, report, params) {
  const query = Object.keys(params)
    .map((k) => k + '=' + encodeURIComponent(params[k]))
    .join('&');
  const response = UrlFetchApp.fetch(RINVY_URL + report + (query ? '?' + query : ''), {
    headers: { Authorization: 'Bearer ' + key },
    muteHttpExceptions: true,
  });
  const body = JSON.parse(response.getContentText());
  if (!body.ok) throw new Error(report + ': ' + body.error);
  return body;
}

function readKpis() {
  const tz = Session.getScriptTimeZone();
  const yesterday = Utilities.formatDate(new Date(Date.now() - 864e5), tz, 'yyyy-MM-dd');
  const range = { startDate: yesterday, endDate: yesterday };
  const sheet = SpreadsheetApp.getActive().getSheetByName('KPIs');

  RINVY_KEYS.forEach((key) => {
    const purchases = rinvy(key, 'purchases', range);
    const waste = rinvy(key, 'waste', range);
    sheet.appendRow([
      yesterday,
      purchases.kitchen.name,
      purchases.data[0].total,
      waste.data.daily[0].estimatedCost,
    ]);
  });
}

Can one key read several kitchens?

Not yet. A key belongs to the kitchen it was made in. Create one key in each kitchen and read them in a loop, as the script above does.