Maxio Feature Templates API

openapi: 3.2.0
info:
  title: Maxio Feature Templates API
  version: '1.0'
  contact:
    email: support@maxio.com
  description: 'Operations tagged Feature Templates across 2 of this provider''s published API definitions: maxio-advanced-billing-openapi31json.json, maxio-advanced-billing-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{site}.chargify.com
  description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
- url: https://events.chargify.com/{site}
  description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
- url: https://{site}.ebilling.maxio.com
  description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
security:
- BasicAuth: []
tags:
- name: Feature Templates
  description: 'The Feature Template object defines a feature once at the site level, such as Single Sign-On, a monthly API call limit, or a support tier.


    A feature template is not billable on its own. Attach the template to products or components to grant the feature to subscribers. The kind (access_right, usage_limit, or service_right) determines how the feature''s value behaves. For more information, see Configure Entitlements.'
paths:
  /features.json:
    parameters: []
    get:
      tags:
      - Feature Templates
      summary: listFeatureTemplates
      description: 'Lists the feature templates defined for your site, active (non-archived) ones by default. Pass `status=archived` or `status=all` to widen the result set.


        Supply `page` or `per_page` to paginate. Without either parameter, the response includes the full result set.'
      operationId: listFeatureTemplates
      parameters:
      - name: page
        in: query
        description: 'Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.

          Use in query `page=1`.'
        style: form
        explode: true
        schema:
          minimum: 1.0
          type: integer
          contentEncoding: int32
          default: 1
          examples:
          - 1
      - name: per_page
        in: query
        description: 'This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.

          Use in query `per_page=200`.'
        style: form
        explode: true
        schema:
          maximum: 200.0
          type: integer
          contentEncoding: int32
          default: 20
          examples:
          - 50
      - name: status
        in: query
        description: Filters by archived state. Defaults to `active` (non-archived templates only).
        style: form
        explode: true
        schema:
          allOf:
          - $ref: '#/components/schemas/status1'
          - description: Filters by archived state. Defaults to `active` (non-archived templates only).
      - name: q
        in: query
        description: Filters to feature templates whose name contains this substring (case-insensitive).
        style: form
        explode: true
        schema:
          type: string
      - name: kind
        in: query
        description: Filters by feature kind.
        style: form
        explode: true
        schema:
          allOf:
          - $ref: '#/components/schemas/kind'
          - description: Filters by feature kind.
      - name: updated_from
        in: query
        description: Returns feature templates updated on or after this date.
        style: form
        explode: true
        schema:
          type: string
          contentEncoding: date
      - name: updated_to
        in: query
        description: Returns feature templates updated on or before this date.
        style: form
        explode: true
        schema:
          type: string
          contentEncoding: date
      - name: sort_by
        in: query
        description: The field to sort results by.
        style: form
        explode: true
        schema:
          allOf:
          - $ref: '#/components/schemas/sort_by'
          - description: The field to sort results by.
      - name: sort_direction
        in: query
        description: The sort direction of the returned feature templates.
        style: form
        explode: true
        schema:
          allOf:
          - $ref: '#/components/schemas/sort_direction'
          - description: The sort direction of the returned feature templates.
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/FeatureTemplatesListResponse'
                - examples:
                  - items:
                    - id: 1001
                      key: sso
                      name: Single Sign-On
                      description: null
                      kind: access_right
                      unit: null
                      value_type: boolean
                      default_value: 'true'
                      default_periodicity_interval: null
                      default_periodicity_unit: null
                      archived_at: null
                      created_at: '2024-01-15T10:00:00-05:00'
                      updated_at: '2024-01-15T10:00:00-05:00'
                      products_count: 2
                      plans_count: 5
                    total_count: 1
                    archived_count: 0
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    items:
                    - id: 1001
                      key: sso
                      name: Single Sign-On
                      description: null
                      kind: access_right
                      unit: null
                      value_type: boolean
                      default_value: 'true'
                      default_periodicity_interval: null
                      default_periodicity_unit: null
                      archived_at: null
                      created_at: '2024-01-15T10:00:00-05:00'
                      updated_at: '2024-01-15T10:00:00-05:00'
                      products_count: 2
                      plans_count: 5
                    total_count: 1
                    archived_count: 0
        '403':
          description: Forbidden
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
      deprecated: false
    post:
      tags:
      - Feature Templates
      summary: createFeatureTemplate
      description: Defines a new feature at the site level. Feature templates aren't billable on their own. Attach a template to products or components to grant the feature to subscribers.
      operationId: createFeatureTemplate
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateFeatureTemplateRequest'
              - examples:
                - feature:
                    key: sso
                    name: Single Sign-On
                    kind: access_right
              contentMediaType: application/json
            examples:
              Example:
                value:
                  feature:
                    key: sso
                    name: Single Sign-On
                    kind: access_right
        required: false
      responses:
        '201':
          description: Created
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/FeatureTemplateResponse'
                - examples:
                  - feature:
                      id: 1001
                      key: sso
                      name: Single Sign-On
                      description: null
                      kind: access_right
                      unit: null
                      value_type: boolean
                      default_value: 'true'
                      default_periodicity_interval: null
                      default_periodicity_unit: null
                      archived_at: null
                      created_at: '2024-01-15T10:00:00-05:00'
                      updated_at: '2024-01-15T10:00:00-05:00'
                      products_count: 0
                      plans_count: 0
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    feature:
                      id: 1001
                      key: sso
                      name: Single Sign-On
                      description: null
                      kind: access_right
                      unit: null
                      value_type: boolean
                      default_value: 'true'
                      default_periodicity_interval: null
                      default_periodicity_unit: null
                      archived_at: null
                      created_at: '2024-01-15T10:00:00-05:00'
                      updated_at: '2024-01-15T10:00:00-05:00'
                      products_count: 0
                      plans_count: 0
        '403':
          description: Forbidden
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
        '422':
          description: Unprocessable Entity (WebDAV)
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                  examples:
                  - errors:
                    - Key can't be blank
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    errors:
                    - Key can't be blank
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
  /features/{id}.json:
    parameters: []
    get:
      tags:
      - Feature Templates
      summary: readFeatureTemplate
      description: Returns a single feature template. Archived feature templates are not addressable here and return `404`. Restore a template first to read or update it.
      operationId: readFeatureTemplate
      parameters:
      - name: id
        in: path
        description: The Advanced Billing id of the feature template.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureTemplateResponse'
        '403':
          description: Forbidden
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
        '404':
          description: Not Found
          headers: {}
          content: {}
      deprecated: false
    put:
      tags:
      - Feature Templates
      summary: updateFeatureTemplate
      description: 'Updates the name, description, unit, value type, default value, or default periodicity of a feature template. `key` is rejected on every update. `kind` is rejected once any feature catalog item has been created from this template.


        Archived feature templates are not addressable here and return `404`. Restore a template first to update it.'
      operationId: updateFeatureTemplate
      parameters:
      - name: id
        in: path
        description: The Advanced Billing id of the feature template.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeatureTemplateRequest'
        required: false
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureTemplateResponse'
        '403':
          description: Forbidden
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
        '404':
          description: Not Found
          headers: {}
          content: {}
        '422':
          description: Unprocessable Entity (WebDAV)
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
      deprecated: false
    delete:
      tags:
      - Feature Templates
      summary: archiveFeatureTemplate
      description: 'Archives a feature template. Archived feature templates are not addressable via Read Feature Template or Update Feature Template. Both endpoints return `404` until the template is restored.


        The feature template record itself is never hard-deleted, and can always be restored with Restore Feature Template. Reversibility does not extend to `remove_from_catalog=true`: the feature catalog items and entitlements that parameter destroys are gone permanently, and restoring the template will not bring subscriber access back.'
      operationId: archiveFeatureTemplate
      parameters:
      - name: id
        in: path
        description: The Advanced Billing id of the feature template.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: remove_from_catalog
        in: query
        description: When `true`, also destroys every feature catalog item created from this template and cascades to their entitlements, revoking subscriber access immediately. When `false` (default), the feature template and its feature catalog items are archived, and existing entitlements are preserved.
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: No Content
          headers: {}
          content: {}
        '403':
          description: Forbidden
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
        '404':
          description: Not Found
          headers: {}
          content: {}
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
  /features/{id}/restore.json:
    parameters: []
    post:
      tags:
      - Feature Templates
      summary: restoreFeatureTemplate
      description: Clears the feature template's archived state. Feature catalog items created from this template are not automatically restored. Restore each one individually.
      operationId: restoreFeatureTemplate
      parameters:
      - name: id
        in: path
        description: The Advanced Billing id of the feature template.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureTemplateResponse'
        '403':
          description: Forbidden
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
        '404':
          description: Not Found
          headers: {}
          content: {}
        '422':
          description: Unprocessable Entity (WebDAV)
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                contentMediaType: application/json
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
components:
  schemas:
    ErrorListResponse1:
      title: ErrorListResponse1
      required:
      - errors
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: ''
      description: Error which contains list of messages.
    EntitlementPeriodicityUnit:
      title: EntitlementPeriodicityUnit
      enum:
      - hour
      - day
      - week
      - month
      - year
      type: string
      description: The recurring window over which a `usage_limit` feature's allowance resets.
    status1:
      title: status1
      enum:
      - active
      - archived
      - all
      type: string
    FeatureTemplatesListResponse:
      title: FeatureTemplatesListResponse
      required:
      - items
      - total_count
      - archived_count
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FeatureTemplate'
          description: ''
        total_count:
          type: integer
          description: Total number of feature templates matching the filters, across all pages.
          contentEncoding: int32
        archived_count:
          type: integer
          description: Number of archived feature templates matching the filters. Returned as `0` unless the active result set is empty or `status=archived` was requested.
          contentEncoding: int32
    Feature:
      title: Feature
      required:
      - key
      - name
      - kind
      type: object
      properties:
        key:
          type: string
          description: A unique, lowercase, underscore-separated identifier for the feature. Immutable once set.
          examples:
          - sso
        name:
          type: string
          description: The display name of the feature.
        description:
          type:
          - string
          - 'null'
        kind:
          allOf:
          - $ref: '#/components/schemas/FeatureKind'
          - description: 'The behavior of a feature:

              - `access_right`: a boolean entitlement. A subscriber either has access or does not.

              - `usage_limit`: a quantified allowance measured over a recurring period (for example, "10,000 API calls per month").

              - `service_right`: a free-form value (text, boolean, or number) that isn''t a simple access flag or a metered limit.'
        unit:
          type:
          - string
          - 'null'
          description: Required when `kind` is `usage_limit`.
        value_type:
          allOf:
          - $ref: '#/components/schemas/FeatureValueType'
          - description: Required when `kind` is `service_right`. Ignored for other kinds, where it is inferred automatically.
        default_value:
          type:
          - string
          - 'null'
        default_periodicity_interval:
          type:
          - integer
          - 'null'
          description: Only valid when `kind` is `usage_limit`.
          contentEncoding: int32
        default_periodicity_unit:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/EntitlementPeriodicityUnit'
          - description: Only valid when `kind` is `usage_limit`. Must be set together with `default_periodicity_interval`.
    Feature1:
      title: Feature1
      type: object
      properties:
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        unit:
          type:
          - string
          - 'null'
        value_type:
          allOf:
          - $ref: '#/components/schemas/FeatureValueType'
          - description: The data type of a feature's value. For `access_right` features this is always `boolean`, and for `usage_limit` features this is always `numeric`. For `service_right` features, you choose the value type explicitly.
        default_value:
          type:
          - string
          - 'null'
        default_periodicity_interval:
          type:
          - integer
          - 'null'
          contentEncoding: int32
        default_periodicity_unit:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/EntitlementPeriodicityUnit'
          - {}
      description: '`key` cannot be changed once set. `kind` cannot be changed once any feature catalog item has been created from this template.'
    sort_by:
      title: sort_by
      enum:
      - name
      - updated_at
      - kind
      - value_type
      type: string
    FeatureTemplate:
      title: FeatureTemplate
      type: object
      properties:
        id:
          type: integer
          description: The Advanced Billing id of the feature template.
          contentEncoding: int32
        key:
          type: string
          description: A unique, lowercase, underscore-separated identifier for the feature. Immutable once set.
          examples:
          - sso
        name:
          type: string
          description: The display name of the feature.
          examples:
          - Single Sign-On
        description:
          type:
          - string
          - 'null'
        kind:
          allOf:
          - $ref: '#/components/schemas/FeatureKind'
          - description: 'The behavior of a feature:

              - `access_right`: a boolean entitlement. A subscriber either has access or does not.

              - `usage_limit`: a quantified allowance measured over a recurring period (for example, "10,000 API calls per month").

              - `service_right`: a free-form value (text, boolean, or number) that isn''t a simple access flag or a metered limit.'
        unit:
          type:
          - string
          - 'null'
          description: The unit the feature is measured in (for example, `requests` or `GB`). Required when `kind` is `usage_limit`.
        value_type:
          allOf:
          - $ref: '#/components/schemas/FeatureValueType'
          - description: The data type of a feature's value. For `access_right` features this is always `boolean`, and for `usage_limit` features this is always `numeric`. For `service_right` features, you choose the value type explicitly.
        default_value:
          type:
          - string
          - 'null'
          description: A default value used to pre-populate new feature catalog items created from this template.
        default_periodicity_interval:
          type:
          - integer
          - 'null'
          description: For `usage_limit` features, the default periodicity interval used to pre-populate new feature catalog items. Always `null` for other kinds.
          contentEncoding: int32
        default_periodicity_unit:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/EntitlementPeriodicityUnit'
          - description: For `usage_limit` features, the default periodicity unit used to pre-populate new feature catalog items. Always `null` for other kinds.
        archived_at:
          type:
          - string
          - 'null'
          description: The date and time the feature template was archived, or `null` if it is active.
          contentEncoding: date-time
        created_at:
          type: string
          contentEncoding: date-time
        updated_at:
          type: string
          contentEncoding: date-time
        products_count:
          type: integer
          description: The number of **components** this feature template is currently attached to via an active feature catalog item. Despite the name, this counts components, not products. In the Advanced Billing UI, components are labeled "Products."
          contentEncoding: int32
        plans_count:
          type: integer
          description: The number of **products** this feature template is currently attached to via an active feature catalog item. Despite the name, this counts products, not plans. In the Advanced Billing UI, products are labeled "Plans."
          contentEncoding: int32
      description: A feature that can be granted to subscribers, defined once at the site level and then attached to products or components.
    FeatureValueType:
      title: FeatureValueType
      enum:
      - text
      - boolean
      - numeric
      type: string
      description: The data type of a feature's value. For `access_right` features this is always `boolean`, and for `usage_limit` features this is always `numeric`. For `service_right` features, you choose the value type explicitly.
    UpdateFeatureTemplateRequest:
      title: UpdateFeatureTemplateRequest
      required:
      - feature
      type: object
      properties:
        feature:
          allOf:
          - $ref: '#/components/schemas/Feature1'
          - description: '`key` cannot be changed once set. `kind` cannot be changed once any feature catalog item has been created from this template.'
    CreateFeatureTemplateRequest:
      title: CreateFeatureTemplateRequest
      required:
      - feature
      type: object
      properties:
        feature:
          $ref: '#/components/schemas/Feature'
    sort_direction:
      title: sort_direction
      enum:
      - asc
      - desc
      type: string
    FeatureTemplateResponse:
      title: FeatureTemplateResponse
      required:
      - feature
      type: object
      properties:
        feature:
          allOf:
          - $ref: '#/components/schemas/FeatureTemplate'
          - description: A feature that can be granted to subscribers, defined once at the site level and then attached to products or components.
    kind:
      title: kind
      enum:
      - access_right
      - usage_limit
      - service_right
      - all
      type: string
    FeatureKind:
      title: FeatureKind
      enum:
      - access_right
      - usage_limit
      - service_right
      type: string
      description: 'The behavior of a feature:

        - `access_right`: a boolean entitlement. A subscriber either has access or does not.

        - `usage_limit`: a quantified allowance measured over a recurring period (for example, "10,000 API calls per month").

        - `service_right`: a free-form value (text, boolean, or number) that isn''t a simple access flag or a metered limit.'
  securitySchemes:
    BasicAuth:
      type: http
      description: The `username` is a Maxio Chargify API key. The `password` is `x`.
      scheme: basic
x-refined-from:
- maxio-advanced-billing-openapi31json.json
- maxio-advanced-billing-openapi.yml
x-provenance:
  method: harvested
  publisher: Maxio
  source: https://developers.maxio.com/static/exports/maxio-advanced-billing-openapi31json.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)