fabric Real-time Pricing Engine API

openapi: 3.0.1
info:
  title: Cart Actions Endpoints Real-time Pricing Engine API
  description: fabric's **Cart API** lets you add, update, and remove items from your Storefront cart, either as a guest user or as a logged-in user. It also provides functionality to merge carts when you switch from guest user to logged-in user, and apply coupons and other attributes (for example, gift wrapping) to the line items. Additionally, the API supports more advanced tasks such as using multiple carts within a B2B organization, sharing carts, and supporting a unified cart experience for multi-region and multi-brand businesses.<p>The Cart API provides high performance, scalability, multi-tenancy, and configurability to the end-to-end order processing actions that start from the item being added to the cart; through the pre-checkout stage that includes billing, shipping, and payment details; to the checkout stage where the order is processed and confirmed by fabric's Order Management System (OMS)
  contact:
    name: Cart Support
    email: support.cnc@fabric.inc
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
security:
- bearerAuth: []
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:
    priceError:
      type: object
      description: The validation errors related to the price.
      properties:
        type:
          type: string
          description: The error code.
          example: Not found
        message:
          type: string
          description: An error message corresponding to the `type`.
          example: Price doesn't exist for product 179089, channels [12, 10], date Wed Nov 16 14:11:16 UYT 2022 and price lists [197090]
    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
    priceParameterBySku:
      allOf:
      - $ref: '#/components/schemas/priceParameter'
      - type: object
        properties:
          sku:
            type: string
            description: Product SKU
            example: '1000019501'
          quantity:
            type: integer
            description: Number of products ordered. This value is required for the range-based pricing method.
            format: int32
            example: 500
    notAppliedCoupon:
      type: object
      description: Coupon details
      example:
        couponCode: SUPERCOUPON
        promotionId: 624b5aa2a8fd12000965dfdc
        message: Invalid coupon
      properties:
        couponCode:
          type: string
          nullable: true
          description: Coupon code
          example: SUPERCOUPON
        promotionId:
          type: string
          nullable: true
          description: A 24-character system-generated coupon ID generated using the [create coupon](/v3/api-reference/offers/coupons/create-coupon) endpoint.
          example: 624b5aa2a8fd12000965dfdc
        message:
          type: string
          nullable: true
          description: Reason why coupon not applied
          example: Invalid coupon
    shippingDetailReference:
      description: Shipping details reference
      type: object
      properties:
        shippingCost:
          type: number
          format: double
          description: Shipping cost
          example: 150.25
        shippingMethodId:
          type: string
          description: Shipping method ID
          example: dfsae-2d32113-32lpdd
        shippingDiscount:
          type: number
          format: double
          description: Discount amount
          example: 150.25
        shippingMethodName:
          type: string
          description: Shipping method name
          nullable: true
          example: Express Delivery
    calculatedPriceOffersByProductId:
      type: object
      description: Discounts or special offers applied to the price.
      properties:
        price:
          $ref: '#/components/schemas/calculatedPriceObject'
        discounts:
          type: array
          description: A list of discounts applied to the price.
          items:
            $ref: '#/components/schemas/promotionDiscountWithPromoMessage'
        additionalAttributes:
          type: array
          description: A placeholder for additional price attributes, in name-values pairs.
          items:
            type: object
        promotionMessages:
          $ref: '#/components/schemas/rtpePromotionMessages'
    suggestedProduct:
      type: object
      description: Complimentary or free products offered to shoppers in the context of BuyGet and SpendGet promotions.
      properties:
        promotionId:
          type: string
          nullable: true
          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
          nullable: true
          description: The promotion name
          example: Buy shoes get socks for free
        itemId:
          type: integer
          nullable: true
          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
    rtpePromotionMessages:
      allOf:
      - $ref: '#/components/schemas/promotionMessages'
      - type: array
        items:
          type: object
          properties:
            promoId:
              type: string
              description: A 24-character system-generated coupon ID generated using the [create coupon](/v3/api-reference/offers/coupons/create-coupon) endpoint.
              example: 61df12345678900009b7091c
    cartProductAttribute:
      description: Product attribute as defined within Product Catalog.
      required:
      - value
      - name
      type: object
      properties:
        attributeId:
          type: string
          description: Attribute ID
          example: 60c2a358eb2ec30008ae70a1
        name:
          type: string
          description: Attribute name
          example: gift wrapping (small)
        description:
          type: string
          description: Attribute description
          nullable: true
          example: Gift wrapping for a small package
        mapping:
          type: string
          description: Attribute mapping
          nullable: true
          example: ITEM
        type:
          type: string
          description: Attribute type
          example: GIFT
          nullable: true
        value:
          type: string
          description: Attribute value
          nullable: true
          example: 'true'
        price:
          type: number
          format: double
          nullable: true
          description: Attribute price
          example: 10
        level:
          type: string
          description: Attribute level
          nullable: true
          example: order
    evaluateCartResponse:
      type: object
      description: The response of the evaluation request of the cart promotion.
      properties:
        cartItems:
          type: array
          description: The list of items in the cart.
          items:
            allOf:
            - $ref: '#/components/schemas/lineItemReference'
            - type: object
              description: The discount details.
              properties:
                discounts:
                  type: array
                  description: A list of applicable discounts.
                  items:
                    $ref: '#/components/schemas/promotionDiscount'
            - type: object
              description: The details of price attributes.
              properties:
                priceAttributes:
                  $ref: '#/components/schemas/priceAttributes'
            - $ref: '#/components/schemas/productCollectionsReference'
        errors:
          type: array
          description: The error details.
          example:
          - Parameter doesn't exist
          items:
            type: string
            description: The list of errors.
            example: Parameter doesn't exist
        appliedDiscounts:
          type: array
          description: The details of the discounts applied to the cart.
          items:
            $ref: '#/components/schemas/appliedDiscount'
          example:
          - promotionId: 6197ec46e836ff000952c665
            promotionName: Buy shoes get socks for free
            couponCode: SUPERCOUPON20
            type: COUPON
            amount: 105.15
            discountScope: SKU
            discountType: AMOUNT_OFF
            value: 10
        suggestedProducts:
          type: array
          description: Suggested free products
          items:
            $ref: '#/components/schemas/suggestedProduct'
          example:
          - promotionId: 6197ec46e836ff000952c665
            promotionName: Buy shoes get socks for free
            itemId: 234343
            itemIds:
            - 1120201
            - 1120202
            sku: SHOE1234
            skus:
            - SHOE-1
            - SHOE-2
            eligiblePriceLists:
            - 10000
            quantity: 2
            promotionQuantity: 10
            isFree: true
            discountType: PERCENTAGE_OFF
            amount: 105.15
        notAppliedCoupons:
          type: array
          description: Rejected coupons
          items:
            $ref: '#/components/schemas/notAppliedCoupon'
          example:
          - couponCode: SUPERCOUPON
            promotionId: 624b5aa2a8fd12000965dfdc
            message: Invalid coupon
        promotionMessages:
          $ref: '#/components/schemas/rtpePromotionMessages'
    promotionMessages:
      type: array
      description: The promotion message that is displayed to the customer.
      required:
      - message
      - locales
      - type
      items:
        type: object
        description: Message description for the promotion
        properties:
          title:
            type: string
            description: Message name
            example: Buy 2 get 1 free
          message:
            type: string
            description: Message description
            example: Offer valid at participating stores through September 5, 2023.
          pages:
            type: array
            description: The types of web pages where the message is displayed.
            items:
              type: string
              description: Page type
              enum:
              - PDP
              - PLP
              - Cart
              - Checkout
              example: PDP
          locales:
            type: array
            description: The geographic regions where the promotion message is displayed, determined by the user's IP address. Locales define language and country-specific settings for promotions.
            items:
              type: string
              description: Locale
              example: en-CA
          type:
            type: string
            description: "Specifies the promotion message type.\n  - `DISCOUNT`: The discount has been applied.\n  - `PROXIMITY`: The product or cart is close to meeting discount conditions.\n  - `POTENTIAL_DISCOUNT`: The product could qualify for a discount but has not yet."
            enum:
            - DISCOUNT
            - PROXIMITY
            - POTENTIAL_DISCOUNT
            example: DISCOUNT
          threshold:
            type: integer
            format: int32
            description: Indicates a quantity or amount that is close to meeting the discount requirement. If the user reaches this value, a promotion message is displayed. This field is only valid for PROXIMITY messages.
            example: 2
    priceAdditionalProperties:
      type: object
      description: The additional parameters for calculating the price.
      properties:
        additionalProperties:
          type: array
          description: The additional properties for calculating the price.
          example:
          - id: length
            value: 10
          - id: width
            value: 20
          items:
            type: object
            properties:
              id:
                description: The variable ID.
                type: string
                example: length
              value:
                description: The variable value.
                type: number
                example: 10
                format: double
    priceParameterById:
      allOf:
      - $ref: '#/components/schemas/priceParameter'
      - type: object
        properties:
          quantity:
            type: integer
            description: Number of products ordered, required for the range-based pricing method. For more information about range-based pricing method, see the [discount type](/v3/offers/user-guides/offers/coupons/overview#defining-discounts-and-how-they’re-applied) section.
            format: int32
            example: 500
          itemId:
            type: integer
            description: Item ID obtained from Product Catalog.
            format: int32
            example: 12345
    lineItemReference:
      description: Line item details
      required:
      - quantity
      - itemId
      type: object
      properties:
        itemId:
          $ref: '#/components/schemas/cartItemId'
        position:
          minimum: 1
          type: integer
          description: Line item position (starts at 1)
          format: int32
          example: 1
        sku:
          type: string
          description: Line item SKU
          example: 16B2GS8LD5FDS
        productAttributes:
          description: Line item product attributes
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/cartProductAttribute'
        quantity:
          type: integer
          format: int32
          description: Line item quantity within the cart
          example: 15
        priceListId:
          type: integer
          format: int32
          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.
          nullable: true
          example: 108674
        price:
          description: Individual line item price
          allOf:
          - $ref: '#/components/schemas/calculatedPriceObject'
          - nullable: true
        groups:
          type: array
          description: List of group IDs for groups or category the line items belongs to
          nullable: true
          items:
            type: string
            description: ID of group or category to which line item belongs
            example: 61d38e117162b7dba69c3d6d
        attributes:
          type: object
          additionalProperties: true
          description: Line item attributes passed by caller
          nullable: true
          example:
            productFamily: Laptop computers
        shippingDetails:
          description: Shipping details
          allOf:
          - $ref: '#/components/schemas/shippingDetailReference'
          - nullable: true
    priceParameter:
      allOf:
      - $ref: '#/components/schemas/priceAdditionalProperties'
      - type: object
        properties:
          selectedAddOns:
            type: array
            description: List of add-ons selected for the product.
            example:
            - blind_motor
            items:
              type: string
              example: blind_motor
              description: Add-on name
    calculatedPriceObject:
      type: object
      description: The calculated price details for line items.
      example:
        sale: 1000.15
        cost: 900.15
        base: 2000.15
        unitPriceWithoutDiscounts: 2000.15
        lineTotalWithoutDiscounts: 2000.15
        lineTotalWithDiscounts: 2000.15
        type: BASE
      properties:
        sale:
          type: number
          description: Sale price of the product.
          format: double
          example: 1000.15
          nullable: true
        cost:
          type: number
          description: Cost of goods sold, from either producing or purchasing from other vendors.
          format: double
          example: 900.15
        base:
          type: number
          description: The base price of a single item before any discounts.
          format: double
          example: 2000.15
        unitPriceWithoutDiscounts:
          type: number
          nullable: true
          description: Price of a single item without discount. This price is either the `base` or `sale` price. The type used is noted in the `type` property.
          format: double
          example: 2000.15
        lineTotalWithoutDiscounts:
          type: number
          nullable: true
          description: Total price of all items without calculating discounts. This is the `unitPriceWithoutDiscounts` multiplied by the quantity.
          format: double
          example: 5000.15
        lineTotalWithDiscounts:
          type: number
          nullable: true
          description: Total price of all items after all discounts. This is the unitPriceWithoutDiscounts multiplied by the quantity, less the promotion discounts.
          format: double
          example: 5000.15
        type:
          type: string
          nullable: true
          description: Price type
          example: BASE
        currency:
          type: string
          description: Currency string value
          example: USD
    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
          nullable: true
          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:
         

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