Trawl

Shops

Your crossed-out prices and product pages, checked against the brand's own site. Read the results over the API.

Base URL
https://api.trawl.me

Authentication

Send a developer API key as a bearer token. Every route is a read: nothing here changes your data.

The key

Owner
A member of your organization.
Scope
trawl:shops:read. In the web app, create it with the access “Shops data, read only” (preselected in a Shops organization). “Read only” cannot call Shops routes. A key made before this choice has full access.
Limit
120 requests a minute per key owner, shared with their web session. 5 CSV exports a minute.

Errors

401
No key, or a key that does not work.
403
The key lacks the scope.
404
Your organization does not have Shops.
422
A value outside the list. The message names the allowed ones.
429
Over the limit. Wait a minute and go on.

API keys

curl "https://api.trawl.me/api/shops/matches?status=too_high" \
  -H "Authorization: Bearer $TRAWL_API_KEY"
Every JSON answer
{
  "type": "success",
  "message": "…",
  "data": …
}

Read everything, each day

Your catalog is read each morning, each brand's site at least every 7 days. You have nothing to start: read the result.

  1. Read summary. Go on when checkedAt is today and at least 10 minutes old.
  2. Read sales.
  3. For each sale, read matches?sale={handle}&perPage=200 until a page comes back short.
  4. For its brand pages, read the same with group=product&include=pages.
  5. Read summary again. If checkedAt moved, start over.

Load variants by variantKey, brand pages by productId.

What you no longer read has left its sale. Keep your own history if you need one.

A match with no catalog.sale shows only in a list without sale.

Fix lines land later than the check: read fixes?since=.

const get = async (path) => {
  const res = await fetch(`https://api.trawl.me/api/shops${path}`, {
    headers: { Authorization: `Bearer ${process.env.TRAWL_API_KEY}` },
  });
  return (await res.json()).data;
};

const { checkedAt } = await get("/summary");

for (const sale of await get("/sales")) {
  for (let page = 0; ; page += 1) {
    const rows = await get(
      `/matches?sale=${sale.handle}&perPage=200&page=${page}`,
    );
    save(rows); // by variantKey
    if (rows.length < 200) break;
  }
}

const after = await get("/summary");
if (after.checkedAt !== checkedAt) { /* start over */ }

Latest check

GET /api/shops/summary

The counts of the latest check, and the brands Trawl does not cover yet.

Returns

checkedAtdate
When the check started writing. It moves before the check ends.
byStatusobject
Variants per status.
matchedinteger
Variants with a price verdict.
tooHighGapnumber
Total gap in euros, each product once at its biggest gap.
notCoveredarray
Brands not read, with their variant count.
kpiobject
Brands, products, prices and pages, with what each loses and why.
curl "https://api.trawl.me/api/shops/summary" \
  -H "Authorization: Bearer $TRAWL_API_KEY"
Response
{
  "type": "success",
  "message": "shop summary",
  "data": {
    "variants": 1240,
    "products": 612,
    "byStatus": {
      "too_high": 86,
      "ok": 702,
      "not_found": 318,
      "name_only": 41,
      "not_comparable": 93
    },
    "matched": 788,
    "tooHighGap": 1842.5,
    "notCovered": [{ "vendor": "Ostra", "variants": 57 }, …],
    "byVendor": […],
    "checkedAt": "2026-11-03T07:04:00.000Z",
    "kpi": {
      "brands": { "onSale": 24, "comparable": 22, "covered": 19, … },
      "products": { "onSale": 612, "matched": 391, … },
      "price": { "judged": 788, "tooHigh": 86, "tooHighPct": 10.9, … },
      "listing": { "rated": 240, "brandBetter": 96, … }
    }
  }
}

Sales

GET /api/shops/sales

Your sales in your home page's order, then the ones off the home, latest start first.

Returns

handlestring
The value for sale on matches.
positioninteger
0 is first on your home. null off the home.
kpiobject
The same counts as summary, for this sale.
curl "https://api.trawl.me/api/shops/sales" \
  -H "Authorization: Bearer $TRAWL_API_KEY"
Response
{
  "type": "success",
  "message": "shop sales",
  "data": [
    {
      "handle": "northfold",
      "title": "Northfold",
      "image": "https://your-shop.example/northfold.jpg",
      "startAt": "2026-11-01T08:00:00.000Z",
      "endAt": "2026-11-09T22:00:00.000Z",
      "discountLabel": "-50%",
      "position": 0,
      "kpi": { "brands": { … }, "products": { … }, "price": { … }, "listing": { … } }
    }
  ]
}

List matches

GET /api/shops/matches

One match per variant, biggest gap first. data is a bare array: read until a page comes back short.

Parameters

statusenum
The price verdict. Statuses
listingenum
Which page tells the buyer more. Page verdicts
confidenceenum
high, medium or low. With group=product, lists only the variants at that level.
cheaperboolean
true: only what is cheaper at the brand. Combines with the other filters. Cheaper at the brand
salestring
A sale handle.
searchstring
A catalog product id, SKU or barcode.
sortenum
gap by default. impact: too high first, then pages where the brand tells more.
groupenum
product: one row per product, with its variants. Those carry no price or verdict.
includeenum
pages: adds the brand page. Needs group=product.
pageinteger
From 0. Default 0.
perPageinteger
From 1 to 200. Default 50. Above 200 is a 422.
formatenum
csv: every match of the filter, unpaged, one row per variant.
curl "https://api.trawl.me/api/shops/matches?sale=northfold" \
  -H "Authorization: Bearer $TRAWL_API_KEY"
Response
{
  "type": "success",
  "message": "shop match list",
  "data": [
    {
      "id": "6a1f3c9e2b7d4e0012ab34cd",
      "variantKey": "[\"8841203\"]|4410",
      "status": "too_high",
      "confidence": "high",
      "gap": 34,
      "gapPct": 35.8,
      …
    }
  ]
}

One match

GET /api/shops/matches/:id

A match with both product pages side by side.

Adds to the match

pagesobject
catalog and brand. null: no page read. Check readable before you use one.
listingPointsobject
Why the page verdict: the points per criterion and their total.
fixesobject
The pair's fix list.

A page has gallery, description, factList, sectionTexts and text among its fields.

Section texts stop at 300 characters. text holds the page, up to 7,000.

curl "https://api.trawl.me/api/shops/matches/6a1f3c9e2b7d4e0012ab34cd" \
  -H "Authorization: Bearer $TRAWL_API_KEY"
Response
{
  "type": "success",
  "message": "shop match",
  "data": {
    "id": "6a1f3c9e2b7d4e0012ab34cd",
    …
    "pages": {
      "catalog": { "url": "https://your-shop.example/products/merino-crew-sweater", "readable": true, … },
      "brand": {
        "url": "https://northfold.example/crew",
        "readable": true,
        "photos": 6,
        "facts": 5,
        "sections": ["composition", "care"],
        "sectionTexts": { "composition": "100% merino wool." },
        …
      }
    },
    "listingPoints": {
      "sections": 1,
      "photos": 2,
      "resolution": 0,
      "facts": 1,
      "fixes": 8,
      "keyFacts": 2,
      "total": 12
    },
    "fixes": { … }
  }
}

List fixes

GET /api/shops/fixes

The lines to add to your product pages, quoted from the brand. One entry per pair of pages.

Parameters

productIdstring
One catalog product.
sinceISO date
Only the lists made since then. Not a date: 422.
pageinteger
From 0. Default 0.
perPageinteger
From 1 to 200. Default 50. Above 200 is a 422.
formatenum
csv: one row per line to add, unpaged.

Each change

kindenum
conflict, missing_info, longer_description or missing_photo.
sectionstring
The part of the page it belongs to.
linestring
The text to paste, in your page's language.
sourcestring
The brand's own words.
currentstring
Your words, for a conflict only.
whystring
A short reason.
urlstring
The photo, for missing_photo.
curl "https://api.trawl.me/api/shops/fixes?since=2026-11-03" \
  -H "Authorization: Bearer $TRAWL_API_KEY"
