Catalogue API — Setu Docs

Reading time — 5 minutes

#Catalogue APIs

The catalogue resource is used to define the list of products housed by a single storefront.

The CRUD functionality for the catalogue resource is handled a little differently for the catalogue resource as compare to the seller and storefront resource. The only point of difference is the way the catalogue resource handles Add and Update functionality. Until now, Create was handled using POST where as Update was handled using PATCH and naturally these were two separate APIs. The catalogue resource handles Add and Update in a single API and utilises PUT to handle the same.

Even though they're the same API call for the sake of consistency we'll create separate sections for each of them.

The Catalogue API can be used to–

Add catalogue items for a storefront
Update catalogue items for a storefront
Delete catalogue items

#Add catalogue items for a storefront

Add a list of new catalogue items to a storefront's catalogue. The API is automatically treated as an Add catalogue items API, if new catalogue_item_id's are specified, or else will be used to update details against the provided id.

Sample Request

Method	`PUT`
Path	`/api/storefront/<storefront_id>/catalogue`

Sample Request Body

[
    {
        "catalogue_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "sub_categories": [
        "F&B"
        ],
        "catalogue_item_description": {
        "name": "",
        "symbol": "string",
        "short_description": "string",
        "long_description": "string",
        "images": [
            "string"
        ],
        "subcategory_specific_requirements": {
            "prepackaged_commodities": {
            "manufacturer_or_packer_name": "string",
            "manufacturer_or_packer_address": "string",
            "common_or_generic_name_of_commodity": "string",
            "manufacture_or_packing_date": "string",
            "imported_product_country_of_origin": "string"
            },
            "prepackaged_food": {
            "is_vegetarian": true,
            "ingredients_info": "string",
            "nutritional_info": "string",
            "additives_info": "string",
            "brand_owner_name": "string",
            "brand_owner_address": "string",
            "brand_owner_FSSAI_license_no": "string",
            "other_FSSAI_license_no": "string",
            "importer_name": "string",
            "importer_address": "string",
            "importer_FSSAI_logo": "string",
            "importer_FSSAI_license_no": "string",
            "imported_product_country_of_origin": "string",
            "other_importer_name": "string",
            "other_importer_address": "string",
            "other_premises": "string",
            "other_importer_country_of_origin": "string"
            },
            "food_beverages": {
            "is_vegetarian": true
            }
        },
        "price": {
            "is_selling_price_exclusive_of_gst": true,
            "max_retail_price": 130,
            "selling_price": 110,
            "sgst_tax_rate": null,
            "cgst_tax_rate": null,
            "igst_tax_rate": null,
            "total_tax_rate": 18,
        }
        },
        "inventory": { // 2000 SKUs each of 300 gm
        "unit_denomination": "GM", // ENUM
        "unit_value": 300, // Unit Denomination Multiple
        "quantity": 2000 
        },
        "item_policies": {
        "returnable": true,
        "return_window": 7,
        "seller_pickup_return": true,
        "cancellable": true,
        "cod_availability": true,
        "time_to_ship": 3,
        "max_sale_quantity": 0,
        "min_sale_quantity": 0
        },
        "serviceability": {
        "radius": 0,
        "pincodes": [
            0
        ]
        }
    }
]
    

Things to keep in mind—

