List Subscription Events

GET https://api.chartmogul.com/v1/subscription_events

Lists an array of subscription event objects from your ChartMogul account.

curl -X GET "https://api.chartmogul.com/v1/subscription_events?per_page=5&event_type=subscription_cancelled&plan_external_id=gold_monthly" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json"
ChartMogul::SubscriptionEvent.all(
  event_type: "subscription_cancelled",
  plan_external_id: "gold_monthly",
  per_page: 5,
)
ChartMogul.SubscriptionEvent.all(config, {
  event_type: "subscription_cancelled",
  plan_external_id: "gold_monthly",
  per_page: 5,
});
ChartMogul\SubscriptionEvent::all([
  "event_type" => "subscription_cancelled",
  "plan_external_id" => "gold_monthly",
  "per_page" => 5
]);
api.ListSubscriptionEvents(
  &cm.FilterSubscriptionEvents{
    PlanExternalID: "gold_monthly",
    EventType:      "subscription_cancelled",
  },
  &cm.MetaCursor{},
)
chartmogul.SubscriptionEvent.all(
  config,
  per_page=5,
  event_type="subscription_cancelled",
  plan_external_id="gold_monthly",
)
{
  "subscription_events": [
    {
      "id": 73966836,
      "data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      "data_source_customer_external_id": "cus_0001",
      "subscription_set_external_id": null,
      "subscription_external_id": "sub_0001",
      "plan_external_id": "gold_monthly",
      "event_date": "2022-04-09T11:17:14Z",
      "effective_date": "2022-04-09T10:04:13Z",
      "event_type": "subscription_cancelled",
      "external_id": null,
      "errors": {},
      "created_at": "2022-04-09T11:17:14Z",
      "updated_at": "2022-04-09T11:17:14Z",
      "quantity": null,
      "currency": null,
      "amount_in_cents": null,
      "tax_amount_in_cents": null,
      "event_order": 100,
      "retracted_event_id": null
    },
    {
      "id": 73966786,
      "data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      "data_source_customer_external_id": "cus_0002",
      "subscription_set_external_id": null,
      "subscription_external_id": "sub_0002",
      "plan_external_id": "gold_monthly",
      "event_date": "2022-04-09T11:16:17Z",
      "effective_date": "2022-04-09T11:16:17Z",
      "event_type": "subscription_cancelled",
      "external_id": null,
      "errors": {},
      "created_at": "2022-04-09T11:16:17Z",
      "updated_at": "2022-04-09T11:16:17Z",
      "quantity": null,
      "currency": null,
      "amount_in_cents": null,
      "tax_amount_in_cents": null,
      "event_order": null,
      "retracted_event_id": null
    }
  ],
  "meta": {
    "next_key": null,
    "prev_key": null,
    "before_key": "2022-04-10T22:27:35.834Z",
    "page": 1,
    "total_pages": 1
  },
  "cursor": "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more": true
}
#<ChartMogul::SubscriptionEvents:0x000000012d47a238
  @meta={ # deprecated with version 4.0.0
    :next_key=>nil, 
    :prev_key=>nil, 
    :before_key=>"2022-04-10T22:27:35.834Z", 
    :page=>1, 
    :total_pages=>1
  }, 
  @subscription_events=[
    #<ChartMogul::SubscriptionEvent:0x000000012d479f40 
      @id=73966836, 
      @data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      @customer_external_id="cus_0001", 
      @subscription_set_external_id="", 
      @subscription_external_id="sub_0001", 
      @plan_external_id="gold_monthly", 
      @event_date="2022-04-09T11:17:14Z", 
      @effective_date="2022-04-09T10:04:13Z", 
      @event_type="subscription_cancelled", 
      @external_id="", 
      @errors={}, 
      @created_at="2022-04-09T11:17:14Z",
      @updated_at="2022-04-09T11:17:14Z",
      @quantity="",
      @currency="",
      @amount_in_cents="",
      @tax_amount_in_cents=nil,
      @retracted_event_id=nil
    >, 
    #<ChartMogul::SubscriptionEvent:0x000000012d478cd0
      @id=73966786, 
      @data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba", 
      @customer_external_id="cus_0002",
      @subscription_set_external_id=nil,
      @subscription_external_id="sub_0002",
      @plan_external_id="gold_monthly", 
      @event_date="2022-09-13T23:00:00Z",
      @effective_date="2022-09-15T23:00:00Z", 
      @event_type="subscription_cancelled", 
      @external_id="",
      @errors={}, 
      @created_at="2022-09-26T08:29:22Z",
      @updated_at="2022-09-26T08:29:43Z", 
      @quantity=nil,
      @currency="USD",
      @amount_in_cents=nil,
      @tax_amount_in_cents=nil,
      @retracted_event_id=nil
    >
  ],
  @has_more=true, 
  @cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k"
