# Products list

Browse JioMart catalogue products with a filter expression, optional PIN context and continuation.

- Platform: [JioMart](https://docs.upscrape.com/docs/platforms/jiomart)
- Capability ID: `jiomart.products.list`
- Cost: 1 credit per request
- Maximum runtime: 30 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": {
    "filter": "journey:standard:::department:groceries",
    "page_size": 20,
    "pincode": "400001"
  },
  "capability": "jiomart.products.list"
}'
```

## Input

Use filter for a JioMart catalogue filter expression, such as a standard-journey department browse. pincode or location can provide request context; conflicting top-level and nested PINs are rejected.

page starts at 1. page_size accepts 1 to 100 and bounds the rows returned from one native page. Use page_id from the response to resume a sliced native page.

Keep filter, PIN, sort_on and page_size unchanged when following page_id. sort_on is passed through rather than locally re-sorting the page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | `string` | No |  |
| `location` | `object` | No |  |
| `location.city` | `string` | No | City name. |
| `location.latitude` | `string` | No | Latitude in decimal degrees. |
| `location.longitude` | `string` | No | Longitude in decimal degrees. |
| `location.pincode` | `string` | No | Postal code (PIN) that sets the delivery location. |
| `location.state` | `string` | No | State or region name. |
| `page` | `integer` | No | Native upstream page number. Use returned page_id continuation to consume every row when page_size is smaller than a native page. At least 1. |
| `page_id` | `string` | No | Use the returned pagination.next_cursor or page.next_id unchanged, with the same query, filter, collection, PIN, sort and page_size. |
| `page_size` | `integer` | No | Maximum products returned from one native page. Returned continuation preserves any remaining rows; no additional native pages are scanned in this call. From 1 to 100. |
| `pincode` | `string` | No | Postal code (PIN) that sets the delivery location. |
| `sort_on` | `string` | No | Passed unchanged to JioMart; results preserve JioMart's own order. price_asc is not guaranteed to be strictly ascending. No local page sorting. |

### Example input

```json
{
  "filter": "journey:standard:::department:groceries",
  "page_size": 20,
  "pincode": "400001"
}
```

## Response

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

Product rows are catalogue observations. Do not convert catalogue sellability, price or store IDs into a claim of verified local stock.

Use page.next_id or pagination.next_cursor for continuation. Numeric page selects a native JioMart page.

price_asc is not a guarantee of strict low-to-high order across the returned page or later pages.

### Illustrative sample output

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

```json
{
  "items": [
    {
      "brand": {
        "_custom_json": {},
        "action": {
          "page": {
            "query": {
              "brand": [
                ""
              ]
            },
            "type": "products"
          },
          "type": "page"
        },
        "name": "parle",
        "type": "brand",
        "uid": 3
      },
      "discount": "",
      "name": "Parle-G Biscuits 40 g",
      "price": {
        "currency_code": "INR",
        "currency_symbol": "₹",
        "effective": {
          "max": 5,
          "min": 5
        },
        "marked": {
          "max": 5,
          "min": 5
        }
      },
      "sellable": true,
      "slug": "parle-g-biscuits-45-g-mffner-7551663",
      "store_ids": [
        3442
      ],
      "type": "product",
      "uid": 7551663
    },
    {
      "brand": {
        "_custom_json": {},
        "action": {
          "page": {
            "query": {
              "brand": [
                ""
              ]
            },
            "type": "products"
          },
          "type": "page"
        },
        "name": "cadbury",
        "type": "brand",
        "uid": 91
      },
      "discount": "",
      "name": "Cadbury Gems Chocolate 6.61 g",
      "price": {
        "currency_code": "INR",
        "currency_symbol": "₹",
        "effective": {
          "max": 5,
          "min": 5
        },
        "marked": {
          "max": 5,
          "min": 5
        }
      },
      "sellable": true,
      "slug": "cadbury-gems-chocolate-711-g-mffmu2-7508008",
      "store_ids": [
        3442
      ],
      "type": "product",
      "uid": 7508008
    },
    {
      "brand": {
        "_custom_json": {},
        "action": {
          "page": {
            "query": {
              "brand": [
                ""
              ]
            },
            "type": "products"
          },
          "type": "page"
        },
        "name": "YIPPEE",
        "type": "brand",
        "uid": 2536
      },
      "discount": "",
      "name": "YiPPee Magic Masala Noodles with Added Veggies 25 g",
      "price": {
        "currency_code": "INR",
        "currency_symbol": "₹",
        "effective": {
          "max": 5,
          "min": 5
        },
        "marked": {
          "max": 5,
          "min": 5
        }
      },
      "sellable": true,
      "slug": "yippee-magic-masala-noodles-with-added-veggies-25g-mffn65-7533975",
      "store_ids": [
        3442
      ],
      "type": "product",
      "uid": 7533975
    }
  ],
  "page": {
    "has_next": true,
    "has_previous": false,
    "item_total": 188000,
    "next_id": "2",
    "type": "cursor"
  },
  "pagination": {
    "has_more": true,
    "next_cursor": "2",
    "total": 188000
  }
}
```
### Illustrative output fields

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

| Path | Observed type | Example |
| --- | --- | --- |
| `items` | `array` | 3 items |
| `items` | `array` | 3 items |
| `page` | `object` | 5 fields |
| `page.has_next` | `boolean` | true |
| `page.has_previous` | `boolean` | false |
| `page.item_total` | `integer` | 188000 |
| `page.next_id` | `string` | 2 |
| `page.type` | `string` | cursor |
| `pagination` | `object` | 3 fields |
| `pagination.has_more` | `boolean` | true |
| `pagination.next_cursor` | `string` | 2 |
| `pagination.total` | `integer` | 188000 |

## 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)