> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reorderjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Activity Log

> Read the global subscription activity log or the per-subscription event timeline — with filtering, sorting, and full state-diff payloads.

The activity log endpoints give you a tamper-evident audit trail for all subscription lifecycle events. You can query the global log for DataTable views, fetch the full state-diff payload for a single event, or retrieve the ordered timeline scoped to one subscription. All routes are read-only, require an authenticated Medusa Admin user, and default to `created_at desc` ordering.

<Info>All routes require an authenticated Medusa Admin user. Unauthenticated requests return `401`.</Info>

## Actor type values

| Value       | Meaning                                      |
| ----------- | -------------------------------------------- |
| `user`      | Medusa Admin user                            |
| `customer`  | Storefront customer who triggered the action |
| `system`    | Internal system action                       |
| `scheduler` | Scheduled job                                |

## Event type groups

Events are namespaced by domain: `subscription.*`, `renewal.*`, `dunning.*`, `cancellation.*`.

The `subscription.*` group includes the initial `subscription.created` event written when a subscription is first created through storefront checkout.

***

## GET /admin/subscription-logs

Returns the paginated global activity log for Admin DataTable views.

### Query parameters

<ParamField query="limit" type="number">
  Number of results per page.
</ParamField>

<ParamField query="offset" type="number">
  Zero-based result offset for pagination.
</ParamField>

<ParamField query="q" type="string">
  Free-text search.
</ParamField>

<ParamField query="order" type="string">
  Field to sort by. Database-backed: `created_at`, `event_type`, `actor_type`. In-memory: `subscription_reference`, `customer_name`, `reason`.
</ParamField>

<ParamField query="direction" type="string">
  Sort direction. One of `asc` or `desc`. Defaults to `desc`.
</ParamField>

<ParamField query="subscription_id" type="string">
  Filter to events for a specific subscription.
</ParamField>

<ParamField query="customer_id" type="string">
  Filter to events for a specific customer.
</ParamField>

<ParamField query="event_type" type="string | string[]">
  Filter by event type. Accepts a single value or an array.
</ParamField>

<ParamField query="actor_type" type="string | string[]">
  Filter by actor type. Accepts a single value or an array.
</ParamField>

<ParamField query="date_from" type="string">
  ISO datetime lower bound for `created_at`.
</ParamField>

<ParamField query="date_to" type="string">
  ISO datetime upper bound for `created_at`.
</ParamField>

### Response

<ResponseField name="subscription_logs" type="object[]" required>
  Array of activity log list items.

  <Expandable title="log item properties">
    <ResponseField name="id" type="string">Log record ID.</ResponseField>
    <ResponseField name="subscription_id" type="string">ID of the linked subscription.</ResponseField>
    <ResponseField name="event_type" type="string">Namespaced event type (e.g. `subscription.paused` or `subscription.created`).</ResponseField>
    <ResponseField name="actor_type" type="string">Type of actor that triggered the event.</ResponseField>
    <ResponseField name="actor_id" type="string | null">Raw actor ID, or `null` for system/scheduler actors.</ResponseField>
    <ResponseField name="actor" type="object">Enriched actor summary with `type`, `id`, `email`, `name`, and `display`.</ResponseField>
    <ResponseField name="subscription" type="object">Subscription summary with reference, customer name, product info, and variant title.</ResponseField>
    <ResponseField name="reason" type="string | null">Reason recorded with the event, or `null`.</ResponseField>
    <ResponseField name="change_summary" type="string">Comma-separated list of changed field names.</ResponseField>
    <ResponseField name="created_at" type="string">Event timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number" required>Total matching records.</ResponseField>
<ResponseField name="limit" type="number" required>Page size used.</ResponseField>
<ResponseField name="offset" type="number" required>Result offset used.</ResponseField>

```json Response example theme={null}
{
  "subscription_logs": [
    {
      "id": "slog_123",
      "subscription_id": "sub_123",
      "event_type": "subscription.created",
      "actor_type": "customer",
      "actor_id": "cus_123",
      "actor": {
        "type": "customer",
        "id": "cus_123",
        "email": null,
        "name": "Jane Doe",
        "display": "Jane Doe"
      },
      "subscription": {
        "subscription_id": "sub_123",
        "reference": "SUB-001",
        "customer_id": "cus_123",
        "customer_name": "Jane Doe",
        "product_title": "Coffee Subscription",
        "variant_title": "1 kg"
      },
      "reason": null,
      "change_summary": "subscription_created",
      "created_at": "2026-04-15T10:00:00.000Z"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}
```

### Errors

| Code  | Error          | Meaning                                                 |
| ----- | -------------- | ------------------------------------------------------- |
| `400` | `invalid_data` | Invalid query parameter shape or unsupported sort field |

***

## GET /admin/subscription-logs/:id

Returns the full detail payload for a single activity log event, including the previous state, new state, and a field-level diff.

### Path parameters

<ParamField path="id" type="string" required>
  Activity log record ID.
</ParamField>

### Response

Returns a `subscription_log` object with all list fields plus:

<ResponseField name="subscription_log" type="object" required>
  <Expandable title="additional detail fields">
    <ResponseField name="previous_state" type="object | null">State snapshot before the event.</ResponseField>
    <ResponseField name="new_state" type="object | null">State snapshot after the event.</ResponseField>
    <ResponseField name="changed_fields" type="object[]">Field-level diff. Each entry has `field`, `before`, and `after`.</ResponseField>
    <ResponseField name="metadata" type="object | null">Event-specific metadata (e.g. linked `renewal_cycle_id` or `order_id`).</ResponseField>
  </Expandable>
</ResponseField>

```json Response example theme={null}
{
  "subscription_log": {
    "id": "slog_123",
    "subscription_id": "sub_123",
    "event_type": "renewal.succeeded",
    "actor_type": "scheduler",
    "actor_id": null,
    "actor": {
      "type": "scheduler",
      "id": null,
      "email": null,
      "name": null,
      "display": null
    },
    "subscription": {
      "subscription_id": "sub_123",
      "reference": "SUB-001",
      "customer_id": "cus_123",
      "customer_name": "Jane Doe",
      "product_title": "Coffee Subscription",
      "variant_title": "1 kg"
    },
    "reason": null,
    "change_summary": "status, processed_at",
    "created_at": "2026-04-15T10:03:00.000Z",
    "previous_state": {
      "status": "scheduled"
    },
    "new_state": {
      "status": "succeeded"
    },
    "changed_fields": [
      {
        "field": "status",
        "before": "scheduled",
        "after": "succeeded"
      }
    ],
    "metadata": {
      "renewal_cycle_id": "re_123",
      "order_id": "order_123"
    }
  }
}
```

### Errors

| Code  | Error       | Meaning                            |
| ----- | ----------- | ---------------------------------- |
| `404` | `not_found` | Activity log record does not exist |

***

## GET /admin/subscriptions/:id/logs

Returns the paginated activity log timeline scoped to a single subscription. Accepts the same query parameters as the global list and applies `subscription_id = :id` automatically.

### Path parameters

<ParamField path="id" type="string" required>
  Subscription ID.
</ParamField>

### Query parameters

Same as `GET /admin/subscription-logs`. Default sort is `created_at desc`.

### Response

Same shape as `GET /admin/subscription-logs`.

```json Response example theme={null}
{
  "subscription_logs": [
    {
      "id": "slog_123",
      "subscription_id": "sub_123",
      "event_type": "subscription.paused",
      "actor_type": "user",
      "actor_id": "user_123",
      "actor": {
        "type": "user",
        "id": "user_123",
        "email": "admin@example.com",
        "name": "Admin User",
        "display": "admin@example.com"
      },
      "subscription": {
        "subscription_id": "sub_123",
        "reference": "SUB-001",
        "customer_id": "cus_123",
        "customer_name": "Jane Doe",
        "product_title": "Coffee Subscription",
        "variant_title": "1 kg"
      },
      "reason": "customer requested pause",
      "change_summary": "status, paused_at",
      "created_at": "2026-04-15T10:00:00.000Z"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}
```