subscription_event

Collection: subscription_events

A subscription event is a structured audit log entry for a subscription lifecycle action. Every significant event that happens to a subscription — billing attempts, cancellations, reactivations, past-due changes, dunning emails, etc. — is recorded as a subscription event. Events are read-only; they are created automatically by the system.

Subscription events can be retrieved individually by ID, or as a collection scoped to a subscription (/subscriptions/{id}/subscription_events) or a store (/stores/{id}/subscription_events).

Event Types

event_type	Description	Typical event_source
`created`	A new subscription was created from a checkout transaction.	cit_checkout
`billing_success`	A scheduled or reattempt billing was successful.	mit_recurring, mit_dunning, mit_admin
`billing_failed`	A scheduled or reattempt billing failed. Includes error_message.	mit_recurring, mit_dunning, mit_admin
`cancelled`	The subscription was cancelled by a customer or admin.	cit_customer_portal, mit_admin, mit_api
`reactivated`	A previously cancelled subscription was reactivated.	mit_admin, mit_api
`modified`	One or more subscription fields were updated (frequency, dates, etc.). Changes are in the `changes` field.	mit_admin, mit_api
`past_due_updated`	The subscription's past-due amount changed. Changes show before/after values.	mit_system, mit_recurring, mit_admin
`dunning_email_sent`	A dunning reminder email was sent to the customer. Details include `failed_days` and `email_type`.	mit_dunning
`dunning_reattempt`	An automated billing reattempt was triggered by the dunning schedule. Details include `failed_days`.	mit_dunning
`auto_cancelled`	The subscription was automatically cancelled by the dunning system after the cancellation schedule was exhausted.	mit_dunning

Required Scopes

Full store_full_access

Read subscriptions_read

Write subscriptions_write

Actions

GET View a subscription event

HEAD Get just the header response

OPTIONS Get a response explaining which HTTP methods are supported

Properties (6)

event_type String · Read-only

The primary classification of this event. See the full list of event types above.

createdbilling_successbilling_failedcancelledreactivatedmodifiedpast_due_updateddunning_email_sentdunning_reattemptauto_cancelled

event_source String · Read-only

Who or what initiated this event. Uses the MIT/CIT naming convention to distinguish merchant-initiated from customer-initiated actions.

Examples: mit_system, mit_admin, mit_api, mit_dunning, mit_recurring, cit_checkout, cit_customer_portal.

changes Object (JSON) · Read-only

A structured JSON diff of what changed on the subscription for modified and past_due_updated events. Only keys that actually changed are included. Each key contains a before and after value.

Null for event types that do not involve a diff. Example: {"frequency": {"before": "1m", "after": "3m"}}

error_message String · Read-only · max 500

The gateway or processor error message for billing_failed events. Truncated to 500 characters.

Null for non-failure events.

details Object (JSON) · Read-only

Additional event-specific context as a JSON object. Contents vary by event type. Examples: dunning step number, cancellation reason, invoice status, email type sent.

Null if no additional context.

date_created DateTime · Read-only

The date and time this event was recorded.

Link Relations (5)

self This Subscription Event

fx:store GET PATCH PUT DELETE This Store

fx:subscription GET PATCH PUT This Subscription

fx:customer GET PATCH PUT DELETE This Customer

fx:transaction GET PATCH PUT POST Related Transaction

https://api.foxycart.com/subscription_events/{id}

Example Representation

Show _links

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://api.foxycart.com/subscription_events/123",
      "title": "This Subscription Event"
    },
    "fx:store": {
      "href": "https://api.foxycart.com/stores/456",
      "title": "This Store"
    },
    "fx:subscription": {
      "href": "https://api.foxycart.com/subscriptions/321",
      "title": "This Subscription"
    },
    "fx:customer": {
      "href": "https://api.foxycart.com/customers/789",
      "title": "This Customer"
    },
    "fx:transaction": {
      "href": "https://api.foxycart.com/transactions/999",
      "title": "Related Transaction"
    }
  },
  "event_type": "billing_failed",
  "event_source": "mit_recurring",
  "changes": null,
  "error_message": "Subscription Transaction Failed: Card declined.",
  "details": {
    "order_total": 29.99
  },
  "date_created": "2026-03-01T08:00:00-0700"
}