Class: AdvancedBilling::EventsController

Inherits:
BaseController show all
Defined in:
lib/advanced_billing/controllers/events_controller.rb

Overview

EventsController

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

#list_events(options = {}) ⇒ Array[EventResponse]

Lists events for a site. Events include various activity that happens around a Site. This information is especially useful to track down issues that arise when subscriptions are not created due to errors. Within the UI, Events are referred to as Site Activity. For more information, see [Site Activity](https://maxio.zendesk.com/hc/en-us/articles/24250671733517-Site- Activity). Use query string filters to narrow down results. You can use the filter parameter to filter by event key.

Legacy Filters

The following keys are no longer supported.

  • payment_failure_recreated
  • payment_success_recreated
  • renewal_failure_recreated
  • renewal_success_recreated
  • zferral_revenue_post_failure - (Specific to the deprecated Zferral integration)
  • zferral_revenue_post_success - (Specific to the deprecated Zferral integration)

Event Key

The event type is identified by the key property. See Event Key for a complete list of supported keys.

Event Specific Data

Different event types may include additional data in event_specific_data property. While some events share the same schema for event_specific_data, others may not include it at all. For precise mappings from key to event_specific_data, refer to Event.

Example

Here’s an example event for the subscription_product_change event:

{
    "event": {
        "id": 351,
        "key": "subscription_product_change",
        "message": "Product changed on Mark Alan's subscription from
'Basic' to 'Pro'",
        "subscription_id": 205,
        "event_specific_data": {
            "new_product_id": 3,
            "previous_product_id": 2
        },
        "created_at": "2012-01-30T10:43:31-05:00"
    }
}

Here’s an example event for the subscription_state_change event:

 {
     "event": {
         "id": 353,
         "key": "subscription_state_change",
         "message": "State changed on Mark Alan's subscription to Pro from
trialing to active",
         "subscription_id": 205,
         "event_specific_data": {
             "new_subscription_state": "active",
             "previous_subscription_state": "trialing"
         },
         "created_at": "2012-01-30T10:43:33-05:00"
     }
 }

Enhanced Catalog Experience

If you’re using the [enhanced Catalog experience](page:help/announcements/2026-announcements#new-catalog-experie nce-and-terminology), you’ll see updated naming in webhook events and messages. Event name changes:

  • subscription_product_change → subscription_plan_change
  • component_allocation_change → allocation_change
  • component_billing_date_change → product_billing_date_change Message updates:
  • “Plan changed on Subscription from previous plan to new plan”
  • “Successful payment for allocation changes to Product on Subscription”
  • “Failed payment for allocation changes to Product on 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. greater than or equal to the one specified. than or equal to the one specified. returned events. event keys after comma. Use in query filter=signup_success,payment_success. filter you would like to apply to your search. 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. 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 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. (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.

Parameters:

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • since_id (Integer) —

    Optional parameter: Returns events with an id

  • max_id (Integer) —

    Optional parameter: Returns events with an id less

  • direction (Direction) —

    Optional parameter: The sort direction of the

  • filter (Array[EventKey]) —

    Optional parameter: You can pass multiple

  • date_field (ListEventsDateField) —

    Optional parameter: The type of

  • start_date (String) —

    Optional parameter: The start date (format

  • end_date (String) —

    Optional parameter: The end date (format

  • start_datetime (String) —

    Optional parameter: The start date and time

  • end_datetime (String) —

    Optional parameter: The end date and time

Returns:



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

def list_events(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/events.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['since_id'], key: 'since_id'))
               .query_param(new_parameter(options['max_id'], key: 'max_id'))
               .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['end_date'], key: 'end_date'))
               .query_param(new_parameter(options['start_datetime'], key: 'start_datetime'))
               .query_param(new_parameter(options['end_datetime'], key: 'end_datetime'))
               .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(EventResponse.method(:from_hash))
                .is_response_array(true))
    .execute
end

#list_subscription_events(options = {}) ⇒ Array[EventResponse]

Lists events for a subscription.

Event Key

The event type is identified by the key property. See Event Key for a complete list of supported keys.

Event Specific Data

Different event types may include additional data in event_specific_data property. While some events share the same schema for event_specific_data, others may not include it at all. For precise mappings from key to event_specific_data, refer to Event.

Enhanced Catalog Experience

If you’re using the [enhanced Catalog experience](page:help/announcements/2026-announcements#new-catalog-experie nce-and-terminology), you’ll see updated naming in webhook events and messages. Event name changes:

  • subscription_product_change → subscription_plan_change
  • component_allocation_change → allocation_change
  • component_billing_date_change → product_billing_date_change Message updates:
  • “Successful payment for allocation changes to Product on Subscription”
  • “Failed payment for allocation changes to Product on Subscription”
  • “Plan changed on Subscription from previous plan to new plan” the 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. greater than or equal to the one specified. than or equal to the one specified. returned events. event keys after comma. Use in query filter=signup_success,payment_success.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • since_id (Integer) —

    Optional parameter: Returns events with an id

  • max_id (Integer) —

    Optional parameter: Returns events with an id less

  • direction (Direction) —

    Optional parameter: The sort direction of the

  • filter (Array[EventKey]) —

    Optional parameter: You can pass multiple

Returns:



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/advanced_billing/controllers/events_controller.rb', line 201

def list_subscription_events(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/events.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['subscription_id'], key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .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['direction'], key: 'direction'))
               .query_param(new_parameter(options['filter'], key: 'filter'))
               .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(EventResponse.method(:from_hash))
                .is_response_array(true))
    .execute
end

#read_events_count(options = {}) ⇒ CountResponse

Returns the total count of events for a given site. If you’re using the [enhanced Catalog experience](page:help/announcements/2026-announcements#new-catalog-experie nce-and-terminology), you’ll see updated naming in webhook events and messages. Event name changes:

  • subscription_product_change → subscription_plan_change
  • component_allocation_change → allocation_change
  • component_billing_date_change → product_billing_date_change Message updates:
  • “Successful payment for allocation changes to Product on Subscription”
  • “Failed payment for allocation changes to Product on Subscription”
  • “Plan changed on Subscription from previous plan to new plan” 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. greater than or equal to the one specified. than or equal to the one specified. returned events. event keys after comma. Use in query filter=signup_success,payment_success.

Parameters:

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • since_id (Integer) —

    Optional parameter: Returns events with an id

  • max_id (Integer) —

    Optional parameter: Returns events with an id less

  • direction (Direction) —

    Optional parameter: The sort direction of the

  • filter (Array[EventKey]) —

    Optional parameter: You can pass multiple

Returns:



259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/advanced_billing/controllers/events_controller.rb', line 259

def read_events_count(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/events/count.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['since_id'], key: 'since_id'))
               .query_param(new_parameter(options['max_id'], key: 'max_id'))
               .query_param(new_parameter(options['direction'], key: 'direction'))
               .query_param(new_parameter(options['filter'], key: 'filter'))
               .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(CountResponse.method(:from_hash)))
    .execute
end