>
{
  subscription_events: [
    {
      id: 73966836,
      data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      data_source_customer_external_id: "cus_0001",
      subscription_set_external_id: null,
      subscription_external_id: "sub_0001",
      plan_external_id: "gold_monthly",
      event_date: "2022-04-09T11:17:14Z",
      effective_date: "2022-04-09T10:04:13Z",
      event_type: "subscription_cancelled",
      external_id: null,
      errors: {},
      created_at: "2022-04-09T11:17:14Z",
      updated_at: "2022-04-09T11:17:14Z",
      quantity: null,
      currency: null,
      amount_in_cents: null,
      tax_amount_in_cents: null,
      event_order: 100,
      retracted_event_id: null
    },
    {
      id: 73966786,
      data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      data_source_customer_external_id: "cus_0002",
      subscription_set_external_id: null,
      subscription_external_id: "sub_0002",
      plan_external_id: "gold_monthly",
      event_date: "2022-04-09T11:16:17Z",
      effective_date: "2022-04-09T11:16:17Z",
      event_type: "subscription_cancelled",
      external_id: null,
      errors: {},
      created_at: "2022-04-09T11:16:17Z",
      updated_at: "2022-04-09T11:16:17Z",
      quantity: null,
      currency: null,
      amount_in_cents: null,
      tax_amount_in_cents: null,
      event_order: null,
      retracted_event_id: null
    }
  ],
  meta: {
    next_key: null,
    prev_key: null,
    before_key: "2022-04-10T22:27:35.834Z",
    page: 1,
    total_pages: 1
  },
  cursor: "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  has_more: true
}
Doctrine\Common\Collections\ArrayCollection::__set_state(array(
  "elements" => 
  array (
    0 => 
    ChartMogul\SubscriptionEvent::__set_state(array(
      id=>73966836, 
      data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      customer_external_id="cus_0001", 
      subscription_set_external_id="", 
      subscription_external_id="sub_0001", 
      plan_external_id="gold_monthly", 
      event_date="2022-04-09T11:17:14Z", 
      effective_date="2022-04-09T10:04:13Z", 
      event_type="subscription_cancelled", 
      external_id="", 
      errors={}, 
      created_at="2022-04-09T11:17:14Z",
      updated_at="2022-04-09T11:17:14Z",
      quantity="",
      currency="",
      amount_in_cents="",
      tax_amount_in_cents=None,
      event_order=100,
      retracted_event_id=None
    )),
    ChartMogul\SubscriptionEvent::__set_state(array(
      id=>73966786, 
      data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      customer_external_id="cus_0002", 
      subscription_set_external_id="", 
      subscription_external_id="sub_0002", 
      plan_external_id="gold_monthly", 
      event_date="2022-04-09T11:17:14Z", 
      effective_date="2022-04-09T10:04:13Z", 
      event_type="subscription_cancelled", 
      external_id="", 
      errors={}, 
      created_at="2022-04-09T11:17:14Z",
      updated_at="2022-04-09T11:17:14Z",
      quantity="",
      currency="",
      amount_in_cents="",
      tax_amount_in_cents=None,
      event_order=100,
      retracted_event_id=None
    )),
  ),
  "next_key" => NULL, # deprecated with version 6.0.0
  "prev_key" => NULL, # deprecated with version 6.0.0
  "before_key" => "2022-04-10T22:27:35.834Z", # deprecated with version 6.0.0
  "page" => 1, # deprecated with version 6.0.0
  "total_pages" => 1, # deprecated with version 6.0.0
  "cursor" => "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more" => true
  )
);
(*chartmogul.SubscriptionEvents)(0xc012034b69)({
  SubscriptionEvents: ([]chartmogul.SubscriptionEvent) (len=2) {
    (chartmogul.SubscriptionEvent) {
    ID: (uint64) 23223966,
    DataSourceUUID: (string) (len=39) "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
    CustomerExternalID: (string) (len=8) "cus_0001",
    SubscriptionSetExternalID: (string) "",
    SubscriptionExternalID: (string) (len=8) "sub_0001",
    PlanExternalID: (string) (len=12) "gold_monthly",
    EventDate: (string) (len=20) "2022-04-09T11:17:14Z",
    EffectiveDate: (string) (len=20) "2022-04-09T10:04:13Z",
    EventType: (string) (len=28) "subscription_cancelled",
    ExternalID: (string) (len=8) "",
    Errors: (interface{}) {},
    CreatedAt: (string) (len=20) "2022-04-09T11:17:14Z",
    UpdatedAt: (string) (len=20) "2022-04-09T11:17:14Z",
    Quantity: (int32) 1,
    Currency: (string) (len=3) "USD",
    AmountInCents: (int32) 1000,
    TaxAmountInCents: (int32) 0,
    EventOrder: (int32)100,
    RetractedEventId: (string) "",
    },
    (chartmogul.SubscriptionEvent) {
    ID: (uint64) 23223967
    DataSourceUUID: (string) (len=39) "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
    CustomerExternalID: (string) (len=8) "cus_0002",
    SubscriptionSetExternalID: (string) "",
    SubscriptionExternalID: (string) (len=8) "sub_0001",
    PlanExternalID: (string) (len=12) "gold_monthly",
    EventDate: (string) (len=20) "2022-04-09T11:16:17Z",
    EffectiveDate: (string) (len=20) "2022-04-09T11:16:17Z",
    EventType: (string) (len=28) "subscription_cancelled",
    ExternalID: (string) (len=8) "",
    Errors: (interface{}) {},
    CreatedAt: (string) (len=20) "2022-04-09T11:16:17Z",
    UpdatedAt: (string) (len=20) "2022-04-09T11:16:17Z",
    Quantity: (int32) 1,
    Currency: (string) (len=3) "USD",
    AmountInCents: (int32) 100,
    TaxAmountInCents: (int32) 0,
    EventOrder: (int32)100,
    RetractedEventId: (string) "",
    },
  },
  MetaCursor: (chartmogul.MetaCursor) { // deprecated with version v4
    NextKey: (uint64) 0
    PrevKey: (uint64) 0
    BeforeKey: (string) (len=24) "2022-04-10T22:27:35.834Z"
    Page: (uint64) 1
    TotalPages: (uint64) 1
  },
  Cursor: (string) (len=44) "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  HasMore: (bool) true
})
SubscriptionEvents(
  subscription_events=[
    <SubscriptionEvent{
      id=73966836, 
      data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      customer_external_id="cus_0001", 
      subscription_set_external_id="", 
      subscription_external_id="sub_0001", 
      plan_external_id="gold_monthly", 
      event_date="2022-04-09T11:17:14Z", 
      effective_date="2022-04-09T10:04:13Z", 
      event_type="subscription_cancelled", 
      external_id="", 
      errors={}, 
      created_at="2022-04-09T11:17:14Z",
      updated_at="2022-04-09T11:17:14Z",
      quantity="",
      currency="",
      amount_in_cents="",
      tax_amount_in_cents=None,
      event_order=100,
      retracted_event_id=None
    }>,
    <SubscriptionEvent{
      id=73966786,
      data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba", 
      customer_external_id="cus_0002",
      subscription_set_external_id=None,
      subscription_external_id="sub_0002",
      plan_external_id="gold_monthly", 
      event_date="2022-04-09T11:16:17Z",
      effective_date="2022-04-09T11:16:17Z", 
      event_type="subscription_cancelled", 
      external_id="",
      errors={}, 
      created_at="2022-04-09T11:16:17Z",
      updated_at="2022-04-09T11:16:17Z", 
      quantity=nil,
      currency="USD",
      amount_in_cents=nil,
      tax_amount_in_cents=None,
      event_order=100,
      retracted_event_id=None
    }>],
  meta=[ # deprecated with version 4.0.0
    next_key=None, 
    prev_key=None, 
    before_key="2022-04-10T22:27:35.834Z", 
    page=1, 
    total_pages=1
  ],
  cursor='AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k',
  has_more=True
)

