> ## 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.

# Retrieve a promotion

> Returns a complete `PromotionDetail` object, including eligibility, redemption limits, and type-specific `details`.



## OpenAPI

````yaml https://openapi.commercengine.io/ce-admin.json get /offer/promotions/{id}
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: Segments
    description: Segments
  - name: Shipping
    description: Shipping
  - name: SSE
    description: SSE
  - name: Store
    description: Store
  - name: Webhooks
    description: Webhooks
paths:
  /offer/promotions/{id}:
    parameters:
      - name: id
        in: path
        description: promotion id
        required: true
        schema:
          type: string
    get:
      tags:
        - Coupons & promotions
      summary: Retrieve a promotion
      description: >-
        Returns a complete `PromotionDetail` object, including eligibility,
        redemption limits, and type-specific `details`.
      operationId: get-promotion
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  success:
                    type: boolean
                  content:
                    properties:
                      promotion:
                        $ref: '#/components/schemas/PromotionDetail'
                    type: object
components:
  schemas:
    PromotionDetail:
      title: PromotionDetail
      description: >-
        Full promotion returned on retrieve and update. Same shape as
        `Promotion`.
      allOf:
        - $ref: '#/components/schemas/Promotion'
      x-tags:
        - Coupons & promotions
    Promotion:
      title: Promotion
      allOf:
        - $ref: '#/components/schemas/CouponPromotionCommonDetail'
        - type: object
          required:
            - promotion_type
            - can_be_used_with_other_promotion
          properties:
            store_id:
              type: string
              readOnly: true
            promotion_type:
              $ref: '#/components/schemas/PromotionType'
            can_be_used_with_other_promotion:
              type: boolean
            priority:
              type:
                - integer
                - 'null'
              maximum: 5
              minimum: 1
            applies_to_product:
              enum:
                - all
                - product
                - category
            details:
              description: Promotion rules; shape depends on `promotion_type`.
              oneOf:
                - $ref: '#/components/schemas/AutoScaleBasedOnQuantity'
                - $ref: '#/components/schemas/AutoScaleBasedOnAmount'
                - $ref: '#/components/schemas/CustomSlabsBasedOnQuantity'
                - $ref: '#/components/schemas/CustomSlabsBasedOnAmount'
                - $ref: '#/components/schemas/BuyXGetYRuleBasedOnQuantity'
                - $ref: '#/components/schemas/BuyXGetYRuleBasedOnAmount'
                - $ref: '#/components/schemas/VolumeBasedRule'
                - $ref: '#/components/schemas/FreeShippingDetails'
                - $ref: '#/components/schemas/DiscountRule'
            terms_and_conditions:
              type:
                - array
                - 'null'
              items:
                type: string
      x-tags:
        - Coupons & promotions
    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
        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_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
    PromotionType:
      title: PromotionType
      type: string
      enum:
        - discount
        - free-goods
        - free-shipping
        - buy-x-get-y
        - volume-based
    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:
              sku:
                type:
                  - string
                  - 'null'
                readOnly: true
              product_name:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              stock_available:
                type: string
                readOnly: true
              images:
                type: string
                readOnly: true
              product_id:
                type:
                  - string
                  - 'null'
              variant_id:
                type:
                  - string
                  - 'null'
              auto_scale:
                type: boolean
              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:
              sku:
                type:
                  - string
                  - 'null'
                readOnly: true
              product_name:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              stock_available:
                type: string
                readOnly: true
              images:
                type: string
                readOnly: true
              product_id:
                type:
                  - string
                  - 'null'
              variant_id:
                type:
                  - string
                  - 'null'
              auto_scale:
                type: boolean
              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:
              sku:
                type:
                  - string
                  - 'null'
                readOnly: true
              product_name:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              stock_available:
                type: string
                readOnly: true
              images:
                type: string
                readOnly: true
              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
              auto_scale:
                type: boolean
                readOnly: true
      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:
              sku:
                type:
                  - string
                  - 'null'
                readOnly: true
              product_name:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              stock_available:
                type: string
                readOnly: true
              images:
                type: string
                readOnly: true
              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
              auto_scale:
                type: boolean
                readOnly: true
      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'
              minimum_purchase_amount:
                type:
                  - number
                  - 'null'
                readOnly: true
              auto_scale:
                type: boolean
                readOnly: true
        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'
              auto_scale:
                type: boolean
                readOnly: true
        maximum_discount_amount:
          description: It can be null for get_offer_type = free
          type:
            - number
            - 'null'
      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:
              sku:
                type:
                  - string
                  - 'null'
                readOnly: true
              product_name:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              stock_available:
                type: string
                readOnly: true
              images:
                type: string
                readOnly: true
              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
    FreeShippingDetails:
      title: FreeShippingDetails
      description: >-
        Free shipping has no rule. Returns `null` on read; send an empty array
        on write.
      type:
        - array
        - 'null'
      default: []
      maxItems: 0
      x-tags:
        - Coupons & promotions
    DiscountRule:
      title: DiscountRule
      type: object
      required:
        - discount_type
        - products
        - category_id
      properties:
        discount_type:
          type: string
          enum:
            - percentage
            - fixed-amount
        discount_percent:
          type: number
        fixed_discount_amount:
          type:
            - number
            - 'null'
        maximum_discount_amount:
          type:
            - number
            - 'null'
        products:
          type: array
          items:
            type: object
            properties:
              sku:
                type:
                  - string
                  - 'null'
                readOnly: true
              product_name:
                type: string
                readOnly: true
              status:
                type: string
                readOnly: true
              stock_available:
                type: string
                readOnly: true
              images:
                type: string
                readOnly: true
              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'
              minimum_purchase_amount:
                type:
                  - number
                  - 'null'
                readOnly: true
              auto_scale:
                type: boolean
                readOnly: true
        category_id:
          description: Array of category ids
          type: array
          items:
            type: string
      x-tags:
        - Coupons & promotions
    CouponPromotionStatus:
      title: CouponPromotionStatus
      type: string
      enum:
        - draft
        - scheduled
        - active
        - inactive
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.