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

# Report Subscription Event

> Tell Cuprice about a subscription your checkout created or changed

Cuprice does not see your payments. Call this endpoint from your backend after your payment provider confirms a purchase, a plan change, a cancellation or a failed payment. The subscriber then shows up in your Cuprice dashboard (Customers and Analytics). Feature gating does not depend on it.

## Endpoint

```
POST /api/v1/projects/{slug}/subscription-events
```

## Authentication

**Authorization** `string` *required*

Bearer token with your API key. Requires `read_write` permission.

## Path Parameters

**slug** `string` *required*

The project's slug. The checkout link carries it as `cuprice_project_slug`.

## Body Parameters

**event** `string` *required*

One of:

* `"subscription.created"`: first successful purchase
* `"subscription.updated"`: plan change or renewal
* `"subscription.canceled"`: the customer canceled
* `"payment.failed"`: a payment failed (the subscriber is marked `past_due`)

**provider** `string` *required*

Name of your payment provider, for example `"stripe"`, `"paddle"` or `"payriff"`.

**externalId** `string` *required*

The subscription or order ID in your provider. Later events with the same ID update the same record.

**planId** `number` *required*

Cuprice's numeric plan ID (`cuprice_plan_id` from the checkout link). The plan has to belong to this project. Custom plans have no Cuprice plan (`cuprice_plan_id=0`), so they cannot be reported.

**customerEmail** `string` *required*

The customer's email. Cuprice matches an existing subscriber by this email or by `externalId`.

**customerName** `string`

The customer's name.

**externalCustomerId** `string`

The customer ID in your provider.

**amount** `number`

Amount charged per interval.

**currency** `string`

Must be the project currency (USD, EUR, GBP or JPY, whichever the project uses). Any other code is rejected. Leave it out to use the project currency.

**interval** `string`

`"month"` or `"year"`. Defaults to `"month"`.

**status** `string`

Your provider's status, for example `"active"` or `"trialing"`. Defaults to `"active"` for created and updated events.

## Response

```json theme={null}
{
  "ok": true,
  "subscriberId": 91,
  "customerSubscriptionId": 57
}
```

## Errors

| Status | When |
| - | - |
| 400 | A required field is missing, `event` is not one of the four values, or `currency` is not the project currency |
| 401 | Missing or invalid API key |
| 403 | The key is read-only or not allowed for this project |
| 404 | No project with this slug in your account |
| 500 | `planId` is not a plan in this project, or another server error |

## Example

```bash theme={null}
curl -X POST https://app.cuprice.io/api/v1/projects/my-saas-app/subscription-events \
  -H "Authorization: Bearer cpk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "subscription.created",
    "provider": "stripe",
    "externalId": "sub_1Q2w3E4r",
    "planId": 768,
    "customerEmail": "ana@example.com",
    "customerName": "Ana Lopez",
    "amount": 29,
    "currency": "USD",
    "interval": "month",
    "status": "active"
  }'
```


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