openapi: 3.0.0
x-mint:
mcp:
enabled: true
info:
title: Offers - Coupon codes
description: >-
fabric Coupon codes are alphanumeric strings that shoppers can enter during
checkout to get a discount on their purchase. Depending on the coupon
settings, shoppers can enter one or more coupon codes during the checkout.
Use this endpoint to get the coupon codes that are currently available.
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:
/coupon-codes:
get:
tags:
- Coupon Codes
summary: Get all coupon codes
description: >-
This endpoint provides coupon code lists. Use parameters to filter
results, for example, set `status` as 'ACTIVE' for active coupons, or
add `userId` for user-specific coupon codes. Navigate the results using
the query parameters `size` and `startCursor`.
operationId: getCouponCodes
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/queryParameterStartCursor'
- name: userId
in: query
description: Filter coupon codes by user ID
schema:
type: string
example: user0001
required: false
- name: promotionId
description: >-
Filter coupon codes by promotion ID generated using the [create
promotion](/v3/api-reference/offers/promotions/create-promotion)
endpoint.
in: query
schema:
type: string
example: 641cf986ca5b2c3180787e09
required: false
- name: couponCode
in: query
description: >-
Filter coupon codes generated using the [generate coupon
codes](/v3/api-reference/offers/coupons/generate-coupon-codes)
endpoint.
schema:
type: string
example: SUMMER
required: false
- name: status
in: query
description: Filter coupon codes by their status
schema:
type: string
enum:
- ACTIVE
- INACTIVE
- REDEEMED
- name: startFrom
in: query
description: >-
Filter coupon codes based on the start date of the coupon, in UTC
format. `startFrom` and `StartTo` represent date range for the start
date of the coupon code. For example, you can find coupon codes
where start date is from '2023-03-01T01:14:50.967Z' to
'2023-03-10T01:14:50.967Z'
schema:
type: string
example: '2023-03-24T01:14:50.967Z'
required: false
- name: startTo
in: query
description: >-
Filter coupon codes based on the start date of the coupon, in UTC
format. `startFrom` and `StartTo` represent date range for the start
date of the coupon code. For example, you can find coupon codes
where start date is from '2023-03-01T01:14:50.967Z' to
'2023-03-10T01:14:50.967Z'
schema:
type: string
example: '2023-03-24T01:14:50.967Z'
required: false
- name: endFrom
in: query
description: >-
Filter coupon codes based on the end date of the coupon, in UTC
format. `endFrom` and `endTo` represent date range for the end date
of the coupon code. For example, you can find coupon codes where end
date is from '2023-04-01T01:14:50.967Z' to
'2023-04-10T01:14:50.967Z'
schema:
type: string
example: '2023-04-24T01:14:50.967Z'
required: false
- name: endTo
in: query
description: >-
Filter coupon codes based on the end date of coupon, in UTC format.
`endFrom` and `endTo` represent date range for the end date of the
coupon code. For example, you can find coupon codes where end date
is from '2023-04-01T01:14:50.967Z' to '2023-04-10T01:14:50.967Z'
schema:
type: string
example: '2023-03-24T01:14:50.967Z'
required: false
- name: additionalAttributes
in: query
description: >-
Filter coupon codes by additional attributes.
This filter needs
to be a valid JSON array and `name:values` pairs to be able to make
the search.
schema:
type: string
example: '[{"name":"brand","values":"123"}]'
required: false
- name: promotionAdditionalAttributes
in: query
description: >-
Filter coupon codes by supplementary attributes of a promotion.
This filter needs to be a valid JSON array and `name:values` pairs
to be able to make the search.
schema:
type: string
example: '[{"name":"type","values":"Holiday"}]'
required: false
- name: title
in: query
description: Filter coupon codes by promotion title
schema:
type: string
example: Summer promotion
required: false
responses:
'200':
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponse'
content:
application/json:
schema:
$ref: '#/components/schemas/getCouponCodesResponse'
'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/badStartCursorError'
- $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'
/coupon-codes/batch:
put:
tags:
- Coupon Codes
summary: Bulk update coupon codes
description: >-
Use this endpoint to update multiple coupon codes using identifiers.
Identifiers are a unique combination of a coupon code and a promotion
ID. You can update up to 25 codes at a time.
operationId: bulkUpdateCouponCodes
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/bulkUpdateCouponCodesRequest'
responses:
'200':
description: Accepted
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponse'
content:
application/json:
schema:
$ref: '#/components/schemas/bulkUpdateCouponCodesResponse'
'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/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'
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
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
badStartCursorError:
type: object
description: Invalid `startCursor` value sent
properties:
type:
description: The error code.
type: string
example: REQUEST_VALIDATION
message:
description: An error message corresponding to the `type`.
type: string
example: Start cursor is invalid
couponCodes:
type: object
description: Details of coupon codes
required:
- id
- couponCode
- promotionId
- status
- createdAt
- updatedAt
properties:
id:
description: 24-character system-generated coupon code
type: string
example: 641cf99d2de161c5a6d7a481
title:
description: Title of the promotion associated with the coupon code
type: string
example: Summer coupons
userId:
description: User ID of the user who created the coupon code
type: string
example: 5e2cfb9b45570b000864c4b5
nullable: true
couponCode:
description: Coupon code
type: string
example: SUMMER
versionId:
description: Version ID of the coupon code, for internal reference
type: string
example: 3
promotionId:
description: 24-character system-generated promotion ID
type: string
example: 641cf986ca5b2c3180787e05
startAt:
description: Start date of the coupon code, in UTC format
type: string
format: date-time
example: 2023-08-10T19:00:00.000Z
endAt:
description: End date of the coupon code, in UTC format
type: string
format: date-time
example: 2023-08-10T09:10:57.811Z
status:
description: Status of the coupon code
type: string
enum:
- ACTIVE
- INACTIVE
- REDEEMED
example: ACTIVE
additionalAttributes:
description: Merchant-specified attributes associated with the coupon code
type: array
items:
type: object
required:
- name
- values
properties:
name:
description: >-
Merchant-specified attribute `name` associated with the coupon
code
type: string
example: brand
values:
oneOf:
- type: string
description: >-
Merchant-specified attribute `value` associated with the
coupon code
example: '2'
- type: array
description: >-
Merchant-specified attribute `values` associated with the
coupon code
items:
type: string
description: >-
Merchant-specified attribute `value` associated with the
coupon code
example:
- '2'
- '3'
promotionAdditionalAttributes:
description: >-
Merchant-specified attributes of the promotion associated with the
coupon code
type: array
items:
type: object
required:
- name
- values
properties:
name:
description: >-
Merchant-specified attribute `name` associated with the
related promotion
type: string
example: eventName
values:
oneOf:
- type: string
description: >-
Merchant-specified attribute `value` associated with the
related promotion
example: Store sale
- type: array
description: >-
Merchant-specified attribute `values` associated with the
related promotion
items:
type: string
description: >-
Merchant-specified attribute `values` associated with
the related promotion
example:
- Holiday
- Christmas
createdAt:
$ref: '#/components/schemas/createdAt'
updatedAt:
$ref: '#/components/schemas/updatedAt'
getCouponCodesResponse:
type: object
description: The paginated response of coupon codes.
properties:
query:
$ref: '#/components/schemas/cursorQuery'
data:
type: array
description: An array containing coupon details.
items:
$ref: '#/components/schemas/couponCodes'
bulkUpdateCouponCodesRequest:
type: object
description: The details to update the coupon codes.
required:
- data
properties:
data:
type: array
description: The coupon codes to be updated.
items:
type: object
description: The details of the coupon code to be updated.
required:
- identifier
properties:
identifier:
type: object
description: >-
The ID of the coupon code. It's a unique combination of a
coupon code and the associated promotion ID.
required:
- promotionId
- couponCode
properties:
promotionId:
oneOf:
- type: string
description: A 24-character system-generated promotion ID.
example: 6380e7ecb419a30009865fad
- type: object
description: >-
The merchant-specified attributes for the promotion,
in `name:value` pairs.
required:
- name
- values
properties:
name:
type: string
description: >-
The merchant-specified unique name for the
additional property associated with the promotion.
example: coupon_id
values:
type: string
description: >-
The merchant-specified `value` for the `name`
attribute associated with the promotion.
example: '1233222'
couponCode:
type: string
description: The coupon code.
example: XMAS2022
userId:
type: string
description: The ID of the user who can redeem the coupon.
example: 6380e7ecb419a30009865fad
status:
type: string
description: >-
Coupon code status. `ACTIVE` represents the coupon codes are
ready to be redeemed and `INACTIVE` represents the coupon
codes are disabled and can't be redeemed.
enum:
- ACTIVE
- INACTIVE
example: ACTIVE
additionalAttributes:
description: >-
The merchant-specified additional attributes for the coupon
code.
type: array
items:
type: object
required:
- name
- values
properties:
name:
description: >-
The merchant-specified `name` associated with the coupon
code.
type: string
example: brand
values:
oneOf:
- type: string
description: >-
The merchant-specified `values` for the `name`
attribute associated with the coupon code.
example: Nike
- type: array
description: >-
The merchant-specified attribute `values` associated
with the coupon code.
items:
type: string
description: >-
The merchant-specified attribute `value`
associated with the coupon code.
example:
- '2'
- '3'
bulkUpdateCouponCodesResponse:
type: object
description: The list of updated coupon codes.
properties:
data:
type: array
description: The list of updated coupon codes.
minItems: 1
items:
$ref: '#/components/schemas/couponCodes'
errors:
type: array
description: The list of possible errors.
items:
type: object
description: The error details.
properties:
identifier:
type: object
description: >-
The ID of the coupon code. It's a unique combination of
`couponCode` and associated `promotionId`.
properties:
promotionId:
oneOf:
- type: string
description: A 24-character system-generated promotion ID.
example: 6380e7ecb419a30009865fad
- type: object
description: >-
The merchant-specified attributes for the promotion,
in `name:value` pairs.
required:
- name
- values
properties:
name:
type: string
description: >-
The merchant-specified unique name for the
additional property associated with the promotion.
example: coupon_id
values:
type: string
description: >-
The merchant-specified `value` for the `name`
attribute associated with the promotion.
example: '1233222'
couponCode:
type: string
description: The coupon code.
example: XMAS2022
type:
type: string
description: The error code.
example: COUPON_CODE_NOT_FOUND
message:
type: string
description: An error message corresponding to the `type`.
example: Coupon code not found
couponCodeError:
type: object
description: Invalid data for generating coupon codes
properties:
type:
description: The error code.
type: string
example: REQUEST_VALIDATION
message:
description: An error message corresponding to the `type`.
type: string
example: Invalid data. Start value must be greater than or equal to 1.
parameters:
xFabricTenantId:
in: header
name: x-fabric-tenant-id
schema:
type: string
minLength: 24
maxLength: 24
required: true
example: 5f328bf0b5f328bf0b5f328b
description: >-
A header used by fabric to identify the tenant making the request. You
must include tenant id in the authentication header for an API request
to access any of fabric’s endpoints. You can retrieve the tenant id ,
which is also called account id, from
[Copilot](/v3/platform/settings/account-details/getting-the-account-id).
This header is required.
xFabricChannelId:
in: header
name: x-fabric-channel-id
schema:
type: string
example: '12'
description: >-
x-fabric-channel-id identifies the sales channel where the API request
is being made; primarily for multichannel use cases. The channel ids are
12 corresponding to US and 13 corresponding to Canada. The default
channel id is 12. This field is required.
xClientId:
in: header
name: x-client-id
schema:
type: string
required: false
example: copilot
description: >-
A unique identifier obtained from
[Copilot](/v3/platform/settings/api-apps/getting-system-app-credentials)
for the System app in the fabric ecosystem, essential for OpenID Connect
authentication flows.
xFabricRequestId:
in: header
name: x-fabric-request-id
description: A unique request ID.
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
queryParameterSize:
name: size
in: query
description: The maximum number of records per page.
required: false
schema:
type: integer
format: int32
minimum: 1
default: 10
maximum: 100
queryParameterStartCursor:
name: startCursor
in: query
description: >-
Specifies the record from which the search will start, effectively
skipping all records before this point.
required: false
schema:
type: string
maxLength: 1000
example: H796HJHGANLSADS
headers:
xFabricRequestIdResponse:
description: Unique request ID
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002