Catalog API
The Catalog API assists in the first step of your customer journey by providing a robust endpoint for product discovery. You can access the Catalog API in two ways.
Pre-configured catalog
Your business users can create a specific catalog of products from the universe of products available through a UI in their Orchestrpay dashboard. This is typically used when doing promotions or if you wish to display curated, cross-categories product lists.
In the example above, business users have created an "Eid Essentials" catalog manually and they're fetching it through the API to display the products assigned in the catalog in real time.
When you query the API with a pre-configured catalog, the data returned is in real-time, meaning any change that is made by business users through the dashboard will be reflected instantly.
You can also create multiple catalogs and assign tags to them, such as homepage, you can then query the Catalogs API to list all the categories that you should display on your homepage, allowing business users to take control of it without the need for pushing a software update.
Pre-configured catalogs have no category-specific attributes.
Querying live objects
The Catalog API also allows you to build a full fledged product browser with dynamic category-specific attributes, filtering and sorting.
The Display Size is a typical category-specific attribute present when you're browsing the "Television & Video" category as well as their sub-categories.
Note that the API doesn't return product rating or price range as category specific attribute, but you can hard code them in the UI and use them to query.
Fetch Catalogs
GET /catalogs
The below properties can be passed through the query string (e.g. /catalogs?filter.tags=homepage)
| Property | Description | Example |
|---|---|---|
filter.catalogId | The ID(s) of the pre-configured catalog. Use the $in filter operator if you want to browse multiple at once. by | ?filter.catalogId=$in:9ba08b71-ebb3-4be2-a604-00c6c5451a8f |
filter.tags | Browse products only from catalogs that have had this tag assigned by business users. | &filter.tags=homepage |
{
"catalogs": [
{
"id": "9ba08b71-ebb3-4be2-a604-00c6c5451a8f",
"title":{
"en": "Eid Essentials",
"ar": "أساسيات العيد",
},
"tags": ["homepage","eid2025","no-promo"],
"totalProducts": 192,
}
]
}
Fetch Categories
Pre-configured catalogs
GET /catalogs-products
The below properties can be passed through the query string (e.g. /catalogs-products?sortBy=popularity:DESC)
| Property | Description | Example |
|---|---|---|
filter.catalogId | The ID(s) of the pre-configured catalog. Use the $in filter operator if you want to browse multiple at once. by | ?filter.catalogId=$in:9ba08b71-ebb3-4be2-a604-00c6c5451a8f |
filter.tags | Browse products only from catalogs that have had this tag assigned by business users. | &filter.tags=homepage |
perPage | Number of products to display per page. Maximum value is 100. | &perPage=25 |
filter.ratingsCount | Filter based on the number of ratings that were submitted for the product. | &filters.ratingsAcount=$gt:100 |
filter.ratingsAverage | Filter based on the average rating of the products. | &filters.ratingsAverage=$btw:4,5 |
filter.title | Performs a full text search on the product title, uses the arabic title if any arabic letter is present in the value. | &filters.title=$ilike:ATA 32HON |
filter.price | Filter by product price. | &filters.price=$btw:35000,72000 |
isInStock | Defaults to true. | &isInStock=false |
sortBy | Default column to sort by. Available options are popularity, price, ratingsAverage. | &sortBy=popularity:ASC |
{
"catalogs": [
{
"title": {
"en": "Your catalog title"
},
"id": "9ba08b71-ebb3-4be2-a604-00c6c5451a8f",
"children": [],
"categoryAttributes": [],
"products": [
// An array of Product Objects
],
}
],
"pagination": {
"totalItems": 12,
"currentPage": 1,
"pageSize": 25,
"totalPages": 1
}
}
Querying live products
GET /category
The below properties can be passed through the query string (e.g. /category?sortBy=popularity:DESC)
| Property | Description | Example |
|---|---|---|
page | The current page to fetch the data for. | &page=3 |
perPage | Number of products to display per page. Maximum value is 100. | &perPage=25 |
filter.attr.{attribute} | Filters the products by the category-specific attribute ID, using our Filter Operators. | &filter.attr.3e449962-c304-402f-b0b9-a1be5b73565f=$in:[5f803479-2d79-40ff-8f0b-35162464181a,4c1881f2-d34c-4b3b-960b-bf7d5a12d420] This will return only TVs that are "LED & LCD TVs" or "OLED TVs". |
filter.ratingsCount | Filter based on the number of ratings that were submitted for the product. | &filters.ratingsAcount=$gt:100 |
filter.ratingsAverage | Filter based on the average rating of the products. | &filters.ratingsAverage=$btw:4,5 |
categoryId | The parent category that you're trying to fetch the products / child categories for. | &categoryId=3e449962-c304-402f-b0b9-a1be5b73565f` |
filter.title | Performs a full text search on the product title, uses the arabic title if any arabic letter is present in the value. | &filters.title=$ilike:ATA 32HON |
filter.price | Filter by product price. | &filters.price=$btw:35000,72000 |
isInStock | Defaults to true. | &isInStock=false |
sortBy | Default column to sort by. Available options are popularity, price, ratingsAverage. | &sortBy=popularity:ASC |
{
"categories": [
{
"title": {
"key": "category_electronics",
"en": "Electronics",
"ar": "Electronics",
},
"id": "3e449962-c304-402f-b0b9-a1be5b73565f",
"children": [
{
"title": {
"key": "category_led_lcd_tvs",
"en": "LED & LCD TVs",
"ar": "LED & LCD TVs"
},
"id": "5f803479-2d79-40ff-8f0b-35162464181a",
},
{
"title": {
"key": "category_oled_tvs",
"en": "OLED TVs",
"ar": "OLED TVs"
},
"id": "4c1881f2-d34c-4b3b-960b-bf7d5a12d420",
},
// ...
],
"categoryAttributes": [
{
"title": {
"key": "category_display_size",
"en": "Display Size",
"ar": "Display Size"
},
"id": "6769aaab-573b-4960-8757-db2a59b5df31",
"values": [
{
"id": "4a3df447-dd50-4ebe-aefd-af7306e7954e",
"title": {
"key": "attr_4a3df447-dd50-4ebe-aefd-af7306e7954e",
"en": "32",
"ar": "32"
},
},
{
"id": "0b462a50-8a28-4ece-877e-77fe1761a534",
"title": {
"key": "attr_0b462a50-8a28-4ece-877e-77fe1761a534",
"en":"39",
"ar":"39"
},
},
// ...
]
},
{
"title": {
"key": "category_brand",
"en": "Brand",
"ar": "Brand"
},
"id": "ec80351f-12b8-47c2-9378-d22ccbfa5a78",
"values": [
{
"title": {
"key": "attr_35f76f54-4deb-44bd-8a53-09aea6b3e50c",
"en": "AKAI",
"ar": "AKAI"
},
"id": "35f76f54-4deb-44bd-8a53-09aea6b3e50c"
},
{
"title": {
"key": "attr_e080646f-77a1-43a6-b92f-a5e61379464d",
"en": "Armadillo",
"ar": "Armadillo"
},
"id": "e080646f-77a1-43a6-b92f-a5e61379464d"
},
// ...
]
}
]
}
],
"products": [
// An array of Product Objects
],
"pagination": {
"totalItems": 290,
"currentPage": 1,
"pageSize": 25,
"totalPages": 12
}
}