Class: AdvancedBilling::SubscriptionComponentsController

Inherits:
BaseController
  • Object
show all
Defined in:
lib/advanced_billing/controllers/subscription_components_controller.rb

Overview

SubscriptionComponentsController

Constant Summary

Constants inherited from BaseController

BaseController::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseController

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseController

#initialize, #new_api_call_builder, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from AdvancedBilling::BaseController

Instance Method Details

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

This method returns an undefined value.

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](https://maxio.zendesk.com/hc/en-us/articles/24260323329805-Events-Ba sed-Billing-Overview). Use this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes Advanced Billing to bill for events when the subscription is renewed. Note: it is possible to stream events for a subscription at any time, regardless of component activation status. The activation status only determines if the subscription should be billed for event-based component usage at renewal. id of the subscription of the component

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Advanced Billing

  • component_id (Integer) —

    Required parameter: The Advanced Billing id

  • body (ActivateEventBasedComponent) (defaults to: nil) —

    Optional parameter: Example:



727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 727

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

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

This endpoint creates a new allocation, setting the current allocated quantity for the Component and recording a memo. Notice: Allocations can only be updated for Quantity, On/Off, and Prepaid Components.

Allocations Documentation

Full documentation on how to record Allocations in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Componen t-Allocations-Overview). It is focused on how allocations operate within the Advanced Billing UI.It goes into greater detail on how the user interface will react when recording allocations. This documentation also goes into greater detail on how proration is taken into consideration when applying component allocations.

Proration Schemes

Changing the allocated quantity of a component mid-period can result in either a Charge or Credit being applied to the subscription. When creating an allocation via the API, you can pass the upgrade_charge, downgrade_credit, and accrue_charge to be applied. Notice: These proration and accural fields will be ignored for Prepaid Components since this component type always generate charges immediately without proration. For background information on prorated components and upgrade/downgrade schemes, see [Setting Component Allocations.](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-C omponent-Allocations-Proration). See the tables below for valid values. | upgrade_charge | Definition

           

-----------| | full         | A charge is added for the full price of the component.            | | prorated     | A charge is added for the prorated price of the component change. | | none         | No charge is added.           |

downgrade_credit Definition                                        
full            A full price credit is added for the amount owed.
prorated        A prorated credit is added for the amount owed.  
none            No charge is added.                              
accrue_charge Definition
                                               

|---------------|--------------------------------------------------------- ---------------------------------------------------| | true        | Attempt to charge the customer at next renewal. | | false       | Attempt to charge the customer right away. If it fails, the charge will be accrued until the next renewal. |

Order of Resolution for upgrade_charge and downgrade_credit

  1. Per allocation in API call (within a single allocation of the allocations array)
  2. [Component-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Componen t-Allocations-Overview)
  3. Allocation API call top level (outside of the allocations array)
  4. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Componen t-Allocations-Proration#proration-schemes)

