Update a Subscription Event

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

Updates an existing subscription event.

curl -X PATCH "https://api.chartmogul.com/v1/subscription_events" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "subscription_event":
              {
                "external_id": "evnt_001",
                "data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
                "effective_date":"2022-04-30",
                "currency":"USD",
                "amount_in_cents":"100"
              }
        }'
ChartMogul::SubscriptionEvent.new.update!(
  external_id: "evnt_001",
  data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
  effective_date: "2022-04-30",
  currency: "USD",
  amount_in_cents: 100,
)
ChartMogul.SubscriptionEvent.updateWithParams(config, {
  subscription_event: {
    external_id: "evnt_001",
    data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
    effective_date: "2022-04-30",
    currency: "USD",
    amount_in_cents: 100,
  },
});
ChartMogul\SubscriptionEvent::updateWithParams([
  "subscription_event" => [
    "external_id" => "evnt_001",
    "data_source_uuid" => "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
    "effective_date" => "2022-04-30",
    "currency" => "USD",
    "amount_in_cents" => "100"
  ]
]);
api.UpdateSubscriptionEvent(&cm.SubscriptionEvent{
  ExternalID:     "evnt_001",
  DataSourceUUID: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
  EffectiveDate:  "2022-04-30",
  Currency:       "USD",
  AmountInCents:  100,
})
chartmogul.SubscriptionEvent.modify_with_params(
  config,
  data={
    "subscription_event": {
      "external_id": "evnt_001",
      "data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
      "effective_date": "2022-04-30",
      "currency": "USD",
      "amount_in_cents": 100,
    }
  },
)
{
  "id": 23223966,
  "data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
  "customer_external_id": "scus_001",
  "subscription_set_external_id": null,
  "subscription_external_id": "sub_0001",
  "plan_external_id": "gold_monthly",
  "event_date": "2022-03-30T00:00:00Z",
  "effective_date": "2022-04-30T00:00:00Z",
  "event_type": "subscription_start_scheduled",
  "external_id": "evnt_001",
  "errors": {},
  "created_at": "2022-03-31T14:30:48Z",
  "updated_at": "2022-04-12T09:58:06Z",
  "quantity": 1,
  "currency": "USD",
  "amount_in_cents": "100",
  "tax_amount_in_cents": 0,
  "event_order": 100,
  "retracted_event_id": null
}
<ChartMogul::SubscriptionEvent:0x00000001313bf858
  @data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba", 
  @customer_external_id="scus_001", 
  @subscription_set_external_id="", 
  @subscription_external_id="sub_0001", 
  @plan_external_id="gold_monthly", 
  @event_date="2022-03-30T00:00:00Z", 
  @effective_date="2022-04-30T00:00:00Z", 
  @event_type="subscription_start_scheduled", 
  @external_id="evnt_001", 
  @quantity=1, 
  @currency="USD", 
  @amount_in_cents="100",
  @id=23223966, 
  @errors={}, 
  @created_at="2022-03-31T11:42:18Z", 
  @updated_at="2022-04-12T09:58:06Z", 
  @tax_amount_in_cents=nil,
  @retracted_event_id=nil
