openapi: 3.0.0
x-mint:
  mcp:
    enabled: true
info:
  title: Offers - Price Lists API
  description: >-
    fabric Price lists is a collection of items and their assigned prices. An
    item can exist in multiple price lists. This gives you the ability to assign
    different prices to the same item. Price lists let you set the currency and
    duration of the prices. For example, if the price list expires, prices of
    items within the price list will also expire.
  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:
  /price-lists:
    get:
      tags:
        - Price Lists
      summary: Get all price lists
      description: Get a paginated list of all price lists.
      operationId: getPriceLists
      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
              - '-isDefault'
              - +isDefault
              - '-id'
              - +id
        - name: status
          in: query
          description: >-
            Status by which records are filtered.<br>ACTIVE: If today's date is
            between a price list's 'startAt' date and 'endAt' date, that price
            list is considered active.
          required: false
          schema:
            type: string
            enum:
              - ACTIVE
            example: ACTIVE
        - name: name
          description: Filter the records matching the price list name.
          in: query
          schema:
            type: string
            example: US price list
        - name: isDefault
          description: >
            - `true`: This price list is designated as the default price list.

            - `false`: This price list isn't designated as the default price
            list.
          in: query
          schema:
            type: boolean
            example: true
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPriceListsResponse'
        '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:
        - Price Lists
      summary: Create price list
      description: >-
        Create a price list. Based on the currency code you define for a price
        list, you will be able to create or update prices under the price list
        for the defined currency code only.
      operationId: createPriceList
      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/createPriceListRequest'
      responses:
        '201':
          description: Created
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createPriceListResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/priceListNameExists'
                  - $ref: '#/components/schemas/priceListNameError'
                  - $ref: '#/components/schemas/currencyNotValid'
                  - $ref: '#/components/schemas/priceListStartAtError'
                  - $ref: '#/components/schemas/priceListEndAtError'
                  - $ref: '#/components/schemas/priceListInconsistentDates'
                  - $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'
  /price-lists/{id}:
    put:
      tags:
        - Price Lists
      summary: Update a specific price list
      description: Update a specific price list by ID.
      operationId: updatePriceList
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - name: id
          in: path
          required: true
          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.
          schema:
            type: integer
            format: int32
            example: 1000003
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updatePriceListRequest'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updatePriceListResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/priceListNameExists'
                  - $ref: '#/components/schemas/priceListNameError'
                  - $ref: '#/components/schemas/currencyNotValid'
                  - $ref: '#/components/schemas/priceListStartAtError'
                  - $ref: '#/components/schemas/priceListEndAtError'
                  - $ref: '#/components/schemas/priceListInconsistentDates'
                  - $ref: '#/components/schemas/currencyNotValid'
                  - $ref: '#/components/schemas/priceListIdInvalidError'
                  - $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/priceListNotFound'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    delete:
      tags:
        - Price Lists
      summary: Delete a specific price list
      description: Delete a specific price list by ID.
      operationId: deletePriceList
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - name: id
          in: path
          required: true
          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.
          schema:
            type: integer
            format: int32
            example: 1000003
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deletePriceListResponse'
              example:
                id: 1000003
                name: US price list
                isDefault: false
                currency: USD
                channelId: '12'
                startAt: '2021-05-04T09:23:51.459Z'
                endAt: '2021-06-09T09:23:51.459Z'
                createdAt: '2019-08-20T14:15:22Z'
                updatedAt: '2019-08-20T14:15:22Z'
                isDeleted: true
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/priceListIdInvalidError'
                  - $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/priceListNotFound'
        '500':
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    get:
      tags:
        - Price Lists
      summary: Get a specific price list
      description: Get a specific price list by ID.
      operationId: getPriceList
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - name: id
          in: path
          required: true
          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.
          schema:
            type: integer
            format: int32
            example: 1000003
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPriceListResponse'
        '400':
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/priceListIdInvalidError'
                  - $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/priceListNotFound'
        '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
    currencyNotValid:
      type: object
      description: Currency not valid error
      properties:
        type:
          description: The error code.
          type: string
          example: INVALID_CURRENCY_CODE
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Invalid currency
    priceListNotFound:
      type: object
      description: Price list not found error
      properties:
        type:
          description: The error code.
          type: string
          example: PRICE_LIST_NOT_FOUND
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: No price list found with this ID
    createdAt:
      type: string
      format: date-time
      description: The timestamp of when the price list was created.
      example: 2019-08-20T14:15:22.000Z
    updatedAt:
      type: string
      format: date-time
      description: The timestamp of when the price list was last updated.
      example: 2019-08-20T14:15:22.000Z
    isDeleted:
      type: boolean
      description: |
        - `true`: The price list is deleted.
        - `false`: The price list isn't deleted.
      example: false
    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
    priceList:
      type: object
      description: The details of the price list.
      required:
        - id
        - name
        - isDefault
        - currency
        - createdAt
        - updatedAt
        - isDeleted
      properties:
        id:
          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: 1000003
        name:
          description: The name of the price list.
          type: string
          example: US price list
        isDefault:
          description: >
            - `true`: This price list is designated as the default price list.

            - `false`: This price list isn't designated as the default price
            list.
          type: boolean
          example: false
        currency:
          description: The currency code of the price list.
          type: string
          format: iso-4217
          example: USD
        channelId:
          description: The sales channel.
          type: string
          example: '12'
        startAt:
          description: >-
            Start time for the price list to be active. If no value is sent, the
            current date will be set as the start date.
          type: string
          format: date-time
          example: 2021-05-04T09:23:51.459Z
        endAt:
          description: >-
            The end time of price list. The end time must be specified if the
            price list's start time is provided.
          type: string
          format: date-time
          example: 2021-06-09T09:23:51.459Z
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        isDeleted:
          $ref: '#/components/schemas/isDeleted'
    priceListRequest:
      type: object
      description: The inputs to create or update price lists.
      required:
        - name
        - isDefault
        - currency
      properties:
        name:
          description: The name of the price list.
          type: string
          example: US price list
        isDefault:
          description: >
            Available options to designate the price list as default include:

            - `true`: This price list is designated as the default price list.

            - `false`: This price list isn't designated as the default price
            list.
          type: boolean
          example: false
        currency:
          description: The currency code defined for the price list.
          type: string
          format: iso-4217
          example: USD
        startAt:
          description: >-
            The start time when the price list becomes active. If no value is
            specified, the current date is used as the start time.
          type: string
          format: date-time
          example: 2021-05-04T09:23:51.459Z
        endAt:
          description: >-
            The end time of the price list. If `startAt` is specified, then
            `endAt becomes mandatory.
          type: string
          format: date-time
          example: 2021-06-09T09:23:51.459Z
    getPriceListResponse:
      $ref: '#/components/schemas/priceList'
    getPriceListsResponse:
      type: object
      description: The sample response of price lists.
      properties:
        query:
          $ref: '#/components/schemas/offsetQuery'
        data:
          description: The details of price lists
          type: array
          items:
            $ref: '#/components/schemas/priceList'
    createPriceListResponse:
      $ref: '#/components/schemas/priceList'
    updatePriceListResponse:
      $ref: '#/components/schemas/priceList'
    deletePriceListResponse:
      $ref: '#/components/schemas/priceList'
    createPriceListRequest:
      $ref: '#/components/schemas/priceListRequest'
    updatePriceListRequest:
      $ref: '#/components/schemas/priceListRequest'
    priceListNameExists:
      type: object
      description: Duplicated price list name error
      properties:
        type:
          description: The error code.
          type: string
          example: PRICE_LIST_NAME_EXISTS
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Price list name already exists
    priceListNameError:
      type: object
      description: Invalid price list name
      properties:
        type:
          description: The error code.
          type: string
          example: PRICE_LIST_NAME_IS_REQUIRED
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Price list name is required
    priceListStartAtError:
      type: object
      description: Invalid start time error
      properties:
        type:
          description: The error code.
          type: string
          example: PRICE_LIST_INVALID_START_AT
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Start time is invalid, it must be in ISO 8601 format
    priceListEndAtError:
      type: object
      description: Invalid end time error
      properties:
        type:
          description: The error code.
          type: string
          example: PRICE_LIST_INVALID_END_AT
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: End time is invalid, it must be in ISO 8601 format
    priceListInconsistentDates:
      type: object
      description: Inconsistent start and end times
      properties:
        type:
          description: The error code.
          type: string
          example: PRICE_LIST_INCONSISTENT_DATES
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Start time must be earlier than the end at time
    priceListIdInvalidError:
      type: object
      description: Invalid price list ID
      properties:
        type:
          description: The error code.
          type: string
          example: PRICE_LIST_ID_INVALID
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Price list ID is required and must be an integer.
  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 through which the API
        request is being made; primarily for multichannel use cases. It is a
        required field.
    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
    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