openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Features API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
tags:
- name: Features
  description: "A feature indicates some benefit that is received as a result of having an active subscription. This translates to tags being applied to the subscriber's account allowing access to some resource to be controlled.\n\nThere are three types of feature - `access`, `promotion`, and `usage`.\n\nThe `access` feature is designed to simply give access to some resource, for example a streaming service. If its tag is present on the subscriber's account then access to that resource should be provided.\n\nThe `promotion` feature coupled with the [promotions service](/docs/promotions-builder/overview) allows subscribers to get access to a specific promotion. This is achieved using a tag which is used as a constraint on the promotion. A promotion feature may have multiple promotions associated with it, but just one must be selected when configuring the feature for an offering's plan.\n\n The `usage` feature is designed to measure some sort of usage of a resource. This currently relies on [commerce extensions](/docs/api/commerce-extensions/commerce-extensions-introduction) to manage usage.\n\n Once defined a feature may be attached to an offering, making it available for use with any of that offering's plans. Once attached it must be configured for each of the offering's plans it is applicable to. For the `promotion` feature this involves specifying which of that feature's tags, and hence which promotion, should be applied when subscribed to that offering. Similarly, for the `promotion` feature the default value for the usage metric must be supplied.\n"
paths:
  /v2/subscriptions/features:
    parameters:
    - $ref: '#/components/parameters/Filter'
    post:
      tags:
      - Features
      summary: Create a feature
      operationId: CreateFeature
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/FeatureCreate'
      responses:
        '201':
          description: Success. The feature is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - Features
      parameters:
      - $ref: '#/components/parameters/PageOffset'
      - $ref: '#/components/parameters/PageLimit'
      summary: List features
      description: "Retrieves a list of all subscription features.\n\n### Filtering\n\nThis endpoint supports filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering).\n\nThe following attributes and operators are supported.\n\n| Operator | Attribute | Description |\n| --- | --- | --- | \n| `eq` | `external_ref` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |\n| `eq` | `tag` | Equals. Checks if the values of two operands are equal. If they are, the condition is true. |\n| `in` | `external_ref`, `tag` | In. Checks if the value is in the specified list. If it is, the condition is true. |\n"
      operationId: ListFeatures
      responses:
        '200':
          description: Success. A list of features is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Feature'
                  links:
                    $ref: '#/components/schemas/Links'
        '400':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/subscriptions/features/{feature_uuid}:
    parameters:
    - name: feature_uuid
      in: path
      description: The unique identifier of a feature.
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
    get:
      tags:
      - Features
      summary: Get feature
      operationId: GetFeature
      responses:
        '200':
          description: Success. The feature details are returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - Features
      summary: Delete feature
      description: Remove a feature.
      operationId: DeleteFeature
      responses:
        '204':
          description: Success. The feature is removed.
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      tags:
      - Features
      summary: Update a feature
      description: Specify whichever attributes you want to change. The values of the other attributes remain the same. If the attributes section is empty, the feature is not updated. For fields that are optional, an existing value can be removed by specifying a value of null.
      operationId: UpdateFeature
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/FeatureUpdate'
      responses:
        '200':
          description: Success. The feature details are updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Feature'
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/WriteConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    PageOffset:
      name: page[offset]
      description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      in: query
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        maximum: 10000
        example: 10
    Filter:
      name: filter
      in: query
      required: false
      schema:
        type: string
        format: string
        description: 'Some Subscriptions API endpoints support filtering. For the general syntax, see [**Filtering**](/guides/Getting-Started/filtering), but you must go to a specific endpoint to understand the attributes and operators an endpoint supports.

          '
        example: eq(name,Alan Turing)
    PageLimit:
      name: page[limit]
      description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used.
      in: query
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        example: 100
  responses:
    ForbiddenError:
      description: Forbidden. The operation is forbidden on this entity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found:
              value:
                errors:
                - title: Permission denied
                  status: '404'
                  detail: 'Permission denied: plan tenancy mismatch'
    NotFoundError:
      description: Not found. The requested entity does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            not-found:
              value:
                errors:
                - title: Not Found
                  status: '404'
                  detail: No plan found
    WriteConflictError:
      description: Write conflict. Unable to perform the operation at this time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            errors:
            - title: Write Conflict
              status: '409'
    ValidationError:
      description: Bad request. The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing-name:
              value:
                errors:
                - title: Validation Error
                  status: '400'
                  detail: 'data.attributes.name: "name" is required'
    InternalServerError:
      description: Internal server error. There was a system failure in the platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal-server-error:
              value:
                errors:
                - title: Internal Server Error
                  status: '500'
  schemas:
    FeatureResponseAttributes:
      allOf:
      - $ref: '#/components/schemas/FeatureAttributes'
    Timestamps:
      required:
      - created_at
      - updated_at
      properties:
        updated_at:
          description: The date and time a resource was updated.
          type: string
          example: '2017-01-10T11:41:19.244842Z'
        created_at:
          description: The date and time a resource was created.
          type: string
          example: '2017-01-10T11:41:19.244842Z'
    Link:
      anyOf:
      - $ref: '#/components/schemas/LinkURI'
      - $ref: '#/components/schemas/LinkObject'
    Error:
      required:
      - status
      - title
      properties:
        status:
          type: string
          description: The HTTP response code of the error.
          example: '500'
        title:
          type: string
          description: A brief summary of the error.
          example: Internal server error
        detail:
          type: string
          description: Optional additional detail about the error.
          example: An internal error has occurred.
        meta:
          type: object
          description: Additional supporting meta data for the error.
          example:
            missing_ids:
            - e7d50bd5-1833-43c0-9848-f9d325b08be8
    FeatureAccessAttributes:
      required:
      - type
      - tag
      properties:
        type:
          type: string
          enum:
          - access
          example: access
        tag:
          $ref: '#/components/schemas/FeatureTag'
    FeatureUpdate:
      required:
      - id
      - type
      - attributes
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionFeatureType'
        attributes:
          $ref: '#/components/schemas/FeatureUpdateAttributes'
    SubscriptionFeatureType:
      type: string
      example: subscription_feature
      enum:
      - subscription_feature
    ErrorResponse:
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Link'
    FeaturePromotion:
      required:
      - name
      - tag
      properties:
        name:
          type: string
          description: The name of the feature.
          minLength: 3
          maxLength: 1024
          example: Digital library access
        tag:
          $ref: '#/components/schemas/FeatureTag'
        promotion_id:
          $ref: '#/components/schemas/UUID'
    FeatureAttributes:
      required:
      - name
      - configuration
      properties:
        external_ref:
          $ref: '#/components/schemas/ExternalRef'
        name:
          type: string
          description: The name of the feature.
          minLength: 3
          maxLength: 1024
          example: Digital library access
        description:
          type: string
          description: The feature description to display to customers.
          maxLength: 1024
          example: Access to over 100 ebooks via the digital library.
        configuration:
          $ref: '#/components/schemas/FeatureConfiguration'
    LinkObject:
      type: object
      properties:
        href:
          type: string
          format: uri
          example: http://example.com/articles/1/comments
        title:
          type: string
          example: Comments
        describedby:
          type: string
          format: uri
          example: http://example.com/schemas/article-comments
    FeatureConfiguration:
      type: object
      required:
      - type
      properties:
        type:
          description: The type of feature, one of access, promotion or usage.
          enum:
          - access
          - promotion
          - usage
          example: access
          x-go-type: string
      oneOf:
      - $ref: '#/components/schemas/FeatureAccessAttributes'
      - $ref: '#/components/schemas/FeaturePromotionAttributes'
      - $ref: '#/components/schemas/FeatureUsageAttributes'
      discriminator:
        propertyName: type
        mapping:
          access: '#/components/schemas/FeatureAccessAttributes'
          promotion: '#/components/schemas/FeaturePromotionAttributes'
          usage: '#/components/schemas/FeatureUsageAttributes'
    FeatureCreate:
      required:
      - type
      - attributes
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionFeatureType'
        attributes:
          $ref: '#/components/schemas/FeatureAttributes'
    UUID:
      type: string
      description: The unique identifier.
      format: uuid
      x-go-type: uuid.UUID
      x-go-type-import:
        name: uuid
        path: github.com/google/uuid
      example: 11111111-2222-3333-4444-555555555555
    LinkURI:
      type: string
      format: uri
      example: http://example.com/articles/1/comments
      nullable: true
    OwnerMeta:
      readOnly: true
      type: string
      format: string
      description: The owner of a resource, either `store` or `organization`.
      example: store
    ExternalRefUpdate:
      description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
      type: string
      example: abc123
      maxLength: 2048
      nullable: true
    FeatureTag:
      type: string
      description: A tag to add to the customer's account when entitled to the feature.
      minLength: 1
      maxLength: 64
      pattern: ^[0-9A-Za-z_-]+$
      example: digital_library_access
    Feature:
      required:
      - type
      - attributes
      - meta
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        type:
          $ref: '#/components/schemas/SubscriptionFeatureType'
        attributes:
          $ref: '#/components/schemas/FeatureResponseAttributes'
        meta:
          $ref: '#/components/schemas/FeatureMeta'
    FeatureUpdateAttributes:
      properties:
        external_ref:
          $ref: '#/components/schemas/ExternalRefUpdate'
        name:
          type: string
          description: The name of the feature.
          minLength: 3
          maxLength: 1024
          example: Digital library access
        description:
          type: string
          description: The feature description to display to customers.
          maxLength: 1024
          example: Access to over 100 ebooks via the digital library.
          nullable: true
        configuration:
          $ref: '#/components/schemas/FeatureConfiguration'
    FeaturePromotionAttributes:
      required:
      - type
      - promotions
      properties:
        type:
          type: string
          enum:
          - promotion
          example: promotion
        promotions:
          type: array
          items:
            $ref: '#/components/schemas/FeaturePromotion'
    FeatureMeta:
      readOnly: true
      required:
      - owner
      - timestamps
      properties:
        owner:
          $ref: '#/components/schemas/OwnerMeta'
        timestamps:
          $ref: '#/components/schemas/Timestamps'
    FeatureUsageAttributes:
      required:
      - type
      - tag
      - label
      - default_value
      properties:
        type:
          type: string
          enum:
          - usage
          example: usage
        tag:
          $ref: '#/components/schemas/FeatureTag'
        label:
          type: string
          description: The property that has a usage limit.
          minLength: 3
          maxLength: 1024
          example: Digital downloads
        default_value:
          type: integer
          description: The default initial value
          example: 10
    ExternalRef:
      description: A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.
      type: string
      example: abc123
      maxLength: 2048
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer