openapi: 3.0.0
"x-mint": {
    "mcp": {
      "enabled": true
    }
  }
info:
  title: Offers - Segments
  description: Segmentation is a way of grouping customers who share similar characteristics. They may be grouped in a number of ways such as, age group, demographics, location, device type, etc. After creating a segment of customers, you can target promotions to a specific customer segment by linking the promotion to a 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:
  /segments:
    get:
      tags:
        - Segments
      summary: Get all segments
      description: Get a paginated list of all the created segments.
      operationId: getSegments
      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 segments 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: Spender
      responses:
        "200":
          description: Accepted
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getSegmentsResponse'
        "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:
        - Segments
      summary: Create segment
      description: Create a segment to group a specific set of customers. By segmenting customers, you can gain insight into which products are popular among different customer segments, and can create targeted retention strategies. You can also create targeted marketing campaigns that can result in higher conversion rates and increased sales.
      operationId: createSegment
      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/createSegmentRequest'
      responses:
        "201":
          description: Created
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createSegmentResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/segmentNameExist'
                  - $ref: '#/components/schemas/segmentNameNotValid'
                  - $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'
  /segments/{segmentId}:
    put:
      tags:
        - Segments
      summary: Update a specific segment
      description: Update a specific segment by ID.
      operationId: updateSegment
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - name: segmentId
          in: path
          required: true
          description: Segment ID to update the segment
          schema:
            type: integer
            format: int32
            example: 10002
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateSegmentRequest'
      responses:
        "200":
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updateSegmentResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/segmentNameExist'
                  - $ref: '#/components/schemas/segmentNameNotValid'
                  - $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/segmentNotFound'
        "500":
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    get:
      tags:
        - Segments
      summary: Get a specific segment
      description: Get details of a specific segment by ID.
      operationId: getSegment
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - in: path
          name: segmentId
          schema:
            type: integer
            format: int32
            example: 1000002
          required: true
          description: Segment ID
      responses:
        "200":
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getSegmentResponse'
        "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/segmentNotFound'
        "500":
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
    delete:
      tags:
        - Segments
      summary: Delete a specific segment
      description: Delete a specific segment by ID.
      operationId: deleteSegment
      security:
        - AuthorizationToken: []
      parameters:
        - $ref: '#/components/parameters/xFabricTenantId'
        - $ref: '#/components/parameters/xFabricChannelId'
        - $ref: '#/components/parameters/xClientId'
        - $ref: '#/components/parameters/xFabricRequestId'
        - name: segmentId
          in: path
          required: true
          description: Segment ID to delete the segment
          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/deleteSegmentResponse'
              example:
                 id: 1000002
                 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: Not Found
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/segmentNotFound'
        "500":
          description: Internal server error
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error500'
  /segments/actions/verify-dependencies:
    post:
      tags:
        - Segments
      summary: Verify whether the specified segments are linked to any offers
      description: Use this endpoint to verify whether the specified segment IDs are active and being used in promotions and coupons. The objective is to prevent deletion of segments that are already linked to active or scheduled promotions and coupons.
      operationId: verifySegmentsDependencies
      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/verifySegmentDependenciesRequest'
      responses:
        "200":
          description: OK
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verifySegmentDependenciesResponse'
        "400":
          description: Bad request
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/xFabricRequestIdResponse'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/segmentIdsRequired'
                  - $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.
    # 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
    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

    # Segments
    segment:
      type: object
      description: The segment details.
      required:
        - id
        - name
        - values
        - createdAt
        - updatedAt
        - isDeleted
      properties:
        id:
          description: The segment ID.
          type: integer
          format: int32
          example: 1000002
        name:
          description: The name of the segment type.
          type: string
          example: Spender
        values:
          description: The options within a segment type.
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            example: High Spender
          example:
            - High spender
            - Medium spender
            - Browser
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        isDeleted:
          $ref: '#/components/schemas/isDeleted'
    segmentRequest:
      type: object
      description: The details of segment.
      required:
        - name
        - values
      properties:
        name:
          description: The name of the segment type.
          type: string
          maxLength: 300
          example: Customer Type
        values:
          description: The options within a segment type.
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            example: High Spender
          example:
            - High spender
            - Medium spender
            - Browser
    getSegmentsResponse:
      type: object
      description: The paginated response of segments.
      properties:
        query:
          $ref: "#/components/schemas/offsetQuery"
        data:
          description: The segments list.
          type: array
          items:
            $ref: '#/components/schemas/segment'
    getSegmentResponse:
      $ref: '#/components/schemas/segment'
    createSegmentResponse:
      $ref: '#/components/schemas/segment'
    updateSegmentResponse:
      $ref: '#/components/schemas/segment'
    deleteSegmentResponse:
      $ref: '#/components/schemas/segment'
    createSegmentRequest:
      $ref: '#/components/schemas/segmentRequest'
    updateSegmentRequest:
      $ref: '#/components/schemas/segmentRequest'
    verifySegmentDependenciesRequest:
      type: object
      description: A sample request to verify whether the specified segment IDs are currently active and used in promotions and coupons.
      required:
        - segmentIds
      properties:
        segmentIds:
          type: array
          description: A sample response indicating the status of the specified segment IDs.
          maxItems: 50
          minItems: 1
          items:
            description: The Segment ID.
            type: integer
            format: int32
            example: 100000
    verifySegmentDependenciesResponse:
      type: object
      description: A sample response indicating the status of the specified segment IDs.
      properties:
        data:
          type: array
          description: List with the dependency status of the provided segment IDs.
          items:
            type: object
            description: The segment ID and its status.
              - segmentId
              - dependencyStatus
            properties:
              segmentId:
                description: The segment 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
    # Segments - Errors
    segmentNameExist:
      type: object
      description: The error due to duplicate segment name.
      properties:
        type:
          description: The error code.
          type: string
          example: SEGMENT_NAME_EXISTS
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Segment name already exists
    segmentNameNotValid:
      type: object
      description: The error due to invalid segment.
      properties:
        type:
          description: The error code.
          type: string
          example: SEGMENT_NAME_VALUE_CANNOT_BE_EMPTY
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: Segment name can't be empty
    segmentNotFound:
      type: object
      description: Segment not found error
      properties:
        type:
          description: The error code.
          type: string
          example: SEGMENT_NOT_FOUND
        message:
          description: An error message corresponding to the `type`.
          type: string
          example: No segment with this ID is found
    segmentIdsRequired:
      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 'segmentIds'

  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