>
{
  id: 23223966,
  data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
  customer_external_id: "scus_001",
  subscription_set_external_id: null,
  subscription_external_id: "sub_0001",
  plan_external_id: "gold_monthly",
  event_date: "2022-03-30T00:00:00Z",
  effective_date: "2022-04-30T00:00:00Z",
  event_type: "subscription_start_scheduled",
  external_id: "evnt_001",
  errors: {},
  created_at: "2022-03-31T14:30:48Z",
  updated_at: "2022-04-12T09:58:06Z",
  quantity: 1,
  currency: "USD",
  amount_in_cents: "100",
  tax_amount_in_cents: 0,
  event_order: 100,
  retracted_event_id: null
}
ChartMogul\SubscriptionEvent::__set_state(array(
  "id" => 23223966,
  "data_source_uuid" => "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
  "customer_external_id" => "scus_001",
  "subscription_set_external_id" => NULL,
  "subscription_external_id" => "sub_0001",
  "plan_external_id" => "gold_monthly",
  "event_date" => "2022-03-30T00:00:00Z",
  "effective_date" => "2022-04-30T00:00:00Z",
  "event_type" => "subscription_start_scheduled",
  "external_id" => "evnt_001",
  "errors" => array(),
  "created_at" => "2022-03-31T11:42:18Z",
  "updated_at" => "2022-04-12T09:58:06Z",
  "quantity" => 1,
  "currency" => "USD",
  "amount_in_cents" => "100",
  "tax_amount_in_cents" => 0,
  "event_order" => 100,
  "retracted_event_id" => NULL
));
(*chartmogul.SubscriptionEvent)(0xc03201e5a1)({
  ID: (uint64) 23223966,
  DataSourceUUID: (string) (len=39) "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
  CustomerExternalID: (string) (len=8) "scus_001",
  SubscriptionSetExternalID: (string) "",
  SubscriptionExternalID: (string) (len=8) "sub_0001",
  PlanExternalID: (string) (len=12) "gold_monthly",
  EventDate: (string) (len=20) "2022-03-30T00:00:00Z",
  EffectiveDate: (string) (len=20) "2022-04-30T00:00:00Z",
  EventType: (string) (len=28) "subscription_start_scheduled",
  ExternalID: (string) (len=8) "evnt_001",
  Errors: (interface{}) {},
  CreatedAt: (string) (len=20) "2022-03-31T11:42:18Z",
  UpdatedAt: (string) (len=20) "2022-04-12T09:58:06Z",
  Quantity: (int32) 1,
  Currency: (string) (len=3) "USD",
  AmountInCents: (int32) 100,
  TaxAmountInCents: (int32) 0,
  EventOrder: (int32)100,
  RetractedEventId: (string) ""
})
<SubscriptionEvent{
  data_source_uuid="ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba", 
  customer_external_id="scus_001", 
  subscription_set_external_id="", 
  subscription_external_id="sub_0001", 
  plan_external_id="gold_monthly", 
  event_date="2022-03-30T00:00:00Z", 
  effective_date="2022-04-30T00:00:00Z", 
  event_type="subscription_start_scheduled", 
  external_id="evnt_001", 
  quantity=1, 
  currency="USD", 
  amount_in_cents="100",
  id=23223966, 
  errors={}, 
  created_at="2022-03-31T11:42:18Z", 
  updated_at="2022-04-12T09:58:06Z", 
  tax_amount_in_cents=None,
  event_order=100,
  retracted_event_id=None
}>

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.

Body parameters

To update a subscription event, the required parameters are either:

external_id string optional required
A unique identifier specified by you for the subscription event. Typically an identifier from your internal system. Accepts alphanumeric characters.
data_source_uuid string optional required
The ChartMogul unique identifier for the source where the subscription event is being added.
id integer optional required
The ChartMogul UUID of a subscription event.
customer_external_id string optional
A unique identifier specified by you for the customer.
event_type string optional
One of the seven subscription event types. See event types table on Create a Subscription Event
event_date string optional default: "00:00:00"
The date and time when this event was raised. Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
effective_date string optional default: "00:00:00"
The date and time when this event takes effect. Must be an ISO 8601-formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.
subscription_external_id string optional
A unique identifier specified by you for subscription for which the subscription event is being updated. Typically an identifier from your internal system.
plan_external_id string optional
A unique identifier specified by you for the plan.
currency string optional
The three-letter currency code of the currency in which this invoice is being billed, e.g. USD, EUR, GBP. Refer to the full list of supported currencies. Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.
amount_in_cents integer optional
The final amount charged towards this subscription on subscription start or subscription update, for the specified quantity and service period, after discounts, taxes and fees have been applied. Expected in cents (or pence for GBP, etc.). Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.
quantity integer optional default: 1
The quantity of subscription addressed by this subscription event. Can be any non-zero integer. Defaults to 1. Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.
subscription_set_external_id string optional
A reference identifier for a set of subscriptions in order to group several subscriptions into one set.
tax_amount_in_cents integer optional default: 0
The tax in cents that has been applied to subscription addressed by this subscription event. Defaults to 0.
retracted_event_id string optional
Required for retracted subscription event. Refers to an external_id of the subscription event that is getting retracted. Required for subscription_event_retracted event type.
event_order integer optional
Order in which simultaneous events for a subscription will be processed. Subscription Line Items and Subscription Events with event_order are ordered in ascending order. If not provided, it defaults to null and gets ordered as the last event for the subscription among other simultaneous events.

Response

The response contains the subscription event object:

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_at
The date and time when the subscription event was disabled (null for non-disabled records).
disabled_by
The email address of the user who disabled the subscription event (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).