Response
{
  "type": "success",
  "message": "shop fixes",
  "data": [
    {
      "productId": "8841203",
      "handle": "merino-crew-sweater",
      "url": "https://your-shop.example/products/merino-crew-sweater",
      "title": "Merino crew sweater",
      "vendor": "Northfold",
      "brandUrl": "https://northfold.example/crew",
      "at": "2026-11-03T07:12:00.000Z",
      "variants": [{ "variantId": "4410", "sku": "NF-CREW-M", "barcode": "3700000000013" }],
      "changes": [
        {
          "kind": "missing_info",
          "section": "Composition",
          "line": "Composition: 100% merino wool.",
          "source": "100% merino wool.",
          "current": null,
          "why": "Buyers look for it."
        },
        {
          "kind": "missing_info",
          "section": "Care",
          "line": "Hand wash cold.",
          "source": "Hand wash cold.",
          "current": null,
          "why": "Only the brand says it."
        },
        …,
        { "kind": "missing_photo", "url": "https://northfold.example/crew-back.jpg" }
      ]
    }
  ]
}

The match object

Each row says how old it is. The list leaves out the fix lines.

Fields

variantKeystring
Stable id of this variant, the key to load on.
productIdstring
Your catalog product, the key to load brand pages on.
vendorstring
Its brand.
statusenum
The price verdict. Statuses
reasonenum
Why there is none, when there is none. Reasons
matchedByenum
The proof that tied your product to the brand's. How a match is made
confidenceenum
How sure we are, or null. Confidence
catalogobject
Your side. crossed is your crossed-out price. seenAt: last read of your catalog.
brandobject
The brand's side. full is the higher of price and compareAt. seenAt: last time we saw it. available: false when sold out at the brand, no field when its page does not say.
brandCheaperobject
{ gapEur, gapPct, seenAt } when the brand sells below your price, else null. Cheaper at the brand
gapnumber
Your crossed-out price minus the brand's full price, in euros.
gapPctnumber
The same in percent of the brand's full price.
listingenum
The page verdict. Page verdicts
firstTooHighAtdate
When the price first turned too high.
checkedAtdate
The check that wrote this match.
One match
{
  "id": "6a1f3c9e2b7d4e0012ab34cd",
  "variantKey": "[\"8841203\"]|4410",
  "productId": "8841203",
  "vendor": "Northfold",
  "status": "too_high",
  "reason": null,
  "matchedBy": "barcode",
  "confidence": "high",
  "catalog": {
    "title": "Merino crew sweater",
    "variantTitle": "M",
    "sku": "NF-CREW-M",
    "barcode": "3700000000013",
    "url": "https://your-shop.example/products/merino-crew-sweater",
    "price": 59,
    "crossed": 129,
    "currency": "EUR",
    "seenAt": "2026-11-03T06:02:00.000Z",
    "sale": {
      "handle": "northfold",
      "title": "Northfold",
      "position": 0,
      …
    },
    "image": "https://your-shop.example/crew.jpg"
  },
  "brand": {
    "name": "Northfold",
    "title": "Crew sweater in merino",
    "variantTitle": "M",
    "sku": "NF-CREW-M",
    "barcode": "3700000000013",
    "url": "https://northfold.example/crew",
    "image": "https://northfold.example/crew.jpg",
    "price": 95,
    "compareAt": null,
    "full": 95,
    "currency": "EUR",
    "seenAt": "2026-11-02T05:40:00.000Z",
    "gone": false
  },
  "brandCheaper": null,
  "gap": 34,
  "gapPct": 35.8,
  "listing": "brand_better",
  "firstTooHighAt": "2026-10-28T07:10:00.000Z",
  "checkedAt": "2026-11-03T07:04:00.000Z"
}

Statuses

too_high
Your crossed-out price is more than €1 above the brand's full price.
ok
It is not.
not_found
No product at the brand could be proven the same.
not_comparable
The same product, but the two prices cannot be compared.
name_only
Only a similar name was found.
curl "https://api.trawl.me/api/shops/matches?status=too_high" \
  -H "Authorization: Bearer $TRAWL_API_KEY"

Reasons

Why a match has no price verdict.

brand_not_covered
Trawl does not read this brand's site yet.
not_at_brand
None of your references is anywhere at the brand: it does not sell this product.
match_missed
One of your references is at the brand, but it is not matched yet.
no_ref
Your reference gives nothing to look up, like a bare model number.
sku_not_on_site
Written before the three above. The next check replaces it.
name_only
Only the name matched.
variant_unclear
The product matched, but not one of its variants for sure.
pack_mismatch
The two sides sell a different quantity.
starting_price
The brand shows a "from" price for a product you sell in one configuration.
second_hand
Second-hand pieces, with no list price.
other_product
A reference matched, but the items look different and Pinch did not confirm them.
brand_gone
The brand no longer sells it. Its last price proves nothing.
A match with no verdict
{
  "status": "not_found",
  "reason": "not_at_brand",
  "matchedBy": null,
  "confidence": null,
  "gap": null
}

