> ## Documentation Index > Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # List all promotions > List all promotions ## OpenAPI ````yaml https://openapi.commercengine.io/ce-admin.json get /offer/promotions openapi: 3.1.0 info: title: CE Admin APIs version: '1.0' summary: Comprehensive admin interface for managing your e-commerce platform description: >- Complete administrative API suite for Commerce Engine, providing powerful tools to manage products, orders, customers, inventory, analytics, and system configuration. Designed for administrators and backend integrations requiring full platform control. license: name: All Rights Reserved url: https://www.commercengine.io/contact-us contact: email: support@commercengine.io url: https://www.commercengine.io/contact-us name: Support servers: - url: https://staging.api.commercengine.io/api/v1/{store_id}/admin description: Staging Server variables: store_id: default: store_id description: Store ID - url: https://prod.api.commercengine.io/api/v1/{store_id}/admin description: Prod Server variables: store_id: default: store_id description: Store ID security: - Authorization: [] tags: - name: Analytics description: Analytics - name: Catalog description: Catalog - name: Coupons & promotions description: Coupons & promotions - name: Customers description: Customers - name: Filter Options description: Filter Options - name: Inventories description: Inventories - name: Marketplace description: Marketplace - name: Marketplace Catalog description: Marketplace Catalog - name: Media Gallery description: Media Gallery - name: Metrics description: Metrics - name: Orders description: Orders - name: Payments description: Payments - name: Payouts description: Payouts - name: POS description: POS - name: POSAdmin description: Admin endpoints to be used as proxy in pos - name: Segments description: Segments - name: Shipping description: Shipping - name: SSE description: SSE - name: Store description: Store - name: Webhooks description: Webhooks paths: /offer/promotions: get: tags: - Coupons & promotions summary: List all promotions description: List all promotions operationId: list-promotions parameters: - $ref: '#/components/parameters/pageNumber' - $ref: '#/components/parameters/pageLimit' - $ref: '#/components/parameters/sortByOptions' - $ref: '#/components/parameters/searchKeyword' - $ref: '#/components/parameters/columnBasedFilters' responses: '200': description: OK content: application/json: schema: type: object properties: message: type: string success: type: boolean content: properties: promotions: type: array items: $ref: '#/components/schemas/Promotion' pagination: $ref: '#/components/schemas/Pagination' type: object components: parameters: pageNumber: name: page in: query required: false schema: type: integer default: 1 minimum: 1 description: page number of pagination list pageLimit: name: limit in: query required: false schema: type: integer default: 25 minimum: 1 description: no of rows per page sortByOptions: name: sort_by in: query required: false schema: description: >- json string in format {'field_name':'asc', 'other_field_name':'desc', ...} type: string description: 'JSON string format: {"field1":"asc", "field2":"desc"}' searchKeyword: name: search in: query required: false schema: type: string description: search keyword columnBasedFilters: name: filters in: query required: false schema: type: string example: >- {"condition":"AND","filters":[{"type":"data","field":"status","operator":"equals","value":"success"}]} description: JSON object schemas: Promotion: title: Promotion allOf: - oneOf: - $ref: '#/components/schemas/DiscountCouponPromotion' - $ref: '#/components/schemas/TieredDiscountCouponPromotion' - $ref: '#/components/schemas/FreeGoodCouponPromotion' - $ref: '#/components/schemas/BuyXGetYCouponPromotion' - $ref: '#/components/schemas/VolumeBasedCouponPromotion' - $ref: '#/components/schemas/FreeShipingCouponPromotion' - type: object required: - promotion_type - can_be_used_with_other_promotion properties: promotion_type: $ref: '#/components/schemas/PromotionType' can_be_used_with_other_promotion: type: boolean priority: type: - integer - 'null' maximum: 5 minimum: 1 x-tags: - Coupons & promotions Pagination: title: Pagination description: pagination metadata structure type: object properties: total_records: type: integer total_pages: type: integer previous_page: description: Previous page number type: - integer - 'null' limit: type: integer default: 25 next_page: description: Next page number type: - integer - 'null' DiscountCouponPromotion: title: DiscountCouponPromotion allOf: - $ref: '#/components/schemas/CouponPromotionCommonDetail' - type: object required: - details - applies_to_product properties: details: $ref: '#/components/schemas/DiscountRule' applies_to_product: enum: - all - product - category TieredDiscountCouponPromotion: title: TieredDiscountCouponPromotion allOf: - $ref: '#/components/schemas/CouponPromotionCommonDetail' - type: object required: - details properties: details: $ref: '#/components/schemas/TieredDiscountRule' FreeGoodCouponPromotion: title: FreeGoodCouponPromotion allOf: - $ref: '#/components/schemas/CouponPromotionCommonDetail' - type: object required: - details - applies_to_product properties: details: $ref: '#/components/schemas/FreeGoodsRule' applies_to_product: enum: - product BuyXGetYCouponPromotion: title: BuyXGetYCouponPromotion allOf: - $ref: '#/components/schemas/CouponPromotionCommonDetail' - type: object required: - details - applies_to_product properties: details: $ref: '#/components/schemas/BuyXGetYRule' applies_to_product: enum: - product VolumeBasedCouponPromotion: title: VolumeBasedCouponPromotion allOf: - $ref: '#/components/schemas/CouponPromotionCommonDetail' - type: object required: - details - applies_to_product properties: details: $ref: '#/components/schemas/VolumeBasedRule' applies_to_product: enum: - product FreeShipingCouponPromotion: title: FreeShipingCouponPromotion allOf: - $ref: '#/components/schemas/CouponPromotionCommonDetail' - type: object required: - details - applies_to_product properties: details: description: Send empty array. type: array default: [] applies_to_product: type: string const: all PromotionType: title: PromotionType type: string enum: - discount - tiered-discount - free-goods - free-shipping - buy-x-get-y - volume-based CouponPromotionCommonDetail: title: CouponPromotionCommonDetail type: object required: - name - status - customer_eligibility - starts_at properties: id: type: string readOnly: true name: type: string description: type: string tags: type: - array - 'null' items: type: string active: type: boolean readOnly: true status: description: >- this key is ignored in create coupon api and draft status will be added by default. required in update coupon api only. allOf: - $ref: '#/components/schemas/CouponPromotionStatus' customer_eligibility: enum: - all - customer - segment - customer-group customer_id: description: required if customer_eligibility = customer type: array items: type: string segment_id: description: required if customer_eligibility = segment type: array items: type: string customer_group_id: type: array items: type: string redemption_limits: type: - object - 'null' properties: total_redemptions: type: - integer - 'null' per_customer_redemptions: type: - integer - 'null' per_coupon_code_redemptions: type: - integer - 'null' required: - total_redemptions - per_customer_redemptions - per_coupon_code_redemptions redemption_count: type: integer readOnly: true minimum_order_total: description: >- Ignored when `coupon_type` or `promotion_type` is `tiered-discount`. Each slab in `details` defines its own `order_value` threshold. type: - integer - 'null' default: 0 for_first_time_customer_only: type: boolean default: false can_be_used_with_promotion: type: boolean default: false can_earn_loyalty_points: type: boolean default: true can_redeem_loyalty_points: type: boolean default: true starts_at: type: string format: date-time expires_at: type: - string - 'null' format: date-time created_at: type: string format: date-time readOnly: true modified_at: type: string format: date-time readOnly: true x-tags: - Coupons & promotions DiscountRule: title: DiscountRule oneOf: - $ref: '#/components/schemas/PercentageDiscountRule' - $ref: '#/components/schemas/FixedAmountDiscountRule' x-tags: - Coupons & promotions TieredDiscountRule: title: TieredDiscountRule type: object required: - slabs - maximum_discount_amount properties: slabs: type: array items: $ref: '#/components/schemas/TieredDiscountSlab' maximum_discount_amount: description: Caps the discount across all slabs. Use `null` for no cap. type: - number - 'null' x-tags: - Coupons & promotions FreeGoodsRule: title: FreeGoodsRule oneOf: - $ref: '#/components/schemas/AutoScaleBasedOnQuantity' - $ref: '#/components/schemas/AutoScaleBasedOnAmount' - $ref: '#/components/schemas/CustomSlabsBasedOnQuantity' - $ref: '#/components/schemas/CustomSlabsBasedOnAmount' x-tags: - Coupons & promotions BuyXGetYRule: title: BuyXGetYRule oneOf: - $ref: '#/components/schemas/BuyXGetYRuleBasedOnQuantity' - $ref: '#/components/schemas/BuyXGetYRuleBasedOnAmount' x-tags: - Coupons & promotions VolumeBasedRule: title: VolumeBasedRule type: object required: - products - maximum_discount_amount properties: products: type: array items: type: object required: - product_id - variant_id - slabs properties: product_id: type: - string - 'null' variant_id: type: - string - 'null' slabs: type: array items: type: object required: - quantity - condition - discount_percent properties: quantity: type: integer condition: enum: - less-or-equal - greater discount_percent: type: number maximum_discount_amount: type: - number - 'null' x-tags: - Coupons & promotions CouponPromotionStatus: title: CouponPromotionStatus type: string enum: - draft - scheduled - active - inactive PercentageDiscountRule: title: PercentageDiscountRule type: object required: - discount_type - discount_percent - maximum_discount_amount - products - category_id properties: discount_type: type: string const: percentage discount_percent: type: number maximum_discount_amount: type: - number - 'null' products: type: array items: type: object required: - product_id - variant_id - minimum_quantity - maximum_quantity - minimum_value - maximum_value properties: product_id: type: - string - 'null' variant_id: type: - string - 'null' minimum_quantity: type: - integer - 'null' maximum_quantity: type: - integer - 'null' minimum_value: type: - number - 'null' maximum_value: type: - number - 'null' category_id: description: Array of category ids type: array items: type: string x-tags: - Coupons & promotions FixedAmountDiscountRule: title: FixedAmountDiscountRule type: object required: - discount_type - fixed_discount_amount - products - category_id properties: discount_type: type: string const: fixed-amount fixed_discount_amount: type: number products: type: array items: type: object required: - product_id - variant_id - minimum_quantity - maximum_quantity - minimum_value - maximum_value properties: product_id: type: - string - 'null' variant_id: type: - string - 'null' minimum_quantity: type: - integer - 'null' maximum_quantity: type: - integer - 'null' minimum_value: type: - number - 'null' maximum_value: type: - number - 'null' category_id: description: Array of category ids type: array items: type: string x-tags: - Coupons & promotions TieredDiscountSlab: title: TieredDiscountSlab oneOf: - $ref: '#/components/schemas/PercentageTieredDiscountSlab' - $ref: '#/components/schemas/FixedAmountTieredDiscountSlab' x-tags: - Coupons & promotions AutoScaleBasedOnQuantity: title: AutoScaleBasedOnQuantity type: object required: - spending_criteria_type - products properties: spending_criteria_type: type: string const: minimum-quantity products: type: array items: type: object required: - product_id - variant_id - auto_scale - slab properties: product_id: type: - string - 'null' variant_id: type: - string - 'null' auto_scale: type: boolean const: true slab: type: object properties: buy_quantity: type: integer get_quantity: type: integer condition: enum: - greater-or-equal required: - buy_quantity - get_quantity - condition x-tags: - Coupons & promotions AutoScaleBasedOnAmount: title: AutoScaleBasedOnAmount type: object required: - spending_criteria_type - products properties: spending_criteria_type: type: string const: minimum-purchase-amount products: type: array items: type: object required: - product_id - variant_id - auto_scale - slab properties: product_id: type: - string - 'null' variant_id: type: - string - 'null' auto_scale: type: boolean const: true slab: type: object properties: minimum_purchase_amount: type: number get_quantity: type: integer condition: enum: - greater-or-equal required: - minimum_purchase_amount - get_quantity - condition x-tags: - Coupons & promotions CustomSlabsBasedOnQuantity: title: CustomSlabsBasedOnQuantity type: object required: - spending_criteria_type - products properties: spending_criteria_type: type: string const: minimum-quantity products: type: array items: type: object required: - product_id - variant_id - slabs properties: product_id: type: - string - 'null' variant_id: type: - string - 'null' slabs: type: array items: type: object properties: buy_quantity: type: integer get_quantity: type: integer condition: enum: - greater-or-equal required: - buy_quantity - get_quantity - condition x-tags: - Coupons & promotions CustomSlabsBasedOnAmount: title: CustomSlabsBasedOnAmount type: object required: - spending_criteria_type - products properties: spending_criteria_type: type: string const: minimum-purchase-amount products: type: array items: type: object required: - product_id - variant_id - slabs properties: product_id: type: - string - 'null' variant_id: type: - string - 'null' slabs: type: array items: type: object properties: minimum_purchase_amount: type: number get_quantity: type: integer condition: enum: - greater-or-equal required: - minimum_purchase_amount - get_quantity - condition x-tags: - Coupons & promotions BuyXGetYRuleBasedOnQuantity: title: BuyXGetYRuleBasedOnQuantity description: |- Additional fields required in addition to marked as required. 1) buy_product_id or buy_variant_id or buy_from_category_id 2) get_product_id or get_variant_id or get_from_category_id 3) get_free_quantity or get_discount_percent type: object required: - spending_criteria_type - products - maximum_discount_amount properties: spending_criteria_type: type: string const: minimum-quantity products: type: array items: type: object required: - minimum_quantity - buy_product_id - buy_variant_id - buy_from_category_id - get_product_id - get_variant_id - get_from_category_id - get_quantity - get_offer_type - get_discount_percent properties: minimum_quantity: type: integer minimum: 1 buy_product_id: type: - string - 'null' buy_variant_id: type: - string - 'null' buy_from_category_id: type: - string - 'null' get_product_id: type: - string - 'null' get_variant_id: type: - string - 'null' get_from_category_id: type: - string - 'null' get_quantity: type: integer minimum: 1 get_offer_type: enum: - discount - free get_discount_percent: description: It can be null for get_offer_type = free type: - number - 'null' maximum_discount_amount: description: It can be null for get_offer_type = free type: - number - 'null' x-tags: - Coupons & promotions BuyXGetYRuleBasedOnAmount: title: BuyXGetYRuleBasedOnAmount description: |- Additional fields required in addition to marked as required. 1) buy_product_id or buy_variant_id or buy_from_category_id 2) get_product_id or get_variant_id or get_from_category_id 3) get_free_quantity or get_discount_percent type: object required: - spending_criteria_type - products - maximum_discount_amount properties: spending_criteria_type: type: string const: minimum-purchase-amount products: type: array items: type: object required: - minimum_purchase_amount - buy_product_id - buy_variant_id - buy_from_category_id - get_product_id - get_variant_id - get_from_category_id - get_quantity - get_offer_type - get_discount_percent properties: minimum_purchase_amount: type: number minimum: 1 buy_product_id: type: - string - 'null' buy_variant_id: type: - string - 'null' buy_from_category_id: type: - string - 'null' get_product_id: type: - string - 'null' get_variant_id: type: - string - 'null' get_from_category_id: type: - string - 'null' get_quantity: type: integer minimum: 1 get_offer_type: enum: - discount - free get_discount_percent: description: It can be null for get_offer_type = free type: - number - 'null' maximum_discount_amount: description: It can be null for get_offer_type = free type: - number - 'null' x-tags: - Coupons & promotions PercentageTieredDiscountSlab: title: PercentageTieredDiscountSlab type: object required: - order_value - condition - discount_type - discount_percent properties: order_value: description: The order total the cart is evaluated against for this slab. type: number condition: description: >- This key defines how the system will evaluate the order total to determine if the discount should be applied, based on the specified slab. The last slab must use `greater` so the highest tier stays open-ended. enum: - less-or-equal - greater discount_type: type: string const: percentage discount_percent: type: number x-tags: - Coupons & promotions FixedAmountTieredDiscountSlab: title: FixedAmountTieredDiscountSlab type: object required: - order_value - condition - discount_type - fixed_discount_amount properties: order_value: description: The order total the cart is evaluated against for this slab. type: number condition: description: >- This key defines how the system will evaluate the order total to determine if the discount should be applied, based on the specified slab. The last slab must use `greater` so the highest tier stays open-ended. enum: - less-or-equal - greater discount_type: type: string const: fixed-amount fixed_discount_amount: type: number x-tags: - Coupons & promotions securitySchemes: Authorization: type: http scheme: bearer ````