Reference
Help Center

Create a Subscription Event

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

Creates a subscription_event object for the specified data_source and customer.

Examples

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,
    }
  },
)

Result Format

{
  "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
}>

Subscription Event Types

The table below lists the subscription event types for the event_type attribute.

Subscription Event TypeDescription
subscription_startEvent 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_retractedEvent type that should be sent when a scheduled start to a new subscription is subsequently withdrawn.
subscription_cancelledEvent type that should be sent when a subscription gets canceled.
subscription_cancellation_scheduledEvent type that should be sent when a subscription cancellation is scheduled for a future date.
scheduled_subscription_cancellation_retractedEvent type that should be sent when a scheduled cancellation to a subscription is subsequently withdrawn.
subscription_updatedEvent 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_scheduledEvent type that should be sent when an update of an existing subscription is scheduled for a future date.
scheduled_subscription_update_retractedEvent type that should be sent when a scheduled update (e.g., upgrade or downgrade) to a subscription is subsequently withdrawn.
subscription_event_retractedEvent 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.

📘

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.
Language
Credentials
Basic
base64
: