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

# Webhooks

> Creem webhooks guide: receive real-time payment notifications, handle subscription lifecycle events, and verify webhook signatures securely.

## What is a webhook?

Creem uses webhooks to push real-time notifications to you about your payments and subscriptions. All webhooks use HTTPS and deliver a JSON payload that can be used by your application. You can use webhook feeds to do things like:

* Automatically enable access to a user after a successful payment
* Automatically remove access to a user after a canceled subscription
* Confirm that a payment has been received by the same customer that initiated it.

In case webhooks are not successfully received by your endpoint, Creem automatically retries the request with a progressive backoff. There are 5 attempts in total — the initial delivery, then retries after 30 seconds, 5 minutes, 30 minutes and 6 hours. Events are not retried after 24 hours, even if attempts remain. Creem waits up to 15 seconds for a response, and a slower response counts as a failed attempt. Because the same event can be delivered more than once, your handler should be idempotent. You can also resend webhook events manually from your Merchant dashboard under [Developers section](https://creem.io/dashboard/developers). Automatic retries keep the event `id`, but a manual resend is sent with a new `id` and `created_at`.

## Steps to receive a webhook

You can start receiving real-time events in your app using the steps:

* Create a local endpoint to receive requests
* Register your development webhook endpoint on the Developers tab of the Creem dashboard
* Test that your webhook endpoint is working properly using the test environment
* Deploy your webhook endpoint to production
* Register your production webhook endpoint on Creem live dashboard

> [!NOTE]
>
> On Next.js projects, the [@creem\_io/nextjs adapter](https://docs.creem.io/code/sdks/nextjs.md) exports a
> `Webhook` helper that verifies signatures and surfaces typed lifecycle callbacks. Use it as your
> default implementation before falling back to manual parsing.

### 1. Create a local endpoint to receive requests

In your local application, create a new route that can accept POST requests.

```ts Next.js theme={null}
// app/api/webhook/creem/route.ts
import { Webhook } from "@creem_io/nextjs";

export const POST = Webhook({
  webhookSecret: process.env.CREEM_WEBHOOK_SECRET!,
  onCheckoutCompleted: async ({ customer, product }) => {
    console.log(`${customer.email} purchased ${product.name}`);
  },
  onGrantAccess: async ({ customer, metadata }) => {
    const userId = metadata?.referenceId as string;
    await grantAccess(userId, customer.email);
  },
  onRevokeAccess: async ({ customer, metadata }) => {
    const userId = metadata?.referenceId as string;
    await revokeAccess(userId, customer.email);
  },
});
```

```ts Node.js theme={null}
import type { NextApiRequest, NextApiResponse } from "next";

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== "POST") {
    return res.status(405).end();
  }

  const payload = req.body;
  console.log(payload);
  res.status(200).end();
}
```

On receiving an event, you should respond with an HTTP 200 OK to signal to Creem that the event was successfully delivered. Any 2xx status code counts as delivered.

### 2. Register your development webhook endpoint

The quickest way to receive events locally is the [Creem CLI](https://docs.creem.io/code/cli.md#local-webhooks): it registers a temporary endpoint for you and forwards events to your server with the real signature header, no public URL needed.

```sh theme={null}
creem listen --forward-to http://localhost:3000/api/webhooks
```

Otherwise, register your publicly accessible HTTPS URL in the Creem dashboard.

> [!TIP]
>
> You can create a tunnel to your localhost server using a tool like ngrok. For example:
> [https://8733-191-204-177-89.sa.ngrok.io/api/webhooks](https://8733-191-204-177-89.sa.ngrok.io/api/webhooks)

![](https://nucn5fajkcc6sgrd.public.blob.vercel-storage.com/test-webhook-yBodvIWasxCmgr4bYqZJBlWg8qbUD2.png)

### 3. Test that your webhook endpoint is working properly

Create a few test payments to check that your webhook endpoint is receiving the events.

### 4. Deploy your webhook endpoint

After you're done testing, deploy your webhook endpoint to production.

### 5. Register your production webhook endpoint

Once your webhook endpoint is deployed to production, you can register it in the Creem dashboard.

## Register endpoints programmatically

Every step above can also be done from code, so an integration (or an AI agent) can provision its own endpoint. The public API exposes webhook endpoint management under `/v1/webhooks`; the same operations are available in the TypeScript SDK and the CLI. Keys need the `webhooks:read` or `webhooks:write` scope.

```typescript TypeScript SDK theme={null}
import { Creem } from "creem";

const creem = new Creem({ apiKey: process.env.CREEM_API_KEY });

// The signing secret is returned on create only. Store it, then verify
// every delivery with it (see "Webhook Signatures" below).
const webhook = await creem.webhooks.create({
  url: "https://example.com/webhooks/creem",
  name: "Production billing events",
  events: ["checkout.completed", "subscription.paid"],
});
console.log(webhook.id, webhook.secret);

// Pause deliveries without losing the configuration.
await creem.webhooks.update(webhook.id, { status: "disabled" });

// Fetch the secret again later.
const { secret } = await creem.webhooks.getSecret(webhook.id);
```

```sh CLI theme={null}
creem webhooks create --url https://example.com/webhooks/creem --event checkout.completed --event subscription.paid --json
creem webhooks list --json
creem webhooks update wh_123 --status disabled --json
creem webhooks secret wh_123 --json
creem webhooks delete wh_123 --yes --json
```

An empty `events` list subscribes the endpoint to every event type. See the [Webhooks API reference](https://docs.creem.io/api-reference/endpoint/create-webhook.md) for the full contract.

## Network Configuration

> [!NOTE]
>
> Creem does not provide static source IP addresses for outbound webhooks in either Test Mode or
> production. If your firewall or WAF protects the webhook endpoint, do not rely on source-IP
> allowlists as the authentication mechanism. Keep the endpoint reachable over HTTPS and verify
> every request with the `creem-signature` header.

> [!TIP]
>
> Bot protection and WAF products can challenge webhook deliveries because webhooks are automated
> server-to-server requests. If this happens, add a route-level exception or skip rule for your
> webhook endpoint. On Cloudflare specifically, Bot Fight Mode cannot be skipped with custom rules;
> disable it or use Super Bot Fight Mode or Bot Management with a skip rule.

## Webhook Signatures

### How to verify Creem signature?

Creem signature is sent in the `creem-signature` header of the webhook request. The signature is generated using the HMAC-SHA256 algorithm with the webhook secret as the key, and the request payload as the message.

> [accordion] Sample Webhook Header
>
> ```json theme={null}
> {
> 'creem-signature': 'dd7bdd2cf1f6bac6e171c6c508c157b7cd3cc1fd196394277fb59ba0bdd9b87b'
> }
> ```

Use the TypeScript SDK to verify the signature before processing the event payload.

> [!TIP]
>
> You can find your webhook secret on the Developers>Webhook page.

![](https://nucn5fajkcc6sgrd.public.blob.vercel-storage.com/Screenshot%202024-10-03%20at%2014.26.39-MtSMvooQi4OrZoh9eMyFZngfc0CrQn.png)

```typescript theme={null}
import { verifyWebhookSignature } from "creem/webhooks";

await verifyWebhookSignature(rawBody, request.headers, {
  secret: process.env.CREEM_WEBHOOK_SECRET!,
});
```

If you are not using the SDK, generate the signature with HMAC-SHA256 using the raw request body and compare it with the `creem-signature` header.

```typescript theme={null}
import * as crypto from 'crypto';

  generateSignature(payload: string, secret: string): string {
    const computedSignature = crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
    return computedSignature;
  }
```

In the code snippet above, the `payload` is the request body, and the `secret` is the webhook secret.
Simply compare the generated Signature with the one received on the header to complete the verification process.

## Event Types

List of supported event types and their payloads.

### checkout.completed

A checkout session was completed, returning all the information about the payment and the order created.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_5WHHcZPv7VS0YUsberIuOz",
>   "eventType": "checkout.completed",
>   "created_at": 1728734327412,
>   "object": {
>     "id": "ch_4l0N34kxo16AhRKUHFUuXr",
>     "object": "checkout",
>     "request_id": "my-request-id",
>     "order": {
>       "object": "order",
>       "id": "ord_4aDwWXjMLpes4Kj4XqNnUA",
>       "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
>       "product": "prod_d1AY2Sadk9YAvLI0pj97f",
>       "amount": 1000,
>       "currency": "EUR",
>       "sub_total": 1000,
>       "tax_amount": 210,
>       "amount_due": 1210,
>       "amount_paid": 1210,
>       "status": "paid",
>       "type": "recurring",
>       "transaction": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>       "created_at": "2024-10-12T11:58:33.097Z",
>       "updated_at": "2024-10-12T11:58:33.097Z",
>       "mode": "local"
>     },
>     "product": {
>       "id": "prod_d1AY2Sadk9YAvLI0pj97f",
>       "object": "product",
>       "name": "Monthly",
>       "description": "Monthly",
>       "price": 1000,
>       "currency": "EUR",
>       "billing_type": "recurring",
>       "billing_period": "every-month",
>       "recurring_interval": "month",
>       "recurring_interval_count": 1,
>       "trial_period_days": null,
>       "trial_price": null,
>       "status": "active",
>       "tax_mode": "exclusive",
>       "business_net_pricing": false,
>       "tax_category": "saas",
>       "default_success_url": "",
>       "created_at": "2024-10-11T11:50:00.182Z",
>       "updated_at": "2024-10-11T11:50:00.182Z",
>       "mode": "local"
>     },
>     "units": 1,
>     "customer": {
>       "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
>       "object": "customer",
>       "email": "customer@emaildomain",
>       "name": "Tester Test",
>       "metadata": null,
>       "country": "NL",
>       "external_id": null,
>       "created_at": "2024-10-11T09:16:48.557Z",
>       "updated_at": "2024-10-11T09:16:48.557Z",
>       "mode": "local"
>     },
>     "subscription": {
>       "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>       "object": "subscription",
>       "product": "prod_d1AY2Sadk9YAvLI0pj97f",
>       "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
>       "collection_method": "charge_automatically",
>       "status": "active",
>       "current_period_start_date": "2024-10-12T11:58:38.000Z",
>       "current_period_end_date": "2024-11-12T11:58:38.000Z",
>       "canceled_at": null,
>       "created_at": "2024-10-12T11:58:45.425Z",
>       "updated_at": "2024-10-12T11:58:45.425Z",
>       "metadata": {
>         "custom_data": "mycustom data",
>         "internal_customer_id": "internal_customer_id"
>       },
>       "mode": "local"
>     },
>     "license_keys": [
>       {
>         "id": "lk_2wMk1RtYqPnZ7bVxCdEfGh",
>         "object": "license",
>         "product_id": "prod_d1AY2Sadk9YAvLI0pj97f",
>         "key": "ABCDE-FGHIJ-KLMNO-PQRST-UVWXY",
>         "status": "inactive",
>         "activation": 0,
>         "activation_limit": 1,
>         "expires_at": null,
>         "created_at": "2024-10-12T11:58:33.097Z",
>         "instance": null,
>         "mode": "local"
>       }
>     ],
>     "custom_fields": [],
>     "status": "completed",
>     "metadata": {
>       "custom_data": "mycustom data",
>       "internal_customer_id": "internal_customer_id"
>     },
>     "mode": "local"
>   }
> }
> ```

#### License keys

If the purchased product issues license keys, the checkout object also carries a `license_keys` array, as shown in the sample above.

> [!NOTE]
>
> `license_keys` is only present when the order actually issued license keys. For a product without
> a license key feature the field is **omitted entirely** — check whether it is present rather than
> expecting an empty array.

Each entry is a license **object**, not a key string:

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the license, prefixed with `lk_`. |
| `object` | string | Always `license`. |
| `product_id` | string | The product the license was issued for. |
| `key` | string | The license key itself: five groups of five uppercase alphanumeric characters, for example `ABCDE-FGHIJ-KLMNO-PQRST-UVWXY`. |
| `status` | string | One of `inactive`, `active`, `expired`, or `disabled`. A key stays `inactive` until its first successful activation. |
| `activation` | number | Number of times the key has been activated so far. |
| `activation_limit` | number \| null | Maximum number of activations allowed. `null` means unlimited. |
| `expires_at` | string \| null | ISO 8601 expiry date. `null` means the key does not expire. |
| `created_at` | string | ISO 8601 date the license was created. |
| `instance` | object \| null | The associated license instance, when one exists. |
| `mode` | string | The environment the license belongs to. |

> [!TIP]
>
> You do not need a real purchase to see this shape. In the dashboard go to **Settings → Webhooks**,
> open a webhook and use **Send test event** — the `checkout.completed` payload it delivers includes
> a populated `license_keys` array.

One key is issued per license key feature on the product, multiplied by the number of units purchased — a three-unit order of a keyed product delivers three entries. Always treat `license_keys` as a list, never as a single key.

When `license_keys` is present, the checkout also carries a deprecated `feature` object that repeats only the first key. It is left out of the sample above. Read `license_keys` instead.

For issuing and managing keys, see [Licenses](https://docs.creem.io/features/addons/licenses.md).

#### Discounts

When a discount code was applied to the checkout, the payload carries three more fields. The order gets `discount_amount`, the amount taken off the price, and `discount`, the ID of the discount. The checkout gets a `discount` object:

```json theme={null}
"discount": {
  "id": "dis_3e6Z6TzvHKdsjEgXnGDEp0",
  "discountCode": "LAUNCH20",
  "name": "Launch discount",
  "type": "percentage",
  "amount": 20,
  "duration": "repeating",
  "durationInMonths": 3
}
```

`order.amount` and `order.sub_total` stay the price before the discount, and `amount_paid` is what the customer was charged. For a `percentage` discount, `amount` is the percentage. `durationInMonths` is omitted when the discount has no month count. Subscription events carry the same `discount` object on the subscription when a discount was redeemed for it.

### subscription.active

Received when a new subscription is created, the payment was successful and Creem collected the payment creating a new subscription object in your account.
It also fires whenever an existing subscription changes back to `active` from another status, for example when a paused subscription resumes.
Use only for synchronization, we encourage using `subscription.paid` for activating access.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_6EptlmjazyGhEPiNQ5f4lz",
>   "eventType": "subscription.active",
>   "created_at": 1726515642348,
>   "object": {
>       "id": "sub_21lfZb67szyvMiXnm6SVi0",
>       "object": "subscription",
>       "product": {
>           "id": "prod_AnVJ11ujp7x953ARpJvAF",
>           "object": "product",
>           "name": "My Product - Product 01",
>           "description": "Test my product",
>           "price": 10000,
>           "currency": "EUR",
>           "billing_type": "recurring",
>           "billing_period": "every-month",
>           "recurring_interval": "month",
>           "recurring_interval_count": 1,
>           "trial_period_days": null,
>           "trial_price": null,
>           "status": "active",
>           "tax_mode": "inclusive",
>           "business_net_pricing": false,
>           "tax_category": "saas",
>           "default_success_url": "",
>           "created_at": "2024-09-16T16:12:09.813Z",
>           "updated_at": "2024-09-16T16:12:09.813Z",
>           "mode": "local"
>       },
>       "customer": {
>           "id": "cust_3biFPNt4Cz5YRDSdIqs7kc",
>           "object": "customer",
>           "email": "customer@emaildomain",
>           "name": "Tester Test",
>           "metadata": null,
>           "country": "SE",
>           "external_id": null,
>           "created_at": "2024-09-16T16:13:39.265Z",
>           "updated_at": "2024-09-16T16:13:39.265Z",
>           "mode": "local"
>       },
>       "items": [
>           {
>               "object": "subscription_item",
>               "id": "sitem_5Rt2YkLm8QxW3vNbJp6sHc",
>               "product_id": "prod_AnVJ11ujp7x953ARpJvAF",
>               "price_id": "pprice_3Dk9WqZr5TmB1xLvNc7yPa",
>               "units": 1,
>               "created_at": "2024-09-16T19:40:41.990Z",
>               "updated_at": "2024-09-16T19:40:41.990Z",
>               "mode": "local"
>           }
>       ],
>       "collection_method": "charge_automatically",
>       "status": "active",
>       "current_period_start_date": "2024-09-16T19:40:38.000Z",
>       "current_period_end_date": "2024-10-16T19:40:38.000Z",
>       "canceled_at": null,
>       "created_at": "2024-09-16T19:40:41.984Z",
>       "updated_at": "2024-09-16T19:40:42.121Z",
>       "mode": "local"
>   }
> }
> ```

### subscription.paid

A subscription transaction was paid by the customer. Fires for the first payment and every renewal. `last_transaction` is the transaction that was just paid, with the amount charged, tax and discount. Its `customer` field is `null` in this event, so read the customer from the subscription's `customer` object.

`subscription.canceled`, `subscription.scheduled_cancel` and `subscription.expired` also carry `last_transaction`, set to the subscription's most recent paid or refunded transaction when it has one. The other `subscription.*` events don't include `last_transaction`, `last_transaction_id`, `last_transaction_date` or `next_transaction_date`.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_21mO1jWmU2QHe7u2oFV7y1",
>   "eventType": "subscription.paid",
>   "created_at": 1728734327355,
>   "object": {
>     "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>     "object": "subscription",
>     "product": {
>       "id": "prod_d1AY2Sadk9YAvLI0pj97f",
>       "object": "product",
>       "name": "Monthly",
>       "description": "Monthly",
>       "price": 1000,
>       "currency": "EUR",
>       "billing_type": "recurring",
>       "billing_period": "every-month",
>       "recurring_interval": "month",
>       "recurring_interval_count": 1,
>       "trial_period_days": null,
>       "trial_price": null,
>       "status": "active",
>       "tax_mode": "exclusive",
>       "business_net_pricing": false,
>       "tax_category": "saas",
>       "default_success_url": "",
>       "created_at": "2024-10-11T11:50:00.182Z",
>       "updated_at": "2024-10-11T11:50:00.182Z",
>       "mode": "local"
>     },
>     "customer": {
>       "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
>       "object": "customer",
>       "email": "customer@emaildomain",
>       "name": "Tester Test",
>       "metadata": null,
>       "country": "NL",
>       "external_id": null,
>       "created_at": "2024-10-11T09:16:48.557Z",
>       "updated_at": "2024-10-11T09:16:48.557Z",
>       "mode": "local"
>     },
>     "items": [
>       {
>         "object": "subscription_item",
>         "id": "sitem_2Zk7QwX9rTbN4vLmPq8sYd",
>         "product_id": "prod_d1AY2Sadk9YAvLI0pj97f",
>         "price_id": "pprice_6hJx3VnR8kWcT1yMbQ5uZa",
>         "units": 1,
>         "created_at": "2024-10-12T11:58:45.430Z",
>         "updated_at": "2024-10-12T11:58:45.430Z",
>         "mode": "local"
>       }
>     ],
>     "collection_method": "charge_automatically",
>     "status": "active",
>     "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>     "last_transaction": {
>       "id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>       "object": "transaction",
>       "amount": 1000,
>       "amount_paid": 1210,
>       "currency": "EUR",
>       "type": "invoice",
>       "tax_country": "NL",
>       "tax_amount": 210,
>       "status": "paid",
>       "refunded_amount": null,
>       "order": "ord_4aDwWXjMLpes4Kj4XqNnUA",
>       "subscription": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>       "customer": null,
>       "description": "Subscription payment",
>       "period_start": 1728734318000,
>       "period_end": 1731412718000,
>       "created_at": 1728734327109,
>       "mode": "local"
>     },
>     "last_transaction_date": "2024-10-12T11:58:38.000Z",
>     "next_transaction_date": "2024-11-12T11:58:38.000Z",
>     "current_period_start_date": "2024-10-12T11:58:38.000Z",
>     "current_period_end_date": "2024-11-12T11:58:38.000Z",
>     "canceled_at": null,
>     "created_at": "2024-10-12T11:58:45.425Z",
>     "updated_at": "2024-10-12T11:58:45.425Z",
>     "metadata": {
>       "custom_data": "mycustom data",
>       "internal_customer_id": "internal_customer_id"
>     },
>     "mode": "local"
>   }
> }
> ```

### subscription.canceled

The subscription was canceled by the merchant or by the customer. It also fires when a scheduled cancellation takes effect at the end of the period.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_2iGTc600qGW6FBzloh2Nr7",
>   "eventType": "subscription.canceled",
>   "created_at": 1728734337932,
>   "object": {
>     "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>     "object": "subscription",
>     "product": {
>       "id": "prod_d1AY2Sadk9YAvLI0pj97f",
>       "object": "product",
>       "name": "Monthly",
>       "description": "Monthly",
>       "price": 1000,
>       "currency": "EUR",
>       "billing_type": "recurring",
>       "billing_period": "every-month",
>       "recurring_interval": "month",
>       "recurring_interval_count": 1,
>       "trial_period_days": null,
>       "trial_price": null,
>       "status": "active",
>       "tax_mode": "exclusive",
>       "business_net_pricing": false,
>       "tax_category": "saas",
>       "default_success_url": "",
>       "created_at": "2024-10-11T11:50:00.182Z",
>       "updated_at": "2024-10-11T11:50:00.182Z",
>       "mode": "local"
>     },
>     "customer": {
>       "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
>       "object": "customer",
>       "email": "customer@emaildomain",
>       "name": "Tester Test",
>       "metadata": null,
>       "country": "NL",
>       "external_id": null,
>       "created_at": "2024-10-11T09:16:48.557Z",
>       "updated_at": "2024-10-11T09:16:48.557Z",
>       "mode": "local"
>     },
>     "items": [
>       {
>         "object": "subscription_item",
>         "id": "sitem_2Zk7QwX9rTbN4vLmPq8sYd",
>         "product_id": "prod_d1AY2Sadk9YAvLI0pj97f",
>         "price_id": "pprice_6hJx3VnR8kWcT1yMbQ5uZa",
>         "units": 1,
>         "created_at": "2024-10-12T11:58:45.430Z",
>         "updated_at": "2024-10-12T11:58:45.430Z",
>         "mode": "local"
>       }
>     ],
>     "collection_method": "charge_automatically",
>     "status": "canceled",
>     "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>     "last_transaction": {
>       "id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>       "object": "transaction",
>       "amount": 1000,
>       "amount_paid": 1210,
>       "currency": "EUR",
>       "type": "invoice",
>       "tax_country": "NL",
>       "tax_amount": 210,
>       "status": "paid",
>       "refunded_amount": null,
>       "order": "ord_4aDwWXjMLpes4Kj4XqNnUA",
>       "subscription": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>       "customer": null,
>       "description": "Subscription payment",
>       "period_start": 1728734318000,
>       "period_end": 1731412718000,
>       "created_at": 1728734327109,
>       "mode": "local"
>     },
>     "last_transaction_date": "2024-10-12T11:58:38.000Z",
>     "current_period_start_date": "2024-10-12T11:58:38.000Z",
>     "current_period_end_date": "2024-11-12T11:58:38.000Z",
>     "canceled_at": "2024-10-12T11:58:57.813Z",
>     "created_at": "2024-10-12T11:58:45.425Z",
>     "updated_at": "2024-10-12T11:58:57.827Z",
>     "metadata": {
>       "custom_data": "mycustom data",
>       "internal_customer_id": "internal_customer_id"
>     },
>     "mode": "local"
>   }
> }
> ```

### subscription.scheduled\_cancel

The subscription was scheduled for cancellation at the end of the current billing period. The subscription remains active until `current_period_end_date`, after which it transitions to `canceled`.
This event is triggered when a customer or merchant requests cancellation but opts to cancel at the end of the period rather than immediately. You can use this event to notify the customer about the upcoming cancellation or to offer retention incentives.

The subscription can be resumed before the period ends using the [Resume Subscription](https://docs.creem.io/api-reference/endpoint/resume-subscription.md) endpoint, which will change the status back to `active` and prevent the cancellation.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_4RfTc700qGW6FBzloh3Ms8",
>   "eventType": "subscription.scheduled_cancel",
>   "created_at": 1728734337932,
>   "object": {
>     "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>     "object": "subscription",
>     "product": {
>       "id": "prod_d1AY2Sadk9YAvLI0pj97f",
>       "object": "product",
>       "name": "Monthly",
>       "description": "Monthly",
>       "price": 1000,
>       "currency": "EUR",
>       "billing_type": "recurring",
>       "billing_period": "every-month",
>       "recurring_interval": "month",
>       "recurring_interval_count": 1,
>       "trial_period_days": null,
>       "trial_price": null,
>       "status": "active",
>       "tax_mode": "exclusive",
>       "business_net_pricing": false,
>       "tax_category": "saas",
>       "default_success_url": "",
>       "created_at": "2024-10-11T11:50:00.182Z",
>       "updated_at": "2024-10-11T11:50:00.182Z",
>       "mode": "local"
>     },
>     "customer": {
>       "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
>       "object": "customer",
>       "email": "customer@emaildomain",
>       "name": "Tester Test",
>       "metadata": null,
>       "country": "NL",
>       "external_id": null,
>       "created_at": "2024-10-11T09:16:48.557Z",
>       "updated_at": "2024-10-11T09:16:48.557Z",
>       "mode": "local"
>     },
>     "items": [
>       {
>         "object": "subscription_item",
>         "id": "sitem_2Zk7QwX9rTbN4vLmPq8sYd",
>         "product_id": "prod_d1AY2Sadk9YAvLI0pj97f",
>         "price_id": "pprice_6hJx3VnR8kWcT1yMbQ5uZa",
>         "units": 1,
>         "created_at": "2024-10-12T11:58:45.430Z",
>         "updated_at": "2024-10-12T11:58:45.430Z",
>         "mode": "local"
>       }
>     ],
>     "collection_method": "charge_automatically",
>     "status": "scheduled_cancel",
>     "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>     "last_transaction": {
>       "id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>       "object": "transaction",
>       "amount": 1000,
>       "amount_paid": 1210,
>       "currency": "EUR",
>       "type": "invoice",
>       "tax_country": "NL",
>       "tax_amount": 210,
>       "status": "paid",
>       "refunded_amount": null,
>       "order": "ord_4aDwWXjMLpes4Kj4XqNnUA",
>       "subscription": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>       "customer": null,
>       "description": "Subscription payment",
>       "period_start": 1728734318000,
>       "period_end": 1731412718000,
>       "created_at": 1728734327109,
>       "mode": "local"
>     },
>     "last_transaction_date": "2024-10-12T11:58:38.000Z",
>     "next_transaction_date": "2024-11-12T11:58:38.000Z",
>     "current_period_start_date": "2024-10-12T11:58:38.000Z",
>     "current_period_end_date": "2024-11-12T11:58:38.000Z",
>     "canceled_at": null,
>     "created_at": "2024-10-12T11:58:45.425Z",
>     "updated_at": "2024-10-12T11:58:57.827Z",
>     "metadata": {
>       "custom_data": "mycustom data",
>       "internal_customer_id": "internal_customer_id"
>     },
>     "mode": "local"
>   }
> }
> ```

### subscription.past\_due

The subscription payment has failed and the subscription is now past due. This occurs when a payment attempt fails (e.g., card declined, insufficient funds). Creem will automatically retry the payment according to the retry schedule. If a retry succeeds, the subscription transitions back to `active`. If all retries are exhausted, the subscription is canceled.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_7HkTd800rHX7GCampi4Nt9",
>   "eventType": "subscription.past_due",
>   "created_at": 1731413131204,
>   "object": {
>     "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>     "object": "subscription",
>     "product": {
>       "id": "prod_d1AY2Sadk9YAvLI0pj97f",
>       "object": "product",
>       "name": "Monthly",
>       "description": "Monthly",
>       "price": 1000,
>       "currency": "EUR",
>       "billing_type": "recurring",
>       "billing_period": "every-month",
>       "recurring_interval": "month",
>       "recurring_interval_count": 1,
>       "trial_period_days": null,
>       "trial_price": null,
>       "status": "active",
>       "tax_mode": "exclusive",
>       "business_net_pricing": false,
>       "tax_category": "saas",
>       "default_success_url": "",
>       "created_at": "2024-10-11T11:50:00.182Z",
>       "updated_at": "2024-10-11T11:50:00.182Z",
>       "mode": "local"
>     },
>     "customer": {
>       "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
>       "object": "customer",
>       "email": "customer@emaildomain",
>       "name": "Tester Test",
>       "metadata": null,
>       "country": "NL",
>       "external_id": null,
>       "created_at": "2024-10-11T09:16:48.557Z",
>       "updated_at": "2024-10-11T09:16:48.557Z",
>       "mode": "local"
>     },
>     "items": [
>       {
>         "object": "subscription_item",
>         "id": "sitem_2Zk7QwX9rTbN4vLmPq8sYd",
>         "product_id": "prod_d1AY2Sadk9YAvLI0pj97f",
>         "price_id": "pprice_6hJx3VnR8kWcT1yMbQ5uZa",
>         "units": 1,
>         "created_at": "2024-10-12T11:58:45.430Z",
>         "updated_at": "2024-10-12T11:58:45.430Z",
>         "mode": "local"
>       }
>     ],
>     "collection_method": "charge_automatically",
>     "status": "past_due",
>     "current_period_start_date": "2024-10-12T11:58:38.000Z",
>     "current_period_end_date": "2024-11-12T11:58:38.000Z",
>     "canceled_at": null,
>     "created_at": "2024-10-12T11:58:45.425Z",
>     "updated_at": "2024-11-12T12:05:30.827Z",
>     "metadata": {
>       "custom_data": "mycustom data",
>       "internal_customer_id": "internal_customer_id"
>     },
>     "mode": "local"
>   }
> }
> ```

### subscription.unpaid

The subscription moved to the `unpaid` status after failed payment collection. Treat it like `subscription.past_due` in payment-recovery UI, and suspend access according to your policy.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_h9hBneNdvWvA8hQzIBzDx",
>   "eventType": "subscription.unpaid",
>   "created_at": 1772265400331,
>   "object": {
>       "id": "sub_3xx35QzxsnpFiJ3vRB9YKt",
>       "object": "subscription",
>       "product": {
>           "id": "prod_L8mMzoYLOOZpMpTBwGw0k",
>           "object": "product",
>           "name": "Pro Plan",
>           "description": "Pro Plan",
>           "price": 2999,
>           "currency": "USD",
>           "billing_type": "recurring",
>           "billing_period": "every-month",
>           "recurring_interval": "month",
>           "recurring_interval_count": 1,
>           "trial_period_days": null,
>           "trial_price": null,
>           "status": "active",
>           "tax_mode": "exclusive",
>           "business_net_pricing": false,
>           "tax_category": "saas",
>           "default_success_url": null,
>           "created_at": "2026-01-12T09:14:22.512Z",
>           "updated_at": "2026-01-12T09:14:22.512Z",
>           "mode": "test"
>       },
>       "customer": {
>           "id": "cust_ubD9UtnJpafXNKQ5UaV0H",
>           "object": "customer",
>           "email": "customer@example.com",
>           "name": "Test Customer",
>           "metadata": null,
>           "country": "US",
>           "external_id": null,
>           "created_at": "2026-01-28T07:55:41.903Z",
>           "updated_at": "2026-01-28T07:55:41.903Z",
>           "mode": "test"
>       },
>       "items": [
>           {
>               "object": "subscription_item",
>               "id": "sitem_4Hn8TzQb2WxK6rLpVm1cYe",
>               "product_id": "prod_L8mMzoYLOOZpMpTBwGw0k",
>               "price_id": "pprice_7Pq2LsXv9NdR4kBjTw3hMf",
>               "units": 1,
>               "created_at": "2026-01-28T07:56:10.118Z",
>               "updated_at": "2026-01-28T07:56:10.118Z",
>               "mode": "test"
>           }
>       ],
>       "collection_method": "charge_automatically",
>       "status": "unpaid",
>       "current_period_start_date": "2026-02-28T07:56:07.282Z",
>       "current_period_end_date": "2026-03-30T07:56:07.282Z",
>       "canceled_at": null,
>       "created_at": "2026-01-28T07:56:10.104Z",
>       "updated_at": "2026-02-28T07:56:39.871Z",
>       "metadata": {},
>       "mode": "test"
>   }
> }
> ```

### subscription.expired

The subscription was expired, given that the `current_period_end_date` has been reached without a new payment.
Payment retries can happen at this stage, and the subscription status will be terminal only when status is changed to `canceled`.
Creem checks once a day for subscriptions whose `current_period_end_date` fell on the previous day, so the event arrives up to a day after the period ended. The event doesn't change the subscription, and `status` shows its current value.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_V5CxhipUu10BYonO2Vshb",
>   "eventType": "subscription.expired",
>   "created_at": 1734463872058,
>   "object": {
>       "id": "sub_7FgHvrOMC28tG5DEemoCli",
>       "object": "subscription",
>       "product": {
>           "id": "prod_3ELsC3Lt97orn81SOdgQI3",
>           "object": "product",
>           "name": "Subs",
>           "description": "Subs",
>           "price": 1200,
>           "currency": "EUR",
>           "billing_type": "recurring",
>           "billing_period": "every-year",
>           "recurring_interval": "year",
>           "recurring_interval_count": 1,
>           "trial_period_days": null,
>           "trial_price": null,
>           "status": "active",
>           "tax_mode": "exclusive",
>           "business_net_pricing": false,
>           "tax_category": "saas",
>           "default_success_url": "",
>           "created_at": "2023-12-11T17:33:32.186Z",
>           "updated_at": "2023-12-11T17:33:32.186Z",
>           "mode": "local"
>       },
>       "customer": {
>           "id": "cust_3y4k2CELGsw7n9Eeeiw2hm",
>           "object": "customer",
>           "email": "customer@emaildomain",
>           "name": "Alec Erasmus",
>           "metadata": null,
>           "country": "NL",
>           "external_id": null,
>           "created_at": "2023-12-09T16:09:20.709Z",
>           "updated_at": "2023-12-09T16:09:20.709Z",
>           "mode": "local"
>       },
>       "items": [
>           {
>               "object": "subscription_item",
>               "id": "sitem_6Wd3MxR7kTq1ZbNv8LpJsA",
>               "product_id": "prod_3ELsC3Lt97orn81SOdgQI3",
>               "price_id": "pprice_2Gk5VnY8rQc3XtMw6BjLzE",
>               "units": 1,
>               "created_at": "2023-12-16T12:40:05.063Z",
>               "updated_at": "2023-12-16T12:40:05.063Z",
>               "mode": "local"
>           }
>       ],
>       "collection_method": "charge_automatically",
>       "status": "active",
>       "last_transaction_id": "tran_6ZeTvMqMkGdAIIjw5aAcnh",
>       "last_transaction": {
>           "id": "tran_6ZeTvMqMkGdAIIjw5aAcnh",
>           "object": "transaction",
>           "amount": 1200,
>           "amount_paid": 1452,
>           "currency": "EUR",
>           "type": "invoice",
>           "tax_country": "NL",
>           "tax_amount": 252,
>           "status": "paid",
>           "refunded_amount": null,
>           "order": "ord_1Lq7XcV3mRt9ZwKbN5pYdS",
>           "subscription": "sub_7FgHvrOMC28tG5DEemoCli",
>           "customer": null,
>           "description": "Subscription payment",
>           "period_start": 1702730387000,
>           "period_end": 1734352787000,
>           "created_at": 1702730412658,
>           "mode": "local"
>       },
>       "last_transaction_date": "2023-12-16T12:39:47.000Z",
>       "next_transaction_date": "2024-12-16T12:39:47.000Z",
>       "current_period_start_date": "2023-12-16T12:39:47.000Z",
>       "current_period_end_date": "2024-12-16T12:39:47.000Z",
>       "canceled_at": null,
>       "created_at": "2023-12-16T12:40:05.058Z",
>       "updated_at": "2023-12-16T12:40:05.058Z",
>       "mode": "local"
>   }
> }
> ```

### refund.created

A refund was created by the merchant. Creem sends the event once the refund reaches the `succeeded` status.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_61eTsJHUgInFw2BQKhTiPV",
> "eventType": "refund.created",
> "created_at": 1728734351631,
> "object": {
>   "id": "ref_3DB9NQFvk18TJwSqd0N6bd",
>   "object": "refund",
>   "status": "succeeded",
>   "refund_amount": 1210,
>   "refund_currency": "EUR",
>   "reason": "requested_by_customer",
>   "transaction": {
>     "id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>     "object": "transaction",
>     "amount": 1000,
>     "amount_paid": 1210,
>     "currency": "EUR",
>     "type": "invoice",
>     "tax_country": "NL",
>     "tax_amount": 210,
>     "status": "refunded",
>     "refunded_amount": 1210,
>     "order": "ord_4aDwWXjMLpes4Kj4XqNnUA",
>     "subscription": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>     "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
>     "description": "Subscription payment",
>     "period_start": 1728734318000,
>     "period_end": 1731412718000,
>     "created_at": 1728734327109,
>     "mode": "local"
>   },
>   "subscription": {
>     "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
>     "object": "subscription",
>     "product": "prod_d1AY2Sadk9YAvLI0pj97f",
>     "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
>     "collection_method": "charge_automatically",
>     "status": "canceled",
>     "last_transaction_id": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>     "last_transaction_date": "2024-10-12T11:58:38.000Z",
>     "current_period_start_date": "2024-10-12T11:58:38.000Z",
>     "current_period_end_date": "2024-11-12T11:58:38.000Z",
>     "canceled_at": "2024-10-12T11:58:57.813Z",
>     "created_at": "2024-10-12T11:58:45.425Z",
>     "updated_at": "2024-10-12T11:58:57.827Z",
>     "metadata": {
>       "custom_data": "mycustom data",
>       "internal_customer_id": "internal_customer_id"
>     },
>     "mode": "local"
>   },
>   "checkout": {
>     "id": "ch_4l0N34kxo16AhRKUHFUuXr",
>     "object": "checkout",
>     "request_id": "my-request-id",
>     "product": "prod_d1AY2Sadk9YAvLI0pj97f",
>     "units": 1,
>     "custom_fields": [],
>     "status": "completed",
>     "metadata": {
>       "custom_data": "mycustom data",
>       "internal_customer_id": "internal_customer_id"
>     },
>     "mode": "local"
>   },
>   "order": {
>     "object": "order",
>     "id": "ord_4aDwWXjMLpes4Kj4XqNnUA",
>     "customer": "cust_1OcIK1GEuVvXZwD19tjq2z",
>     "product": "prod_d1AY2Sadk9YAvLI0pj97f",
>     "amount": 1000,
>     "currency": "EUR",
>     "sub_total": 1000,
>     "tax_amount": 210,
>     "amount_due": 1210,
>     "amount_paid": 1210,
>     "status": "paid",
>     "type": "recurring",
>     "transaction": "tran_5yMaWzAl3jxuGJMCOrYWwk",
>     "created_at": "2024-10-12T11:58:33.097Z",
>     "updated_at": "2024-10-12T11:58:33.097Z",
>     "mode": "local"
>   },
>   "customer": {
>     "id": "cust_1OcIK1GEuVvXZwD19tjq2z",
>     "object": "customer",
>     "email": "customer@emaildomain",
>     "name": "Tester Test",
>     "metadata": null,
>     "country": "NL",
>     "external_id": null,
>     "created_at": "2024-10-11T09:16:48.557Z",
>     "updated_at": "2024-10-11T09:16:48.557Z",
>     "mode": "local"
>   },
>   "created_at": 1728734351525,
>   "mode": "local"
> }
> }
> ```

### dispute.created

A dispute was created by the customer

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
>   "id": "evt_6mfLDL7P0NYwYQqCrICvDH",
>   "eventType": "dispute.created",
>   "created_at": 1750941264812,
>   "object": {
>     "id": "disp_6vSsOdTANP5PhOzuDlUuXE",
>     "object": "dispute",
>     "amount": 1331,
>     "currency": "EUR",
>     "transaction": {
>       "id": "tran_4Dk8CxWFdceRUQgMFhCCXX",
>       "object": "transaction",
>       "amount": 1100,
>       "amount_paid": 1331,
>       "currency": "EUR",
>       "type": "invoice",
>       "tax_country": "NL",
>       "tax_amount": 231,
>       "status": "chargeback",
>       "refunded_amount": 1331,
>       "order": "ord_57bf8042UmG8fFypxZrfnj",
>       "subscription": "sub_5sD6zM482uwOaEoyEUDDJs",
>       "customer": "cust_OJPZd2GMxgo1MGPNXXBSN",
>       "description": "Subscription payment",
>       "period_start": 1750941201000,
>       "period_end": 1753533201000,
>       "created_at": 1750941205659,
>       "mode": "sandbox"
>     },
>     "subscription": {
>       "id": "sub_5sD6zM482uwOaEoyEUDDJs",
>       "object": "subscription",
>       "product": "prod_3EFtQRQ9SNIizK3xwfxZHu",
>       "customer": "cust_OJPZd2GMxgo1MGPNXXBSN",
>       "collection_method": "charge_automatically",
>       "status": "active",
>       "current_period_start_date": "2025-06-26T12:33:21.000Z",
>       "current_period_end_date": "2025-07-26T12:33:21.000Z",
>       "canceled_at": null,
>       "created_at": "2025-06-26T12:33:23.589Z",
>       "updated_at": "2025-06-26T12:33:26.102Z",
>       "mode": "sandbox"
>     },
>     "checkout": {
>       "id": "ch_1bJMvqGGzHIftf4ewLXJeq",
>       "object": "checkout",
>       "product": "prod_3EFtQRQ9SNIizK3xwfxZHu",
>       "units": 1,
>       "custom_fields": [
>         {
>           "key": "testing",
>           "text": {
>             "value": "asdfasdf",
>             "max_length": 255
>           },
>           "type": "text",
>           "label": "Testing",
>           "optional": false
>         }
>       ],
>       "status": "completed",
>       "mode": "sandbox"
>     },
>     "order": {
>       "object": "order",
>       "id": "ord_57bf8042UmG8fFypxZrfnj",
>       "customer": "cust_OJPZd2GMxgo1MGPNXXBSN",
>       "product": "prod_3EFtQRQ9SNIizK3xwfxZHu",
>       "amount": 1100,
>       "currency": "EUR",
>       "sub_total": 1100,
>       "tax_amount": 231,
>       "amount_due": 1331,
>       "amount_paid": 1331,
>       "status": "paid",
>       "type": "recurring",
>       "transaction": "tran_4Dk8CxWFdceRUQgMFhCCXX",
>       "created_at": "2025-06-26T12:32:41.395Z",
>       "updated_at": "2025-06-26T12:32:41.395Z",
>       "mode": "sandbox"
>     },
>     "customer": {
>       "id": "cust_OJPZd2GMxgo1MGPNXXBSN",
>       "object": "customer",
>       "email": "customer@emaildomain",
>       "name": "Alec Erasmus",
>       "metadata": null,
>       "country": "NL",
>       "external_id": null,
>       "created_at": "2025-02-05T10:11:01.146Z",
>       "updated_at": "2025-02-05T10:11:01.146Z",
>       "mode": "sandbox"
>     },
>     "created_at": 1750941264728,
>     "mode": "sandbox"
>   }
> }
> ```

### subscription.update

A subscription object was updated without a change of status. A status change sends the matching status event instead, such as `subscription.paused`.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_5pJMUuvqaqvttFVUvtpY32",
> "eventType": "subscription.update",
> "created_at": 1737890536421,
> "object": {
>   "id": "sub_2qAuJgWmXhXHAuef9k4Kur",
>   "object": "subscription",
>   "product": {
>     "id": "prod_1dP15yoyogQe2seEt1Evf3",
>     "object": "product",
>     "name": "Monthly Sub",
>     "description": "Test Test",
>     "price": 1000,
>     "currency": "EUR",
>     "billing_type": "recurring",
>     "billing_period": "every-month",
>     "recurring_interval": "month",
>     "recurring_interval_count": 1,
>     "trial_period_days": null,
>     "trial_price": null,
>     "status": "active",
>     "tax_mode": "exclusive",
>     "business_net_pricing": false,
>     "tax_category": "saas",
>     "default_success_url": "",
>     "created_at": "2025-01-26T11:17:16.082Z",
>     "updated_at": "2025-01-26T11:17:16.082Z",
>     "mode": "local"
>   },
>   "customer": {
>     "id": "cust_2fQZKKUZqtNhH2oDWevQkW",
>     "object": "customer",
>     "email": "customer@emaildomain",
>     "name": "John Doe",
>     "metadata": null,
>     "country": "NL",
>     "external_id": null,
>     "created_at": "2025-01-26T11:18:24.071Z",
>     "updated_at": "2025-01-26T11:18:24.071Z",
>     "mode": "local"
>   },
>   "items": [
>     {
>       "object": "subscription_item",
>       "id": "sitem_3QWlqRbAat2eBRakAxFtt9",
>       "product_id": "prod_5jnudVkLGZWF4AqMFBs5t5",
>       "price_id": "pprice_4W0mJK6uGiQzHbVhfaFTl1",
>       "units": 1,
>       "created_at": "2025-01-26T11:20:40.296Z",
>       "updated_at": "2025-01-26T11:20:40.296Z",
>       "mode": "local"
>     }
>   ],
>   "collection_method": "charge_automatically",
>   "status": "active",
>   "current_period_start_date": "2025-01-26T11:20:36.000Z",
>   "current_period_end_date": "2025-02-26T11:20:36.000Z",
>   "canceled_at": null,
>   "created_at": "2025-01-26T11:20:40.292Z",
>   "updated_at": "2025-01-26T11:22:16.388Z",
>   "mode": "local"
> }
> }
> ```

### subscription.trialing

A subscription started a trial period

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_2ciAM8ABYtj0pVueeJPxUZ",
> "eventType": "subscription.trialing",
> "created_at": 1739963911073,
> "object": {
>   "id": "sub_dxiauR8zZOwULx5QM70wJ",
>   "object": "subscription",
>   "product": {
>     "id": "prod_3kpf0ZdpcfsSCQ3kDiwg9m",
>     "object": "product",
>     "name": "trail",
>     "description": "asdfasf",
>     "price": 1100,
>     "currency": "EUR",
>     "billing_type": "recurring",
>     "billing_period": "every-month",
>     "recurring_interval": "month",
>     "recurring_interval_count": 1,
>     "trial_period_days": 7,
>     "trial_price": null,
>     "status": "active",
>     "tax_mode": "exclusive",
>     "business_net_pricing": false,
>     "tax_category": "saas",
>     "default_success_url": "",
>     "created_at": "2025-02-19T11:18:07.570Z",
>     "updated_at": "2025-02-19T11:18:07.570Z",
>     "mode": "test"
>   },
>   "customer": {
>     "id": "cust_4fpU8kYkQmI1XKBwU2qeME",
>     "object": "customer",
>     "email": "customer@emaildomain",
>     "name": "Alec Erasmus",
>     "metadata": null,
>     "country": "NL",
>     "external_id": null,
>     "created_at": "2024-11-07T23:21:11.763Z",
>     "updated_at": "2024-11-07T23:21:11.763Z",
>     "mode": "test"
>   },
>   "items": [
>     {
>       "object": "subscription_item",
>       "id": "sitem_1xbHCmIM61DHGRBCFn0W1L",
>       "product_id": "prod_3kpf0ZdpcfsSCQ3kDiwg9m",
>       "price_id": "pprice_517h9CebmM3P079bGAXHnE",
>       "units": 1,
>       "created_at": "2025-02-19T11:18:30.690Z",
>       "updated_at": "2025-02-19T11:18:30.690Z",
>       "mode": "test"
>     }
>   ],
>   "collection_method": "charge_automatically",
>   "status": "trialing",
>   "current_period_start_date": "2025-02-19T11:18:25.000Z",
>   "current_period_end_date": "2025-02-26T11:18:25.000Z",
>   "canceled_at": null,
>   "created_at": "2025-02-19T11:18:30.674Z",
>   "updated_at": "2025-02-19T11:18:30.674Z",
>   "mode": "test"
>   }
> }
> ```

