ONDC Buyer App Util API'sVersion 1.0.0

Endpoint Details

This endpoint allows you to get a list of catalog items with various filtering and sorting options.

endpoint:
  path: /catalogue
  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: orderBy
      in: query
      description: Specifies the field by which to order the results.
      required: false
      schema:
        type: string
    - name: order
      in: query
      description: Defines the sort order. Possible values are ASC (ascending) or DESC (descending).
      required: false
      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: likeBehaviour
      in: query
      description: Logical operator for combining filter conditions. Possible values are or or and.
      required: false
      schema:
        type: string
  response:
    description: JSON object containing catalog items with options to filter, sort, and paginate.

Endpoint Url:

/catalogue

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

Endpoint Description and Usage:

This endpoint is used to retrieve catalog items from the ONDC network. The request supports various query parameters for filtering, sorting, and pagination. 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 retrieve catalog items using this endpoint:

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

Query Parameters

The GET request supports the following optional query parameters for filtering and pagination:

parameters:
  - name: orderBy
    in: query
    description: Specifies the field by which to order the results.
    required: false
    schema:
      type: string

  - name: order
    in: query
    description: Defines the sort order. Possible values are ASC (ascending) or DESC (descending).
    required: false
    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: likeBehaviour
    in: query
    description: Logical operator for combining filter conditions. Possible values are or or and.
    required: false
    schema:
      type: string

Encrypted Response

When the 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:

[
  {
    "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