Scan a receipt

POST

/api/pantry/receipts

curl --request POST \
  --url http://localhost:3000/api/pantry/receipts \
  --header 'Content-Type: multipart/form-data' \
  --cookie merran.session_token=<merran.session_token> \
  --form file=@file \
  --form text=example

• Your Merran

Reads a receipt into a draft to look over before anything goes in the pantry: photos of a paper one, screenshots or a PDF of an emailed one (up to 6 files, one file field each), or its text. Each line says what it is, how much, and the shopping list item it was bought for. Add it with POST /pantry/receipts/{receiptId}/add; it’s forgotten after a day. Uses the household’s model for receipts, which must be able to read photos or PDFs if those are sent, and counts towards its AI spend. With an API key, it needs the pantry: write permission.

Authorizations

• session
• apiKey

Request Body^required

Media typemultipart/form-data

object

file

A photo, screenshot or PDF of the receipt.

string format: binary

text

The receipt’s text, as from an email.

string

Responses

201

Read, waiting for a look.

Media typeapplication/json

object

id

required

string

store

required

string | null

date

required

The day on it.

string | null

total

required

number | null

lines

required

Array<object>

object

id

required

string

text

required

As printed.

string

name

required

What it is, plainly.

string

amount

required

string | null

price

required

number | null

kind

required

Food goes in the pantry; household things and the rest don’t, unless they’re picked.

string

Allowed values: food household other

listItem

required

The shopping list item it was bought for, taken off the list when it’s added.

object

id

required

string

name

required

string

files

required

The receipt’s photos or PDF, to compare with.

Array<object>

object

url

required

string

mediaType

required

string

Allowed values: image/jpeg application/pdf

createdAt

required

string format: date-time

Example

{
  "id": "0199e8b0-5a10-7a01-8b00-00000000002e",
  "store": "Walmart",
  "date": "2026-10-14",
  "total": 48.12,
  "lines": [
    {
      "id": "0d1b5c2a9e44",
      "text": "GV WHL MLK 1GAL",
      "name": "whole milk",
      "amount": "1 gal",
      "price": 3.48,
      "kind": "food",
      "listItem": {
        "id": "0199e8b0-5a10-7a01-8b00-00000000001d",
        "name": "milk"
      }
    }
  ],
  "files": [
    {
      "url": "/api/pantry/receipts/0199e8b0-5a10-7a01-8b00-00000000002e/files/0",
      "mediaType": "image/jpeg"
    }
  ],
  "createdAt": "2026-10-15T18:30:00.000Z"
}

400

Nothing to read, or a file Merran can’t read.

Media typeapplication/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."
    }
  }
}

401

Not signed in.

Media typeapplication/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.

Media typeapplication/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."
    }
  }
}

413

The files are too big.

Media typeapplication/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."
    }
  }
}

422

It isn’t a receipt (receipt_is_recipe when it’s a recipe), or the model can’t read photos or PDFs.

Media typeapplication/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."
    }
  }
}

429

This month’s AI limit is reached.

Media typeapplication/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."
    }
  }
}