# List promotions

Find Blinkit deals on the home feed, in a product search or on a shelf, with discount and price filters.

- Platform: [Blinkit](https://docs.upscrape.com/docs/platforms/blinkit)
- Capability ID: `blinkit.promotions`
- Cost: 3 credits per request
- Maximum runtime: 60 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "limit": 5,
    "max_pages": 3,
    "max_scan": 60,
    "min_discount_percent": 20,
    "pincode": "560102",
    "query": "chips"
  },
  "capability": "blinkit.promotions"
}'
```

## Input

Choose exactly one location: a six-digit pincode, a place name in location_query, or both latitude and longitude. Do not combine location modes. A pincode represents one delivery point, not every address in the area.

Use query for search deals, subcategory_id for shelf deals, or neither for the home feed. Do not combine query and subcategory_id.

Search and shelf scans inspect up to max_scan distinct products: 100 by default, configurable from 1 to 500. max_pages also limits traversal. Discount, price and deal-type filters apply after scanning; the scan bound is not a count of returned deals. max_scan does not affect the home feed.

Use include to request fulfillment details where available.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deal_type` | `string` | No | Deal classification, or any_promotion for any evidenced deal or explicit offer marker. Allowed values: `percentage_discount`, `amount_discount`, `b1g1`, `free_item`, `flash_offer`, `any_promotion`. |
| `include` | `array<string>` | No | Optional fields or enrichments to include. Allowed values: `fulfillment`. |
| `latitude` | `number` | No | Latitude of the delivery address. From -90 to 90. |
| `limit` | `integer` | No | Maximum promotions returned. From 1 to 100. Default: `20`. |
| `location_query` | `string` | No | Free-text Indian location resolved before fetching location-dependent Blinkit data. |
| `longitude` | `number` | No | Longitude of the delivery address. From -180 to 180. |
| `max_pages` | `integer` | No | Maximum pages fetched from the selected source. From 1 to 20. Default: `3`. |
| `max_price` | `integer` | No | Return only product promotions whose normalized selling price is at or below this value. At least 0. |
| `max_scan` | `integer` | No | Maximum distinct products inspected in search/shelf mode, across at most max_pages pages. Filters are applied after scanning. No effect on the home feed. From 1 to 500. Default: `100`. |
| `min_discount_percent` | `number` | No | Return only promotions with a normalized percentage discount at or above this value. From 0 to 100. |
| `offset` | `integer` | No | Number of deduplicated promotions to skip. From 0 to 10000. Default: `0`. |
| `pincode` | `string` | No | Six-digit Indian pincode; surrounding whitespace is allowed and trimmed. Do not combine with coordinates. |
| `promotion_type` | `string` | No | Promotion placement type to return. Allowed values: `all`, `deals`, `banners`, `flash_offers`. Default: `all`. |
| `query` | `string` | No | Search for product deals. Cannot be combined with subcategory_id. |
| `subcategory_id` | `string` | No | Scan deals on this shelf. Cannot be combined with query. |

### Example input

```json
{
  "limit": 5,
  "max_pages": 3,
  "max_scan": 60,
  "min_discount_percent": 20,
  "pincode": "560102",
  "query": "chips"
}
```

## Response

Successful output is returned in `results[0].data`.

Prices, MRP and inventory can be null when Blinkit provides no value. A real zero stays zero. Keep stock_status (in_stock, low_stock, out_of_stock or unknown), available and is_sold_out separate from price. Missing or conflicting availability signals must remain unknown.

Check partial, partial_reason, scanned_products and has_more. An empty bounded scan does not prove there are no matching deals elsewhere.

### Illustrative sample output

This example shows one response. Values and optional fields vary with the data available.

