fabric Promotions API

openapi: 3.2.0
info:
  title: Offers Promotions API
  description: 'fabric Promotions are discounts on items, carts, or shipping methods. These endpoints allow you to create and manage promotional discounts that are applied to a customers'' cart that meets the required conditions.

    <Note> Because promotions are linked to specific price lists, you must submit the correct price list ID. </Note>

    '
  version: 3.0.0
  x-audience: external-public
  termsOfService: https://fabric.inc/terms-of-use
  contact:
    name: Offers support
    email: support@fabric.inc
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
servers:
- url: https://api.fabric.inc/v3
  description: Production environment
tags:
- name: Promotions
paths:
  /promotions:
    get:
      tags:
      - Promotions
      summary: Get All Promotions
      description: Retrieves a paginated list of all promotions.
      operationId: getPromotions
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - $ref: '#/components/parameters/queryParameterSize'
      - $ref: '#/components/parameters/queryParameterOffset'
      - name: sort
        in: query
        description: The criteria to sort the results. Use the format {sort order}{field name}, where `-` refers to a descending order and `+` refers to an ascending order.
        required: false
        schema:
          type: string
          default: -updatedAt
          enum:
          - -updatedAt
          - +updatedAt
          - -startAt
          - +startAt
          - -endAt
          - +endAt
          - -name
          - +name
      - name: search
        in: query
        description: The keyword to filter the promotions.
        required: false
        schema:
          type: string
          example: BLACK FRIDAY
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPromotionsResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/badSizeError'
                - $ref: '#/components/schemas/badSortingError'
                - $ref: '#/components/schemas/missingTenantHeader'
                - $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    post:
      tags:
      - Promotions
      summary: Create Promotion
      description: Create a promotion to apply to one or more items to increase sales, or to a customer segment to reward existing customers or attract new ones. Promotions are configured with rules that define the promotion type, conditions, and discounts.
      operationId: createPromotion
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createPromotionRequest'
      responses:
        '201':
          description: Created
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createPromotionResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/promotionNameExists'
                - $ref: '#/components/schemas/promotionDateError'
                - $ref: '#/components/schemas/promotionBuyOperatorError'
                - $ref: '#/components/schemas/promotionDiscountRequired'
                - $ref: '#/components/schemas/promotionDiscountError'
                - $ref: '#/components/schemas/promotionFixedError'
                - $ref: '#/components/schemas/missingTenantHeader'
                - $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
  /promotions/{promotionId}:
    put:
      tags:
      - Promotions
      summary: Update a Specific Promotion
      description: Updates a specific promotion using the corresponding `promotionId`.
      operationId: updatePromotion
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - name: promotionId
        in: path
        required: true
        description: The promotion ID generated when using the [create promotion](/v3/api-reference/offers/promotions/create-promotion) endpoint.
        schema:
          type: string
          example: 61df12345678900009b7091c
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updatePromotionRequest'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updatePromotionResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/promotionNameExists'
                - $ref: '#/components/schemas/promotionDateError'
                - $ref: '#/components/schemas/promotionBuyOperatorError'
                - $ref: '#/components/schemas/promotionDiscountRequired'
                - $ref: '#/components/schemas/promotionDiscountError'
                - $ref: '#/components/schemas/promotionFixedError'
                - $ref: '#/components/schemas/promotionExpired'
                - $ref: '#/components/schemas/missingTenantHeader'
                - $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '404':
          description: Not Found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promotionNotFound'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    get:
      tags:
      - Promotions
      summary: Get a Specific Promotion
      description: Retrieves a specific promotion using the corresponding `promotionId`.
      operationId: getPromotion
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - in: path
        name: promotionId
        schema:
          type: string
          example: 61df12345678900009b7091c
        required: true
        description: The promotion ID generated when using the [create promotion](/v3/api-reference/offers/promotions/create-promotion) endpoint.
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPromotionResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/promotionInvalidId'
                - $ref: '#/components/schemas/missingTenantHeader'
                - $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '404':
          description: Not Found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promotionNotFound'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    delete:
      tags:
      - Promotions
      summary: Delete a Specific Promotion
      description: Delete a specific promotion using the corresponding `promotionId`.
      operationId: deletePromotion
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - name: promotionId
        in: path
        required: true
        description: The promotion ID generated when using the [create promotion](/v3/api-reference/offers/promotions/create-promotion) endpoint.
        schema:
          type: string
        example: 61dfc146bf98990009b7091c
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deletePromotionResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/promotionDeleteError'
                - $ref: '#/components/schemas/promotionInvalidId'
                - $ref: '#/components/schemas/missingTenantHeader'
                - $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '404':
          description: Not Found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promotionNotFound'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
  /promotions/{promotionId}/actions/toggle:
    post:
      tags:
      - Promotions
      summary: Enable or Disable a Promotion
      description: Use this endpoint to change the status of a promotion by enabling or disabling it. You can't change the status of a promotion that's currently in the `ACTIVE` state. You can enable promotions that are disabled or disable promotions that haven't yet expired.
      operationId: togglePromotion
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - in: path
        name: promotionId
        schema:
          type: string
          example: 61df12345678900009b7091c
        required: true
        description: The promotion ID generated when using the [create promotion](/v3/api-reference/offers/promotions/create-promotion) endpoint.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/togglePromotionRequest'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/togglePromotionResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/promotionDisabledError'
                - $ref: '#/components/schemas/promotionInvalidId'
                - $ref: '#/components/schemas/promotionActiveError'
                - $ref: '#/components/schemas/missingTenantHeader'
                - $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '404':
          description: Not Found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promotionNotFound'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
  /promotions/{promotionId}/actions/end:
    post:
      tags:
      - Promotions
      summary: End a Promotion
      description: End a specific promotion using the corresponding `promotionId`. To end a promotion, set the `status` to `EXPIRED` and set both the `startAt` and `endAt` dates to the current date.
      operationId: endPromotion
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      - in: path
        name: promotionId
        schema:
          type: string
          example: 61df12345678900009b7091c
        required: true
        description: The promotion ID generated when using the [create promotion](/v3/api-reference/offers/promotions/create-promotion) endpoint.
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promotionEndResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/promotionIsExpired'
                - $ref: '#/components/schemas/promotionInvalidId'
                - $ref: '#/components/schemas/missingTenantHeader'
                - $ref: '#/components/schemas/error400'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '404':
          description: Not Found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promotionNotFound'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
  /promotions/search:
    post:
      tags:
      - Promotions
      summary: Search for Promotions
      description: Use this endpoint to search for promotions based on specified filter conditions.
      operationId: searchPromotions
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricChannelId'
      - $ref: '#/components/parameters/xClientId'
      - $ref: '#/components/parameters/xFabricRequestId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchPromotionRequest'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchPromotionResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/error400'
                - $ref: '#/components/schemas/invalidSearchFilterField'
                - $ref: '#/components/schemas/invalidPromoState'
                - $ref: '#/components/schemas/invalidFilterOperator'
                - $ref: '#/components/schemas/invalidPromoStackingType'
                - $ref: '#/components/schemas/missingTenantHeader'
        '401':
          description: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error401'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
