# Promotions List List genuinely discounted products from a selected live Carrefour KSA campaign: Best Deals, Weekend Sale, or Monthly Stock Up. - Platform: [Carrefour KSA](https://docs.upscrape.com/docs/platforms/carrefourksa) - Capability ID: `carrefourksa.promotions.list` - Cost: 1 credit per request - Maximum runtime: 120 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 YOUR_API_KEY" \ --header "Content-Type: application/json" \ --header "Prefer: wait=30" \ --data '{ "input": { "page": 0, "page_size": 5, "promotion_type": "best_deals", "sort_by": "relevance" }, "capability": "carrefourksa.promotions.list" }' ``` ## Input | Field | Type | Required | Description | | --- | --- | --- | --- | | `page` | `integer` | No | 0-based campaign page. | | `page_size` | `integer` | No | Campaign products inspected per page. Maximum 100. | | `promotion_type` | `string` | No | Curated live Carrefour KSA promotion campaign. | | `sort_by` | `string` | No | Sort order. | ### Example input ```json { "page": 0, "page_size": 5, "promotion_type": "best_deals", "sort_by": "relevance" } ``` ## Response Successful output is returned in `results[0].data`. Raw platform output is intentionally open-ended and may evolve with the upstream source. ### Illustrative sample output This redacted fixture is an example, not a fixed response schema. ```json { "pagination": { "num_of_pages": 109, "page": 0, "returned_promotions": 3, "total_products": 545 }, "promotion": { "name": "Best Deals", "slug": "promo-ksa-best-dealss", "type": "best_deals", "upstream_name": "Best deals", "url": "https://www.carrefourksa.com/mafsau/en/c/promo-ksa-best-dealss" }, "promotions": [ { "soldByWeight": false, "isBulk": false, "ean": "6281012045324", "isFBC": false, "category": [ { "aliasName": "FKSA1500000", "id": "FKSA1500000", "level": 1, "name": "Beverages", "url": "/c/FKSA1500000/" }, { "aliasName": "FKSA1530000", "id": "FKSA1530000", "level": 2, "name": "Kids Drinks", "url": "/c/FKSA1530000/" }, { "aliasName": "FKSA1530100", "id": "FKSA1530100", "level": 3, "name": "Kids Juices", "url": "/c/FKSA1530100/" }, { "aliasName": "FKSA1530103", "id": "FKSA1530103", "level": 4, "name": "Kids Juice", "url": "/c/FKSA1530103/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/sys-master-root/hef/hbd/10957258489886/95637_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/sys-master-root/hef/hbd/10957258489886/95637_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/sys-master-root/hef/hbd/10957258489886/95637_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/kids-juice/suntop-orange-125ml-x18/p/95637", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 3 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "ageRestricted": false, "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Suntop Orange Juice 125ml Pack of 18", "id": "95637", "promoBadges": [], "productCategoriesHearchi": "Beverages/Kids Drinks/Kids Juices/Kids Juice", "price": { "currency": "SAR", "discount": { "endDate": "8/25/2026, 8:59:00 PM", "formattedValue": "SAR13.25", "minBuyingValue": "13.25", "price": 13.25, "type": "percentage", "value": 30 }, "formattedValue": "SAR19.00", "minBuyingValue": "19.00", "price": 19 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "125mlx18", "brand": { "id": "12788", "name": "Suntop" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "countryOrigin": null, "deliveryFees": { "freeDeliveryThreshold": 120 }, "productOrigin": null, "countryOriginEn": null, "nutritionIndicator": null, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 3, "maxToOrder": 3, "min": 1, "size": "125mlx18", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "collection_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "6281007045544", "isFBC": false, "category": [ { "aliasName": "FKSA1600000", "id": "FKSA1600000", "level": 1, "name": "Fresh Food", "url": "/c/FKSA1600000/" }, { "aliasName": "FKSA1670000", "id": "FKSA1670000", "level": 2, "name": "Meat & Poultry", "url": "/c/FKSA1670000/" }, { "aliasName": "FKSA1670300", "id": "FKSA1670300", "level": 3, "name": "Chicken", "url": "/c/FKSA1670300/" }, { "aliasName": "FKSA1670302", "id": "FKSA1670302", "level": 4, "name": "Chicken Breast", "url": "/c/FKSA1670302/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_main.jpg?im=Resize=1700", "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_1.jpg?im=Resize=1700", "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_2.jpg?im=Resize=1700", "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_3.jpg?im=Resize=1700", "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_4.jpg?im=Resize=1700", "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_5.jpg?im=Resize=1700", "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_6.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_1.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_1.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_2.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_2.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_3.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_3.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_4.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_4.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_5.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_5.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" }, { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_6.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/599582/1779012000/599582_6.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/chicken-breast/alyoum-chicken-breast-fillet-450g/p/599582", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "FRESH", "preorder": false, "howGood": false, "bulkMessage": "", "ageRestricted": false, "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Alyoum Fresh Chicken Breast Fillet Chilled 450g", "id": "599582", "promoBadges": [ { "id": "a72f55da-96e5-4e30-9b9c-d93188d791ca", "placement": "AREA-A", "priority": 1, "seller": "Carrefour", "text": { "boldText": "BESTSELLER", "normalText": "" }, "type": "BestSeller" } ], "productCategoriesHearchi": "Fresh Food/Meat & Poultry/Chicken/Chicken Breast", "price": { "currency": "SAR", "discount": { "endDate": "8/25/2026, 8:59:00 PM", "formattedValue": "SAR16.99", "minBuyingValue": "16.99", "price": 16.99, "type": "percentage", "value": 25 }, "formattedValue": "SAR22.75", "minBuyingValue": "22.75", "price": 22.75 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "450 g", "brand": { "id": "13621", "name": "Almarai:alyoum" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "countryOrigin": null, "deliveryFees": { "freeDeliveryThreshold": 120 }, "productOrigin": null, "countryOriginEn": null, "nutritionIndicator": null, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "450 g", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "collection_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] }, { "soldByWeight": false, "isBulk": false, "ean": "6281020300637", "isFBC": false, "category": [ { "aliasName": "FKSA1700000", "id": "FKSA1700000", "level": 1, "name": "Food Cupboard", "url": "/c/FKSA1700000/" }, { "aliasName": "FKSA1714000", "id": "FKSA1714000", "level": 2, "name": "Tins, Jars & Packets", "url": "/c/FKSA1714000/" }, { "aliasName": "FKSA1714600", "id": "FKSA1714600", "level": 3, "name": "Powdered Milk", "url": "/c/FKSA1714600/" } ], "freeGift": false, "amendableOrders": [], "links": { "defaultImages": [ "https://cdn.mafrservices.com/pim-content/SAU/media/product/158700/1767078603/158700_main.jpg?im=Resize=1700" ], "images": [ { "href": "https://cdn.mafrservices.com/pim-content/SAU/media/product/158700/1767078603/158700_main.jpg?im=Resize=200", "kind": "image", "properties": { "format": "plpThumbnail", "imageType": "GALLERY", "url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/158700/1767078603/158700_main.jpg?im=Resize=200" }, "rel": "assets", "type": "GET" } ], "productUrl": { "href": "/mafsau/en/powdered-milk/luna-milk-powder-pouch-2-25kg/p/158700", "kind": "product", "rel": "self", "type": "GET" }, "tracking": [] }, "type": "FOOD", "promoVoucher": {}, "variants": [], "dxtVouchers": [], "isMarketPlace": false, "availability": { "isAvailable": true, "max": 50 }, "servingIntents": [ "SLOTTED" ], "foodType": "DRY", "preorder": false, "howGood": false, "bulkMessage": "", "ageRestricted": false, "isVirtualBundle": false, "supplier": "Carrefour", "delivery": [], "name": "Luna Milk Powder Pouch 2.25Kg", "id": "158700", "promoBadges": [], "productCategoriesHearchi": "Food Cupboard/Tins, Jars & Packets/Powdered Milk", "price": { "currency": "SAR", "discount": { "endDate": "8/25/2026, 8:59:00 PM", "formattedValue": "SAR49.99", "minBuyingValue": "49.99", "price": 49.99, "type": "percentage", "value": 37 }, "formattedValue": "SAR79.95", "minBuyingValue": "79.95", "price": 79.95 }, "warranty": false, "extraLoyaltyPointsEarned": 0, "size": "2.25kg", "brand": { "id": "03315", "name": "Luna" }, "isExpress": false, "loyaltyPoints": 0, "isScalable": false, "isRecommended": false, "countryOrigin": null, "deliveryFees": { "freeDeliveryThreshold": 120 }, "productOrigin": null, "countryOriginEn": null, "nutritionIndicator": null, "unit": { "incrementBy": 1, "itemsPerUnit": 0, "max": 50, "maxToOrder": 50, "min": 1, "size": "2.25kg", "unitItem": 0, "unitOfMeasure": "pieces" }, "page_type": "collection_id", "stock": { "stockLevelStatus": "inStock" }, "isDirectMatch": false, "offers": [ { "brightbites": false, "id": "offer_carrefour_", "internationalShipping": false, "purchaseIndicators": { "SHIPPING": [ "SLOTTED" ] }, "sellerName": "Carrefour", "serviceProductTypes": null, "shippingIndicator": "SLOTTED", "shopId": "0000", "type": "main" } ], "availableVariants": [] } ] } ``` ### Illustrative output fields Derived from the sample above for orientation only. These fields are not a fixed response schema. | Path | Observed type | Example | | --- | --- | --- | | `pagination` | `object` | 4 fields | | `pagination.num_of_pages` | `integer` | 109 | | `pagination.page` | `integer` | 0 | | `pagination.returned_promotions` | `integer` | 3 | | `pagination.total_products` | `integer` | 545 | | `promotion` | `object` | 5 fields | | `promotion.name` | `string` | Best Deals | | `promotion.slug` | `string` | promo-ksa-best-dealss | | `promotion.type` | `string` | best_deals | | `promotion.upstream_name` | `string` | Best deals | | `promotion.url` | `string` | https://www.carrefourksa.com/mafsau/en/c/promo-ksa-best-dealss | | `promotions` | `array` | 3 items | | `promotions` | `array` | 3 items | ## 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)