Class: AdvancedBilling::SubscriptionComponentsController

In order to bill your subscribers on your Events data under the Events-Based Billing feature, the components must be activated for the subscriber. Learn more about the role of activation in the [Events-Based Billing docs](maxio.zendesk.com/hc/en-us/articles/24260323329805-Events-Ba sed-Billing-Overview). Use this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes Advanced Billing to bill for events when the subscription is renewed. *Note: it is possible to stream events for a subscription at any time, regardless of component activation status. The activation status only determines if the subscription should be billed for event-based component usage at renewal.* id of the subscription of the component

Parameters:

subscription_id (Integer) —

Required parameter: The Advanced Billing
component_id (Integer) —

Required parameter: The Advanced Billing id
body (ActivateEventBasedComponent) (defaults to: nil) —

Optional parameter: Example:

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 727

def activate_event_based_component(subscription_id,
                                   component_id,
                                   body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/event_based_billing/subscriptions/{subscription_id}/components/{component_id}/activate.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true))
    .execute
end

#allocate_component(subscription_id, component_id, body: nil) ⇒ `AllocationResponse`

This endpoint creates a new allocation, setting the current allocated quantity for the Component and recording a memo. Notice: Allocations can only be updated for Quantity, On/Off, and Prepaid Components. ## Allocations Documentation Full documentation on how to record Allocations in the Advanced Billing UI can be located [here](maxio.zendesk.com/hc/en-us/articles/24251883961485-Componen t-Allocations-Overview). It is focused on how allocations operate within the Advanced Billing UI.It goes into greater detail on how the user interface will react when recording allocations. This documentation also goes into greater detail on how proration is taken into consideration when applying component allocations. ## Proration Schemes Changing the allocated quantity of a component mid-period can result in either a Charge or Credit being applied to the subscription. When creating an allocation via the API, you can pass the ‘upgrade_charge`, `downgrade_credit`, and `accrue_charge` to be applied. Notice: These proration and accural fields will be ignored for Prepaid Components since this component type always generate charges immediately without proration. For background information on prorated components and upgrade/downgrade schemes, see [Setting Component Allocations.](maxio.zendesk.com/hc/en-us/articles/24251906165133-C omponent-Allocations-Proration). See the tables below for valid values. | upgrade_charge | Definition | |—————-|——————————————————– ———–| | `full` | A charge is added for the full price of the component. | | `prorated` | A charge is added for the prorated price of the component change. | | `none` | No charge is added. | | downgrade_credit | Definition | |——————|—————————————————| | `full` | A full price credit is added for the amount owed. | | `prorated` | A prorated credit is added for the amount owed. | | `none` | No charge is added. | | accrue_charge | Definition | |—————|——————————————————— —————————————————| | `true` | Attempt to charge the customer at next renewal.

| ‘false` | Attempt to charge the customer right away. If it fails, the charge will be accrued until the next renewal. | ### Order of Resolution for upgrade_charge and downgrade_credit

Per allocation in API call (within a single allocation of the

‘allocations` array)

[Component-level default

value](maxio.zendesk.com/hc/en-us/articles/24251883961485-Componen t-Allocations-Overview)

