openapi: 3.0.0
"x-mint": {
    "mcp": {
      "enabled": true
    }
  }
info:
  title: Offers - Exports
  description: fabric Export endpoints let you export data to CSV files based on the provided filters.
  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:
  /offers-exports:
    post:
      tags:
        - Exports
      summary: Initiate export request
      description: Initiate an export request based on the specified filter criteria.
      operationId: createExport
      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/createExport'
      responses:
        "201":
          description: Created
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createExportResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/exportTypeNotValidError'
                  - $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'
    get:
      tags:
        - Exports
      summary: Get all export requests
      description: Get a paginated list of all the export requests.
      operationId: listExports
      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: Field to sort export requests
          required: false
          schema:
            type: string
            example: +startedAt
        - name: type
          in: query
          description: Type of data to export
          required: false
          schema:
            type: string
            example: REDEMPTION
            enum:
              - REDEMPTION
              - CALCULATED_PRICE
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exportListResponse'
        "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/badOffsetError'
                  - $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'
  /offers-exports/{exportId}:
    get:
      tags:
        - Exports
      summary: Get export request by ID
      description: Get the details of a specific export request by the corresponding `exportId` that was generated from the [initiate export request](/v3/api-reference/offers/exports/initiate-export-request) endpoint.
      operationId: getExportById
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - in: path
          name: exportId
          required: true
          description: The `exportId` value that was generated from the [initiate export request](/v3/api-reference/offers/exports/initiate-export-request) endpoint.
          schema:
            type: string
            example: '1e7b9912-1d88-4412-9f25-ff4730eb14ce'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: "#/components/headers/xFabricRequestIdResponse"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/createExportResponse'
                  - type: object
                    properties:
                      fileId:
                        type: string
                        description: The S3 `fileId` value to generate a downloadable CSV using the [download exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file) endpoint.
                        example: 'redemption/tenantId/1687472977242-redemption-export.csv'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/exportNotFoundError'
                  - $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'
  /offers-exports/actions/download-export-file:
    post:
      tags:
        - Exports
      summary: Download exported CSV file
      description: This endpoint lets you generate a URL, using fileId, from which you can download the exported CSV file. The generated URL expires in five mins.
      operationId: downloadExport
      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/downloadExportUrl'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: "#/components/headers/xFabricRequestIdResponse"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/downloadExportUrlResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/fileExpiredError'
                  - $ref: '#/components/schemas/invalidFileIdError'
                  - $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:
    # Header errors
    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
    # Generic errors
    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
    # Pagination
    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.
    # Pagination - Errors
    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
    badOffsetError:
      type: object
      description: An error indicating that an invalid pagination offset value was provided.
      properties:
        type:
          description: The error code.
          type: string
          example: REQUEST_VALIDATION
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Offset must be an integer

    # Exports
    createExport:
      type: object
      description: The sample request to initiate data export.
      required:
        - type
      properties:
        type:
          type: string
          description: The type of data to export. 
          enum:
            - REDEMPTION
            - CALCULATED_PRICE
          example: REDEMPTION
        filters:
          type: array
          maxItems: 20
          description: Filters to apply when exporting the data. You can include multiple `filter` values in the request. If you do not include any `filters` parameter, all export data of the specified data type is returned. For more information on using filters to refine your data, see the [export parameters](/v3/api-reference/offers/developer-guide/exporting-csv#export-parameters) section.
          items:
            type: object
            required:
              - field
              - value
              - operator
            properties:
              field:
                type: string
                description: |
                  The name of the field, which is always paired with `value`. The field name is always paired with the corresponding `value` parameter. The filtering values you can choose from depend on the type of data you're exporting. For more information on the available `field` options for each data type, see the [export parameters](/v3/api-reference/offers/developer-guide/exporting-csv#export-parameters) section.
                minLength: 3
                maxLength: 120
                example: storeId
              value:
                description: The value or values corresponding to the `field` parameter. The `field` parameter defines the name of the field, and the `value` parameter provides the corresponding value. For example, if the `field` parameter is `priceListIds`, the corresponding `value` parameter must be an array.
                oneOf:
                  - type: string
                    minLength: 1
                    maxLength: 120
                    example: "store001"
                  - type: array
                    minItems: 1
                    maxItems: 200
                    items:
                      oneOf:
                        - type: string
                          description: The values corresponding to the `field`. The `field` parameter defines the name of the field, and the `value` parameter provides the corresponding value. For example, if the `field` parameter is `priceListIds`, the corresponding `value` parameter must be an array.
                          example: "60ec76eee1f1dc1234567890"
                        - type: number
                          description: The values corresponding to the `field`. The `field` parameter defines the name of the field, and the `value` parameter provides the corresponding value. For example, if the `field` parameter is `priceListIds`, the corresponding `value` parameter must be an array.
                          example: 100000
              operator:
                type: string
                description: Operator between field and value to filter data.
                enum:
                  - EQUAL
                  - GREATER_THAN_OR_EQUAL_TO
                  - LESS_THAN
                  - IN
                example: EQUAL
    createExportResponse:
      type: object
      description: The sample response of the create export request.
      required:
        - exportId
        - startedAt
        - status
        - type
      properties:
        exportId:
          type: string
          description: The unique ID for the export request that is used to retrieve the export details.
          example: 'ab50fe48-5da0-4e77-92d1-bb629eedf19e'
        startedAt:
          type: string
          description: The start time of the export process.
          example: '2023-05-17T21:24:52.398Z'
        endedAt:
          type: string
          description: The end time of the export process.
          example: 'null'
          nullable: true
        totalDataExported:
          type: number
          description: The total number of exported data in the CSV file. Each row in the CSV file represents one record of exported data.
          example: 0
        status:
          type: string
          description: |
            The status of the export process. The [download exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file) endpoint can generate a download URL only if the export status is `COMPLETED`. The following are possible statuses:
              - `IN_PROGRESS`
              - `COMPLETED`
              - `ERROR`
          example: IN_PROGRESS
        errors:
          type: array
          description: Errors during the export process. For more information about the error messages, see the [exporting CSV](/v3/api-reference/offers/developer-guide/exporting-csv#export-calculated-price-error) section.
          example: []
          items:
            type: object
            properties:
              type:
                type: string
                description: The error code.
              message:
                type: string
                description: An error message corresponding to the `type`.
        type:
          type: string
          description: The type of data to export.
          example: REDEMPTION
        filters:
          type: array
          items:
            type: object
            required:
              - field
              - value
              - operator
            properties:
              field:
                type: string
                description: The name of the field. This is always paired with `value`.
                example: storeId
              value:
                description: The value or values corresponding to the `field` parameter. The `field` parameter defines the name of the field, and the `value` parameter provides the corresponding value. For example, if the `field` parameter is `priceListIds`, the corresponding `value` parameter must be an array.
                oneOf:
                  - type: string
                    minLength: 1
                    maxLength: 120
                    example: "store001"
                  - type: array
                    minItems: 1
                    maxItems: 200
                    items:
                      oneOf:
                        - type: string
                          description: The values corresponding to the `field`. The `field` parameter defines the name of the field, and the `value` parameter provides the corresponding value. For example, if the `field` parameter is `priceListIds`, the corresponding `value` parameter must be an array.
                          example: "60ec76eee1f1dc1234567890"
                        - type: number
                          description: The values corresponding to the `field`. The `field` parameter defines the name of the field, and the `value` parameter provides the corresponding value. For example, if the `field` parameter is `priceListIds`, the corresponding `value` parameter must be an array.
                          example: 100000
              operator:
                type: string
                description: Operator between `field` and `value` to filter data.
                example: EQUAL
    exportListResponse:
      type: object
      description: A paginated response of export requests.
      properties:
        query:
          $ref: '#/components/schemas/offsetQuery'
        data:
          description: The response data.
          type: array
          items:
            $ref: '#/components/schemas/listExportData'
    listExportData:
      type: object
      description: An overview of export request.
      required:
        - exportId
        - startedAt
        - status
        - type
      properties:
        exportId:
          type: string
          description: The unique ID for the export request that is used to retrieve the export details.
          example: 'ab50fe48-5da0-4e77-92d1-bb629eedf19e'
        startedAt:
          type: string
          description: The start time of the export process.
          example: '2023-05-17T21:24:52.398Z'
        endedAt:
          type: string
          description: The end time of the export process.
          example: 'null'
          nullable: true
        status:
          type: string
          description: The status of the export process. The [download exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file) endpoint can generate a download URL only if the export status is `COMPLETED`.
          enum:
            - IN_PROGRESS
            - COMPLETED
            - ERROR
          example: IN_PROGRESS
        type:
          type: string
          description: The type of data to export.
          example: REDEMPTION
        totalDataExported:
          type: number
          description: The total number of exported data in the CSV file. Each row in the CSV file represents one record of exported data.
          example: 0
        fileId:
          type: string
          description: The S3 `fileId` value to generate a downloadable CSV using the [download exported CSV file](/v3/api-reference/offers/exports/download-exported-csv-file) endpoint.
          example: redemption/tenantId/1687294954996-redemption-export.csv
          nullable: true
    downloadExportUrl:
      type: object
      description: The downloadable URL of the file.
      required:
        - fileId
      properties:
        fileId:
          type: string
          description: The `fileId` value retrieved from the [get export request by ID](/v3/api-reference/offers/exports/get-export-request-by-id) endpoint. This is used to download the exported CSV.
          example: redemption/tenantId/1687472972-redemption-export.csv
    downloadExportUrlResponse:
      type: object
      description: The URL of the downloadable CSV.
      required:
        - url
        - fileId
      properties:
        url:
          type: string
          description: The AWS S3 URL to download the exported CSV.
          example: https://bucket-name.s3.amazonaws.com/redemption/tenantId/1687472972-redemption-export.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA26KLJWUAPER5A
        fileId:
          type: string
          description: The S3 `fileId` value to generate a downloadable CSV.
          example: redemption/tenantId/1687472972-redemption-export.csv
    # Exports - Errors
    exportTypeNotValidError:
      type: object
      description: An error message because export type isn't valid.
      properties:
        type:
          description: The error code.
          type: string
          example: REQUEST_VALIDATION
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Export type not valid.
    exportNotFoundError:
      type: object
      description: Export not found error
      properties:
        type:
          description: The error code.
          type: string
          example: EXPORT_NOT_FOUND
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: The export ID you entered doesn’t exist.
    fileExpiredError:
      type: object
      description: File expired error
      properties:
        type:
          description: The error code.
          type: string
          example: FILE_EXPIRED
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Exported file has expired
    invalidFileIdError:
      type: object
      description: Invalid fileId error
      properties:
        type:
          description: The error code.
          type: string
          example: INVALID_FILE_ID
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: fileId isn't valid

  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: The sales channel ID.
    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
    # Pagination
    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
    queryParameterOffset:
      name: offset
      in: query
      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.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 0
        example: 0
        default: 0
  headers:
    xFabricRequestIdResponse:
      description: Unique request ID
      schema:
        type: string
        example: 263e731c-45c8-11ed-b878-0242ac120002