Store coupons

Active coupons available at one store. Returns chain-wide coupons plus any store-scoped overrides, sorted with store-scoped first then by savings percentage descending.

GET/v1/stores/{store_id}/coupons$0.01

Path parameters

Name	Type	Description
`store_id`required	uuid	Canonical store id.

Query parameters

Name	Type	Description
`valid_on`	date	ISO date `YYYY-MM-DD`. Filters to coupons whose `valid_from ≤ valid_on ≤ valid_to`. Defaults to today (UTC).
`discount_type`	string	One of `percent_off`, `dollar_off`, `bogo`, `bundle`, `loyalty_price`, `featured`.
`exclude_featured`	booleandefault: `false`	When true, drops `discount_type='featured'` rows. Useful when "featured" is editorial-only at a chain.
`limit`	integerdefault: `50`	1–200.
`offset`	integerdefault: `0`	Cursor offset.

ℹ

Sort order

Store-scoped coupons (where coupons.store_id = store_id) sort first. Within each tier, rows order by savings_pct DESC. Ties break onvalid_to ASC.

Request

curl 'https://api.mainmarket.com/v1/stores/8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10/coupons?valid_on=2026-05-03&exclude_featured=true&limit=50'

Response

200 OKjson

{
  "count": 1,
  "results": [
    {
      "id": "0bc5b1d4-9a25-4d70-8a82-2ab3f6f1d901",
      "chain_id": "12d6...",
      "chain_name": "HEB",
      "chain_logo_url": "https://.../heb.png",
      "store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
      "product_id": "9d4e...",
      "product_name": "HEB Whole Milk",
      "product_brand": "HEB",
      "product_image_url": "https://.../milk.jpg",
      "discount_type": "dollar_off",
      "discount_value": 1.00,
      "min_purchase_qty": 1,
      "description": "$1 off any HEB gallon milk",
      "fine_print": "Limit 4 per transaction",
      "coupon_code": null,
      "valid_from": "2026-04-29",
      "valid_to": "2026-05-13",
      "image_url": "https://.../coupon.png",
      "is_digital_only": true,
      "requires_loyalty": true,
      "is_clippable": true,
      "deep_link_url": "heb://coupons/0bc5...",
      "source": "heb",
      "source_url": "https://www.heb.com/coupons/...",
      "size_text": "1 gal",
      "value_text": "$1 off",
      "catalog_price": 4.49,
      "total_savings": 1.00,
      "total_savings_basis": "catalog_price",
      "savings_pct": 22.27,
      "rating": "good",
      "deal_price": 3.49,
      "bogo_get_qty": null,
      "min_purchase_amount": null,
      "role": "buy"
    }
  ]
}

Each row uses the standard CouponRow shape — see List coupons for the full field reference.

Notable behavior

Coupons are matched to the store via the chain (store.chain_id = coupon.chain_id), plus any store-scoped overrides.
savings_pct requires a catalog_price baseline. Rows without a baseline are still returned but sort to the bottom with savings_pct = null.
Loyalty-required coupons (requires_loyalty=true) are returned by default. Filter them out client-side if your user isn't logged in.

Errors

Name	Type	Description
`404`	Not Found	store_id does not exist.
`422`	Unprocessable Entity	valid_on is not a valid date, or discount_type is unknown.
`402`	Payment Required	Paid route — no payment proof on the request.

Name

Type

Description

store_idrequired

uuid

Canonical store id.

Query parameters

Name	Type	Description
`valid_on`	date	ISO date `YYYY-MM-DD`. Filters to coupons whose `valid_from ≤ valid_on ≤ valid_to`. Defaults to today (UTC).
`discount_type`	string	One of `percent_off`, `dollar_off`, `bogo`, `bundle`, `loyalty_price`, `featured`.
`exclude_featured`	booleandefault: `false`	When true, drops `discount_type='featured'` rows. Useful when "featured" is editorial-only at a chain.
`limit`	integerdefault: `50`	1–200.
`offset`	integerdefault: `0`	Cursor offset.

ℹ

Sort order

Store-scoped coupons (where coupons.store_id = store_id) sort first. Within each tier, rows order by savings_pct DESC. Ties break onvalid_to ASC.

Response

200 OKjson

{
  "count": 1,
  "results": [
    {
      "id": "0bc5b1d4-9a25-4d70-8a82-2ab3f6f1d901",
      "chain_id": "12d6...",
      "chain_name": "HEB",
      "chain_logo_url": "https://.../heb.png",
      "store_id": "8c1a4d1e-30a7-4d92-9e1c-1cb43c6f2e10",
      "product_id": "9d4e...",
      "product_name": "HEB Whole Milk",
      "product_brand": "HEB",
      "product_image_url": "https://.../milk.jpg",
      "discount_type": "dollar_off",
      "discount_value": 1.00,
      "min_purchase_qty": 1,
      "description": "$1 off any HEB gallon milk",
      "fine_print": "Limit 4 per transaction",
      "coupon_code": null,
      "valid_from": "2026-04-29",
      "valid_to": "2026-05-13",
      "image_url": "https://.../coupon.png",
      "is_digital_only": true,
      "requires_loyalty": true,
      "is_clippable": true,
      "deep_link_url": "heb://coupons/0bc5...",
      "source": "heb",
      "source_url": "https://www.heb.com/coupons/...",
      "size_text": "1 gal",
      "value_text": "$1 off",
      "catalog_price": 4.49,
      "total_savings": 1.00,
      "total_savings_basis": "catalog_price",
      "savings_pct": 22.27,
      "rating": "good",
      "deal_price": 3.49,
      "bogo_get_qty": null,
      "min_purchase_amount": null,
      "role": "buy"
    }
  ]
}

Each row uses the standard CouponRow shape — see List coupons for the full field reference.

Notable behavior

Coupons are matched to the store via the chain (store.chain_id = coupon.chain_id), plus any store-scoped overrides.

savings_pct requires a catalog_price baseline. Rows without a baseline are still returned but sort to the bottom with savings_pct = null.

Loyalty-required coupons (requires_loyalty=true) are returned by default. Filter them out client-side if your user isn't logged in.

Name

Type

Description

404

Not Found

store_id does not exist.

422

Unprocessable Entity

valid_on is not a valid date, or discount_type is unknown.

402

Payment Required

Paid route — no payment proof on the request.