Allocation API call top level (outside of the ‘allocations` array)
[Site-level default

value](maxio.zendesk.com/hc/en-us/articles/24251906165133-Componen t-Allocations-Proration#proration-schemes) ### Order of Resolution for accrue charge

Allocation API call top level (outside of the ‘allocations` array)
[Site-level default

value](maxio.zendesk.com/hc/en-us/articles/24251906165133-Componen t-Allocations-Proration#proration-schemes) **NOTE: Proration uses the current price of the component as well as the current tax rates. Changes to either may cause the prorated charge/credit to be wrong.** the subscription of the component

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
component_id (Integer) —

Required parameter: The Advanced Billing id
body (CreateAllocationRequest) (defaults to: nil) —

Optional parameter: Example:

Returns:

(AllocationResponse) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 248

def allocate_component(subscription_id,
                       component_id,
                       body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/components/{component_id}/allocations.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#allocate_components(subscription_id, body: nil) ⇒ `Array[AllocationResponse]`

Creates multiple allocations, setting the current allocated quantity for each of the components and recording a memo. The charges and/or credits that are created will be rolled up into a single total which is used to determine whether this is an upgrade or a downgrade. Be aware of the Order of Resolutions explained below in determining the proration scheme. A ‘component_id` is required for each allocation. This endpoint only responds to JSON. It is not available for XML. the subscription

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
body (AllocateComponents) (defaults to: nil) —

Optional parameter: Example:

Returns:

(Array[AllocationResponse]) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 347

def allocate_components(subscription_id,
                        body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/allocations.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationResponse.method(:from_hash))
                .is_response_array(true)
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#bulk_record_events(api_handle, store_uid: nil, body: nil) ⇒ `void`

This method returns an undefined value.

Use this endpoint to record a collection of events. *Note: this endpoint differs from the standard Chargify API endpoints in that the subdomain will be ‘events` and your site subdomain will be included in the URL path.* A maximum of 1000 events can be published in a single request. A 422 will be returned if this limit is exceeded. which the events should be published. Keen project as an Advanced Billing event data-store, use this parameter to indicate the data-store.

Parameters:

api_handle (String) —

Required parameter: Identifies the Stream for
store_uid (String) (defaults to: nil) —

Optional parameter: If you’ve attached your own
body (Array[EBBEvent]) (defaults to: nil) —

Optional parameter: Example:

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 834

def bulk_record_events(api_handle,
                       store_uid: nil,
                       body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/events/{api_handle}/bulk.json',
                                 Server::EBB)
               .template_param(new_parameter(api_handle, key: 'api_handle')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .query_param(new_parameter(store_uid, key: 'store_uid'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true))
    .execute
end

#bulk_reset_subscription_components_price_points(subscription_id) ⇒ `SubscriptionResponse`

Resets all of a subscription’s components to use the current default. Note: this will update the price point for all of the subscription’s components, even ones that have not been allocated yet. the subscription

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of

Returns:

(SubscriptionResponse) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 159

def bulk_reset_subscription_components_price_points(subscription_id)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/price_points/reset.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash)))
    .execute
end

#bulk_update_subscription_components_price_points(subscription_id, body: nil) ⇒ `BulkComponentsPricePointAssignment`

Updates the price points on one or more of a subscription’s components. The ‘price_point` key can take either a:

Price point id (integer)
Price point handle (string)
‘“_default”` string, which will reset the price point to the

component’s current default price point. the subscription Example:

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
body (BulkComponentsPricePointAssignment) (defaults to: nil) —

Optional parameter:

Returns:

(BulkComponentsPricePointAssignment) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 129

def bulk_update_subscription_components_price_points(subscription_id,
                                                     body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/price_points.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(BulkComponentsPricePointAssignment.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ComponentPricePointErrorException))
    .execute
end

#create_usage(subscription_id, component_id, body: nil) ⇒ `UsageResponse`

## Documentation Full documentation on how to create Components in the Advanced Billing UI can be located [here](maxio.zendesk.com/hc/en-us/articles/24261149711501-Create-E dit-and-Archive-Components). Additionally, for information on how to record component usage against a subscription, please see the following resources: + [Recording Metered Component Usage](maxio.zendesk.com/hc/en-us/articles/24251890500109-Reportin g-Component-Allocations#reporting-metered-component-usage) + [Reporting Prepaid Component Status](maxio.zendesk.com/hc/en-us/articles/24251890500109-Reporti ng-Component-Allocations#reporting-prepaid-component-status) You may choose to report metered or prepaid usage to Advanced Billing as often as you wish. You may report usage as it happens. You may also report usage periodically, such as each night or once per billing period. If usage events occur in your system very frequently (on the order of thousands of times an hour), it is best to accumulate usage into batches on your side, and then report those batches less frequently, such as daily. This will ensure you remain below any API throttling limits. If your use case requires higher rates of usage reporting, we recommend utilizing Events Based Components. ## Create Usage for Subscription This endpoint allows you to record an instance of metered or prepaid usage for a subscription. The ‘quantity` from usage for each component is accumulated to the `unit_balance` on the [Component Line Item](./b3A6MTQxMDgzNzQ-read-subscription-component) for the subscription. ## Price Point ID usage If you are using price points, for metered and prepaid usage components, Advanced Billing gives you the option to specify a price point in your request. You do not need to specify a price point ID. If a price point is not included, the default price point for the component will be used when the usage is recorded. If an invalid `price_point_id` is submitted, the endpoint will return an error. ## Deducting Usage In the event that you need to reverse a previous usage report or otherwise deduct from the current usage balance, you may provide a negative quantity. Example: Previously recorded: “`json {