Cheaper at the brand

too_high compares your crossed-out price with the brand's full price. brandCheaper compares your sale price with the brand's current price. It adds no status: a row is ok or too_high and can be cheaper at the brand as well.

A row counts when

Status
ok or too_high, so a pack, a starting price or an item the brand no longer sells never counts.
Brand
It has a price and is not sold out: brand.available is not false.
Gap
Your price is more than €1 above the brand's, the same threshold as too_high.

gapEur is the difference, gapPct its share of your price, seenAt the date we read the brand's price: a promotion can have ended since.

With group=product, a product is cheaper when one of its listed variants is, and its figure is the biggest gap.

curl "https://api.trawl.me/api/shops/matches?cheaper=true" \
  -H "Authorization: Bearer $TRAWL_API_KEY"
A row cheaper at the brand
{
  "status": "ok",
  "catalog": { "price": 80, … },
  "brand": { "price": 60, … },
  "brandCheaper": {
    "gapEur": 20,
    "gapPct": 25,
    "seenAt": "2026-11-02T05:40:00.000Z"
  }
}

How a match is made

Strongest proof first, against the brand's own site. One market and currency: France, euros.

barcode
The barcode.
sku
The full reference.
sku-stem, sku-seg
Its stem, or a segment of it.
sku-size
Your SKU with your size glued to its end.
sku-within
Your SKU inside a longer brand reference.
name-size, name-price
The same name with the same size, or the same price.
name, name-fuzzy, name-model
Name alone: shown to you, never judged.

A reference match is not enough alone. When the two items look different, Pinch reads both, and only a clear yes keeps the pair.

Two pack sizes, "from" prices, professional and subscription prices, and a brand price of 0 are never judged.

curl "https://api.trawl.me/api/shops/matches?search=NF-CREW-M" \
  -H "Authorization: Bearer $TRAWL_API_KEY"

Confidence

A level, not a percentage. You set your own rule for what reaches a product page.

high
Barcode or full reference, with a price verdict.
medium
A shortened reference, with a price verdict. It can be another colour of the same model.
low
A name match, or one we could not confirm or judge. Look before you use it.
null
No candidate at the brand, or nothing to compare.

With group=product, a product's confidence is the lowest of the variants listed.

curl "https://api.trawl.me/api/shops/matches?confidence=high&status=too_high" \
  -H "Authorization: Bearer $TRAWL_API_KEY"

Page verdicts

Which product page tells the buyer more.

brand_better
The brand's page tells more. Its lines are in fixes.
same
Both pages tell as much.
shop_better
Your page tells more.
null
One of the two pages is not read yet.

Size advice, usage tips, warnings and claims are left out. "Made in China" is never suggested.

curl "https://api.trawl.me/api/shops/matches?listing=brand_better&sort=impact" \
  -H "Authorization: Bearer $TRAWL_API_KEY"

CSV

Add format=csv to matches or fixes. Unpaged. A scraped text that starts like a formula stays text.

cURL
curl "https://api.trawl.me/api/shops/matches?sale=northfold&format=csv" \
  -H "Authorization: Bearer $TRAWL_API_KEY" \
  -o matches.csv
product_id, vendor, status, reason, matched_by,
title, variant, sku, barcode, price, crossed, url,
brand, brand_title, brand_price, brand_compare_at,
brand_full, brand_url, brand_seen_at, brand_gone,
gap_eur, gap_pct, listing, too_high_since,
checked_at, confidence, brand_available,
cheaper_eur, cheaper_pct

Good to know

Sales
A sale shows from the moment it is on your public site.
Rows
A variant with no crossed-out price, or no vendor, has no row.
Leaving
A product that leaves your catalog leaves your matches at the next check, its fix lines with it.
Brand content
Photos and texts come as the brand publishes them. You must have the brands' authorization before you reuse them.
Webhooks
Included with Shops.