subscription_event

Description

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).

Interact with this resource

To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.

Actions

GET
View a subscription_event
HEAD
Get just the header response
OPTIONS
Get a response explaining which HTTP methods are supported

Properties

Property Description Type Constraints
event_type The primary classification of this event. See the full list of event types below. String Read only. One of: created, billing_success, billing_failed, cancelled, reactivated, modified, past_due_updated, dunning_email_sent, dunning_reattempt, auto_cancelled
event_source Who or what initiated this event. Uses the MIT/CIT naming convention to distinguish merchant-initiated from customer-initiated actions. String Read only. Examples: mit_system, mit_admin, mit_api, mit_dunning, mit_recurring, cit_checkout, cit_customer_portal
changes 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. Object (JSON) Read only. Null for event types that do not involve a diff. Example: {"frequency": {"before": "1m", "after": "3m"}}
error_message The gateway or processor error message for billing_failed events. Truncated to 500 characters. String Read only. Null for non-failure events.
details Additional event-specific context as a JSON object. Contents vary by event type. Examples: dunning step number, cancellation reason, invoice status, email type sent. Object (JSON) Read only. Null if no additional context.
date_created The date and time this event was recorded. DateTime Read only.

Event Types Reference

event_type Description Typical event_source
createdA new subscription was created from a checkout transaction.cit_checkout
billing_successA scheduled or reattempt billing was successful.mit_recurring, mit_dunning, mit_admin
billing_failedA scheduled or reattempt billing failed. Includes error_message.mit_recurring, mit_dunning, mit_admin
cancelledThe subscription was cancelled by a customer or admin.cit_customer_portal, mit_admin, mit_api
reactivatedA previously cancelled subscription was reactivated.mit_admin, mit_api
modifiedOne or more subscription fields were updated (frequency, dates, etc.). Changes are in the changes field.mit_admin, mit_api
past_due_updatedThe subscription's past-due amount changed. Changes show before/after values.mit_system, mit_recurring, mit_admin
dunning_email_sentA dunning reminder email was sent to the customer. Details include failed_days and email_type.mit_dunning
dunning_reattemptAn automated billing reattempt was triggered by the dunning schedule. Details include failed_days.mit_dunning
auto_cancelledThe subscription was automatically cancelled by the dunning system after the cancellation schedule was exhausted.mit_dunning

Example Representation

{
  "_links": {
    "curies": [
        {
            "name": "fx",
            "href": "https://api.foxycart.com/rels/{rel}",
            "templated": true
        }
    ],
    "self": {
      "href": "https://api.foxycart.com/subscription_events/12345",
      "title": "This Subscription Event"
    },
    "fx:store": {
      "href": "https://api.foxycart.com/stores/8",
      "title": "This Store"
    },
    "fx:subscription": {
      "href": "https://api.foxycart.com/subscriptions/99",
      "title": "This Subscription"
    },
    "fx:customer": {
      "href": "https://api.foxycart.com/customers/500",
      "title": "This Customer"
    },
    "fx:transaction": {
      "href": "https://api.foxycart.com/transactions/1000000",
      "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"
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api.foxycart.com/subscription_events/12345" rel="https://api.foxycart.com/rels/subscription_event">
  <link rel="self" href="https://api.foxycart.com/subscription_events/12345" title="This Subscription Event"/>
  <link rel="https://api.foxycart.com/rels/store" href="https://api.foxycart.com/stores/8" title="This Store"/>
  <link rel="https://api.foxycart.com/rels/subscription" href="https://api.foxycart.com/subscriptions/99" title="This Subscription"/>
  <link rel="https://api.foxycart.com/rels/customer" href="https://api.foxycart.com/customers/500" title="This Customer"/>
  <link rel="https://api.foxycart.com/rels/transaction" href="https://api.foxycart.com/transactions/1000000" title="Related Transaction"/>
  <event_type>billing_failed</event_type>
  <event_source>mit_recurring</event_source>
  <error_message>Subscription Transaction Failed: Card declined.</error_message>
  <date_created>2026-03-01T08:00:00-0700</date_created>
</resource>

{
    "class": [
        "subscription_event"
    ],
    "properties": {
        "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"
    },
    "links": [
        {
            "rel": ["self"],
            "href": "https://api.foxycart.com/subscription_events/12345"
        },
        {
            "rel": ["https://api.foxycart.com/rels/subscription"],
            "href": "https://api.foxycart.com/subscriptions/99"
        }
    ]
}

Zoomable Resources

This resource has no linked resources which can be "zoomed" in on, filtered and embedded within this resource.