"usage": {
  "quantity": 5000,
  "memo": "Recording 5000 units"
}

} “‘ At this point, `unit_balance` would be `5000`. To reduce the balance to `0`, POST the following payload: “`json {

"usage": {
  "quantity": -5000,
  "memo": "Deducting 5000 units"
}

} “‘ The `unit_balance` has a floor of `0`; negative unit balances are never allowed. For example, if the usage balance is 100 and you deduct 200 units, the unit balance would then be `0`, not `-100`. ## FAQ

Is it possible to record metered usage for more than one component at a

time?

No. Usage should be reported as one API call per component on a single

subscription. For example, to record that a subscriber has sent both an SMS Message and an Email, send an API call for each. the subscription Advanced Billing id for the component or the component’s handle prefixed by ‘handle:`

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
component_id (Integer | String) —

Required parameter: Either the
body (CreateUsageRequest) (defaults to: nil) —

Optional parameter: Example:

Returns:

(UsageResponse) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 603

def create_usage(subscription_id,
                 component_id,
                 body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/components/{component_id}/usages.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true)
                                .validator(proc do |value|
                                  UnionTypeLookUp.get(:CreateUsageComponentId)
                                                 .validate(value)
                                end))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(UsageResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#deactivate_event_based_component(subscription_id, component_id) ⇒ `void`

This method returns an undefined value.

Use this endpoint to deactivate an event-based component for a single subscription. Deactivating the event-based component causes Advanced Billing to ignore related events at subscription renewal. id of the subscription of the component

Parameters:

subscription_id (Integer) —

Required parameter: The Advanced Billing
component_id (Integer) —

Required parameter: The Advanced Billing id

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 757

def deactivate_event_based_component(subscription_id,
                                     component_id)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/event_based_billing/subscriptions/{subscription_id}/components/{component_id}/deactivate.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true))
    .execute
end

#delete_prepaid_usage_allocation(subscription_id, component_id, allocation_id, body: nil) ⇒ `void`

This method returns an undefined value.

Prepaid Usage components are unique in that their allocations are always additive. In order to reduce a subscription’s allocated quantity for a prepaid usage component each allocation must be destroyed individually via this endpoint. ## Credit Scheme By default, destroying an allocation will generate a service credit on the subscription. This behavior can be modified with the optional ‘credit_scheme` parameter on this endpoint. The accepted values are:

‘none`: The allocation will be destroyed and the balances will be

updated but no service credit or refund will be created.

‘credit`: The allocation will be destroyed and the balances will be

updated and a service credit will be generated. This is also the default behavior if the ‘credit_scheme` param is not passed.

‘refund`: The allocation will be destroyed and the balances will be

updated and a refund will be issued along with a Credit Note. the subscription of the component of the allocation

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
component_id (Integer) —

Required parameter: The Advanced Billing id
allocation_id (Integer) —

Required parameter: The Advanced Billing id
body (CreditSchemeRequest) (defaults to: nil) —

Optional parameter: Example:

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 494

def delete_prepaid_usage_allocation(subscription_id,
                                    component_id,
                                    allocation_id,
                                    body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/subscriptions/{subscription_id}/components/{component_id}/allocations/{allocation_id}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(allocation_id, key: 'allocation_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true)
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      SubscriptionComponentAllocationErrorException))
    .execute
end

#list_allocations(subscription_id, component_id, page: 1) ⇒ `Array[AllocationResponse]`

This endpoint returns the 50 most recent Allocations, ordered by most recent first. ## On/Off Components When a subscription’s on/off component has been toggled to on (‘1`) or off (`0`), usage will be logged in this response. ## Querying data via Advanced Billing gem You can also query the current quantity via the [official Advanced Billing Gem.](github.com/chargify/chargify_api_ares) “`# First way component = Chargify::Subscription::Component.find(1, :params => => 7) puts component.allocated_quantity # => 23 # Second way component = Chargify::Subscription.find(7).component(1) puts component.allocated_quantity # => 23 “` the subscription of the component 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`.

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
component_id (Integer) —

