openapi: 3.0.0
"x-mint": {
    "mcp": {
      "enabled": true
    }
  }
info:
  title: Offers - Attributes API
  description: Using attributes, you can group shoppers who share similar characteristics, such as age group, demographics, location, device type, and more. The shopper segmentation can be used to tailor promotions to a specific customer segment by linking the promotion to the segment identifier.
  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:
  /attributes:
    get:
      tags:
        - Attributes
      summary: Get all attributes
      description: Using this endpoint, you can get a paginated list of attributes. You can narrow down the search results by specifying pagination criteria, and you can also sort the results.
      operationId: getAttributes
      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
              - -name
              - +name
        - name: q
          description: Search for attributes by partial match. It matches content in the `name` field or any of the values in the `values` array.
          in: query
          schema:
            type: string
            example: Event
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: "#/components/headers/xFabricRequestIdResponse"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getAttributesResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $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:
        - Attributes
      summary: Create attribute
      description: Use this endpoint to create a new attribute. Attributes can be used as part of the qualifications for promotions or coupons.
      operationId: createAttribute
      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/createAttributeRequest'
      responses:
        "201":
          description: Created
          headers:
            x-fabric-request-id:
              $ref: "#/components/headers/xFabricRequestIdResponse"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createAttributeResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/attributeNameExist'
                  - $ref: '#/components/schemas/attributeNameNotValid'
                  - $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'
  /attributes/{attributeId}:
    put:
      tags:
        - Attributes
      summary: Update attribute
      description: Using this endpoint, you can update an attribute by its ID. You can primarily update attribute and its value.
      operationId: updateAttribute
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - name: attributeId
          in: path
          required: true
          description: A unique identifier of the attribute.
          schema:
            type: integer
            format: int32
            example: 100002
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateAttributeRequest'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updateAttributeResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/attributeNameExist'
                  - $ref: '#/components/schemas/attributeNameNotValid'
                  - $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/attributeNotFound'
        "500":
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    get:
      tags:
        - Attributes
      summary: Get attribute
      description: Using this endpoint, you can get details of an attribute by its ID.
      operationId: getAttribute
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - in: path
          name: attributeId
          schema:
            type: integer
            format: int32
            example: 1000002
          required: true
          description: A unique identifier of the attribute, for external use.
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getAttributeResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $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/attributeNotFound'
        "500":
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    delete:
      tags:
        - Attributes
      summary: Delete attribute
      description: Using this endpoint, you can delete an attribute by its ID.
      operationId: deleteAttribute
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - name: attributeId
          in: path
          required: true
          description: A unique identifier of the attribute, for external use.
          schema:
            type: integer
            format: int32
            example: 1000002
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deleteAttributeResponse'
              example:
                 id: 614b58924e92f6861ac9d43b
                 name: Spender
                 values:
                   - High spender
                   - Medium spender
                   - Browser
                 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/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: Unauthorized
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/attributeNotFound'
        "500":
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
  /attributes/actions/verify-dependencies:
    post:
      tags:
        - Attributes
      summary: Verify whether the specified attributes are linked to any offers
      description: Use this endpoint to verify whether the specified attribute IDs are active and being used in promotions and coupons. The objective is to prevent deletion of attributes that are already linked to active or scheduled promotions and coupons.
      operationId: verifyAttributesDependencies
      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/verifyAttributeDependenciesRequest'
      responses:
        '200':
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verifyAttributeDependenciesResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/attributeIdsRequired'
                  - $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
    # Generic
    createdAt:
      type: string
      format: date-time
      description: Record's creation time
      example: 2019-08-20T14:15:22Z
    updatedAt:
      type: string
      format: date-time
      description: Record's last updated time
      example: 2019-08-20T14:15:22Z
    isDeleted:
      type: boolean
      description: "true: Record is deleted<br>false: Record isn't deleted"
      example: false
    # 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.

    # Attributes
    attribute:
      type: object
      description: The attribute details.
      required:
        - id
        - name
        - values
        - createdAt
        - updatedAt
        - isDeleted
      properties:
        id:
          description: A unique identifier of the attribute, for external use.
          type: integer
          format: int32
          example: 1000002
        name:
          description: The name of the attribute.
          type: string
          example: Brand
        values:
          description: The attribute values.
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            description: The options within an attribute type.
            example: CHS
          example:
            - CHS
            - SOMA
            - WHBM
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        isDeleted:
          $ref: '#/components/schemas/isDeleted'
    attributeRequest:
      type: object
      description: The details of the attribute.
      required:
        - name
        - values
      properties:
        name:
          description: The name of the attribute type.
          type: string
          maxLength: 300
          example: Brand
        values:
          description: The options within an attribute type.
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            example: CHS
          example:
            - CHS
            - SOMA
            - WHBM
    getAttributesResponse:
      type: object
      description: A paginated list of attributes.
      properties:
        query:
          $ref: '#/components/schemas/offsetQuery'
        data:
          description: The list of attributes.
          type: array
          items:
            $ref: '#/components/schemas/attribute'
    getAttributeResponse:
      $ref: '#/components/schemas/attribute'
    createAttributeResponse:
      $ref: '#/components/schemas/attribute'
    updateAttributeResponse:
      $ref: '#/components/schemas/attribute'
    deleteAttributeResponse:
      $ref: '#/components/schemas/attribute'
    createAttributeRequest:
      $ref: '#/components/schemas/attributeRequest'
    updateAttributeRequest:
      $ref: '#/components/schemas/attributeRequest'
    verifyAttributeDependenciesRequest:
      type: object
      description: A sample request to verify the status of the specified attribute IDs.
      required:
        - attributeIds
      properties:
        attributeIds:
          type: array
          description: The attribute IDs.
          maxItems: 50
          minItems: 1
          items:
            type: integer
            format: int32
            example: 100000
    verifyAttributeDependenciesResponse:
      type: object
      description: A sample response indicating the statuses of the specified attribute IDs.
      properties:
        data:
          type: array
          description: A list of attribute IDs along with their respective statuses.
          items:
            type: object
            description: The attribute ID and its status.
            required:
              - attributeId
              - dependencyStatus
            properties:
              attributeId:
                description: The attribute ID.
                type: integer
                format: int32
                example: 100000
              dependencyStatus:
                description: A flag indicating whether the specified segment ID is used in promotions and coupons. The system returns `true` if the segment ID is linked to any promotion or coupon; otherwise,  it returns `false`.
                enum:
                  - ACTIVE
                  - INACTIVE
                type: string
                example: ACTIVE
    # Attributes - Errors
    attributeNameExist:
      type: object
      description: Duplicated attribute name error
      properties:
        type:
          description: The error code.
          type: string
          example: ATTRIBUTE_NAME_EXISTS
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Attribute name already exists
    attributeNameNotValid:
      type: object
      description: Invalid attribute ID
      properties:
        type:
          description: The error code.
          type: string
          example: ATTRIBUTE_NAME_VALUE_CANNOT_BE_EMPTY
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Attribute name can't be empty
    attributeNotFound:
      type: object
      description: Attribute not found error
      properties:
        type:
          description: The error code.
          type: string
          example: ATTRIBUTE_NOT_FOUND
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: No attribute with this ID is found
    attributeIdsRequired:
      type: object
      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 in body must have required property 'attributeIds'

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