Behavior with different types of sources. For automatic sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration), we now permanently store all records added, edited or disabled using the API. Such edits are preserved after customer re-syncs and automatic updates.

For these sources, use the include_edit_histories query parameter when listing subscription events to fetch both the original values imported from the billing system and the edited values. The with_disabled query parameter allows you to include disabled records in the response.

For other automatic sources, edits done via the API may be overwritten during customer re-syncs or automatic updates.

For custom sources, edits are not stored separately from the original data.

Query parameters

external_id string optional
External ID of a subscription event.
customer_external_id string optional
A unique identifier specified by you for the customer. Typically an identifier from your internal system. Accepts alphanumeric characters.
data_source_uuid string optional
The ChartMogul unique identifier for the data source.
subscription_external_id string optional
A unique identifier for a subscription.
event_type string optional
The subscription event type.
event_date datetime optional
The date and time when this event was raised. Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. Lists subscription events with the exact date and time of the event date.
effective_date datetime optional
The date and time when this event takes effect. Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. Lists subscription events with the exact date and time of the effective date.
plan_external_id string optional
A unique identifier specified for the plan.
include_edit_historiesboolean optional default: false
Specifies whether the response should contain the edit_history_summary object with a summary of edits. This object is empty for subscription events in sources not supporting data editing.
with_disabledboolean optional default: false
Specifies whether the response should contain disabled subscription events.
cursor string optional
A value that fetches the next page of subscription events. To fetch the next page of subscription events, set cursor to the value received in the previous page response.
per_page int32 optional default: 200
A limit on the number of subscription events to return per page. The default and maximum value is 200.
next_key int32 optional deprecated
Used for paginating to the next page of subscription events if there is more than one page of subscription events for a given query.
prev_key int32 optional deprecated
Used for paginating to the previous page of subscription events if there is more than one page of subscription events for a given query.

