Class: AdvancedBilling::SubscriptionComponentsController

Activates an event-based component for a single subscription. 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 description here

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: TODO: type

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

def activate_event_based_component(subscription_id,
                                   component_id,
                                   body: nil)
  @api_call
    .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`

Creates an allocation, sets the current allocated quantity for the component, and records a memo. Allocations can only be updated for Quantity, On/Off, and Prepaid Components. When creating an allocation via the API, you can pass the ‘upgrade_charge`, `downgrade_credit`, and `accrue_charge` to be applied. > Note: These proration and accrual fields are ignored for Prepaid Components since this component type always generates charges immediately without proration. For information on prorated components and upgrade/downgrade schemes, see [Setting Component Allocations.](maxio.zendesk.com/hc/en-us/articles/24251906165133-C omponent-Allocations-Proration) ### 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. For more information, see the [Component Allocations](maxio.zendesk.com/hc/en-us/articles/24251883961485-Co mponent-Allocations-Overview) product Documentation. the subscription. of the component description here

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: TODO: type

Returns:

(AllocationResponse) —

Response from the API call.

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

def allocate_component(subscription_id,
                       component_id,
                       body: nil)
  @api_call
    .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, sets the current allocated quantity for each of the components, and records a memo. A ‘component_id` is required for each allocation. 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. ### 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

Parameters:

subscription_id (Integer) —

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

Optional parameter: TODO: type

Returns:

(Array[AllocationResponse]) —

Response from the API call.

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

def allocate_components(subscription_id,
                        body: nil)
  @api_call
    .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.

Records 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. here

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: TODO: type description

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

def bulk_record_events(api_handle,
                       store_uid: nil,
                       body: nil)
  @api_call
    .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 158

def bulk_reset_subscription_components_price_points(subscription_id)
  @api_call
    .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. type description here

Parameters:

subscription_id (Integer) —

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

Optional parameter: TODO:

Returns:

(BulkComponentsPricePointAssignment) —

Response from the API call.

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

def bulk_update_subscription_components_price_points(subscription_id,
                                                     body: nil)
  @api_call
    .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_or_reference, component_id, body: nil) ⇒ `UsageResponse`

Records an instance of metered or prepaid usage for a subscription. You can report metered or prepaid usage to Advanced Billing as often as you wish. You can report usage as it happens or periodically, such as each night or once per billing period. 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, see the following resources: It is not possible to record metered usage for more than one component at a time. 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. See the following product documentation articles for more information:

[Create and Manage

Components](maxio.zendesk.com/hc/en-us/articles/24261149711501-Cre ate-Edit-and-Archive-Components)

[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) The ‘quantity` from usage for each component is accumulated to the `unit_balance` on the [Component Line Item]($e/Subscription%20Components/readSubscriptionComponent) 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. ## Deducting Usage If you need to reverse a previous usage report or otherwise deduct from the current usage balance, you can provide a negative quantity. Example: Previously recorded quantity was 5000: “`json {

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

} “‘ To reduce the quantity 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`. Either the Advanced Billing subscription ID (integer) or the subscription reference (string). Important: In cases where a numeric string value matches both an existing subscription ID and an existing subscription reference, the system will prioritize the subscription ID lookup. For example, if both subscription ID 123 and subscription reference “123” exist, passing “123” will return the subscription with ID 123. Advanced Billing id for the component or the component’s handle prefixed by ‘handle:` description here

Parameters:

subscription_id_or_reference (Integer | String) —

Required parameter:
component_id (Integer | String) —

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

Optional parameter: TODO: type

Returns:

(UsageResponse) —

Response from the API call.

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

def create_usage(subscription_id_or_reference,
                 component_id,
                 body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id_or_reference}/components/{component_id}/usages.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id_or_reference, key: 'subscription_id_or_reference')
                                .is_required(true)
                                .should_encode(true)
                                .validator(proc do |value|
                                  UnionTypeLookUp.get(:CreateUsageSubscriptionIdOrReference)
                                                 .validate(value)
                                end))
               .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.

Deactivates 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 744

def deactivate_event_based_component(subscription_id,
                                     component_id)
  @api_call
    .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.

Deletes a prepaid usage allocation. 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 description here

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: TODO: type

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

def delete_prepaid_usage_allocation(subscription_id,
                                    component_id,
                                    allocation_id,
                                    body: nil)
  @api_call
    .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]`

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. 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 258

def list_allocations(subscription_id,
                     component_id,
                     page: 1)
  @api_call
    .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]`

Lists 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 87

def list_subscription_components(options = {})
  @api_call
    .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`

Lists 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 898

def list_subscription_components_for_site(options = {})
  @api_call
    .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]`

Returns a list of 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. Either the Advanced Billing subscription ID (integer) or the subscription reference (string). Important: In cases where a numeric string value matches both an existing subscription ID and an existing subscription reference, the system will prioritize the subscription ID lookup. For example, if both subscription ID 123 and subscription reference “123” exist, passing “123” will return the subscription with ID 123. 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_or_reference (Integer | String) —

Required parameter:
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 659

def list_usages(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id_or_reference}/components/{component_id}/usages.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['subscription_id_or_reference'], key: 'subscription_id_or_reference')
                                .is_required(true)
                                .should_encode(true)
                                .validator(proc do |value|
                                  UnionTypeLookUp.get(:ListUsagesInputSubscriptionIdOrReference)
                                                 .validate(value)
                                end))
               .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`

Previews 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. description here

Parameters:

subscription_id (Integer) —

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

Optional parameter: TODO: type

Returns:

(AllocationPreviewResponse) —

Response from the API call.

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

def preview_allocations(subscription_id,
                        body: nil)
  @api_call
    .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`

Returns information for a specific component on 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 16

def read_subscription_component(subscription_id,
                                component_id)
  @api_call
    .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.

Records a single event for Events-Based Billing. ## 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: TODO: type description here

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

def record_event(api_handle,
                 store_uid: nil,
                 body: nil)
  @api_call
    .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.

Updates the expiration date for a prepaid usage allocation. 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 type description here

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: TODO:

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

def update_prepaid_usage_allocation_expiration_date(subscription_id,
                                                    component_id,
                                                    allocation_id,
                                                    body: nil)
  @api_call
    .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_or_reference, 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_or_reference, 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`