Create, search, toggle, and end promotions — discounts on items, carts, or shipping methods. The Promotions API is the authoring surface; the Pricing Engine applies the active promotions returned by these endpoints to live cart and pricing calculations.
openapi: 3.0.0
x-mint:
mcp:
enabled: true
info:
title: Offers - Promotions
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
externalDocs:
description: Find out more about Offers
url: https://developer.fabric.inc/docs/offers-overview
servers:
- url: https://api.fabric.inc/v3
description: Production environment
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:
securitySchemes:
AuthorizationToken:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
missingTenantHeader:
type: object
description: Tenant header is missing
properties:
type:
description: The error code.
type: string
example: TENANT_HEADER_REQUIRED
message:
description: An error message corresponding to the `type`.
type: string
example: x-fabric-tenant-id header is required
error400:
type: object
description: Bad request error
properties:
type:
description: The error code.
type: string
example: BAD_REQUEST
message:
description: An error message corresponding to the `type`.
type: string
example: Bad request
error401:
type: object
description: Unauthorized error
properties:
type:
description: The error code.
type: string
example: UNAUTHORIZED
message:
description: An error message corresponding to the `type`.
type: string
example: Invalid credentials
error500:
type: object
description: Internal server error
properties:
type:
description: The error code.
type: string
example: INTERNAL_SERVER_ERROR
message:
description: An error message corresponding to the `type`.
type: string
example: Internal server error
createdAt:
type: string
format: date-time
description: Record's creation time
example: 2019-08-20T14:15:22.000Z
updatedAt:
type: string
format: date-time
description: Record's last updated time
example: 2019-08-20T14:15:22.000Z
cursorQuery:
type: object
description: The pagination details.
properties:
size:
description: The maximum number of records per page.
type: integer
format: int32
minimum: 1
default: 10
maximum: 100
example: 10
nextCursor:
description: Reference point to start the search for records in the next data set
type: string
nullable: true
maxLength: 1000
example: H796HJHGANLSADS
offsetQuery:
type: object
description: Provides pagination data.
properties:
size:
type: integer
format: int32
example: 10
minimum: 1
maximum: 100
default: 10
description: The maximum number of records per page.
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.
count:
type: integer
format: int32
example: 50
description: The total number of available records.
badSizeError:
type: object
description: Pagination size error, an invalid value was sent
properties:
type:
description: The error code.
type: string
example: REQUEST_VALIDATION
message:
description: An error message corresponding to the `type`.
type: string
example: Size should be a valid number
badSortingError:
type: object
description: Invalid sorting values sent
properties:
type:
description: The error code.
type: string
example: REQUEST_VALIDATION
message:
description: >-
An error message corresponding to the `type`. In this case. an
invalid sorting value was sent.
type: string
example: Sorting value must be one of the allowed values
promotion:
type: object
description: Promotion record detail
required:
- id
- name
- startAt
- endAt
- status
- type
- details
properties:
id:
type: string
description: >-
The promotion ID generated when using the [create
promotion](/v3/api-reference/offers/promotions/create-promotion)
endpoint.
example: 638a0227945d970008be0f86
name:
type: string
description: The name of the promotion.
example: Black Friday Promotion
status:
type: string
description: Promotion status
enum:
- ACTIVE
- SCHEDULED
- DISABLED
- EXPIRED
example: SCHEDULED
default: SCHEDULED
type:
type: string
description: >
The type of promotion you want to create. The following are the
promotion types you can create:
- `PRODUCT`: A SKU promotion. Applies a discount to SKUs based on
the value specified in the `discount` object of the request body.
- `CART`: A cart promotion. Applies a discount to the minimum order
amount of the cart based on the `ORDER_VALUE` specified in the
`condition` object of the request body.
- `QUANTITY`: A quantity promotion. Provides discounts on items
based on the quantity requirement set in the promotion.
- `SHIPPING`: A shipping promotion. Provides discounts on the
shipping cost.
- `BUYGET`: A BuyGet promotion. Specifies the _Buy_ conditions and
corresponding _Get_ discounts.
- `SPEND_GET`: A SpendGet promotion. Specifies the total order value
required to qualify for discounts and the applicable discounts based
on the order value.
enum:
- PRODUCT
- CART
- QUANTITY
- SHIPPING
- BUYGET
- SPEND_GET
example: PRODUCT
startAt:
type: string
format: date-time
description: Promotion start time
example: 2019-08-24T14:15:22.000Z
endAt:
type: string
format: date-time
description: Promotion end time
example: 2019-08-25T14:15:22.000Z
buyOperator:
type: string
description: >-
Operator for `conditions` array. It's applied when the promotion
type is `BUYGET`. It's used as an operator between different
condition objects mentioned in the *conditions* array.
default: OR
enum:
- AND
- OR
example: OR
note:
type: string
example: Independence day sale!
description: Promotion note or description
details:
type: array
description: Promotion setup details
items:
type: object
description: Promotion setup detail
properties:
discounts:
$ref: '#/components/schemas/promotionDiscounts'
targetProducts:
$ref: '#/components/schemas/promotionTargetProduct'
conditions:
$ref: '#/components/schemas/promotionCondition'
termsAndConditions:
$ref: '#/components/schemas/promotionTermsAndConditions'
promotionMessages:
$ref: '#/components/schemas/promotionMessages'
proximityMessages:
$ref: '#/components/schemas/proximityMessages'
shipmentMethodIds:
$ref: '#/components/schemas/promotionShipmentMethods'
eligiblePriceLists:
$ref: '#/components/schemas/promotionPriceLists'
limits:
$ref: '#/components/schemas/promotionLimits'
additionalAttributes:
$ref: '#/components/schemas/promotionAdditionalAttributes'
createdAt:
$ref: '#/components/schemas/createdAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
level:
type: integer
format: int32
minimum: 0
maximum: 5
description: >-
Promotion execution order. Promotion types are assigned a default
execution order. First, level 1 promotions will be evaluated. The
result of level 1 will be used as a base price for level 2.
Similarly, the result of level 2 will be used as a base price for
level 3.
example: 3
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. If configured,
`stackingType` will have precedence over the `isStackable` and
`isAlwaysApplied`. The following are possible `stackingType` values:
- `STACKABLE`: This promotion can be combined with other stackable
promotions, allowing multiple
discounts to be applied together. The order in which stackable promotions are applied
is determined by the `level` field, with promotions having a higher priority (lower numeric value)
being applied before those with a lower priority.
- `EXCLUSIVE`: This promotion can't be combined with any other
promotions. The `level` field is
used to determine which exclusive promotion will be evaluated and applied first. Once an exclusive
promotion is applied, no other promotions can be used in the same transaction.
- `TYPE_EXCLUSIVE`: This promotion can't be combined with other
# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-offers-promotions-openapi.yml