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

Activates an event-based component for a single subscription. To bill your subscribers on your Events data under the Events-Based Billing feature, the components must be activated for the subscriber. For more information, see [Design Your Catalog](https://docs.maxio.com/hc/en-us/articles/24181036583053-Design-Yo ur-Catalog?method=componenttypes). Use this endpoint to activate an event-based component for a single subscription. Activating an event-based component causes billing 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



713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 713

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.](https://maxio.zendesk.com/hc/en-us/articles/24251906165133-C omponent-Allocations-Proration)

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. For more information, see the [Component Allocations](https://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:



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# 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

  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. For more information, see the [Component Allocations](https://maxio.zendesk.com/hc/en-us/articles/24251883961485-Co mponent-Allocations-Overview) product documentation. the subscription. description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

Returns:



320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# 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 URL for this API in that events and your site subdomain are included in the 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. This applies to Legacy Metering sites only — it has no effect on Maxio Metering sites. 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



819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 819

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:



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# 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:

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

Parameters:

Returns:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# 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](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, 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:

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:

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

To reduce the quantity 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. 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:



575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
 
# 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



743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 743

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:

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



469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# 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]

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



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# 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:



87
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
 
# 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:



894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 894

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]

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



659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
 
# 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_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. description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

Returns:



365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# 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:



16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# 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. 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. For more information, see [Design Your Catalog](https://docs.maxio.com/hc/en-us/articles/24181036583053-Design-Yo ur-Catalog?method=componenttypes). Note: this endpoint differs from the standard URL for this API in that events and your site subdomain are included in the 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. This applies to Legacy Metering sites only — it has no effect on Maxio Metering sites.

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



785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
 
# File 'lib/advanced_billing/controllers/subscription_components_controller.rb', line 785

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:



411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
 
# 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