For AI agents

How an AI agent can check a Costco receipt for price adjustments here. Nothing to install, no key, no account.

For people: tell your AI, “Use couponpriceadjustment.com/agents to check my Costco receipts for price adjustments.” It reads this page and does the rest. How to set this up with your own assistant.

For agents, do this in order:

  1. Get a receipt. If the user has not given one, ask them to upload a photo or PDF of a Costco warehouse receipt from the last 30 days, or paste its text. If you can read their email, look for it there.
  2. Read the warehouse number, the purchase date, and each item’s number, price, quantity and instant savings (see “Reading a Costco receipt” below).
  3. Call the check: https://www.couponpriceadjustment.com/api/agent/check?warehouse=111&date=2026-11-05&items=1207907:10.99:2,1172471:10.99:1:4.00 (a plain GET works). Tell the user which items can get a price adjustment, how much, and by when.
  4. If you cannot make that request yourself (many chat assistants cannot open a web address they wrote), do not stop and do not send the user to email. Write the same receipt into this link and give it to the user to open:
    https://www.couponpriceadjustment.com/check?warehouse=111&date=2026-11-05&items=1207907:10.99:2,1172471:10.99:1:4.00
    It takes the same warehouse, date and items as the check and shows the answer as a page for people.

Forwarding receipts by email is a separate thing, for alerts that keep coming (see “Ongoing alerts” at the end). Offer it after the check, not in place of it. A short version of this page is at /llms.txt.

What the site knows

  • The current in-warehouse deals (instant savings) at each US Costco warehouse, copied from Costco’s warehouse data and kept here. The check and the deals list answer from this copy.
  • A record of every sale the site has seen and the warehouses it was seen at. The check matches against this record, the same one the site’s own nightly alerts use.
  • How fresh it is: each warehouse’s deals are fetched at most about once a day. A check fetches the warehouse’s deals first if the site’s copy is more than 24 hours old, so a check normally answers from today’s deals. The deals list and the warehouse search do not fetch; they show the copy the site has. Right now 175 of 618 warehouses have deals fetched in the last 24 hours.
  • Every answer includes deals_as_of, the time that warehouse’s deals were last fetched, and a status: fresh (within 48 hours), stale (older and the fetch failed, so newer sales are missing) or not_cached (no copy and the fetch failed; the check only knows sales it saw there before and may miss some).

The rules the check applies

These are the same rules the site uses for its own email alerts.

  1. The purchase was in the last 30 days: from 30 days ago up to today. “Today” is the date in Pacific time.
  2. There is a sale on the same item number.
  3. The sale started after the purchase date. A sale that was already running when the item was bought does not count.
  4. The sale is running today (today is between its first and last day, both included).
  5. Same warehouse: the sale is at the warehouse where the item was bought. That is Costco’s policy. These are "kind": "same_store".
  6. Nearby: if the sale is not at that warehouse but is at another one within 15 miles, the check reports the nearest one as "kind": "nearby". Costco’s policy is to adjust prices at the store where you bought the item, but many stores will adjust it anyway. It’s up to the store.
  7. Amount per unit = the sale’s discount minus the instant savings already taken on that receipt line, divided by the quantity. It only counts if that is more than $0.
  8. Amount owed = the amount per unit times the quantity, rounded to the cent.
  9. Redeem by: the sale’s last day or 30 days after the purchase, whichever comes first.
  10. If more than one sale fits one item, the answer leads with the one at the purchase warehouse, then the biggest amount, and lists the others in other_sales.

The price paid is not part of the math. The amount comes from the sale’s discount, as in the site’s emails. The price is echoed back so you can show it.

Reading a Costco receipt

  • Warehouse number: printed as Whse: 111, or after the city name, as in TIGARD #111.
  • Item number: the number at the start of each item line.
  • Quantity: a line like 2 @ 10.99 before an item means 2 at $10.99 each. The item line shows the total; send the price for one unit.
  • Instant savings: a line like 390305 / 1172471 4.00-. The number after the slash is the item it belongs to; 4.00 is the savings already taken. Send it as that item’s instant savings.

How to call the check

One receipt per request: one warehouse, one purchase date, up to 100 items.

GET

GET https://www.couponpriceadjustment.com/api/agent/check?warehouse=WAREHOUSE&date=YYYY-MM-DD&items=ITEM:PRICE[:QUANTITY[:SAVINGS]],...
FieldWhat to send
warehouseThe warehouse number from the receipt, e.g. 111.
dateThe purchase date, YYYY-MM-DD.
itemsItems separated by commas. Each is ITEM:PRICE, ITEM:PRICE:QUANTITY or ITEM:PRICE:QUANTITY:SAVINGS. PRICE is the price paid for one unit. QUANTITY defaults to 1. SAVINGS is the total instant savings already taken on that line, default 0. Repeat an item number if it is on the receipt twice.

A link for the user, when you cannot make the request

The same three fields on /check give a page a person can read. Write the link with the receipt’s values and show it to the user as a link to tap:

https://www.couponpriceadjustment.com/check?warehouse=WAREHOUSE&date=YYYY-MM-DD&items=ITEM:PRICE[:QUANTITY[:SAVINGS]],...

POST

The same as JSON. items can also be the GET string.

POST https://www.couponpriceadjustment.com/api/agent/check
Content-Type: application/json

{
  "warehouse": "111",
  "date": "2026-11-05",
  "items": [
    { "item": "1207907", "price": 10.99, "quantity": 2 },
    { "item": "1172471", "price": 10.99, "quantity": 1, "instant_savings": 4.00 }
  ]
}

