Report Subscription Event

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

string

required

Bearer token with your API key. Requires read_write permission.

Path Parameters

string

required

The project’s slug. The checkout link carries it as cuprice_project_slug.

Body Parameters

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)

string

required

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

string

required

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

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.

string

required

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

string

The customer’s name.

string

The customer ID in your provider.

number

Amount charged per interval.

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.

string

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

string

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

Response

{
  "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

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"
  }'

Overview

Public Endpoints

API v1 — Projects

API v1 — Features

API v1 — Plans

API v1 — Plan Features

API v1 — Subscriptions

Report Subscription Event

Endpoint

Authentication

Path Parameters

Body Parameters

Response

Errors

Example

​Endpoint

​Authentication

​Path Parameters

​Body Parameters

​Response

​Errors

​Example

Endpoint

Authentication

Path Parameters

Body Parameters

Response

Errors

Example