Recurly Usage API

openapi: 3.2.0
info:
  title: Recurly Usage API
  version: v2021-02-25
  description: 'Operations tagged Usage across 2 of this provider''s published API definitions: recurly-v3-v2021-02-25-api.yaml, recurly-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://v3.recurly.com
- url: https://v3.eu.recurly.com
security:
- api_key: []
tags:
- name: Usage
  description: Send Recurly your customer usage and we will automatically bill them in arrears at the end of the billing cycle. For more info on usage-based billing, click here.
paths:
  /subscriptions/{subscription_id}/add_ons/{add_on_id}/usage:
    get:
      tags:
      - Usage
      operationId: list_usage
      summary: List a subscription add-on's usage records
      parameters:
      - $ref: '#/components/parameters/accept_header'
      - $ref: '#/components/parameters/subscription_id'
      - $ref: '#/components/parameters/add_on_id'
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/order'
      - $ref: '#/components/parameters/usage_sort_dates'
      - $ref: '#/components/parameters/filter_usage_begin_time'
      - $ref: '#/components/parameters/filter_usage_end_time'
      - $ref: '#/components/parameters/billing_status'
      responses:
        '200':
          description: A list of the subscription add-on's usage records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageList'
        '400':
          description: Invalid or unpermitted parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Incorrect site or subscription ID or add-on id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples: []
    post:
      tags:
      - Usage
      operationId: create_usage
      summary: Log a usage record on this subscription add-on
      parameters:
      - $ref: '#/components/parameters/accept_header'
      - $ref: '#/components/parameters/subscription_id'
      - $ref: '#/components/parameters/add_on_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageCreate'
        required: true
      responses:
        '201':
          description: The created usage record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          description: Invalid or unpermitted parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Incorrect site or subscription ID or add-on id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: A validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples: []
    servers:
    - url: https://v3.recurly.com
    - url: https://v3.eu.recurly.com
  /usage/{usage_id}:
    get:
      tags:
      - Usage
      operationId: get_usage
      summary: Get a usage record
      parameters:
      - $ref: '#/components/parameters/accept_header'
      - $ref: '#/components/parameters/usage_id'
      responses:
        '200':
          description: The usage record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          description: Invalid or unpermitted parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Incorrect site or subscription, add-on, or usage ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples: []
    put:
      tags:
      - Usage
      operationId: update_usage
      summary: Update a usage record
      parameters:
      - $ref: '#/components/parameters/accept_header'
      - $ref: '#/components/parameters/usage_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageCreate'
        required: true
      responses:
        '200':
          description: The updated usage record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '400':
          description: Invalid or unpermitted parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Incorrect site or subscription, add-on, or usage ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: A validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples: []
    delete:
      tags:
      - Usage
      operationId: remove_usage
      summary: Delete a usage record
      parameters:
      - $ref: '#/components/parameters/accept_header'
      - $ref: '#/components/parameters/usage_id'
      responses:
        '204':
          description: Usage was successfully deleted.
        '400':
          description: Invalid or unpermitted parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Incorrect site or subscription, add-on, or usage ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: A validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-code-samples: []
    servers:
    - url: https://v3.recurly.com
    - url: https://v3.eu.recurly.com
