ONDC Buyer App Util API'sVersion 1.0.0

Endpoint Details

This endpoint allows you to search catalog items using query terms with various filtering and pagination options.

endpoint:
  path: /catalogue/search
  method: GET
  headers:
    - name: X-API-KEY
      required: true
      description: API key for authentication. This header will be used to identify the consuming channel of the API.
  parameters:
    - name: q
      in: query
      description: Search query term (e.g., the catalogue name or keyword).
      required: true
      schema:
        type: string
    - name: page
      in: query
      description: Indicates the page number for pagination.
      required: false
      schema:
        type: integer
    - name: count
      in: query
      description: Specifies the number of items to return per page.
      required: false
      schema:
        type: integer
    - name: nonPaginated
      in: query
      description: If true, returns all items without pagination.
      required: false
      schema:
        type: boolean
  response:
    description: JSON object containing search results for catalog items based on the query string.

Endpoint Url:

/catalogue/search

Note: Append this path to the appropriate base URL mentioned in the Prerequisites section.

Endpoint Description and Usage:

This endpoint is used to search catalog items in the ONDC network based on query terms. The request requires a search query parameter and supports additional parameters for pagination and filtering. All responses are encrypted and require proper authentication headers.

Security

All requests to this endpoint must be authenticated using the required headers as specified in the Prerequisites section. Ensure that your API key is kept secure and not exposed in client-side code. Failure to provide valid authentication headers will result in a 401 Unauthorized error.

Sample Request:

Here is an example of a cURL command to search catalog items using this endpoint:

curl -X GET \
  {{base_url}}/catalogue/search?q=puma&page=1&count=10 \
  -H "X-API-KEY: YOUR_API_KEY"

Query Parameters

The GET request supports the following query parameters. The 'q' parameter is required for searching:

parameters:
  - name: q
    in: query
    description: Search query term (e.g., the catalogue name or keyword).
    required: true
    schema:
      type: string

  - name: page
    in: query
    description: Indicates the page number for pagination.
    required: false
    schema:
      type: integer

  - name: count
    in: query
    description: Specifies the number of items to return per page.
    required: false
    schema:
      type: integer

  - name: nonPaginated
    in: query
    description: If true, returns all items without pagination.
    required: false
    schema:
      type: boolean

Encrypted Response

When the search request is successful, the API returns an encrypted JSON response:

{
  "status": {
    "code": "200",
    "error": false
  },
  "message": "Success",
  "result": {
    "data": "MKrr+mebGq1DDyrPOOlDrrUhfkD1......................h/XDluF8ybOkCi0Qw==",
    "iv": "1a145a8c8fff7090"
  }
}

Decrypted Response

After decrypting the response data, you will get an array of catalog items matching your search query:

[
  {
    "updatedAt": "2024-09-17T02:20:09.163Z",
    "createdAt": "2024-09-17T02:20:09.163Z",
    "id": "ccd2cb9a-dcb2-4517-954b-e219e25df756",
    "name": "Puma",
    "shortDesc": "<ol>\r\n\t<li>Once a product has been ordered, any further deviations can happen only before 5 days of the proposed delivery...</li>\r\n</ol>\r\n",
    "longDesc": "<ol>\r\n\t<li>Once a product has been ordered, any further deviations can happen only before 5 days of the proposed delivery...</li>\r\n</ol>\r\n",
    "providerId": "48e5d0f1-6255-4f22-8b06-ed16951aa4ec",
    "tAndC": "<ol>\r\n\t<li>The website , https://in.puma.com is owned and operated by Puma Sports India Pvt Ltd...</li>\r\n</ol>\r\n",
    "howToRedeem": "<ol>\r\n\t<li>All customer / users of this web site hereby understand and agree...</li>\r\n</ol>\r\n",
    "denominations": "103,custom_amount",
    "customDenominations": true,
    "category": "C1",
    "denominationToItemId": [
      "103:ccd2cb9a-dcb2-4517-954b-e219e25df756",
      "custom_amount:ccd2cb9a-dcb2-4517-954b-e219e25df756"
    ],
    "defaultDiscount": 0,
    "logo": "https://catalogueproductfiles.s3.ap-south-1.amazonaws.com/brands/e6064c3df4b3bd1ee252780e7764ee8d7e8e9f7960f94ddf893a682bfc7b751a.png",
    "image": [
      "https://catalogueproductfiles.s3.ap-south-1.amazonaws.com/brands/2b0f9d530bda55cb1dbda4b4012398b0466.webp",
      "https://catalogueproductfiles.s3.ap-south-1.amazonaws.com/brands/e6064c3df4b3bd1ee252780e7764ee8d7e8e9f7960f94ddf893a682bfc7b751a.png"
    ],
    "minValue": 50,
    "maxValue": 5000
  }
]

Error Response

If there is an error with the request, the API will return a JSON object with error details:

{
  "status": {
    "code": "500",
    "error": true
  },
  "message": "Internal Server Error",
  "result": null
}

Response Schema (YAML)

The response schema for both encrypted and decrypted responses is as follows:

parameters:
  - name: status
    in: body
    description: Contains response metadata.
    required: true
    schema:
      type: object
      properties:
        code:
          type: string
          description: HTTP-style status code.
        error:
          type: boolean
          description: Indicates if the API encountered an error.

  - name: message
    in: body
    description: Human-readable message describing the result or error.
    required: true
    schema:
      type: string

  - name: result
    in: body
    description: Contains details of the result in case of success; will be null in case of an error.
    required: true
    schema:
      type: object
      nullable: true
      properties:	
        id:
          type: string
          description: Unique identifier for the catalogue item
        name:
          type: string
          description: Name of the catalogue item
        shortDesc:
          type: string
          description: Brief description of the item
        longDesc:
          type: string
          description: Detailed description of the item
        providerId:
          type: string
          description: Identifier for the provider offering the item
        tAndC:
          type: string
          description: Terms and conditions applicable to the item
        howToRedeem:
          type: string
          description: Instructions on how to redeem the item
        denominations:
          type: string
          description: Available denominations for the item
        customDenominations:
          type: boolean
          description: Indicates if custom denominations are supported
        category:
          type: string
          description: Category of the item
        denominationToItemId:
          type: array
          items:
            type: string
          description: Mapping of denomination values to item IDs
        defaultDiscount:
          type: number
          description: Default discount percentage applied to the item
        logo:
          type: string
          format: uri
          description: URL of the item's logo
        image:
          type: array
          items:
            type: string
            format: uri
          description: URLs of images related to the item
        minValue:
          type: number
          description: Minimum redeemable value for the item
        maxValue:
          type: number
          description: Maximum redeemable value for the item