```json
{
  "count": 5,
  "has_more": true,
  "limit": 5,
  "pages_fetched": 3,
  "partial": true,
  "partial_reason": "page_limit",
  "promotion_type": "all",
  "results": [
    {
      "deal_type": "percentage_discount",
      "deeplink_url": "https://blinkit.com/prn/cheetos-puffs-classic-cheese-flavour/prid/674950",
      "discount_amount": 40,
      "discount_percent": 29.85,
      "has_free_item": false,
      "image_url": "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1781603247372-381.png",
      "is_b1g1": false,
      "product": {
        "group_id": 2998111,
        "is_sponsored": true,
        "is_sold_out": false,
        "query": "chips",
        "price_per_unit": 0.696296,
        "rating": 4.6,
        "mrp": 134,
        "rating_count": 8605,
        "location": {
          "latitude": 12.911862,
          "longitude": 77.6445923,
          "pincode": "560102"
        },
        "fulfillment": null,
        "organic_rank": null,
        "discount_percent": 29.85,
        "captured_at": "2026-10-01T08:31:40Z",
        "stock_status": "in_stock",
        "merchant_type": "express",
        "inventory": 4,
        "name": "Cheetos Puffs (Classic Cheese Flavour)",
        "price_per_100_unit": 69.6296,
        "currency": "INR",
        "quantity": 135,
        "price": 94,
        "category_id": null,
        "discount_text": "29% OFF",
        "images": [
          "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1781603247372-381.png",
          "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1781603247372-382.png",
          "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1781603247372-383.png"
        ],
        "available": true,
        "rank": 1,
        "brand": "Cheetos",
        "image_url": "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1781603247372-381.png",
        "subcategory_name": null,
        "variant": "135 g",
        "subcategory_id": null,
        "category_name": null,
        "unit": "g",
        "product_id": 674950,
        "discount_amount": 40,
        "product_url": "https://blinkit.com/prn/cheetos-puffs-classic-cheese-flavour/prid/674950",
        "merchant_id": "40589"
      },
      "promotion_text": "29% OFF",
      "promotion_type": "deals",
      "rank": 1,
      "section": "search",
      "title": "Cheetos Puffs (Classic Cheese Flavour)"
    },
    {
      "deal_type": "percentage_discount",
      "deeplink_url": "https://blinkit.com/prn/beyond-snack-peri-peri-nendran-banana-chips/prid/452633",
      "discount_amount": 20,
      "discount_percent": 33.33,
      "has_free_item": false,
      "image_url": "https://cdn.grofers.com/da/cms-assets/cms/product/71bce0be-f774-4b43-a25d-3a7690afe644.png",
      "is_b1g1": false,
      "product": {
        "group_id": 2352996,
        "is_sponsored": true,
        "is_sold_out": false,
        "query": "chips",
        "price_per_unit": 0.533333,
        "rating": 4.7,
        "mrp": 60,
        "rating_count": 17268,
        "location": {
          "latitude": 12.911862,
          "longitude": 77.6445923,
          "pincode": "560102"
        },
        "fulfillment": null,
        "organic_rank": null,
        "discount_percent": 33.33,
        "captured_at": "2026-10-01T08:31:40Z",
        "stock_status": "in_stock",
        "merchant_type": "express",
        "inventory": 5,
        "name": "Beyond Snack Peri Peri Nendran Banana Chips",
        "price_per_100_unit": 53.3333,
        "currency": "INR",
        "quantity": 75,
        "price": 40,
        "category_id": null,
        "discount_text": "33% OFF",
        "images": [
          "https://cdn.grofers.com/da/cms-assets/cms/product/71bce0be-f774-4b43-a25d-3a7690afe644.png",
          "https://cdn.grofers.com/da/cms-assets/cms/product/238ec09b-4b4f-4111-9bd3-d2163eadf557.png",
          "https://cdn.grofers.com/da/cms-assets/cms/product/664df58d-3b74-4669-9a60-83720039166a.png"
        ],
        "available": true,
        "rank": 2,
        "brand": "Beyond Snack",
        "image_url": "https://cdn.grofers.com/da/cms-assets/cms/product/71bce0be-f774-4b43-a25d-3a7690afe644.png",
        "subcategory_name": null,
        "variant": "75 g",
        "subcategory_id": null,
        "category_name": null,
        "unit": "g",
        "product_id": 452633,
        "discount_amount": 20,
        "product_url": "https://blinkit.com/prn/beyond-snack-peri-peri-nendran-banana-chips/prid/452633",
        "merchant_id": "40589"
      },
      "promotion_text": "33% OFF",
      "promotion_type": "deals",
      "rank": 2,
      "section": "search",
      "title": "Beyond Snack Peri Peri Nendran Banana Chips"
    },
    {
      "deal_type": "percentage_discount",
      "deeplink_url": "https://blinkit.com/prn/snackible-peri-peri-ragi-chips/prid/481420",
      "discount_amount": 10,
      "discount_percent": 20,
      "has_free_item": false,
      "image_url": "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1786543175612-131.png",
      "is_b1g1": false,
      "product": {
        "group_id": 1257529,
        "is_sponsored": false,
        "is_sold_out": false,
        "query": "chips",
        "price_per_unit": 0.701754,
        "rating": 4.7,
        "mrp": 50,
        "rating_count": 20357,
        "location": {
          "latitude": 12.911862,
          "longitude": 77.6445923,
          "pincode": "560102"
        },
        "fulfillment": null,
        "organic_rank": 4,
        "discount_percent": 20,
        "captured_at": "2026-10-01T08:31:40Z",
        "stock_status": "in_stock",
        "merchant_type": "express",
        "inventory": 13,
        "name": "Snackible Peri Peri Ragi Chips",
        "price_per_100_unit": 70.1754,
        "currency": "INR",
        "quantity": 57,
        "price": 40,
        "category_id": null,
        "discount_text": "20% OFF",
        "images": [
          "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1786543175612-131.png",
          "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1786543175612-132.png",
          "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1786543175612-133.png"
        ],
        "available": true,
        "rank": 3,
        "brand": "Snackible",
        "image_url": "https://cdn.grofers.com/da/cms-assets/cms/product/rc-upload-1786543175612-131.png",
        "subcategory_name": null,
        "variant": "57 g",
        "subcategory_id": null,
        "category_name": null,
        "unit": "g",
        "product_id": 481420,
        "discount_amount": 10,
        "product_url": "https://blinkit.com/prn/snackible-peri-peri-ragi-chips/prid/481420",
        "merchant_id": "40589"
      },
      "promotion_text": "20% OFF",
      "promotion_type": "deals",
      "rank": 3,
      "section": "search",
      "title": "Snackible Peri Peri Ragi Chips"
    }
  ],
  "scanned_products": 36,
  "source": "search"
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `count` | `integer` | 5 |
| `has_more` | `boolean` | true |
| `limit` | `integer` | 5 |
| `pages_fetched` | `integer` | 3 |
| `partial` | `boolean` | true |
| `partial_reason` | `string` | page_limit |
| `promotion_type` | `string` | all |
| `results` | `array` | 3 items |
| `results` | `array` | 3 items |
| `scanned_products` | `integer` | 36 |
| `source` | `string` | search |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)