Create a Subscription Event
POST https://api.chartmogul.com/v1/subscription_events
Creates a subscription event for the specified source and customer.
curl -X POST "https://api.chartmogul.com/v1/subscription_events" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"subscription_event":
{
"external_id": "evnt_001",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"event_type": "subscription_start_scheduled",
"event_date": "2022-03-30",
"effective_date":"2022-04-01",
"subscription_external_id":"sub_0001",
"event_order":100,
"plan_external_id":"gold_monthly",
"currency":"USD",
"amount_in_cents":"1000",
"quantity":1
}
}'
ChartMogul::SubscriptionEvent.create!(
amount_in_cents: "1000",
currency: "USD",
customer_external_id: "cus_0001",
data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
effective_date: "2022-04-01",
event_date: "2022-03-30",
event_type: "subscription_start_scheduled",
external_id: "evnt_001",
plan_external_id: "gold_monthly",
subscription_external_id: "sub_0001",
event_order: 100,
quantity: 1,
)
ChartMogul.SubscriptionEvent.create(config, {
subscription_event: {
amount_in_cents: "1000",
currency: "USD",
customer_external_id: "cus_0001",
data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
effective_date: "2022-04-01",
event_date: "2022-03-30",
event_type: "subscription_start_scheduled",
external_id: "evnt_001",
plan_external_id: "gold_monthly",
subscription_external_id: "sub_0001",
event_order: 100,
quantity: 1,
},
});
ChartMogul\SubscriptionEvent::create([
"subscription_event" => [
"amount_in_cents" => 1000,
"currency" => "USD",
"customer_external_id" => "cus_0001",
"data_source_uuid" => "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"effective_date" => "2022-04-01",
"event_date" => "2022-03-30",
"event_type" => "subscription_start_scheduled",
"external_id" => "evnt_001",
"plan_external_id" => "plan_0001",
"quantity" => 1,
"subscription_external_id" => "sub_0001",
"event_order" => 100
]
]);
api.CreateSubscriptionEvent(&cm.SubscriptionEvent{
AmountInCents: 1000,
Currency: "USD",
CustomerExternalID: "cus_0001",
DataSourceUUID: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
EffectiveDate: "2022-04-01",
EventDate: "2022-03-30",
EventType: "subscription_start_scheduled",
ExternalID: "evnt_001",
PlanExternalID: "gold_monthly",
Quantity: 1,
SubscriptionExternalID: "sub_0001",
EventOrder: 100,
})
chartmogul.SubscriptionEvent.create(
config,
data={
"subscription_event": {
"amount_in_cents": 1000,
"currency": "USD",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"effective_date": "2022-04-01",
"event_date": "2022-03-30",
"event_type": "subscription_start_scheduled",
"external_id": "evnt_001",
"plan_external_id": "gold_monthly",
"quantity": 1,
"subscription_external_id": "sub_0001",
"event_order": 100,
}
},
)
{
"id": 23223966,
"data_source_uuid": "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
"customer_external_id": "cus_0001",
"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-01T00:00:00Z",
"event_type": "subscription_start_scheduled",
"external_id": "evnt_001",
"errors": {},
"created_at": "2022-03-31T11:42:18Z",
"updated_at": "2022-03-31T11:42:18Z",
"quantity": 1,
"currency": "USD",
"amount_in_cents": "1000",
"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="cus_0001",
@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-01T00:00:00Z",
@event_type="subscription_start_scheduled",
@external_id="evnt_001",
@quantity=1,
@currency="USD",
@amount_in_cents="1000",
@id=23223966,
@errors={},
@created_at="2022-03-31T11:42:18Z",
@updated_at="2022-03-31T11:42:18Z",
@tax_amount_in_cents=nil,
@retracted_event_id=nil
>
{
id: 23223966,
data_source_uuid: "ds_1fm3eaac-62d0-31ec-clf4-4bf0mbe81aba",
customer_external_id: "cus_0001",
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-01T00:00:00Z",
event_type: "subscription_start_scheduled",
external_id: "evnt_001",
errors: {},
created_at: "2022-03-31T11:42:18Z",
updated_at: "2022-03-31T11:42:18Z",
quantity: 1,
currency: "USD",
amount_in_cents: "1000",
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" => "cus_0001",
"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-01T00:00:00Z",
"event_type" => "subscription_start_scheduled",
"external_id" => "evnt_001",
"errors" => array(),
"created_at" => "2022-03-31T11:42:18Z",
"updated_at" => "2022-03-31T11:42:18Z",
"quantity" => 1,
"currency" => "USD",
"amount_in_cents" => "1000",
"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) "cus_0001",
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-01T00: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-03-31T11:42:18Z",
Quantity: (int32) 1,
Currency: (string) (len=3) "USD",
AmountInCents: (int32) 1000,
TaxAmountInCents: (int32) 0,
EventOrder: (int32) 100,
RetractedEventId: (string) ""
})
<SubscriptionEvent{
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-03-30T00:00:00Z",
effective_date="2022-04-01T00:00:00Z",
event_type="subscription_start_scheduled",
external_id="evnt_001",
quantity=1,
currency="USD",
amount_in_cents="1000",
id=23223966,
errors={},
created_at="2022-03-31T11:42:18Z",
updated_at="2022-03-31T11:42:18Z",
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.
External ID requirement. When creating a subscription event in sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration), you must provide an external ID. For these sources, we now permanently store edits made using the API and need this information to associate the edits with the edited record.
Body parameters
data_source_uuid
string required-
The ChartMogul unique identifier for the source where the subscription event is being added.
customer_external_id
string required-
A unique identifier for the customer. Typically an identifier from your internal system. Accepts alphanumeric characters.
event_type
string required-
One of the ten subscription event types. See below for details.
subscription_start
- Event type that should be sent when a subscription begins immediately before an invoice is generated. This invoice will be generated at the start of the next billing cycle.
subscription_start_scheduled
- Event type that should be sent when a subscription is scheduled to start on a future date.
scheduled_subscription_start_retracted
- Event type that should be sent when a scheduled start to a new subscription is subsequently withdrawn.
subscription_cancelled
- Event type that should be sent when a subscription gets canceled.
subscription_cancellation_scheduled
- Event type that should be sent when a subscription cancellation is scheduled for a future date.
scheduled_subscription_cancellation_retracted
- Event type that should be sent when a scheduled cancellation to a subscription is subsequently withdrawn.
subscription_updated
- Event type that should be sent when a subscription is upgraded or downgraded and the change is effective immediately before an invoice is generated. This invoice will be generated at the start of the next billing cycle.
subscription_update_scheduled
- Event type that should be sent when an update of an existing subscription is scheduled for a future date.
scheduled_subscription_update_retracted
- Event type that should be sent when a scheduled update (e.g., upgrade or downgrade) to a subscription is subsequently withdrawn.
subscription_event_retracted
- Event type that should be sent when a scheduled event is retracted before it takes effect on the subscription. In this case, the request should have the external id of the corresponding scheduled event in the request.
event_date
string required-
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 required-
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 required-
A unique identifier for the subscription to which you’re adding the subscription event. Typically an identifier from your internal system. Accepts alphanumeric characters.
plan_external_id
string optional-
A unique identifier for the plan. Typically an identifier from your internal system. Accepts alphanumeric characters. Required for
subscription_start
,subscription_start_scheduled
,subscription_updated
andsubscription_update_scheduled
event types. currency
string optional-
The three-letter currency code of the currency in which this subscription 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
andsubscription_update_scheduled
event types. amount_in_cents
optional integer-
The final amount charged towards this subscription on subscription start or subscription update, for the specified quantity and plan, 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
andsubscription_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
andsubscription_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
subscription_event_retracted
event type. Refers to the event id of the scheduled subscription event that is being retracted. external_id
string optional-
A unique identifier for the subscription event. Typically an identifier from your internal system. Accepts alphanumeric characters. Required for sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration).
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 tonull
and gets ordered as the last event for the subscription among other simultaneous events.
Retraction event types. Not all retraction event types behave in the same way:
The subscription_event_retracted
type requires a retracted_event_id
and retracts a specific scheduled event of this ID.
The remaining types (i.e. scheduled_subscription_start_retracted
, scheduled_subscription_cancellation_retracted
and scheduled_subscription_update_retracted
) retract a scheduled event based on its subscription_external_id
or subscription_set_external_id
. To be retracted, an event needs to be of the same type and match either the subscription external ID or the subscription set external ID. The event’s effective date must come before the retraction effective date.
Response
The response object contains the following data:
id
- A unique identifier for the subscription event generated by ChartMogul.
data_source_uuid
- A unique identifier for the source where the subscription event has been added, generated by ChartMogul.
customer_external_id
- A 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
- A unique identifier for the subscription to which the subscription event has been added. Typically an identifier from your internal system.
plan_external_id
- A 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
orsubscription_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.