Merran documentation API & integrations

What's on sale

GET

/api/stores/deals

const url = 'http://localhost:3000/api/stores/deals';
const options = {
  method: 'GET',
  headers: {cookie: 'merran.session_token=<merran.session_token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:3000/api/stores/deals \
  --cookie merran.session_token=<merran.session_token>

What’s on sale at the household’s store, by food, each sale judged against what the product usually costs (the lowest in a while first), and the recipes they’re in. From the prices the household has seen this past week: nothing without a Kroger store. With an API key, it needs the list: read permission.

Authorizations

session
apiKey

Responses

200

Its deals.

application/json

object

store

required

The household’s store’s banner, or null without one.

string | null

checkedAt

required

string | null format: date-time

leanOnSales

required

string

Allowed values: off some lots

deals

required

Array<object>

object

food

required

The food: chicken thigh.

string

product

required

object

required

string

upc

required

string | null

name

required

string

brand

required

string | null

size

required

string | null

image

required

string | null

price

required

In the currency’s smallest unit: cents.

integer | null

salePrice

required

integer | null

saleEnds

required

The sale’s last day.

string | null

currency

required

string

aisle

required

string | null

inStock

required

boolean

url

required

string | null

verdict

required

How good a sale is, against what the product usually costs: the lowest in a while, a normal sale, or barely off (under a tenth).

string

Allowed values: lowest sale small

usual

required

integer | null

off

required

How much is off: 0.25.

number

recipes

required

By recipe id, what each recipe uses that’s on sale, named as the recipe has it.

object

key

additional properties

Array<object>

object

name

required

string

verdict

required

How good a sale is, against what the product usually costs: the lowest in a while, a normal sale, or barely off (under a tenth).

string

Allowed values: lowest sale small

Example

{
  "store": "Fry's",
  "checkedAt": "2026-10-01T17:30:00.000Z",
  "leanOnSales": "some",
  "deals": [
    {
      "food": "milk",
      "product": {
        "id": "0001111041700",
        "upc": "0001111041700",
        "name": "Kroger 2% Reduced Fat Milk",
        "brand": "Kroger",
        "size": "1 gal",
        "image": "https://www.kroger.com/product/images/medium/front/0001111041700",
        "price": 349,
        "salePrice": 299,
        "saleEnds": "2026-10-21",
        "currency": "USD",
        "aisle": "Dairy",
        "inStock": true,
        "url": "https://www.frysfood.com/p/milk/0001111041700"
      },
      "verdict": "sale",
      "usual": 349,
      "off": 0.14
    }
  ],
  "recipes": {
    "0199e8b0-5a10-7a01-8b00-000000000006": [
      {
        "name": "milk",
        "verdict": "sale"
      }
    ]
  }
}

401

Not signed in.

application/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}

403

Not allowed.

application/json

object

error

required

object

code

required

string

message

required

string

fields

object

key

additional properties

string

Example

{
  "error": {
    "code": "not_found",
    "message": "There's nothing here.",
    "fields": {
      "name": "Give it a name."
    }
  }
}