components:
  parameters:
    ids:
      name: ids
      in: query
      description: "Filter results by their IDs. Up to 200 IDs can be passed at once using\ncommas as separators, e.g. `ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6`.\n\n**Important notes:**\n\n* The `ids` parameter cannot be used with any other ordering or filtering\n  parameters (`limit`, `order`, `sort`, `begin_time`, `end_time`, etc)\n* Invalid or unknown IDs will be ignored, so you should check that the\n  results correspond to your request.\n* Records are returned in an arbitrary order. Since results are all\n  returned at once you can sort the records yourself.\n"
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
    usage_id:
      name: usage_id
      in: path
      description: Usage Record ID.
      required: true
      schema:
        type: string
    order:
      name: order
      in: query
      description: Sort order.
      schema:
        default: desc
        $ref: '#/components/schemas/AlphanumericSortEnum'
    filter_usage_begin_time:
      name: begin_time
      in: query
      description: 'Inclusively filter by begin_time when `sort=usage_timestamp` or `sort=recorded_timestamp`.

        **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

        '
      schema:
        type: string
        format: date-time
    billing_status:
      name: billing_status
      in: query
      description: Filter by usage record's billing status
      schema:
        type: string
        $ref: '#/components/schemas/BillingStatusEnum'
    usage_sort_dates:
      name: sort
      in: query
      description: 'Sort field. You *really* only want to sort by `usage_timestamp` in ascending

        order. In descending order updated records will move behind the cursor and could

        prevent some records from being returned.

        '
      schema:
        type: string
        $ref: '#/components/schemas/UsageSortEnum'
    filter_usage_end_time:
      name: end_time
      in: query
      description: 'Inclusively filter by end_time when `sort=usage_timestamp` or `sort=recorded_timestamp`.

        **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

        '
      schema:
        type: string
        format: date-time
    limit:
      name: limit
      in: query
      description: Limit number of records 1-200.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
    accept_header:
      name: Accept
      in: header
      description: The API version to use for this request, e.g. `application/vnd.recurly.v2021-02-25`. Requests without a versioned `Accept` header return a 406 response.
      required: true
      schema:
        default: application/vnd.recurly.v2021-02-25
        $ref: '#/components/schemas/AcceptHeaderEnum'
    add_on_id:
      name: add_on_id
      in: path
      description: Add-on ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-gold`.
      required: true
      schema:
        type: string
    subscription_id:
      name: subscription_id
      in: path
      description: Subscription ID or UUID. For ID no prefix is used e.g. `e28zov4fw0v2`. For UUID use prefix `uuid-`, e.g. `uuid-123457890`.
      required: true
      schema:
        type: string
  schemas:
    AlphanumericSortEnum:
      type: string
      enum:
      - asc
      - desc
    ErrorTypeEnum:
      type: string
      enum:
      - bad_request
      - immutable_subscription
      - internal_server_error
      - invalid_api_key
      - invalid_api_version
      - invalid_content_type
      - invalid_permissions
      - invalid_token
      - missing_feature
      - not_found
      - rate_limited
      - service_not_available
      - simultaneous_request
      - tax_service_error
      - transaction
      - unauthorized
      - unavailable_in_api_version
      - unknown_api_version
      - validation
    AcceptHeaderEnum:
      type: string
      enum:
      - application/vnd.recurly.v2021-02-25
      - application/vnd.recurly.v2021-02-25+json
    UsageCreate:
      type: object
      properties:
        merchant_tag:
          type: string
          description: Custom field for recording the id in your own system associated with the usage, so you can provide auditable usage displays to your customers using a GET on this endpoint.
        amount:
          type: number
          format: float
          description: The amount of usage. Can be positive, negative, or 0. If the Decimal Quantity feature is enabled, this value will be rounded to nine decimal places.  Otherwise, all digits after the decimal will be stripped. If the usage-based add-on is billed with a percentage, your usage should be a monetary amount formatted in cents (e.g., $5.00 is "500").
        recording_timestamp:
          type: string
          format: date-time
          description: When the usage was recorded in your system.
        usage_timestamp:
          type: string
          format: date-time
          description: When the usage actually happened. This will define the line item dates this usage is billed under and is important for revenue recognition.
    SubscriptionAddOnPercentageTier:
      type: object
      properties:
        ending_amount:
          type: number
          format: float
          title: Ending amount
          minimum: 1
          maximum: 9999999999999.99
          description: Ending amount for the tier. Allows up to 2 decimal places. Must be left empty if it is the final tier.
        usage_percentage:
          type: string
          title: Usage Percentage
          minimum: 0
          maximum: 100
          description: 'The percentage taken of the monetary amount of usage tracked.

            This can be up to 4 decimal places represented as a string.

            '
    UsageTypeEnum:
      type: string
      enum:
      - price
      - percentage
      title: Usage Type
      description: Type of usage, returns usage type if `add_on_type` is `usage`.
    Usage:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          title: Object type
        merchant_tag:
          type: string
          description: Custom field for recording the id in your own system associated with the usage, so you can provide auditable usage displays to your customers using a GET on this endpoint.
        amount:
          type: number
          format: float
          description: The amount of usage. Can be positive, negative, or 0. If the Decimal Quantity feature is enabled, this value will be rounded to nine decimal places.  Otherwise, all digits after the decimal will be stripped. If the usage-based add-on is billed with a percentage, your usage should be a monetary amount formatted in cents (e.g., $5.00 is "500").
        usage_type:
          $ref: '#/components/schemas/UsageTypeEnum'
        tier_type:
          $ref: '#/components/schemas/TierTypeEnum'
        tiers:
          type: array
          title: Tiers
          items:
            $ref: '#/components/schemas/SubscriptionAddOnTier'
          description: The tiers and prices of the subscription based on the usage_timestamp. If tier_type = flat, tiers = []
        percentage_tiers:
          type: array
          title: Percentage Tiers
          items:
            $ref: '#/components/schemas/SubscriptionAddOnPercentageTier'
          description: The percentage tiers of the subscription based on the usage_timestamp. If tier_type = flat, percentage_tiers = []. This feature is currently in development and requires approval and enablement, please contact support.
        measured_unit_id:
          type: string
          description: The ID of the measured unit associated with the add-on the usage record is for.
        recording_timestamp:
          type: string
          format: date-time
          description: When the usage was recorded in your system.
        usage_timestamp:
          type: string
          format: date-time
          description: When the usage actually happened. This will define the line item dates this usage is billed under and is important for revenue recognition.
        usage_percentage:
          type: number
          format: float
          title: Usage Percentage
          description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.
        unit_amount:
          type: number
          format: float
          title: Unit price
        unit_amount_decimal:
          type: string
          title: Unit Amount Decimal
          minimum: 0
          maximum: 1000000
          description: Unit price that can optionally support a sub-cent value.
        billed_at:
          type: string
          format: date-time
          description: When the usage record was billed on an invoice.
        created_at:
          type: string
          format: date-time
          description: When the usage record was created in Recurly.
        updated_at:
          type: string
          format: date-time
          description: When the usage record was billed on an invoice.
    UsageSortEnum:
      type: string
      default: usage_timestamp
      enum:
      - recorded_timestamp
      - usage_timestamp
    UsageList:
      type: object
      properties:
        object:
          type: string
          title: Object type
          description: Will always be List.
        has_more:
          type: boolean
          description: Indicates there are more results on subsequent pages.
        next:
          type: string
          description: Path to subsequent page of results.
        data:
          type: array
          items:
            $ref: '#/components/schemas/Usage'
    Error:
      type: object
      properties:
        type:
          title: Type
          $ref: '#/components/schemas/ErrorTypeEnum'
        message:
          type: string
          title: Message
        params:
          type: array
          title: Parameter specific errors
          items:
            type: object
            properties:
              param:
                type: string
    TierTypeEnum:
      type: string
      title: Tier type
      description: 'The pricing model for the add-on.  For more information,

        [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our

        [Guide](https://recurly.com/developers/guides/item-addon-guide.html) for an overview of how

        to configure quantity-based pricing models.

        '
      default: flat
      enum:
      - flat
      - tiered
      - stairstep
      - volume
    SubscriptionAddOnTier:
      type: object
      properties:
        ending_quantity:
          type: integer
          title: Ending quantity
          minimum: 1
          maximum: 999999999
          description: Ending quantity for the tier.  This represents a unit amount for unit-priced add ons. Must be left empty if it is the final tier.
        unit_amount:
          type: number
          format: float
          title: Unit amount
          minimum: 0
          maximum: 1000000
          description: Allows up to 2 decimal places. Optionally, override the tiers' default unit amount. If add-on's `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided.
        unit_amount_decimal:
          type: string
          title: Unit amount decimal
          description: 'Allows up to 9 decimal places.  Optionally, override tiers'' default unit amount.

            If `unit_amount_decimal` is provided, `unit_amount` cannot be provided.

            If add-on''s `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided.

            '
        usage_percentage:
          type: string
          title: Usage Percentage
          description: (deprecated) -- Use the percentage_tiers object instead.
          deprecated: true
    BillingStatusEnum:
      type: string
      default: unbilled
      enum:
      - unbilled
      - billed
      - all
  securitySchemes:
    api_key:
      type: http
      description: Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the [API Credentials](https://app.recurly.com/go/developer/api_keys) page.
      scheme: basic
x-refined-from:
- recurly-v3-v2021-02-25-api.yaml
- recurly-openapi.yml
x-readme:
  explorer-enabled: false