sub_categories should be a subset of the categories parameter in the storefront. Please refer to X page for a complete list of categories and sub_categories
Currently, our system allows the user of these APIs to define a product within multiple sub_categories. Eg. [ "F&B" , "prepackaged_food"]
While subcategory_specific_requirements is optional, its values are sub_categories specific. For example, the said catalogue_item belongs to prepackaged_food then the parameters under subcategory_specific_requirements become mandatory.
It is quite possible that you don’t have all the fields available as text. ONDC and our system allows these values to be submitted as images in the catalogue_item_description
is_selling_price_inclusive_of_gst is used to signify the breakdown between taxable_value , tax_value and the selling_price . There are two possible cases—
1. selling_price is inclusive of applicable taxes, i.e. the selling_price is equal to the additiontaxable_value and tax_value. For this, set the "is_selling_price_inclusive_of_gst" as true
2. selling_price isn’t inclusive of the applicable taxes i.e the selling_price is the taxable_value. For this, set the "is_selling_price_inclusive_of_gst" as false
While sgst_tax_rate , cgst_tax_rate and igst_tax_rate are optional, If you are defining them please make sure they add upto to total_tax_rate
While we have already defined serviceability on a storefront level. We allow catalogue_items to overwrite the storefront’s serviceability . This is done to allow finer customisation. For example, fragile / fresh catalogue_items would like to have limited serviceability while the rest of the catalogue_items would like to have wider serviceability.

Sample Response

202 - EMPTY RESPONSE

#Update catalogue items for a storefront

Update a list of new catalogue items to a storefront’s catalogue. The API is automatically treated as an Add catalogue items API, if new catalogue_item_id’s are specified, or else will be used to update details against the provided id.

Sample Request

Method	`PUT`
Path	`/api/storefront/<storefront_id>/catalogue`

Sample Request Body

    PUT /api/storefronts/{storefront_id}/catalogue 
	[
  {
    "catalogue_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sub_categories": [
      "F&B"
    ],
    "catalogue_item_description": {
      "name": "",
      "symbol": "string",
      "short_description": "string",
      "long_description": "string",
      "images": [
        "string"
      ],
      "subcategory_specific_requirements": {
        "prepackaged_commodities": {
          "manufacturer_or_packer_name": "string",
          "manufacturer_or_packer_address": "string",
          "common_or_generic_name_of_commodity": "string",
          "manufacture_or_packing_date": "string",
          "imported_product_country_of_origin": "string"
        },
        "prepackaged_food": {
          "is_vegetarian": true,
          "ingredients_info": "string",
          "nutritional_info": "string",
          "additives_info": "string",
          "brand_owner_name": "string",
          "brand_owner_address": "string",
          "brand_owner_FSSAI_license_no": "string",
          "other_FSSAI_license_no": "string",
          "importer_name": "string",
          "importer_address": "string",
          "importer_FSSAI_logo": "string",
          "importer_FSSAI_license_no": "string",
          "imported_product_country_of_origin": "string",
          "other_importer_name": "string",
          "other_importer_address": "string",
          "other_premises": "string",
          "other_importer_country_of_origin": "string"
        },
        "food_beverages": {
          "is_vegetarian": true
        }
      },
      "price": {
        "is_selling_price_exclusive_of_gst": true,
        "max_retail_price": 130,
        "selling_price": 110,
        "sgst_tax_rate": null,
        "cgst_tax_rate": null,
        "igst_tax_rate": null,
        "total_tax_rate": 18,
      }
    },
    "inventory": { // 2000 SKUs each of 300 gm
      "unit_denomination": "GM", // ENUM
      "unit_value": 300, // Unit Denomination Multiple
      "quantity": 2000 
    },
    "item_policies": {
      "returnable": true,
      "return_window": 7,
      "seller_pickup_return": true,
      "cancellable": true,
      "cod_availability": true,
      "time_to_ship": 3,
      "max_sale_quantity": 0,
      "min_sale_quantity": 0
    },
    "serviceability": {
      "radius": 0,
      "pincodes": [
        0
      ]
    }
  }
]
    

Sample Response

202 - EMPTY RESPONSE

#Delete catalogue items

Deletes a list of existing catalogue items associated with a storefront

Sample Request

Method	`DELETE`
Path	`/api/storefront/<storefront_id>/catalogue`

Sample Request Body

{
	[
		{
			"catalogue_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
		}, 
		{
			"catalogue_item_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
		}
	[
}
    

Sample Response

202 - EMPTY RESPONSE