Response

The response contains an array of subscription event objects:

id

The unique identifier for the subscription event generated by ChartMogul.

data_source_uuid

The unique identifier for the source where the subscription event has been added, generated by ChartMogul.

customer_external_id

The unique identifier for the customer associated with this subscription event. Typically an identifier from your internal system.

subscription_set_external_id

A reference identifier for a set of subscriptions used to group several subscriptions into one set. Returns null if no subscription set is associated.

subscription_external_id

The unique identifier for the subscription to which the subscription event has been added. Typically an identifier from your internal system.

plan_external_id

The unique identifier for the plan associated with this subscription event. Typically an identifier from your internal system.

event_date

The date and time when this event was raised as an ISO 8601-formatted string.

effective_date

The date and time when this event takes effect as an ISO 8601-formatted string.

event_type

The type of subscription event that was created. One of: subscription_start, subscription_start_scheduled, scheduled_subscription_start_retracted, subscription_cancelled, subscription_cancellation_scheduled, scheduled_subscription_cancellation_retracted, subscription_updated, subscription_update_scheduled, scheduled_subscription_update_retracted or subscription_event_retracted.

external_id

The unique identifier for the subscription event specified in the request.

errors

An object containing any validation errors that occurred during the creation of the subscription event.

created_at

The date and time when the subscription event was created in ChartMogul as an ISO 8601-formatted string.

updated_at

The date and time when the subscription event was last updated in ChartMogul as an ISO 8601-formatted string.

quantity

The quantity of subscriptions associated with this subscription event.

currency

The three-letter currency code of the currency in which this subscription is being billed.

amount_in_cents

The final amount charged towards this subscription, after discounts, taxes and fees have been applied, expressed in cents.

tax_amount_in_cents

The tax amount in cents that has been applied to the subscription addressed by this subscription event.

event_order

The order in which simultaneous events for a subscription are processed. Returns null if no specific order was specified.

retracted_event_id

The event ID of the scheduled subscription event that is being retracted. Returns null for non-retraction events.

disabled

A boolean stating whether or not the subscription event was disabled.

disabled_by

The email address of the user who disabled the subscription event (null for non-disabled records).

disabled_at

The date and time when the subscription event was disabled (null for non-disabled records).

user_created

A boolean stating whether or not the subscription event was created by the user for sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration).

edit_history_summary

A summary of edits made to the subscription event, available when you set the include_edit_histories query parameter to true. The object is empty if the subscription events belong to a source not supporting data edits.

The summary contains the following properties:

values_changed
The object with the list of edited or added peroperties. Each property that has been edited or added is represented as an object with its original_value and edited_value.
latest_edit_author
The email address of the user who made the most recent edit to the invoice.
latest_edit_performed_at
The timestamp when the most recent edit was made, in ISO 8601 format.