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](chargify.zendesk.com/hc/en-us/articles/4407720810907#activat ing-components-for-subscribers). Use this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes Chargify 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.* the subscription component

Parameters:

subscription_id (Integer) —

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

Required parameter: The Chargify id of the

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

def activate_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}/activate.json',
                                 Server::DEFAULT)
               .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_nullify404(true)
                .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 Chargify UI can be located [here](maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997) . It is focused on how allocations operate within the Chargify 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-chargify.zendesk.com/hc/en-us/articles/5404527 849997#proration-upgrades-vs-downgrades). 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-chargify.zendesk.com/hc/en-us/articles/5404527849997- Component-Allocations#component-allocations-0-0)

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

value](maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997# proration-schemes) ### Order of Resolution for accrue charge

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

value](maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997# 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.** subscription component

Parameters:

subscription_id (String) —

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

Required parameter: The Chargify id of the
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 639

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::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationResponse.method(:from_hash)))
    .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. subscription

Parameters:

subscription_id (String) —

Required parameter: The Chargify id of the
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 20

def allocate_components(subscription_id,
                        body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/allocations.json',
                                 Server::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationResponse.method(:from_hash))
                .is_response_array(true)
                .local_error('401',
                             'Unauthorized',
                             APIException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ErrorListResponseException))
    .execute
end

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

## Documentation Full documentation on how to create Components in the Chargify UI can be located [here](maxio-chargify.zendesk.com/hc/en-us/articles/5405020625677# creating-components). Additionally, for information on how to record component usage against a subscription, please see the following resources: + [Recording Metered Component Usage](maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997# reporting-metered-component-usage) + [Reporting Prepaid Component Status](maxio-chargify.zendesk.com/hc/en-us/articles/5404527849997 #reporting-prepaid-component-status) You may choose to report metered or prepaid usage to Chargify 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, Chargify 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. subscription for the component or the component’s handle prefixed by ‘handle:`

Parameters:

subscription_id (String) —

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

Required parameter: Either the Chargify id
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 231

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::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(UsageResponse.method(:from_hash))
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             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 Chargify to ignore related events at subscription renewal. the subscription component

Parameters:

subscription_id (Integer) —

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

Required parameter: The Chargify id of the

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

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::DEFAULT)
               .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_nullify404(true)
                .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. subscription component allocation

Parameters:

subscription_id (String) —

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

Required parameter: The Chargify id of the
allocation_id (Integer) —

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