Required parameter: The Advanced Billing id
page (Integer) (defaults to: 1) —

Optional parameter: Result records are organized in

Returns:

(Array[AllocationResponse]) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 306

def list_allocations(subscription_id,
                     component_id,
                     page: 1)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/components/{component_id}/allocations.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(page, key: 'page'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationResponse.method(:from_hash))
                .is_response_array(true)
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#list_subscription_components(options = {}) ⇒ `Array[SubscriptionComponentResponse]`

This request will list a subscription’s applied components. ## Archived Components When requesting to list components for a given subscription, if the subscription contains archived components they will be listed in the server response. the subscription of filter you’d like to apply to your search. Use in query ‘date_field=updated_at`. in which results are returned. Use in query `direction=asc`. Filter to use for List Subscription Components operation YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site”s time zone will be used. If provided, this parameter will be used instead of end_date. fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`. fetching components allocation with matching product family id based on provided ids. Use in query `product_family_ids=1,2,3`. attribute by which to sort. Use in query `sort=updated_at`. YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site”s time zone will be used. If provided, this parameter will be used instead of start_date. parameter: Allows including additional data in the response. Use in query `include=subscription,historic_usages`. set to true, it returns only components that are currently in use. However, if it’s set to false or not provided, it returns all components connected with the subscription.

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
date_field (SubscriptionListDateField) —

Optional parameter: The type
direction (SortingDirection) —

Optional parameter: Controls the order
filter (ListSubscriptionComponentsFilter) —

Optional parameter:
end_date (String) —

Optional parameter: The end date (format
end_datetime (String) —

Optional parameter: The end date and time
price_point_ids (IncludeNotNull) —

Optional parameter: Allows
product_family_ids (Array[Integer]) —

Optional parameter: Allows
sort (ListSubscriptionComponentsSort) —

Optional parameter: The
start_date (String) —

Optional parameter: The start date (format
start_datetime (String) —

Optional parameter: The start date and time
include (Array[ListSubscriptionComponentsInclude]) —

Optional
in_use (TrueClass | FalseClass) —

Optional parameter: If in_use is

Returns:

(Array[SubscriptionComponentResponse]) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 88

def list_subscription_components(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/components.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['subscription_id'], key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['date_field'], key: 'date_field'))
               .query_param(new_parameter(options['direction'], key: 'direction'))
               .query_param(new_parameter(options['filter'], key: 'filter'))
               .query_param(new_parameter(options['end_date'], key: 'end_date'))
               .query_param(new_parameter(options['end_datetime'], key: 'end_datetime'))
               .query_param(new_parameter(options['price_point_ids'], key: 'price_point_ids'))
               .query_param(new_parameter(options['product_family_ids'], key: 'product_family_ids'))
               .query_param(new_parameter(options['sort'], key: 'sort'))
               .query_param(new_parameter(options['start_date'], key: 'start_date'))
               .query_param(new_parameter(options['start_datetime'], key: 'start_datetime'))
               .query_param(new_parameter(options['include'], key: 'include'))
               .query_param(new_parameter(options['in_use'], key: 'in_use'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionComponentResponse.method(:from_hash))
                .is_response_array(true))
    .execute
end

#list_subscription_components_for_site(options = {}) ⇒ `ListSubscriptionComponentsResponse`

This request will list components applied to each subscription. 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`. 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`. attribute by which to sort. Use in query: `sort=updated_at`. in which results are returned. Use in query `direction=asc`. parameter: Filter to use for List Subscription Components For Site operation of filter you’d like to apply to your search. Use in query: ‘date_field=updated_at`. YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query `start_date=2011-12-15`. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site”s time zone will be used. If provided, this parameter will be used instead of start_date. Use in query `start_datetime=2022-07-01 09:00:05`. YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query `end_date=2011-12-16`. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site”s time zone will be used. If provided, this parameter will be used instead of end_date. Use in query `end_datetime=2022-07-01 09:00:05`. fetching components allocation with matching subscription id based on provided ids. Use in query `subscription_ids=1,2,3`. fetching components allocation only if price point id is present. Use in query `price_point_ids=not_null`. fetching components allocation with matching product family id based on provided ids. Use in query `product_family_ids=1,2,3`. Allows including additional data in the response. Use in query `include=subscription,historic_usages`.

Parameters:

page (Integer) —

Optional parameter: Result records are organized in
per_page (Integer) —

Optional parameter: This parameter indicates how
sort (ListSubscriptionComponentsSort) —

Optional parameter: The
direction (SortingDirection) —

Optional parameter: Controls the order
filter (ListSubscriptionComponentsForSiteFilter) —

Optional
date_field (SubscriptionListDateField) —

Optional parameter: The type
start_date (String) —

Optional parameter: The start date (format
start_datetime (String) —

Optional parameter: The start date and time
end_date (String) —

Optional parameter: The end date (format
end_datetime (String) —

Optional parameter: The end date and time
subscription_ids (Array[Integer]) —

Optional parameter: Allows
price_point_ids (IncludeNotNull) —

Optional parameter: Allows
product_family_ids (Array[Integer]) —

Optional parameter: Allows
include (ListSubscriptionComponentsInclude) —

Optional parameter:

Returns:

(ListSubscriptionComponentsResponse) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 909

def list_subscription_components_for_site(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions_components.json',
                                 Server::PRODUCTION)
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['sort'], key: 'sort'))
               .query_param(new_parameter(options['direction'], key: 'direction'))
               .query_param(new_parameter(options['filter'], key: 'filter'))
               .query_param(new_parameter(options['date_field'], key: 'date_field'))
               .query_param(new_parameter(options['start_date'], key: 'start_date'))
               .query_param(new_parameter(options['start_datetime'], key: 'start_datetime'))
               .query_param(new_parameter(options['end_date'], key: 'end_date'))
               .query_param(new_parameter(options['end_datetime'], key: 'end_datetime'))
               .query_param(new_parameter(options['subscription_ids'], key: 'subscription_ids'))
               .query_param(new_parameter(options['price_point_ids'], key: 'price_point_ids'))
               .query_param(new_parameter(options['product_family_ids'], key: 'product_family_ids'))
               .query_param(new_parameter(options['include'], key: 'include'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListSubscriptionComponentsResponse.method(:from_hash)))
    .execute
end

#list_usages(options = {}) ⇒ `Array[UsageResponse]`

This request will return a list of the usages associated with a subscription for a particular metered component. This will display the previously recorded components for a subscription. This endpoint is not compatible with quantity-based components. ## Since Date and Until Date Usage Note: The ‘since_date` and `until_date` attributes each default to midnight on the date specified. For example, in order to list usages for January 20th, you would need to append the following to the URL. “` ?since_date=2016-01-20&until_date=2016-01-21 “` ## Read Usage by Handle Use this endpoint to read the previously recorded components for a subscription. You can now specify either the component id (integer) or the component handle prefixed by “handle:” to specify the unique identifier for the component you are working with. the subscription Advanced Billing id for the component or the component’s handle prefixed by ‘handle:` greater than or equal to the one specified than or equal to the one specified created_at date greater than or equal to midnight (12:00 AM) on the date specified. created_at date less than or equal to midnight (12:00 AM) on the date specified. 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`. 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`.

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
component_id (Integer | String) —

Required parameter: Either the
since_id (Integer) —

Optional parameter: Returns usages with an id
max_id (Integer) —

Optional parameter: Returns usages with an id less
since_date (Date) —

Optional parameter: Returns usages with a
until_date (Date) —

Optional parameter: Returns usages with a
page (Integer) —

Optional parameter: Result records are organized in
per_page (Integer) —

Optional parameter: This parameter indicates how

Returns:

(Array[UsageResponse]) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 678

def list_usages(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/components/{component_id}/usages.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['subscription_id'], key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(options['component_id'], key: 'component_id')
                                .is_required(true)
                                .should_encode(true)
                                .validator(proc do |value|
                                  UnionTypeLookUp.get(:ListUsagesInputComponentId)
                                                 .validate(value)
                                end))
               .query_param(new_parameter(options['since_id'], key: 'since_id'))
               .query_param(new_parameter(options['max_id'], key: 'max_id'))
               .query_param(new_parameter(options['since_date'], key: 'since_date'))
               .query_param(new_parameter(options['until_date'], key: 'until_date'))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(UsageResponse.method(:from_hash))
                .is_response_array(true))
    .execute
