Create a Subscription Event

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

Creates a subscription_event object for the specified data_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
}>

Body parameters

data_source_uuid string required

The ChartMogul unique identifier for the data source where the subscription event is being added.

customer_external_id string required

A unique identifier specified by you 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 specified by you for the subscription which the subscription event is being added. Typically an identifier from your internal system. Accepts alphanumeric characters.

plan_external_id string

A unique identifier specified by you for the plan. Typically an identifier from your internal system. Accepts alphanumeric characters. Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.

currency string

The 3-letter currency code of the currency in which this subscription is being billed, e.g. USD, EUR, GBP. You can refer to our full list of supported currencies. Required for subscription_start, subscription_start_scheduled, subscription_updated and subscription_update_scheduled event types.

amount_in_cents 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 and subscription_update_scheduled event types.

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

A reference identifier for a set of subscriptions in order to group several subscriptions into one set.

tax_amount_in_cents integer default: 0

The tax in cents that has been applied to subscription addressed by this subscription event. Defaults to 0.

retracted_event_id string

Required for subscription_event_retracted event type. Refers to the event id of the scheduled subscription event that is being retracted.

external_id string

A unique identifier specified by you for the subscription event. Typically an identifier from your internal system. Accepts alphanumeric characters.

event_order integer

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.

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.