Optional parameter: Example:

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

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::DEFAULT)
               .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_nullify404(true)
                .is_response_void(true)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             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 Chargify gem You can also query the current quantity via the [official Chargify 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 “` subscription 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 (String) —

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

Required parameter: The Chargify id of the
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 427

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::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationResponse.method(:from_hash))
                .is_response_array(true)
                .local_error('401',
                             'Unauthorized',
                             APIException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             APIException))
    .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. subscription of filter you’d like to apply to your search. Use in query ‘date_field=updated_at`. order in which results are returned. Use in query `direction=asc`. 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. Allows including additional data in the response. Use in query `include=subscription`. parameter: Allows fetching components allocation with matching use_site_exchange_rate based on provided value. Use in query `filter=true`. fetching components allocation with matching currency based on provided values. Use in query `filter=EUR,USD`.

Parameters:

subscription_id (String) —

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

Optional parameter: The type
direction (SortingDirection | nil) —

Optional parameter: Controls the
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 (ListSubscriptionComponentsInclude) —

Optional parameter:
filter_use_site_exchange_rate (TrueClass | FalseClass) —

Optional
filter_currencies (Array[String]) —

Optional parameter: Allows

Returns:

(Array[SubscriptionComponentResponse]) —

response from the API call.

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

def list_subscription_components(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/components.json',
                                 Server::DEFAULT)
               .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')
                             .validator(proc do |value|
                               UnionTypeLookUp.get(:ListSubscriptionComponentsInputDirection)
                                              .validate(value)
                             end))
               .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['filter_use_site_exchange_rate'], key: 'filter[use_site_exchange_rate]'))
               .query_param(new_parameter(options['filter_currencies'], key: 'filter[currencies]'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .is_nullify404(true)
                .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`. order in which results are returned. Use in query `direction=asc`. 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`. parameter: Allows fetching components allocation with matching use_site_exchange_rate based on provided value. Use in query `filter=true`. fetching components allocation with matching currency based on provided values. Use in query `filter=USD,EUR`. parameter: Allows fetching components allocations that belong to the subscription with matching states based on provided values. To use this filter you also have to include the following param in the request `include=subscription`. Use in query `filter[states]=active,canceled&include=subscription`. parameter: The type of filter you’d like to apply to your search. To use this filter you also have to include the following param in the request ‘include=subscription`. start date (format YYYY-MM-DD) with which to filter the date_field. Returns components that belong to the subscription with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. To use this filter you also have to include the following param in the request `include=subscription`. start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components that belong to the subscription 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. To use this filter you also have to include the following param in the request `include=subscription`. date (format YYYY-MM-DD) with which to filter the date_field. Returns components that belong to the subscription with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. To use this filter you also have to include the following param in the request `include=subscription`. end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components that belong to the subscription 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. To use this filter you also have to include the following param in the request `include=subscription`.

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 | nil) —

Optional parameter: Controls the
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:
filter_use_site_exchange_rate (TrueClass | FalseClass) —

Optional
filter_currencies (Array[String]) —

Optional parameter: Allows
filter_subscription_states (Array[SubscriptionState]) —

Optional
filter_subscription_date_field (SubscriptionListDateField) —

Optional
filter_subscription_start_date (String) —

Optional parameter: The
filter_subscription_start_datetime (String) —

Optional parameter: The
filter_subscription_end_date (String) —

Optional parameter: The end
filter_subscription_end_datetime (String) —

Optional parameter: The

Returns:

(ListSubscriptionComponentsResponse) —

response from the API call.

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

def list_subscription_components_for_site(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions_components.json',
                                 Server::DEFAULT)
               .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')
                             .validator(proc do |value|
                               UnionTypeLookUp.get(:ListSubscriptionComponentsForSiteInputDirection)
                                              .validate(value)
                             end))
               .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'))
               .query_param(new_parameter(options['filter_use_site_exchange_rate'], key: 'filter[use_site_exchange_rate]'))
               .query_param(new_parameter(options['filter_currencies'], key: 'filter[currencies]'))
               .query_param(new_parameter(options['filter_subscription_states'], key: 'filter[subscription][states]'))
               .query_param(new_parameter(options['filter_subscription_date_field'], key: 'filter[subscription][date_field]'))
               .query_param(new_parameter(options['filter_subscription_start_date'], key: 'filter[subscription][start_date]'))
               .query_param(new_parameter(options['filter_subscription_start_datetime'], key: 'filter[subscription][start_datetime]'))
               .query_param(new_parameter(options['filter_subscription_end_date'], key: 'filter[subscription][end_date]'))
               .query_param(new_parameter(options['filter_subscription_end_datetime'], key: 'filter[subscription][end_datetime]'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .is_nullify404(true)
                .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. subscription 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 (String) —

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

Required parameter: Either the Chargify id
since_id (Integer) —

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

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

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

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 502

def list_usages(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/components/{component_id}/usages.json',
                                 Server::DEFAULT)
               .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))
               .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
                .is_nullify404(true)
                .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`

Chargify 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` at the `line_items` and `allocations` level respectfully. See example below for Fine-Grained Component Control response. subscription

Parameters:

subscription_id (String) —

Required parameter: The Chargify id of the
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 680

def preview_allocations(subscription_id,
                        body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/allocations/preview.json',
                                 Server::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(AllocationPreviewResponse.method(:from_hash))
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ComponentAllocationErrorException))
    .execute
end

#read_subscription_component(subscription_id, component_id) ⇒ `SubscriptionComponentResponse`

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

Parameters:

subscription_id (String) —

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

Required parameter: The Chargify id of the

Returns:

(SubscriptionComponentResponse) —

response from the API call.

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

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::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionComponentResponse.method(:from_hash))
                .local_error('404',
                             'Not Found',
                             APIException))
    .execute
end

#record_event(subdomain, 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 Chargify. 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 Chargify data ingestion engine. Learn more about the feature in general in the [Events-Based Billing help docs](chargify.zendesk.com/hc/en-us/articles/4407720613403). ## Record Event Use this endpoint to record a single event. *Note: this endpoint differs from the standard Chargify 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 a Chargify event data-store, use this parameter to indicate the data-store.

Parameters:

subdomain (String) —

Required parameter: Your site’s subdomain
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 967

def record_event(subdomain,
                 api_handle,
                 store_uid: nil,
                 body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{subdomain}/events/{api_handle}.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subdomain, key: 'subdomain')
                                .is_required(true)
                                .should_encode(true))
               .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_nullify404(true)
                .is_response_void(true))
    .execute
end

#record_events(subdomain, 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 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 a Chargify event data-store, use this parameter to indicate the data-store.

Parameters:

subdomain (String) —

Required parameter: Your site’s subdomain
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 780

def record_events(subdomain,
                  api_handle,
                  store_uid: nil,
                  body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{subdomain}/events/{api_handle}/bulk.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subdomain, key: 'subdomain')
                                .is_required(true)
                                .should_encode(true))
               .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_nullify404(true)
                .is_response_void(true))
    .execute
end

#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. subscription

Parameters:

subscription_id (String) —

Required parameter: The Chargify id of the

Returns:

(SubscriptionResponse) —

response from the API call.

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

def 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::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash)))
    .execute
end

#update_prepaid_usage_allocation(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. subscription component allocation Example:

Parameters:

subscription_id (String) —

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

Required parameter: The Chargify id of the
allocation_id (Integer) —

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

Optional parameter:

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

def update_prepaid_usage_allocation(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::DEFAULT)
               .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_nullify404(true)
                .is_response_void(true)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             SubscriptionComponentAllocationErrorException))
    .execute
end

#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. subscription Example:

Parameters:

subscription_id (String) —

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

Optional parameter:

Returns:

(BulkComponentSPricePointAssignment) —

response from the API call.

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

def 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::DEFAULT)
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(BulkComponentSPricePointAssignment.method(:from_hash))
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ComponentPricePointErrorException))
    .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) ⇒ void

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

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

#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(subdomain, api_handle, store_uid: nil, body: nil) ⇒ void

#record_events(subdomain, api_handle, store_uid: nil, body: nil) ⇒ void

#reset_subscription_components_price_points(subscription_id) ⇒ SubscriptionResponse

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

#update_subscription_components_price_points(subscription_id, body: nil) ⇒ BulkComponentSPricePointAssignment

#activate_event_based_component(subscription_id, component_id) ⇒ `void`

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

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

#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(subdomain, api_handle, store_uid: nil, body: nil) ⇒ `void`

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

#reset_subscription_components_price_points(subscription_id) ⇒ `SubscriptionResponse`

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

#update_subscription_components_price_points(subscription_id, body: nil) ⇒ `BulkComponentSPricePointAssignment`