end

#preview_allocations(subscription_id, body: nil) ⇒ `AllocationPreviewResponse`

Advanced Billing offers the ability to preview a potential subscription’s quantity-based or on/off component allocation in the middle of the current billing period. This is useful if you want users to be able to see the effect of a component operation before actually doing it. ## Fine-grained Component Control: Use with multiple ‘upgrade_charge`s or `downgrade_credits` When the allocation uses multiple different types of `upgrade_charge`s or `downgrade_credit`s, the Allocation is viewed as an Allocation which uses “Fine-Grained Component Control”. As a result, the response will not include `direction` and `proration` within the `allocation_preview`, but at the `line_items` and `allocations` level respectfully. See example below for Fine-Grained Component Control response. the subscription

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
body (PreviewAllocationsRequest) (defaults to: nil) —

Optional parameter: Example:

Returns:

(AllocationPreviewResponse) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 391

def preview_allocations(subscription_id,
                        body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/allocations/preview.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationPreviewResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ComponentAllocationErrorException))
    .execute
end

#read_subscription_component(subscription_id, component_id) ⇒ `SubscriptionComponentResponse`

This request will list information regarding a specific component owned by a subscription. the subscription of the component. Alternatively, the component’s handle prefixed by ‘handle:`

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
component_id (Integer) —

Required parameter: The Advanced Billing id

Returns:

(SubscriptionComponentResponse) —

response from the API call.

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 17

def read_subscription_component(subscription_id,
                                component_id)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/components/{component_id}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionComponentResponse.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException))
    .execute
end

#record_event(api_handle, store_uid: nil, body: nil) ⇒ `void`

This method returns an undefined value.

## Documentation Events-Based Billing is an evolved form of metered billing that is based on data-rich events streamed in real-time from your system to Advanced Billing. These events can then be transformed, enriched, or analyzed to form the computed totals of usage charges billed to your customers. This API allows you to stream events into the Advanced Billing data ingestion engine. Learn more about the feature in general in the [Events-Based Billing help docs](maxio.zendesk.com/hc/en-us/articles/24260323329805-Events-Ba sed-Billing-Overview). ## Record Event Use this endpoint to record a single event. *Note: this endpoint differs from the standard Chargify API endpoints in that the URL subdomain will be ‘events` and your site subdomain will be included in the URL path. For example:* “` events.chargify.com/my-site-subdomain/events/my-stream-api-handle “` which the event should be published. Keen project as an Advanced Billing event data-store, use this parameter to indicate the data-store.

Parameters:

api_handle (String) —

Required parameter: Identifies the Stream for
store_uid (String) (defaults to: nil) —

Optional parameter: If you’ve attached your own
body (EBBEvent) (defaults to: nil) —

Optional parameter: Example:

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 801

def record_event(api_handle,
                 store_uid: nil,
                 body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/events/{api_handle}.json',
                                 Server::EBB)
               .template_param(new_parameter(api_handle, key: 'api_handle')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .query_param(new_parameter(store_uid, key: 'store_uid'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true))
    .execute
end

#update_prepaid_usage_allocation_expiration_date(subscription_id, component_id, allocation_id, body: nil) ⇒ `void`

This method returns an undefined value.

When the expiration interval options are selected on a prepaid usage component price point, all allocations will be created with an expiration date. This expiration date can be changed after the fact to allow for extending or shortening the allocation’s active window. In order to change a prepaid usage allocation’s expiration date, a PUT call must be made to the allocation’s endpoint with a new expiration date. ## Limitations A few limitations exist when changing an allocation’s expiration date:

An expiration date can only be changed for an allocation that belongs to

a price point with expiration interval options explicitly set.

An expiration date can be changed towards the future with no

limitations.

An expiration date can be changed towards the past (essentially expiring

it) up to the subscription’s current period beginning date. the subscription of the component of the allocation Example:

Parameters:

subscription_id (Integer) —

Required parameter: The Chargify id of
component_id (Integer) —

Required parameter: The Advanced Billing id
allocation_id (Integer) —

Required parameter: The Advanced Billing id
body (UpdateAllocationExpirationDate) (defaults to: nil) —

Optional parameter:

# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 438

def update_prepaid_usage_allocation_expiration_date(subscription_id,
                                                    component_id,
                                                    allocation_id,
                                                    body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}/components/{component_id}/allocations/{allocation_id}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(component_id, key: 'component_id')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(allocation_id, key: 'allocation_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true)
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      SubscriptionComponentAllocationErrorException))
    .execute