components:
  schemas:
    promotionActiveError:
      type: object
      description: Promotion isn't allowed to be updated when it's active
      properties:
        type:
          description: The error code.
          type: string
          example: PROMO_NOT_UPDATED
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Active promotion can't be updated
    promotionTargetProduct:
      type: array
      description: A list of target products for applying the discount.
      minItems: 1
      items:
        type: object
        description: The details of the target products.
        required:
        - type
        - values
        - operator
        properties:
          type:
            type: string
            description: The target type for the promotion.
            enum:
            - SKU
            - CATEGORY
            - ATTRIBUTE
            - PRICE_TYPE
            - COLLECTION
            - PREVIOUS_DISCOUNTS
            example: SKU
          values:
            description: The values corresponding to the selection `type`.
            oneOf:
            - type: string
              description: A list of target products. An asterisk (*) indicates all products are selected; hence, the discount is applied on all products.
              example: '*'
            - type: array
              items:
                oneOf:
                - type: integer
                  format: int32
                  description: A numeric identifier of the target record.
                  example: 10006123
                - type: string
                  description: A non-numeric identifier of the target record.
                  example: 61df12345678900009b7091c
                - type: object
                  description: The merchant-defined attributes associated with the promotion.
                  required:
                  - name
                  - value
                  properties:
                    name:
                      type: string
                      example: couponId
                      description: The merchant-defined `key` for the promotion.
                    value:
                      oneOf:
                      - type: string
                        example: '19822'
                        description: The merchant-defined `value` for the `key`.
                      - type: boolean
                        description: Represents a boolean value.
                        example: true
                      - type: number
                        description: Represents a numeric value.
                        example: 10006123
            - type: integer
              format: int32
              description: Condition numeric identifier
              example: 10006123
          operator:
            description: 'Indicates whether a target product is included or excluded from discounts. The following options are available:

              - `IN`: The target product, with the specified `type` and `value`, is included for the discount to be applied.

              - `NOT_IN`: The target product, with the specified `type` and `value`, is excluded from being discounted.

              - `EQUAL`: The target product will be eligible for the discount if the defined `type` and `value` match the product selection.

              '
            type: string
            enum:
            - IN
            - NOT_IN
            - EQUAL
            - GREATER_THAN
            example: IN
          discountId:
            type: string
            description: Discount ID to link `discount` and `targetProduct`; required for `BUYGET` promotion
            example: '1'
    promotionSegment:
      type: object
      description: The segment details.
      properties:
        id:
          type: integer
          format: int32
          example: 1000002
          description: The segment ID.
        name:
          type: string
          description: The segment name.
          example: Platinum customers
        defaultValue:
          type: array
          description: All segment values that belong to the segment.
          items:
            type: string
            description: The segment value.
            example: age
          example:
          - Teen
          - Young adult
          - Elderly
        value:
          oneOf:
          - type: array
            description: The customer segment to which promotion is applied.
            items:
              type: string
              description: The segment ID.
              example: Young adult
          - type: string
            description: All Segments
            example: '*'
    searchPromotionRequest:
      type: object
      description: The search criteria.
      properties:
        size:
          type: number
          default: 10
          minimum: 1
          maximum: 100
          description: The maximum number of records per page.
          example: 10
        offset:
          type: integer
          format: int32
          example: 10
          minimum: 0
          default: 0
          description: The number of records to skip before returning records. For example, with an offset of 20 and limit of 10, you will get records from 21 to 30.
        sort:
          type: string
          description: The criteria to sort the results. Use the format {sort order}{field name}, where `-` refers to a descending order and `+` refers to an ascending order.
          enum:
          - +updatedAt
          - +name
          - +startAt
          - +endAt
          - +level
          - -updatedAt
          - -name
          - -startAt
          - -endAt
          - -level
        filters:
          type: array
          items:
            type: object
            maxItems: 20
            required:
            - field
            - value
            - operator
            description: The filter conditions.
            properties:
              field:
                type: string
                description: The name of the field. This is always paired with `value`.
                minLength: 3
                maxLength: 120
                example: name
              value:
                description: The value or values corresponding to the `field`. This is always paired with `field`.
                oneOf:
                - type: string
                  minLength: 1
                  maxLength: 120
                  example: Summer
                - type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    description: Search multiple values in the same field.
                    oneOf:
                    - type: string
                      example: collectionId
                    - type: number
                      example: 100000234
                    - type: object
                      properties:
                        name:
                          type: string
                          description: The name to search. This is used to search based on segments or additional attributes.
                          minLength: 1
                          maxLength: 120
                          example: Season
                        value:
                          description: The value corresponding to the `name`. This is used to search based on segments or additional attributes.
                          oneOf:
                          - type: string
                            minLength: 1
                            maxLength: 120
                            example: Winter
                          - type: boolean
                            example: true
                          - type: number
                            example: 111
              operator:
                type: string
                description: The type of search operation. You can use multiple values, separated by commas, for the IN operation; however, you can only use a single value for the EQUALS, GREATER_THAN_OR_EQUAL_TO, and LESS_THAN operations.
                enum:
                - EQUAL
                - GREATER_THAN_OR_EQUAL_TO
                - LESS_THAN
                - IN
                example: EQUAL
    promotionAdditionalAttributes:
      description: Merchant-specified attributes associated with the promotion.
      type: array
      items:
        type: object
        description: Merchant-specified attributes associated with the promotion.
        required:
        - name
        - values
        properties:
          name:
            description: Merchant-specified attribute `name` associated with the promotion.
            type: string
            example: eventName
          values:
            oneOf:
            - type: string
              description: Merchant-specified attribute `value` associated with the promotion.
              example: Store sale
            - type: array
              description: Merchant-specified attribute `values` associated with the promotion.
              items:
                type: string
                description: Merchant-specified attribute `value` associated with the promotion.
                example:
                - Holiday
                - Christmas
    togglePromotionRequest:
      type: object
      description: Toggle data request
      required:
      - isEnabled
      properties:
        isEnabled:
          description: '- `true`: Promotion will be enabled.

            - `false`: Promotion will be disabled.

            '
          type: boolean
          example: false
    proximityMessages:
      type: object
      properties:
        threshold:
          type: integer
          minimum: 0
          description: The proximity threshold value. You muse use a value greater than or equal to 0.
          example: 1
        localizedMessages:
          type: array
          items:
            type: object
            properties:
              locales:
                type: array
                items:
                  type: string
                  description: The intended language or target region for the message.
                  example: en-CA
              message:
                type: string
                description: The localized message for the specified locales.
                example: Buy some more to get the discount!
    promotionConditionDetail:
      type: object
      description: Represents the conditions based on which the promotions apply. For example, consider the `type` is `USER_SEGMENT` with multiple values. To target all the specified segments, use the `AND` operator and to target any one of the segments, use the `OR` operator.
      required:
      - type
      - values
      - operator
      properties:
        type:
          type: string

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-promotions-api-openapi.yml