fabric Real-time Pricing Engine API

openapi: 3.2.0
info:
  title: Offers Real-time Pricing Engine API
  description: fabric's Real-time Pricing Engine (RTPE) endpoints are used to calculate prices and evaluate discounts for individual products and carts.
  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: Real-time Pricing Engine
paths:
  /price-engine/actions/evaluate-products-by-id:
    post:
      tags:
      - Real-time Pricing Engine
      summary: Calculate Prices for Products by Ids
      description: 'Use this endpoint to calculate prices for one or more products in a specific price list using item IDs. If you prefer to use SKUs to calculate product prices, use the [calculate prices for products by SKUs](/v3/api-reference/offers/real-time-pricing-engine/calculate-prices-for-products-by-skus) endpoint.

        '
      operationId: getPricesByProductId
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricDate'
      - $ref: '#/components/parameters/xFabricRequestId'
      - $ref: '#/components/parameters/xFabricChannelId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/evaluateProductsByIdRequest'
        required: true
      responses:
        '200':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluateProductsByIdResponse'
              examples:
                successResponseExample:
                  $ref: '#/components/examples/evaluateProductsSuccessById'
        '207':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Partially succeeded in getting results for each item. Check status in the retrieved objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluateProductsByIdResponse'
        '400':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '401':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceError'
              example:
                type: UNAUTHORIZED_ACCESS
                message: Unauthorized access
        '500':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceError'
              example:
                type: INTERNAL_SERVER_ERROR
                message: Internal Server Error
  /price-engine/actions/evaluate-products-by-sku:
    post:
      tags:
      - Real-time Pricing Engine
      summary: Calculate Prices for Products by Skus
      description: 'Use this endpoint to calculate prices for one or more products in a specific price list by product SKUs. If you prefer to use item IDs to calculate product prices, use the [calculate prices for products by item IDs](/v3/api-reference/offers/real-time-pricing-engine/calculate-prices-for-products-by-item-ids) endpoint.

        <Note>`itemId` is used as the default identifier for a product. If you want to set SKUs as product identifiers and use this endpoint, you must contact fabric support at support@fabric.inc.</Note>

        '
      operationId: evaluatePricesBySku
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricDate'
      - $ref: '#/components/parameters/xFabricRequestId'
      - $ref: '#/components/parameters/xFabricChannelId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/evaluateProductsBySkuRequest'
        required: true
      responses:
        '200':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluateProductsBySkuResponse'
              examples:
                successResponseExample:
                  $ref: '#/components/examples/evaluateProductsSuccessBySKU'
        '207':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Partially succeeded in getting results for each item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluateProductsBySkuResponse'
        '400':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '401':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceError'
              example:
                type: UNAUTHORIZED_ACCESS
                message: Unauthorized access
        '500':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceError'
              example:
                type: INTERNAL_SERVER_ERROR
                message: Internal server error
  /price-engine/actions/evaluate-cart:
    post:
      tags:
      - Real-time Pricing Engine
      summary: Evaluate Cart Promotions
      description: Evaluate cart's total cost instantly, after applying all applicable promotions and discount coupons. Using this endpoint, submit a range of data that will be referenced against the conditions that are set earlier using the promotions, coupons or prices APIs. The response includes the details of the promotions and discounts applied. These promotions and discounts can be displayed on your website to help shoppers know that they're getting their expected discounts.
      operationId: evaluateCart
      security:
      - AuthorizationToken: []
      parameters:
      - $ref: '#/components/parameters/xFabricTenantId'
      - $ref: '#/components/parameters/xFabricDate'
      - $ref: '#/components/parameters/xFabricRequestId'
      - $ref: '#/components/parameters/xFabricChannelId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/evaluateCartRequest'
        required: true
      responses:
        '200':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/evaluateCartResponse'
        '400':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
        '401':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceError'
              example:
                type: UNAUTHORIZED_ACCESS
                message: Unauthorized access
        '404':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceError'
              example:
                type: NOT_FOUND
                message: Item or SKU not found
        '500':
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/priceError'
              example:
                type: INTERNAL_SERVER_ERROR
                message: Internal server error
