openapi: 3.0.0
info:
  title: Entitlements
  version: "1.0"
  description: Read the entitlements of the signed-in customer. An entitlement is
    a benefit that a subscription or membership gives, such as access to video
    content or to a ticket sale.
tags:
  - name: Entitlements
paths:
  /entitlements/entitlements:
    get:
      operationId: listEntitlements
      summary: List entitlements
      description: >-
        Returns the entitlements that the customer in the bearer token holds
        now. Entitlements that have expired or have been revoked are not
        returned.


        An organisation defines its own entitlements, so the values of
        `entitlementId` differ between stores. Ask your Stadion technical
        contact for the entitlement ids of your store.


        An entitlement can take a short time to appear after a purchase, because
        the order is processed asynchronously.
      tags:
        - Entitlements
      responses:
        "200":
          description: The entitlements of the customer. The array is empty when the
            customer has none.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Entitlement"
        "400":
          description: The request is not valid.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "401":
          description: The bearer token is missing or not valid.
security:
  - BearerAuth: []
    ApiKeyAuth: []
components:
  schemas:
    Entitlement:
      description: One entitlement of the customer. The type of `value` depends on `type`.
      oneOf:
        - $ref: "#/components/schemas/BooleanEntitlement"
        - $ref: "#/components/schemas/IntegerEntitlement"
        - $ref: "#/components/schemas/RangeEntitlement"
        - $ref: "#/components/schemas/CustomEntitlement"
      discriminator:
        propertyName: type
        mapping:
          boolean: "#/components/schemas/BooleanEntitlement"
          integer: "#/components/schemas/IntegerEntitlement"
          range: "#/components/schemas/RangeEntitlement"
          custom: "#/components/schemas/CustomEntitlement"
    EntitlementBase:
      type: object
      required:
        - id
        - entitlementId
        - expired
      properties:
        id:
          type: string
          description: The id of this grant of the entitlement to the customer.
        entitlementId:
          type: string
          description: The id of the entitlement that the organisation defined, for
            example `content.video`.
        groupingId:
          type: string
          nullable: true
          description: The id of the group that the organisation has put the entitlement in.
        expired:
          type: boolean
          description: Always `false`, because expired entitlements are not returned.
    BooleanEntitlement:
      allOf:
        - $ref: "#/components/schemas/EntitlementBase"
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - boolean
            value:
              type: boolean
              description: Whether the customer has the benefit.
    IntegerEntitlement:
      allOf:
        - $ref: "#/components/schemas/EntitlementBase"
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - integer
            value:
              type: integer
              description: A quantity, such as the number of devices the customer can use.
    RangeEntitlement:
      allOf:
        - $ref: "#/components/schemas/EntitlementBase"
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - range
            value:
              type: integer
              description: A position on a scale that the organisation defined, such as a
                membership tier.
    CustomEntitlement:
      allOf:
        - $ref: "#/components/schemas/EntitlementBase"
        - type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - custom
            value:
              type: string
              description: A value that the organisation defined.
    ProblemDetails:
      type: object
      description: An error in the problem details format. See [Errors](/docs/errors).
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
servers:
  - url: "{baseUrl}"
    description: Your Storefront API host
    variables:
      baseUrl:
        default: https://your-storefront-api-host
        description: The Storefront API base URL for your store. Your Stadion technical
          contact provides it.