end

Class: AdvancedBilling::SubscriptionComponentsController

Overview

Constant Summary

Constants inherited from BaseController

Instance Attribute Summary

Attributes inherited from BaseController

Instance Method Summary collapse

Methods inherited from BaseController

Constructor Details

Instance Method Details

#activate_event_based_component(subscription_id, component_id, body: nil) ⇒ void

#allocate_component(subscription_id, component_id, body: nil) ⇒ AllocationResponse

#allocate_components(subscription_id, body: nil) ⇒ Array[AllocationResponse]

#bulk_record_events(api_handle, store_uid: nil, body: nil) ⇒ void

#bulk_reset_subscription_components_price_points(subscription_id) ⇒ SubscriptionResponse

#bulk_update_subscription_components_price_points(subscription_id, body: nil) ⇒ BulkComponentsPricePointAssignment

#create_usage(subscription_id, component_id, body: nil) ⇒ UsageResponse

#deactivate_event_based_component(subscription_id, component_id) ⇒ void

#delete_prepaid_usage_allocation(subscription_id, component_id, allocation_id, body: nil) ⇒ void

#list_allocations(subscription_id, component_id, page: 1) ⇒ Array[AllocationResponse]

#list_subscription_components(options = {}) ⇒ Array[SubscriptionComponentResponse]

#list_subscription_components_for_site(options = {}) ⇒ ListSubscriptionComponentsResponse

#list_usages(options = {}) ⇒ Array[UsageResponse]

#preview_allocations(subscription_id, body: nil) ⇒ AllocationPreviewResponse

#read_subscription_component(subscription_id, component_id) ⇒ SubscriptionComponentResponse

#record_event(api_handle, store_uid: nil, body: nil) ⇒ void

#update_prepaid_usage_allocation_expiration_date(subscription_id, component_id, allocation_id, body: nil) ⇒ void

#activate_event_based_component(subscription_id, component_id, body: nil) ⇒ `void`

#allocate_component(subscription_id, component_id, body: nil) ⇒ `AllocationResponse`

#allocate_components(subscription_id, body: nil) ⇒ `Array[AllocationResponse]`

#bulk_record_events(api_handle, store_uid: nil, body: nil) ⇒ `void`

#bulk_reset_subscription_components_price_points(subscription_id) ⇒ `SubscriptionResponse`

#bulk_update_subscription_components_price_points(subscription_id, body: nil) ⇒ `BulkComponentsPricePointAssignment`

#create_usage(subscription_id, component_id, body: nil) ⇒ `UsageResponse`

#deactivate_event_based_component(subscription_id, component_id) ⇒ `void`

#delete_prepaid_usage_allocation(subscription_id, component_id, allocation_id, body: nil) ⇒ `void`

#list_allocations(subscription_id, component_id, page: 1) ⇒ `Array[AllocationResponse]`

#list_subscription_components(options = {}) ⇒ `Array[SubscriptionComponentResponse]`

#list_subscription_components_for_site(options = {}) ⇒ `ListSubscriptionComponentsResponse`

#list_usages(options = {}) ⇒ `Array[UsageResponse]`

#preview_allocations(subscription_id, body: nil) ⇒ `AllocationPreviewResponse`

#read_subscription_component(subscription_id, component_id) ⇒ `SubscriptionComponentResponse`

#record_event(api_handle, store_uid: nil, body: nil) ⇒ `void`

#update_prepaid_usage_allocation_expiration_date(subscription_id, component_id, allocation_id, body: nil) ⇒ `void`