### subscription.paused

A subscription was paused.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_5veN2cn5N9Grz8u7w3yJuL",
> "eventType": "subscription.paused",
> "created_at": 1754041946898,
> "object": {
>   "id": "sub_3ZT1iYMeDBpiUpRTqq4veE",
>   "object": "subscription",
>   "product": {
>     "id": "prod_sYwbyE1tPbsqbLu6S0bsR",
>     "object": "product",
>     "name": "Prod",
>     "description": "My Product Description",
>     "price": 2000,
>     "currency": "EUR",
>     "billing_type": "recurring",
>     "billing_period": "every-month",
>     "recurring_interval": "month",
>     "recurring_interval_count": 1,
>     "trial_period_days": null,
>     "trial_price": null,
>     "status": "active",
>     "tax_mode": "exclusive",
>     "business_net_pricing": false,
>     "tax_category": "saas",
>     "default_success_url": "",
>     "created_at": "2025-08-01T09:51:26.277Z",
>     "updated_at": "2025-08-01T09:51:26.277Z",
>     "mode": "test"
>   },
>   "customer": {
>     "id": "cust_4fpU8kYkQmI1XKBwU2qeME",
>     "object": "customer",
>     "email": "customer@emaildomain",
>     "name": "Test Test",
>     "metadata": null,
>     "country": "NL",
>     "external_id": null,
>     "created_at": "2024-11-07T23:21:11.763Z",
>     "updated_at": "2024-11-07T23:21:11.763Z",
>     "mode": "test"
>   },
>   "items": [
>     {
>       "object": "subscription_item",
>       "id": "sitem_1ZIqcUuxKKDTj5WZPNsN6C",
>       "product_id": "prod_sYwbyE1tPbsqbLu6S0bsR",
>       "price_id": "pprice_1uM3Pi1vJJ3xkhwQuZiM42",
>       "units": 1,
>       "created_at": "2025-08-01T09:51:50.497Z",
>       "updated_at": "2025-08-01T09:51:50.497Z",
>       "mode": "test"
>     }
>   ],
>   "collection_method": "charge_automatically",
>   "status": "paused",
>   "current_period_start_date": "2025-08-01T09:51:47.000Z",
>   "current_period_end_date": "2025-09-01T09:51:47.000Z",
>   "canceled_at": null,
>   "created_at": "2025-08-01T09:51:50.488Z",
>   "updated_at": "2025-08-01T09:52:26.822Z",
>   "mode": "test"
> }
> }
> ```

### credits.granted

Credits were added to a customer's credit account. It fires for every credit that raises a balance, for example a credit through the API or an auto-recharge top-up. Reversals don't fire it. `amount_minor_units` and `balance_after_minor_units` are strings in the account's units.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_4kR9vN2xQ7bT1mY8pW3cLd",
> "eventType": "credits.granted",
> "created_at": 1789430400123,
> "object": {
>   "id": "cct_3mNpK8rW2xY",
>   "object": "customer_credits_grant",
>   "customer_id": "cust_abc123",
>   "account_id": "cca_7hQ2nL5vX9k",
>   "bucket_name": "ai_credits",
>   "unit_label": "credits",
>   "amount_minor_units": "5000",
>   "balance_after_minor_units": "5250",
>   "reference": "order_789",
>   "occurred_at": "2026-09-15T00:00:00.000Z"
> }
> }
> ```

