Merran documentation API & integrations

The shopping lists

GET

/api/list

const url = 'http://localhost:3000/api/list';
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/list \
  --cookie merran.session_token=<merran.session_token>

The household’s lists (one for each store it shops at, the main one first), and everything to buy, by aisle in a walk through the store, with what’s checked off. Each item says which list it’s on, how much, and which planned meals it’s for. With an API key, it needs the list: read permission.

Authorizations

session
apiKey

Responses

200

The list.

application/json

object

lists

required

The household’s lists, the main one first.

Array<object>

object

required

string

name

required

string

main

required

The main list, which takes what no other list does.

boolean

aisles

required

The ids of the aisles that go on it.

Array<string>

aisles

required

In a walk through the store, the household’s country’s to start.

Array<object>

object

required

string

name

required

string

position

required

integer

items

required

By aisle, in the aisles’ order, oldest first in each.

Array<object>

object

required

string

list

required

The list it’s on.

string

name

required

string

amount

required

How much, as it shows: “1 ½ cups”, “half a bag”, or empty.

string

quantity

required

number | null

unit

required

A unit id, like “cup” or “pound”; null for a count.

string | null

amountText

required

An amount in words (“half a bag”), when it isn’t a number.

string | null

aisle

required

Its aisle’s id.

string | null

checked

required

boolean

source

required

How it got on the list: from the plan, typed in, every week, a usual buy, or the assistant.

string

Allowed values: plan typed every-week usual assistant

meals

required

The planned meals it’s for.

Array<object>

object

required

string

name

required

string

createdAt

required

string format: date-time

Example

{
  "lists": [
    {
      "id": "0199e8b0-5a10-7a01-8b00-00000000001c",
      "name": "Shopping list",
      "main": true,
      "aisles": []
    },
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000025",
      "name": "Costco",
      "main": false,
      "aisles": [
        "0199e8b0-5a10-7a01-8b00-000000000021"
      ]
    }
  ],
  "aisles": [
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000020",
      "name": "Produce",
      "position": 0
    },
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000021",
      "name": "Meat & seafood",
      "position": 1
    },
    {
      "id": "0199e8b0-5a10-7a01-8b00-000000000022",
      "name": "Other",
      "position": 2
    }
  ],
  "items": [
    {
      "id": "0199e8b0-5a10-7a01-8b00-00000000001e",
      "list": "0199e8b0-5a10-7a01-8b00-00000000001c",
      "name": "lemons",
      "amount": "2",
      "quantity": 2,
      "unit": null,
      "amountText": null,
      "aisle": "0199e8b0-5a10-7a01-8b00-000000000020",
      "checked": false,
      "source": "plan",
      "meals": [
        {
          "id": "0199e8b0-5a10-7a01-8b00-00000000001b",
          "name": "Lemon Chicken"
        }
      ],
      "createdAt": "2026-10-15T18:30:00.000Z"
    },
    {
      "id": "0199e8b0-5a10-7a01-8b00-00000000001d",
      "list": "0199e8b0-5a10-7a01-8b00-000000000025",
      "name": "chicken thighs",
      "amount": "3 lb",
      "quantity": 3,
      "unit": "pound",
      "amountText": null,
      "aisle": "0199e8b0-5a10-7a01-8b00-000000000021",
      "checked": false,
      "source": "plan",
      "meals": [
        {
          "id": "0199e8b0-5a10-7a01-8b00-00000000001b",
          "name": "Lemon Chicken"
        }
      ],
      "createdAt": "2026-10-15T18:30:00.000Z"
    }
  ]
}

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."
    }
  }
}