Order of Resolution for accrue charge

  1. Allocation API call top level (outside of the allocations array)
  2. [Site-level default value](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-Componen t-Allocations-Proration#proration-schemes) NOTE: Proration uses the current price of the component as well as the current tax rates. Changes to either may cause the prorated charge/credit to be wrong. the subscription of the component

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • component_id (Integer) —

    Required parameter: The Advanced Billing id

  • body (CreateAllocationRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 248

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

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

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

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • body (AllocateComponents) (defaults to: nil) —

    Optional parameter: Example:

Returns:



347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 347

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

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

This method returns an undefined value.

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

Parameters:

  • api_handle (String) —

    Required parameter: Identifies the Stream for

  • store_uid (String) (defaults to: nil) —

    Optional parameter: If you've attached your own

  • body (Array[EBBEvent]) (defaults to: nil) —

    Optional parameter: Example:



834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 834

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

#bulk_reset_subscription_components_price_points(subscription_id) ⇒ SubscriptionResponse

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

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 159

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

#bulk_update_subscription_components_price_points(subscription_id, body: nil) ⇒ BulkComponentsPricePointAssignment

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

  1. Price point id (integer)
  2. Price point handle (string)
  3. "_default" string, which will reset the price point to the component's current default price point. the subscription Example:

Parameters:

Returns:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 129

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

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

Documentation

Full documentation on how to create Components in the Advanced Billing UI can be located [here](https://maxio.zendesk.com/hc/en-us/articles/24261149711501-Create-E dit-and-Archive-Components). Additionally, for information on how to record component usage against a subscription, please see the following resources:

  • [Recording Metered Component Usage](https://maxio.zendesk.com/hc/en-us/articles/24251890500109-Reportin g-Component-Allocations#reporting-metered-component-usage)
  • [Reporting Prepaid Component Status](https://maxio.zendesk.com/hc/en-us/articles/24251890500109-Reporti ng-Component-Allocations#reporting-prepaid-component-status) You may choose to report metered or prepaid usage to Advanced Billing as often as you wish. You may report usage as it happens. You may also report usage periodically, such as each night or once per billing period. If usage events occur in your system very frequently (on the order of thousands of times an hour), it is best to accumulate usage into batches on your side, and then report those batches less frequently, such as daily. This will ensure you remain below any API throttling limits. If your use case requires higher rates of usage reporting, we recommend utilizing Events Based Components.

Create Usage for Subscription

This endpoint allows you to record an instance of metered or prepaid usage for a subscription. The quantity from usage for each component is accumulated to the unit_balance on the Component Line Item for the subscription.

Price Point ID usage

If you are using price points, for metered and prepaid usage components, Advanced Billing gives you the option to specify a price point in your request. You do not need to specify a price point ID. If a price point is not included, the default price point for the component will be used when the usage is recorded. If an invalid price_point_id is submitted, the endpoint will return an error.

Deducting Usage

In the event that you need to reverse a previous usage report or otherwise deduct from the current usage balance, you may provide a negative quantity. Example: Previously recorded:

{
  "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:

{
  "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

  1. Is it possible to record metered usage for more than one component at a time?
  2. No. Usage should be reported as one API call per component on a single subscription. For example, to record that a subscriber has sent both an SMS Message and an Email, send an API call for each. the subscription Advanced Billing id for the component or the component's handle prefixed by handle:

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • component_id (Integer | String) —

    Required parameter: Either the

  • body (CreateUsageRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:



603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 603

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

#deactivate_event_based_component(subscription_id, component_id) ⇒ void

This method returns an undefined value.

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

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Advanced Billing

  • component_id (Integer) —

    Required parameter: The Advanced Billing id



757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 757

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

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

This method returns an undefined value.

Prepaid Usage components are unique in that their allocations are always additive. In order to reduce a subscription's allocated quantity for a prepaid usage component each allocation must be destroyed individually via this endpoint.

Credit Scheme

By default, destroying an allocation will generate a service credit on the subscription. This behavior can be modified with the optional credit_scheme parameter on this endpoint. The accepted values are:

  1. none: The allocation will be destroyed and the balances will be updated but no service credit or refund will be created.
  2. 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.
  3. refund: The allocation will be destroyed and the balances will be updated and a refund will be issued along with a Credit Note. the subscription of the component of the allocation

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • component_id (Integer) —

    Required parameter: The Advanced Billing id

  • allocation_id (Integer) —

    Required parameter: The Advanced Billing id

  • body (CreditSchemeRequest) (defaults to: nil) —

    Optional parameter: Example:



494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 494

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

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

This endpoint returns the 50 most recent Allocations, ordered by most recent first.

On/Off Components

When a subscription's on/off component has been toggled to on (1) or off (0), usage will be logged in this response.

Querying data via Advanced Billing gem

You can also query the current quantity via the official Advanced Billing Gem.

component = Chargify::Subscription::Component.find(1, :params =>
{:subscription_id => 7})
puts component.allocated_quantity
# => 23
# Second way
component = Chargify::Subscription.find(7).component(1)
puts component.allocated_quantity
# => 23

the subscription of the component pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query page=1.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • component_id (Integer) —

    Required parameter: The Advanced Billing id

  • page (Integer) (defaults to: 1) —

    Optional parameter: Result records are organized in

Returns:



306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 306

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

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

This request will list a subscription's applied components.

Archived Components

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

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • date_field (SubscriptionListDateField) —

    Optional parameter: The type

  • direction (SortingDirection) —

    Optional parameter: Controls the order

  • filter (ListSubscriptionComponentsFilter) —

    Optional parameter:

  • end_date (String) —

    Optional parameter: The end date (format

  • end_datetime (String) —

    Optional parameter: The end date and time

  • price_point_ids (IncludeNotNull) —

    Optional parameter: Allows

  • product_family_ids (Array[Integer]) —

    Optional parameter: Allows

  • sort (ListSubscriptionComponentsSort) —

    Optional parameter: The

  • start_date (String) —

    Optional parameter: The start date (format

  • start_datetime (String) —

    Optional parameter: The start date and time

  • include (Array[ListSubscriptionComponentsInclude]) —

    Optional

  • in_use (TrueClass | FalseClass) —

    Optional parameter: If in_use is

Returns:



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 88

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

#list_subscription_components_for_site(options = {}) ⇒ ListSubscriptionComponentsResponse

This request will list components applied to each subscription. pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query page=1. many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query per_page=200. attribute by which to sort. Use in query: sort=updated_at. in which results are returned. Use in query direction=asc. parameter: Filter to use for List Subscription Components For Site operation of filter you'd like to apply to your search. Use in query: date_field=updated_at. YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query start_date=2011-12-15. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of start_date. Use in query start_datetime=2022-07-01 09:00:05. YYYY-MM-DD) with which to filter the date_field. Returns components with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query end_date=2011-12-16. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns components with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site''s time zone will be used. If provided, this parameter will be used instead of end_date. Use in query end_datetime=2022-07-01 09:00:05. fetching components allocation with matching subscription id based on provided ids. Use in query subscription_ids=1,2,3. fetching components allocation only if price point id is present. Use in query price_point_ids=not_null. fetching components allocation with matching product family id based on provided ids. Use in query product_family_ids=1,2,3. Allows including additional data in the response. Use in query include=subscription,historic_usages.

Parameters:

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • sort (ListSubscriptionComponentsSort) —

    Optional parameter: The

  • direction (SortingDirection) —

    Optional parameter: Controls the order

  • filter (ListSubscriptionComponentsForSiteFilter) —

    Optional

  • date_field (SubscriptionListDateField) —

    Optional parameter: The type

  • start_date (String) —

    Optional parameter: The start date (format

  • start_datetime (String) —

    Optional parameter: The start date and time

  • end_date (String) —

    Optional parameter: The end date (format

  • end_datetime (String) —

    Optional parameter: The end date and time

  • subscription_ids (Array[Integer]) —

    Optional parameter: Allows

  • price_point_ids (IncludeNotNull) —

    Optional parameter: Allows

  • product_family_ids (Array[Integer]) —

    Optional parameter: Allows

  • include (ListSubscriptionComponentsInclude) —

    Optional parameter:

Returns:



909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 909

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

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

This request will return a list of the usages associated with a subscription for a particular metered component. This will display the previously recorded components for a subscription. This endpoint is not compatible with quantity-based components.

Since Date and Until Date Usage

Note: The since_date and until_date attributes each default to midnight on the date specified. For example, in order to list usages for January 20th, you would need to append the following to the URL.

?since_date=2016-01-20&until_date=2016-01-21

Read Usage by Handle

Use this endpoint to read the previously recorded components for a subscription. You can now specify either the component id (integer) or the component handle prefixed by "handle:" to specify the unique identifier for the component you are working with. the subscription Advanced Billing id for the component or the component's handle prefixed by handle: greater than or equal to the one specified than or equal to the one specified created_at date greater than or equal to midnight (12:00 AM) on the date specified. created_at date less than or equal to midnight (12:00 AM) on the date specified. pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query page=1. many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query per_page=200.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • component_id (Integer | String) —

    Required parameter: Either the

  • since_id (Integer) —

    Optional parameter: Returns usages with an id

  • max_id (Integer) —

    Optional parameter: Returns usages with an id less

  • since_date (Date) —

    Optional parameter: Returns usages with a

  • until_date (Date) —

    Optional parameter: Returns usages with a

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

Returns:



678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 678

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

#preview_allocations(subscription_id, body: nil) ⇒ AllocationPreviewResponse

Advanced Billing offers the ability to preview a potential subscription's quantity-based or on/off component allocation in the middle of the current billing period. This is useful if you want users to be able to see the effect of a component operation before actually doing it.

Fine-grained Component Control: Use with multiple upgrade_charges or

downgrade_credits When the allocation uses multiple different types of upgrade_charges or downgrade_credits, the Allocation is viewed as an Allocation which uses "Fine-Grained Component Control". As a result, the response will not include direction and proration within the allocation_preview, but at the line_items and allocations level respectfully. See example below for Fine-Grained Component Control response. the subscription

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • body (PreviewAllocationsRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:



391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 391

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

#read_subscription_component(subscription_id, component_id) ⇒ SubscriptionComponentResponse

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

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • component_id (Integer) —

    Required parameter: The Advanced Billing id

Returns:



17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 17

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

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

This method returns an undefined value.

Documentation

Events-Based Billing is an evolved form of metered billing that is based on data-rich events streamed in real-time from your system to Advanced Billing. These events can then be transformed, enriched, or analyzed to form the computed totals of usage charges billed to your customers. This API allows you to stream events into the Advanced Billing data ingestion engine. Learn more about the feature in general in the [Events-Based Billing help docs](https://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:

https://events.chargify.com/my-site-subdomain/events/my-stream-api-handle

which the event should be published. Keen project as an Advanced Billing event data-store, use this parameter to indicate the data-store.

Parameters:

  • api_handle (String) —

    Required parameter: Identifies the Stream for

  • store_uid (String) (defaults to: nil) —

    Optional parameter: If you've attached your own

  • body (EBBEvent) (defaults to: nil) —

    Optional parameter: Example:



801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 801

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

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

This method returns an undefined value.

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

Limitations

A few limitations exist when changing an allocation's expiration date:

  • An expiration date can only be changed for an allocation that belongs to a price point with expiration interval options explicitly set.
  • An expiration date can be changed towards the future with no limitations.
  • An expiration date can be changed towards the past (essentially expiring it) up to the subscription's current period beginning date. the subscription of the component of the allocation Example:

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • component_id (Integer) —

    Required parameter: The Advanced Billing id

  • allocation_id (Integer) —

    Required parameter: The Advanced Billing id

  • body (UpdateAllocationExpirationDate) (defaults to: nil) —

    Optional parameter:



438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 438

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