### credits.consumed

Credits were debited from a customer's credit account, either through the API or by prepaid usage settlement. Reversals don't fire it. Use `balance_after_minor_units` to warn a customer before their balance runs out.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_6pZ3cM8wK1rV5nB2tX9fQs",
> "eventType": "credits.consumed",
> "created_at": 1789430400456,
> "object": {
>   "id": "cct_9tBvR4mX1pQ",
>   "object": "customer_credits_consumption",
>   "customer_id": "cust_abc123",
>   "account_id": "cca_7hQ2nL5vX9k",
>   "bucket_name": "ai_credits",
>   "unit_label": "credits",
>   "amount_minor_units": "10",
>   "balance_after_minor_units": "5240",
>   "reference": "req_01J9X8K2",
>   "occurred_at": "2026-09-15T00:00:00.000Z"
> }
> }
> ```

### customer\_credits.exhausted

A customer's credits ran out while Creem settled a prepaid usage price on one of their products. It fires once per exhaustion: the first refused settlement sends it, and it fires again only after credits were added and ran out again. Creem also emails the customer.

A debit through the API that exceeds the balance doesn't fire this event. That request fails with `422` and the error code `insufficient_balance`. See [Auto-refill](https://docs.creem.io/features/customer-credits/auto-refill.md) for how exhaustion episodes and automatic top-ups work.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_1wT8kP4nR6vY2cM9bX5hLz",
> "eventType": "customer_credits.exhausted",
> "created_at": 1789430400789,
> "object": {
>   "id": "credits-exhausted:store_test:cust_test:default:none",
>   "object": "customer_credits_exhaustion",
>   "customer_id": "cust_test",
>   "bucket_name": "default",
>   "unit_label": "credits",
>   "shortfall_minor_units": "250",
>   "occurred_at": "2026-09-15T00:00:00.000Z"
> }
> }
> ```

### credits.auto\_recharged

An empty credit account was topped up with an automatic charge. It fires only for customers who opted in to auto-recharge, after the charge succeeds and the credits are added. The same top-up also fires `credits.granted`. See [Auto-refill](https://docs.creem.io/features/customer-credits/auto-refill.md) for consent, guardrails, and how the charge is made.

> [accordion] Sample Request Body
>
> ```json theme={null}
> {
> "id": "evt_8nQ5xL2vB7mR3kT9cW1pYd",
> "eventType": "credits.auto_recharged",
> "created_at": 1789430401012,
> "object": {
>   "id": "cct_5kLm2Qx8vRt",
>   "object": "customer_credits_auto_recharge",
>   "customer_id": "cust_test",
>   "bucket_name": "default",
>   "unit_label": "credits",
>   "amount_minor_units": "2000",
>   "currency": "EUR",
>   "charge_reference": "pay_test_charge",
>   "reference": "usage-window:mtr_test:cust_test:2026-01-01:default"
> }
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.