components:
  schemas:
    evaluateProductsByIdRequest:
      type: object
      required:
      - priceListId
      - itemIds
      description: A sample request to evaluate the prices of products by item IDs.
      properties:
        priceListId:
          description: The price list ID associated with the item generated using the [create price list](/v3/api-reference/offers/price-lists/create-price-list) endpoint.
          type: integer
          format: int32
          example: 100275
        itemIds:
          type: array
          description: A list of 50 or fewer item IDs to retrieve prices.
          example:
          - 111111
          - 222222
          minItems: 1
          maxItems: 50
          items:
            type: integer
            description: The product ID.
            example: 11111
            format: int32
        customer:
          $ref: '#/components/schemas/customer'
        priceParameters:
          type: array
          description: The parameters for price calculation.
          items:
            $ref: '#/components/schemas/priceParameterById'
        isAudit:
          type: boolean
          description: A flag indicating whether the audit details should be included in the response. Set to `true` to include the audit details along with the price calculation details and set to `false` to exclude the audit details in the response.
          example: true
        locale:
          type: string
          description: The language code, which is a combination of language in ISO 639 format and country in ISO 3166 format. The default value is en-US.
          example: en-US
    promotionDiscount:
      type: object
      description: Promotion discount
      example:
        amount: 100.15
        quantity: 1
        proratedAmount: 100.15
        proratedQuantity: 1
        application: 1
        promotion:
          id: 6197ec46e836ff000952d668
          value: 2000.15
          groupId: 61a6354d0d70e30009415f16
          level: 1
          isStackable: true
          isAlwaysApplied: true
          name: 20% OFF
          type: Coupon
          discountType: AMOUNT_OFF
          stackingType: STACKABLE
      properties:
        amount:
          type: number
          description: The actual discount amount applied to the price. For example, specifying 100.15 for a product with a base price of 2000.15 results in a discounted price of 1900.
          format: double
          example: 100.15
        quantity:
          type: integer
          description: The number of items eligible for the promotional discount.
          format: int32
          example: 5
        proratedAmount:
          type: number
          description: The discount amount distributed proportionally among all the selected items. The distribution is determined based on each item's price relative to the total price of all participating items. Typically, `proratedAmount` matches the `amount`. However, there might be variations, particularly in the context of Buy-Get promotions.
          format: double
          example: 1000.15
        proratedQuantity:
          type: integer
          description: This is used in conjunction with `proratedAmount` to determine the discount portion allocated to the respective units of BuyGet promotions. This is applicable in partial return scenarios.
          format: int32
          example: 5
        application:
          type:
          - integer
          - 'null'
          description: An identifier for an instance of the Buy-Get promotion that can be applied repeatedly. For example, consider a promotion - Buy 1 shirt and get 1 pant at a 20% off. If a shopper buys three shirts, 20% discount is individually applied to each shirt-pant pair. Each such discounted pair is assigned a unique `application` number for tracking purposes.
          format: int32
          example: 1
        promotion:
          type: object
          description: The promotion details.
          example:
            id: 6197ec46e836ff000952c668
            value: 2000.15
            groupId: 61a6354d0d70e30009415f16
            level: 1
            isStackable: true
            isAlwaysApplied: true
            name: 20% OFF
            type: Coupon
            discountType: AMOUNT_OFF
            stackingType: STACKABLE
          properties:
            id:
              type: string
              description: A 24-character system-generated coupon ID generated using the [create coupon](/v3/api-reference/offers/coupons/create-coupon) endpoint.
              example: 6197ec46e836ff000952c667
            value:
              type: number
              description: The discount in percent or amount.
              format: double
              example: 2000.15
            groupId:
              type:
              - string
              - 'null'
              description: ID of the group or category this product belongs to
              example: 61a6354d0d70e30009415f16
            level:
              type:
              - integer
              - 'null'
              description: The order in which the current promotion is executed.
              format: int32
              example: 1
            isStackable:
              type:
              - boolean
              - 'null'
              description: A flag indicating whether the promotion is stackable. Set to `true` to combine the given promotion with other promotions. The discount of the current promotion is combined with other promotions, if applicable, to the item. Set to `false` if the promotion isn't stackable; the given promotion can't be combined with other promotions.
              example: true
            isAlwaysApplied:
              type:
              - boolean
              - 'null'
              description: A flag indicating whether the promotion is always applied regardless of any exclusive promotions on the same item. Set to `true` if the promotion is always applied and set to `false` if the promotion isn't applied on the item by default.
              example: true
            stackingType:
              type: string
              description: "Defines the rules for how a promotion can be combined with other promotions. This field determines whether a specific promotion can be applied in conjunction with other active promotions during a transaction or if it must be used exclusively. Possible values: - `STACKABLE`: This promotion can be combined with other stackable promotions, allowing multiple\n  discounts to be applied together. The order in which stackable promotions are applied\n  is determined by the `level` field, with promotions having a higher priority (lower numeric value)\n  being applied before those with a lower priority.\n- `EXCLUSIVE`: This promotion can't be combined with any other promotions. The `level` field is\n  used to determine which exclusive promotion will be evaluated and applied first. Once an exclusive\n  promotion is applied, no other promotions can be used in the same transaction.\n- `TYPE_EXCLUSIVE`: This promotion can't be combined with other promotions of the same type.\n  The `level` field is used to determine which promotion within the same type will be evaluated and\n  applied first.\n- `UNIVERSAL`: This promotion can be combined with any other promotions without restrictions.\n  Universal promotions will be evaluated last."
              enum:
              - STACKABLE
              - EXCLUSIVE
              - TYPE_EXCLUSIVE
              - UNIVERSAL
              example: STACKABLE
            name:
              type: string
              description: The name of the promotion.
              example: 20% off
            type:
              type: string
              description: The type of the promotion.
              example: COUPON
            discountType:
              example: PERCENTAGE_OFF
              type: string
              description: The type of discount.
              enum:
              - PERCENTAGE_OFF
              - AMOUNT_OFF
              - FIXED_PRICE
    cartItemId:
      type: integer
      description: Item ID obtained from Product Catalog.
      format: int32
      example: 1730902008
    suggestedProduct:
      type: object
      description: Complimentary or free products offered to shoppers in the context of BuyGet and SpendGet promotions.
      properties:
        promotionId:
          type:
          - string
          - 'null'
          description: A 24-character system-generated coupon ID generated using the [create coupon](/v3/api-reference/offers/coupons/create-coupon) endpoint.
          example: 6197ec46e836ff000952c665
        promotionName:
          type:
          - string
          - 'null'
          description: The promotion name
          example: Buy shoes get socks for free
        itemId:
          type:
          - integer
          - 'null'
          description: The item ID of the free product
          format: int32
          example: 234343
        itemIds:
          type: array
          description: The suggested item IDs from which shoppers can choose one or more items based on the configuration of BuyGet promotion. Even if an item ID is already in the cart, they appear in the list of potential item IDs. This ensures visibility and enables shoppers to make informed decisions during the checkout process.
          items:
            type: integer
            description: The item ID of the free product.
            format: int32
            example: 500001
        sku:
          type: string
          description: The Stock Keeping Unit (SKU) of the free product.
          example: SHOE1234
        skus:
          type: array
          description: The suggested SKUs from which shoppers can choose one or more items based on the configuration of BuyGet promotion. Even if an SKU is already in the cart, they appear in the list of potential SKUs. This ensures visibility and enables shoppers to make informed decisions during the checkout process.
          items:
            type: string
            description: The Stock Keeping Unit (SKU) of the free product.
            example: SHOE-4
        eligiblePriceLists:
          type: array
          description: The [price list IDs](/v3/api-reference/offers/price-lists/create-price-list), eligible for promotions. When they're not specified, the promotion applies to all price lists. specified, promotion applies to all price lists.
          items:
            type: integer
            description: The price list ID associated with the item generated using the [create price list](/v3/api-reference/offers/price-lists/create-price-list) endpoint.
            format: int32
            example: 1000
        quantity:
          type: integer
          description: The number of complimentary items in the promotion.
          format: int32
          example: 2
        promotionQuantity:
          type: integer
          description: The maximum limit of complimentary items available for the BuyGet promotion. For example, consider the `promotionQuantity` is 10 and promotion condition is Buy 1 pair of shoes and Get 1 pair of socks free. If a shopper purchases up to 10 pairs of shoes, they will get an equivalent number of socks for free. However, even if they buy more than 10 pairs of shoes, the maximum free pairs of socks will remain 10, as defined by the `promotionQuantity` parameter.
          format: int32
          example: 10
        isFree:
          type: boolean
          description: A flag indicating whether a free item is included as part of promotion. Set to `true` to indicate a free item is offered as promotion and `false` to indicate otherwise.
        discountType:
          type: string
          description: The type of discount.
          example: PERCENTAGE_OFF
        amount:
          type: number
          description: The discount amount.
          format: double
          example: 100.15
    apiError:
      type: object
      description: The details of validation errors.
      properties:
        type:
          type: string
          description: The error code.
          example: BAD_REQUEST
        message:
          type: string
          description: An error message corresponding to the `type`.
          example: Request isn't valid
        errors:
          description: The error details.
          type: array
          items:
            $ref: '#/components/schemas/cartSubError'
    appliedDiscount:
      type: object
      description: Discount details
      example:
        promotionId: 6197ec46e836ff000952c665
        promotionName: Buy shoes get socks for free
        couponCode: SUPERCOUPON20
        type: COUPON
        amount: 105.15
      properties:
        promotionId:
          type:
          - string
          - 'null'
          description: A 24-character system-generated coupon ID generated using the [create coupon](/v3/api-reference/offers/coupons/create-coupon) endpoint.
          example: 6197ec46e836ff000952c664
        couponCode:
          type:
          - string
          - 'null'
          description: Coupon code
          example: SUPERCOUPON20
        promotionName:
          type:
          - string
          - 'null'
          description: Promotion name
          example: 20% off
        type:
          type:
          - string
          - 'null'
          description: Promotion type
          example: COUPON
        amount:
          type:
          - number
          - 'null'
          description: Discount amount
          format: double
          example: 10.15
    customer:
      type: object
      description: Customer details
      properties:
        id:
          type: string
          description: Unique identifier for the customer
          example: 5e2cfb9b45570b000864c4b5
        segments:
          type: array
          description: A list of segments the customer belongs to.
          example:
          - name: category
            value:
            - GOLD
            - YELLOW
          - name: ageGroup
            value:
            - elderly
          items:
            type: object
            properties:
              name:
                description: The name of the segment the customer belongs to.
                type: string
                example: category
              value:
                type: array
                description: The values of the segment associated with the customer.
                items:
                  type: string
                  description: Segment item
                  example: GOLD
    pdpSuggestedSKU:
      type: array
      description: A list of suggested products.
      items:
        description: The suggested product.
        type: object
        properties:
          promotionId:
            type: string
            description: A 24-character system-generated promotion ID generated using the [create promotion](/v3/api-reference/offers/promotions/create-promotion) endpoint.
            example: 6197ec46e836ff000952c668
          promotionName:
            type: string
            description: The name of the promotion.
            example: Buy Shoes, get socks for free
          skus:
            type: array
            description: A list of Stock Keeping Units (SKUs).
            items:
              description: SKU
              example: SKU1
              type: string
            example:
            - SOCK1
            - SOCK2
            - SOCKN
          eligiblePriceLists:
            type: array
            description: The eligible price lists.
            items:
              description: The price list ID associated with the item generated using the [create price list](/v3/api-reference/offers/price-lists/create-price-list) endpoint.
              example: 10000
              type: integer
              format: int32
            example:
            - 10000
          isFree:
            type: boolean
            description: A flag indicating whether the promotion offers complimentary items. Set to `true` if the promotion includes one or more complimentary items and `false` if it doesn't.
            example: false
          discountType:
            type: string
            description: The type of discount, such as PERCENTAGE_OFF, AMOUNT_OFF, or FIXED_PRICE.
            enum:
            - PERCENTAGE_OFF
            - AMOUNT_OFF
            - FIXED_PRICE
            example: PERCENTAGE_OFF
          amount:
            type: number
            description: The discount amount.
            format: double
            example: 50
          quantity:
            type: number
            description: The number of complimentary items in the cart.
            format: double
            example: 50
    promotionDiscountWithPromoMessage:
      type: object
      description: Promotion discount
      example:
        amount: 100.15
        quantity: 1
        application: 1
        promotion:
          id: 6197ec46e836ff000952d668
          value: 2000.15
          groupId: 61a6354d0d70e30009415f16
          level: 1
          isStackable: true
          isAlwaysApplied: true
          name: 20% OFF
          type: Coupon
          discountType: AMOUNT_OFF
          stackingType: STACKABLE
          promotionMessages:
          - promoId: 6197ec46e836ff000952c666
            title: Get 50% off socks when buying shoes!
            message: Buy any pair of shoes and get 50% off a pair of socks.
            locales:
            - en-US
            - en-GB
            pages:
            - PDP
            - CART
            type: DISCOUNT
      properties:
        amount:
          type: number
          description: The actual amount of the discounts applied to the price. For example, entering 100.15 for a product with a base price of 2000.15 results in a discounted price of 1900.
          format: double
          example: 100.15
        quantity:
          type: integer
          description: The number of items eligible for the promotional discount.
          format: int32
          example: 5
        application:
          type:
          - integer
          - 'null'
          description: The number of times the BuyGet promotion can be used, indicating how many times you can use the promotions, such as get a certain amount or percentage off, or get free items when making a purchase.
          format: int32
          example: 1
        promotion:
          type: object
          description: Promotion object
          example:
            id: 6197ec46e836ff000952c668
            value: 2000.15
            groupId: 61a6354d0d70e30009415f16
            level: 1
            isStackable: true
            isAlwaysApplied: true
            name: 20% OFF
            type: Coupon
            discountType: AMOUNT_OFF
            stackingType: STACKABLE
            promotionMessages:
            - promoId: 6197ec46e836ff000952c666
              title: Get 50% off socks when buying shoes!
              message: Buy any pair of shoes and get 50% off a pair of socks.
              locales:
              - en-US
              - en-GB
              pages:
              - PDP
              - CART
              type: DISCOUNT
          properties:
            id:
              type: string
              description: A 24-character system-generated coupon ID generated using the [create coupon](/v3/api-reference/offers/coupons/create-coupon) endpoint.
              example: 6197ec46e836ff000952c667
            value:
              type: number
              description: The discount applied to the price. This can be specified as a percentage or a fixed amount.
              format: double
              example: 2000.15
            groupId:
              type:
              - string
              - 'null'
              description: ID of the group or category this product belongs to
              example: 61a6354d0d70e30009415f16
            level:
              type:
              - integer
              - 'null'
              description: The order in which the current promotion is executed.
              format: int32
              example: 1
            isStackable:
              type:
              - boolean
              - 'null'
              description: 'Specifies whether the promotion is stackable. You can set one of the following: - `true`: This promotion can be combined with other stackable promotions, allowing multiple discounts to be applied together. - `false`: The promotion isn''t stackable. You can''t combine this promotion with other promotions.'
              example: true
            isAlwaysApplied:
              type:
              - boolean
              - 'null'
              description: 'Specifies whether the promotion is applied regardless of the exclusive promotions on the same item. You can set one of the following values: - `true`: Promotion is applied regardless of the exclusive promotions on the same item. - `false`: Promotion isn''t applied on the item.'
              example: true
            stackingType:
              type: string
              description: "Defines the rules for how a promotion can be combined with other promotions. This field determines whether a specific promotion can be applied in conjunction with other active promotions during a transaction or if it must be used exclusively. Possible values: - `STACKABLE`: This promotion can be combined with other stackable promotions, allowing multiple\n  discounts to be applied together. The order in which stackable promotions are applied\n  is determined by the `level` field, with promotions having a higher priority (lower numeric value)\n  being applied before those with a lower priority.\n- `EXCLUSIVE`: This promotion can't be combined with any other promotions. The `level` field is\n  used to determine which exclusive promotion will be evaluated and applied first. Once an exclusive\n  promotion is applied, no other promotions can be used in the same transaction.\n- `TYPE_EXCLUSIVE`: This promotion can't be combined with other promotions of the same type.\n  The `level` field is used to determine which promotion within the same type will be evaluated and\n  applied first.\n- `UNIVERSAL`: This promotion can be combined with any other promotions without restrictions.\n  Universal promotions will be evaluated last."
              enum:
              - STACKABLE
              - EXCLUSIVE
              - TYPE_EXCLUSIVE
              - UNIVERSAL
              example: STACKABLE
            name:
              type: string
              description: Promotion name
              example: 20% off
            type:
              type: string
              description: Promotion type
              example: COUPON
            discountType:
              example: PERCENTAGE_OFF
              type: string
              description: Discount type
              enum:
              - PERCENTAGE_OFF
              - AMOUNT_OFF
              - FIXED_PRICE
            promotionMessages:
              $ref: '#/components/schemas/rtpePromot

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-real-time-pricing-engine-api-openapi.yml