Skip to content
merran
GitHubInstall

Merran documentation API & integrations

What the extension found at Walmart

POST
/api/stores/walmart/found
curl --request POST \
  --url http://localhost:3000/api/stores/walmart/found \
  --header 'Content-Type: application/json' \
  --cookie merran.session_token=<merran.session_token> \
  --data '{ "items": [ { "itemId": "0199e8b0-5a10-7a01-8b00-00000000001e", "products": [ { "id": "10450114", "upc": null, "name": "Great Value 2% Reduced Fat Milk, Gallon, 128 fl oz", "brand": "Great Value", "size": "128 fl oz", "image": "https://i5.walmartimages.com/seo/milk.jpeg", "price": 327, "salePrice": null, "saleEnds": null, "currency": "USD", "aisle": null, "inStock": true, "url": "https://www.walmart.com/ip/10450114" } ] } ] }'

The products Merran’s browser extension read from Walmart’s search for things on the list. Every price is kept; each thing without a product of the household’s own gets Merran’s pick (the household’s model for shopping when it has AI, else the first in stock), kept for its food. A product someone picked is never replaced, only brought up to date. The answer is the cart to look over. With an API key, it needs the list: write permission.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
items
required
Array<object>
>= 1 items <= 200 items
object
itemId
required
string
products
required
Array<object>
<= 12 items
object
id
required
string
/^[0-9A-Za-z]{1,64}$/
upc
required
string | null
<= 20 characters
name
required
string
>= 1 characters <= 300 characters
brand
required
string | null
<= 120 characters
size
required
string | null
<= 60 characters
image
required
string | null
<= 1000 characters /^https:\/\//
price
required
integer | null
<= 10000000
salePrice
required
integer | null
<= 10000000
saleEnds
required

Walmart’s pages don’t say, so the extension sends null.

string | null format: date
currency
required
string
Allowed values: USD
aisle
required
string | null
<= 60 characters
inStock
required
boolean
url
required
string | null
<= 1000 characters /^https:\/\/www\.walmart\.com\//

Example 

{
  "id": "10450114",
  "upc": null,
  "name": "Great Value 2% Reduced Fat Milk, Gallon, 128 fl oz",
  "brand": "Great Value",
  "size": "128 fl oz",
  "image": "https://i5.walmartimages.com/seo/milk.jpeg",
  "price": 327,
  "salePrice": null,
  "saleEnds": null,
  "currency": "USD",
  "aisle": null,
  "inStock": true,
  "url": "https://www.walmart.com/ip/10450114"
}

Example 

{
  "items": [
    {
      "itemId": "0199e8b0-5a10-7a01-8b00-00000000001e",
      "products": [
        {
          "id": "10450114",
          "upc": null,
          "name": "Great Value 2% Reduced Fat Milk, Gallon, 128 fl oz",
          "brand": "Great Value",
          "size": "128 fl oz",
          "image": "https://i5.walmartimages.com/seo/milk.jpeg",
          "price": 327,
          "salePrice": null,
          "saleEnds": null,
          "currency": "USD",
          "aisle": null,
          "inStock": true,
          "url": "https://www.walmart.com/ip/10450114"
        }
      ]
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Picked, and the cart as it is.

Media typeapplication/json
object
store
required

Walmart.

string
cartUrl
required

Walmart’s cart, to check out.

string
sentAt
required
string | null format: date-time
lines
required
Array<object>
object
itemId
required
string
name
required
string
amount
required
string
product
required
Any of:
object
id
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
suggested
required

Merran’s pick, not one the household chose.

boolean
packages
required
integer
sure
required

How many is worked out from the product’s size, not a guess.

boolean
sent
required

Sent to the cart last time.

boolean
sale
required

Its sale today, if it’s on one.

object
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

What it usually costs, in cents: its most common price over 90 days, else its regular price.

integer | null
toFind
required

Things without a product yet, one for each food, for the extension to look for at Walmart.

Array<object>
object
itemId
required
string
words
required

What to search Walmart for: the food as it’s bought.

string

Example 

{
  "store": "Walmart",
  "cartUrl": "https://www.walmart.com/cart",
  "sentAt": null,
  "lines": [
    {
      "itemId": "0199e8b0-5a10-7a01-8b00-00000000001d",
      "name": "milk",
      "amount": "1 gallon",
      "product": {
        "id": "10450114",
        "upc": null,
        "name": "Great Value 2% Reduced Fat Milk, Gallon, 128 fl oz",
        "brand": "Great Value",
        "size": "128 fl oz",
        "image": "https://i5.walmartimages.com/seo/milk.jpeg",
        "price": 327,
        "salePrice": null,
        "saleEnds": null,
        "currency": "USD",
        "aisle": null,
        "inStock": true,
        "url": "https://www.walmart.com/ip/10450114"
      },
      "suggested": true,
      "packages": 1,
      "sure": true,
      "sent": false,
      "sale": null
    },
    {
      "itemId": "0199e8b0-5a10-7a01-8b00-00000000001e",
      "name": "eggs",
      "amount": "12",
      "product": null,
      "suggested": true,
      "packages": 1,
      "sure": true,
      "sent": false,
      "sale": null
    }
  ],
  "toFind": [
    {
      "itemId": "0199e8b0-5a10-7a01-8b00-00000000001e",
      "words": "eggs"
    }
  ]
}

401

Section titled “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

Section titled “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."
    }
  }
}

422

Section titled “422”

Walmart isn’t turned on on this server.

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

© 2026 Kyle Johnson. Documentation: CC BY 4.0. Merran: AGPL-3.0-or-later.