Maxio Product Features API

openapi: 3.2.0
info:
  title: Maxio Product Features API
  version: '1.0'
  contact:
    email: support@maxio.com
  description: 'Operations tagged Product Features 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: Product Features
  description: 'The Product Feature object attaches a Feature Template to a Product as a feature catalog item with a concrete value, granting that feature to subscribers through the product.


    A product feature applies to the whole product by default, or can be scoped to a single product price point as an override. For more information, see Configure Entitlements.'
paths:
  /products/{product_id}/features.json:
    parameters: []
    get:
      tags:
      - Product Features
      summary: listProductFeatures
      description: Lists the feature catalog items attached to this product, including price-point-specific overrides.
      operationId: listProductFeatures
      parameters:
      - name: product_id
        in: path
        description: The Advanced Billing id of the product.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCatalogItemsListResponse'
        '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
    post:
      tags:
      - Product Features
      summary: createProductFeature
      description: 'Attaches a feature template to this product. Pass `price_point_type: "ProductPricePoint"` and `price_point_id` to scope the feature catalog item to a single product price point instead of the whole product. `value`, the periodicity and the grant expiration fall back to the feature template''s defaults when omitted.


        **Product- or component-level items are a template.** A feature catalog item without `price_point_id` is copied onto price points created after it (except bulk-created price points; Clone Component Price Point applies only the `feature_catalog_items` you send with it, and the automatic clone described below copies the source''s features), but it is not added to price points that already exist, so their subscribers get nothing from it, even with `propagate_to_subscriptions: true`. To grant a feature to existing subscribers, create the item on each existing price point.


        **Restoring a template item.** Restoring an archived product- or component-level item, or creating one again for the same feature template, also restores the price-point copies that were archived together with it (for example, when the feature template was archived). If one of those price points has subscribers without the feature, the call returns `422` naming that price point, unless you send `propagate_to_subscriptions: true`, which restores the copies and grants the feature to those subscribers.


        **Price points with subscribers.** When the feature catalog item is scoped to a price point that already has subscribers and you don''t send `propagate_to_subscriptions: true`, the new feature applies to new subscriptions only. The price point is cloned with its current features, the new feature is applied to the clone, and the response carries the clone''s `price_point_id`. The feature catalog item in the response is also a different record, with a new `id`: later calls for the clone must use that `id`, not the original one. Existing subscribers stay on the original price point, unchanged; sign new subscriptions up on the clone to give them the change. A product price point has subscribers when any live subscription (including one in `awaiting_signup`) is on it. Price points that can''t be cloned (archived or custom ones, or a component price point with an interval on a site without multi-frequency) make the request return `422`, with a message naming `propagate_to_subscriptions: true` as the way to apply the change to existing subscribers instead.'
      operationId: createProductFeature
      parameters:
      - name: product_id
        in: path
        description: The Advanced Billing id of the product.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeatureCatalogItemRequest'
        required: false
      responses:
        '201':
          description: Created
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCatalogItemResponse'
        '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.
  /products/{product_id}/features/{id}.json:
    parameters: []
    get:
      tags:
      - Product Features
      summary: readProductFeature
      description: Returns a single feature catalog item attached to this product.
      operationId: readProductFeature
      parameters:
      - name: product_id
        in: path
        description: The Advanced Billing id of the product.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: id
        in: path
        description: The Advanced Billing id of the feature catalog item.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCatalogItemResponse'
        '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:
      - Product Features
      summary: updateProductFeature
      description: 'Updates the value or periodicity of a feature catalog item attached to this product. A request that changes nothing returns the item as it is.


        **Price points with subscribers.** When the feature catalog item is scoped to a price point that already has subscribers and you don''t send `propagate_to_subscriptions: true`, the update applies to new subscriptions only. The price point is cloned with its current features, the update is applied to the clone, and the response carries the clone''s `price_point_id`. The feature catalog item in the response is also a different record, with a new `id`: later calls for the clone must use that `id`, not the original one. Existing subscribers stay on the original price point, unchanged; sign new subscriptions up on the clone to give them the change. A product price point has subscribers when any live subscription (including one in `awaiting_signup`) is on it. Price points that can''t be cloned (archived or custom ones, or a component price point with an interval on a site without multi-frequency) make the request return `422`, with a message naming `propagate_to_subscriptions: true` as the way to apply the change to existing subscribers instead.'
      operationId: updateProductFeature
      parameters:
      - name: product_id
        in: path
        description: The Advanced Billing id of the product.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: id
        in: path
        description: The Advanced Billing id of the feature catalog item.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeatureCatalogItemRequest'
        required: false
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCatalogItemResponse'
        '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:
      - Product Features
      summary: removeProductFeature
      description: 'Removes a feature catalog item from this product. Returns `204` when the item is removed in place.


        **Price points with subscribers.** When the feature catalog item is scoped to a price point that already has subscribers and you don''t send `destroy_entitlements=true`, the removal applies to new subscriptions only. The price point is cloned with its current features, the removal is applied to the clone, and the call returns `200` with the archived feature catalog item on the clone (carrying the clone''s `price_point_id` and a new `id`) instead of `204`. Existing subscribers stay on the original price point, unchanged; sign new subscriptions up on the clone to give them the change. A product price point has subscribers when any live subscription (including one in `awaiting_signup`) is on it. Price points that can''t be cloned (archived or custom ones, or a component price point with an interval on a site without multi-frequency) make the request return `422`, with a message naming `destroy_entitlements=true` as the way to apply the change to existing subscribers instead.'
      operationId: removeProductFeature
      parameters:
      - name: product_id
        in: path
        description: The Advanced Billing id of the product.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: id
        in: path
        description: The Advanced Billing id of the feature catalog item.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: destroy_entitlements
        in: query
        description: When `true`, permanently deletes this feature catalog item and every entitlement it created, revoking subscriber access immediately. When `false` (default), the feature catalog item is archived and existing entitlements are preserved.
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: The price point had subscribers, so the removal was made on a clone of it. Returns the archived feature catalog item on the clone.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCatalogItemResponse'
        '204':
          description: No Content. The feature catalog item was removed in place.
          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: {}
        '422':
          description: The price point has subscribers but can't be cloned (it is archived or custom, or it is a component price point with an interval on a site without multi-frequency). Send `destroy_entitlements=true` to remove the feature from its existing subscribers instead.
          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.
  /products/{product_id}/features/{id}/restore.json:
    parameters: []
    post:
      tags:
      - Product Features
      summary: restoreProductFeature
      description: 'Clears the archived state of a feature catalog item attached to this product. Returns `422` if the parent feature template is still archived. Restore the feature template first. Otherwise, restoring an item that isn''t archived returns it unchanged.


        **Price points with subscribers.** When the feature catalog item is scoped to a price point that already has subscribers and you don''t send `propagate_to_subscriptions=true`, the restore applies to new subscriptions only. The price point is cloned with its current features, the restore is applied to the clone, and the response carries the clone''s `price_point_id`. The feature catalog item in the response is also a different record, with a new `id`: later calls for the clone must use that `id`, not the original one. Existing subscribers stay on the original price point, unchanged; sign new subscriptions up on the clone to give them the change. A product price point has subscribers when any live subscription (including one in `awaiting_signup`) is on it. Price points that can''t be cloned (archived or custom ones, or a component price point with an interval on a site without multi-frequency) make the request return `422`, with a message naming `propagate_to_subscriptions: true` as the way to apply the change to existing subscribers instead.'
      operationId: restoreProductFeature
      parameters:
      - name: product_id
        in: path
        description: The Advanced Billing id of the product.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: id
        in: path
        description: The Advanced Billing id of the feature catalog item.
        required: true
        schema:
          type: integer
          contentEncoding: int32
      - name: propagate_to_subscriptions
        in: query
        description: When `true`, the restored feature is applied to the existing subscriptions on its price point. When `false` (default), an item scoped to a price point with subscribers is restored on a clone of that price point instead; a product- or component-level item is never cloned, and returns `422` if a price-point copy it restores has subscribers without the feature. See the description.
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureCatalogItemResponse'
        '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.
    FeatureCatalogItemsListResponse:
      title: FeatureCatalogItemsListResponse
      required:
      - features
      - subscriptions_count
      type: object
      properties:
        features:
          type: array
          items:
            $ref: '#/components/schemas/FeatureCatalogItem'
          description: ''
        subscriptions_count:
          type: integer
          description: The number of subscriptions on this product/component that would be affected if a feature catalog item change were propagated with `propagate_to_subscriptions=true`.
          contentEncoding: int32
    UpdateFeatureCatalogItemRequest:
      title: UpdateFeatureCatalogItemRequest
      required:
      - feature
      type: object
      properties:
        feature:
          $ref: '#/components/schemas/Feature3'
    FeatureCatalogItemResponse:
      title: FeatureCatalogItemResponse
      required:
      - feature
      type: object
      properties:
        feature:
          allOf:
          - $ref: '#/components/schemas/FeatureCatalogItem'
          - description: A feature template attached to a specific product or component (or one of their price points), with a concrete value. When a subscriber signs up for or is assigned this product/component, the feature catalog item is provisioned as an entitlement on their subscription.
    FeatureCatalogItem:
      title: FeatureCatalogItem
      type: object
      properties:
        id:
          type: integer
          contentEncoding: int32
        feature_template_id:
          type: integer
          description: The id of the feature template this item was created from.
          contentEncoding: int32
        feature_key:
          type: string
          description: The `key` of the parent feature template.
        feature_name:
          type: string
          description: The `name` of the parent feature template.
        feature_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.'
        value:
          type: string
          description: 'The value granted by this feature catalog item. Interpreted according to `feature_kind`: `"true"`/`"false"` for `access_right`, a numeric string for `usage_limit`, or any string for `service_right` (shaped by the feature template''s `value_type`).'
        periodicity_interval:
          type:
          - integer
          - 'null'
          description: Set when `feature_kind` is `usage_limit`; `null` otherwise.
          contentEncoding: int32
        periodicity_unit:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/EntitlementPeriodicityUnit'
          - description: Set when `feature_kind` is `usage_limit`; `null` otherwise.
        price_point_type:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/FeatureOwnerPricePointType'
          - description: '`null` when this feature catalog item applies to every price point of its owning product/component. Set when the feature catalog item is an override for one specific price point.'
        price_point_id:
          type:
          - integer
          - 'null'
          description: Set together with `price_point_type` for price-point-specific overrides.
          contentEncoding: int32
        archived_at:
          type:
          - string
          - 'null'
          contentEncoding: date-time
        created_at:
          type: string
          contentEncoding: date-time
        updated_at:
          type: string
          contentEncoding: date-time
      description: A feature template attached to a specific product or component (or one of their price points), with a concrete value. When a subscriber signs up for or is assigned this product/component, the feature catalog item is provisioned as an entitlement on their subscription.
    FeatureOwnerPricePointType:
      title: FeatureOwnerPricePointType
      enum:
      - ProductPricePoint
      - PricePoint
      type: string
      description: 'Identifies which kind of price point a feature catalog item override applies to: `ProductPricePoint` for a product price point, `PricePoint` for a component price point. Only relevant when `price_point_id` is set.'
    CreateFeatureCatalogItemRequest:
      title: CreateFeatureCatalogItemRequest
      required:
      - feature
      type: object
      properties:
        feature:
          $ref: '#/components/schemas/Feature2'
      description: The owning product or component is taken from the URL and must not be included in the request body.
    Feature3:
      title: Feature3
      type: object
      properties:
        value:
          type: string
        periodicity_interval:
          type:
          - integer
          - 'null'
          contentEncoding: int32
        periodicity_unit:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/EntitlementPeriodicityUnit'
          - {}
        propagate_to_subscriptions:
          type: boolean
          description: When `true`, existing subscriptions on the item's price point are updated with the new `value`/periodicity by a background job shortly after. Has no effect on a product/component-level item. When `false` (default) and the item's price point already has subscribers, the update is made on a clone of the price point instead, and existing subscribers are unaffected.
          default: false
    Feature2:
      title: Feature2
      required:
      - feature_template_id
      type: object
      properties:
        feature_template_id:
          type: integer
          description: The id of the feature template to attach.
          contentEncoding: int32
        value:
          type: string
          description: The value granted. Defaults to the feature template's `default_value`; required when the template has none.
        periodicity_interval:
          type:
          - integer
          - 'null'
          description: Required for `usage_limit` features, unless the feature template has a default periodicity, which is used when omitted. Must be omitted for other kinds.
          contentEncoding: int32
        periodicity_unit:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/EntitlementPeriodicityUnit'
          - description: Required for `usage_limit` features, unless the feature template has a default periodicity, which is used when omitted. Must be omitted for other kinds.
        price_point_type:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/FeatureOwnerPricePointType'
          - description: 'Set together with `price_point_id` to scope the feature catalog item to a single price point. Omit both to create a product/component-level item, which is a template: it is copied onto price points created afterwards (except bulk-created ones; Clone Component Price Point applies only the items sent with it), but not added to price points that already exist or to their subscribers.'
        price_point_id:
          type:
          - integer
          - 'null'
          contentEncoding: int32
        propagate_to_subscriptions:
          type: boolean
          description: 'Applies to price-point-scoped items only. When `true`, existing subscriptions on that price point are granted an entitlement for this feature by a background job shortly after, instead of at their next subscription change. When `false` (default) and the price point already has subscribers, the feature is created on a clone of the price point instead, and existing subscribers are unaffected. On a product/component-level item it has no effect, except when the call restores that item''s archived price-point copies (creating an item again for a feature template whose item was archived): then `true` grants the feature to those price points'' subscribers, and without it the call returns `422` if any of them lack the feature.'
          default: false
    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)