The answer

  • status: fresh, stale, not_cached or outside_window (bought more than 30 days ago).
  • message: one plain sentence about the whole answer.
  • deals_as_of: when this warehouse’s deals were last fetched, or null.
  • For each item: adjustment_available, and when true, kind, amount_owed, amount_per_unit, sale_start, sale_end, redeem_by, sale_at (the warehouse with the sale, with its distance) and a plain note. Items without an adjustment have a note saying why.
  • total_same_store and total_nearby: the amounts added up.
  • how_to_claim: what to tell the user.

Errors come back as HTTP 400 with {"error": "..."}. The error says what to fix, for example the format of an item. HTTP 404 means the warehouse number is not in the site’s list. HTTP 503 means try again in a few minutes.

Worked example

A receipt from the Tigard warehouse (#111) on November 5, 2026, checked on November 12: two packs of butter at $10.99, and another butter that already got $4.00 instant savings at checkout.

GET https://www.couponpriceadjustment.com/api/agent/check?warehouse=111&date=2026-11-05&items=1207907:10.99:2,1172471:10.99:1:4.00
{
  "status": "fresh",
  "message": "1 of 2 items can get a price adjustment or are on sale nearby. This warehouse's deals were last fetched 2026-11-12T11:48:58.692+00:00.",
  "warehouse": {
    "id": "111",
    "name": "Tigard",
    "state": "Oregon",
    "store_page": "https://www.couponpriceadjustment.com/store/tigard-111"
  },
  "purchase_date": "2026-11-05",
  "today": "2026-11-12",
  "deals_as_of": "2026-11-12T11:48:58.692+00:00",
  "items": [
    {
      "item_number": "1207907",
      "unit_price": 10.99,
      "quantity": 2,
      "instant_savings": 0,
      "adjustment_available": true,
      "kind": "same_store",
      "item_name": "KERRYGOLD UNSALTED IRISH BUTTER 4/8 OZ (2 LBS)",
      "amount_owed": 8,
      "amount_per_unit": 4,
      "sale_start": "2026-11-12",
      "sale_end": "2026-11-25",
      "redeem_by": "2026-11-25",
      "sale_at": { "id": "111", "name": "Tigard", "distance_miles": 0 },
      "note": "On sale at Tigard from 2026-11-12 to 2026-11-25: $4.00 off each. Ask for $8.00 at the membership desk by 2026-11-25."
    },
    {
      "item_number": "1172471",
      "unit_price": 10.99,
      "quantity": 1,
      "instant_savings": 4,
      "adjustment_available": false,
      "note": "Item 1172471 is on sale at Tigard, but the instant savings already taken on this line at checkout cover the whole discount."
    }
  ],
  "total_same_store": 8,
  "total_nearby": 0,
  "how_to_claim": "Bring your receipt (or membership card) to the Costco membership desk and ask for a price adjustment. Price adjustments are honored within 30 days of purchase and while the discount is active.",
  "reminder": "This site only finds price adjustments. The member asks for them at the warehouse; the site cannot claim them.",
  "about": "https://www.couponpriceadjustment.com/agents"
}

The first butter went on sale on November 12, after the purchase, for $4.00 off each. Two were bought, so $8.00 is owed, to ask for by November 25. The second already got its $4.00 at checkout.

Finding a warehouse number

  • It is on the receipt (see above).
  • By city or state: https://www.couponpriceadjustment.com/api/agent/warehouses?q=tigard or ?state=OR (state name or two-letter code), or both. Each result has the warehouse number, city, state, its page on this site and how fresh its deals are. There is no zip code search; use the city name.
  • A list of every warehouse by state: /stores.

Deals at one warehouse

https://www.couponpriceadjustment.com/api/agent/deals?warehouse=111 returns that warehouse’s current deals from the site’s copy: item number, name, discount, regular price, price after the discount, dates and stock. Use it to answer “what is on sale at my Costco?”.

Privacy

  • Send only: the warehouse number, the purchase date, item numbers, prices paid, quantities and instant savings.
  • Never send: the member number, name, email address, payment details, or the receipt image or PDF. The check does not need them.
  • The check does not save what you send and does not write it to the site’s logs. A GET puts the items in the web address, and web addresses can show up in the hosting provider’s standard request logs. Use POST if you would rather avoid that.

Ongoing alerts

The check answers for today only. For alerts that keep coming, the user can sign up themselves (an agent should not do this for them without asking, since it shares their email address and receipt):

  • Forward receipts: email the Costco receipt, with the receipt PDF attached, to receipt@couponpriceadjustment.com from the address that should get the alerts. In the Costco app: Account, Orders & Purchases, Warehouse, View Receipt, Print Receipt, Share, then email it. The site reads the items, emails back right away with anything it finds, and checks every night for 30 days after the purchase. It keeps the email address and the items and prices. Every email has a link to delete all of it.
  • Track an item: at /watch, pick a warehouse and an item and enter an email. After the user confirms by email, the site emails them when that item goes on sale at that warehouse.

What to tell the user

Bring your receipt (or membership card) to the Costco membership desk and ask for a price adjustment. Price adjustments are honored within 30 days of purchase and while the discount is active.

  • List each item with its amount and its redeem-by date, and the total.
  • For nearby items, say where the sale is and that it is up to the store: Costco’s policy is the store where the item was bought.
  • If the status is stale or not_cached, say the answer may be missing newer sales.
  • This site only finds price adjustments. It cannot claim them; the member asks at the warehouse.