---
title: "`POST /admin/identities/{email}/subscription`: record the billed truth for an identity's subscription. Operator-only, written by the Stripe webhook; idempotent per Stripe event id."
method: POST
path: "/admin/identities/{email}/subscription"
tags: ["admin"]
---

# \`POST /admin/identities/{email}/subscription\`: record the billed truth for an identity's subscription. Operator-only, written by the Stripe webhook; idempotent per Stripe event id.

`POST /admin/identities/{email}/subscription`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/admin/identities/{email}/subscription`
- Auth: HTTP bearer

## Path parameters

- `email` string, required

## Request body

- SetSubscriptionRequest: Body for `POST /admin/identities/{email}/subscription`, what Stripe ACTUALLY charges, so recurring revenue stops being an estimate.
  - `billed_pence` integer, required: What the last invoice collected, in minor units (pence).
  - `billing_interval` string, required: Billing interval as Stripe names it: `month`, `year`.
  - `currency` string, required: ISO currency, lowercase (`gbp`).
  - `current_period_end` string, nullable: RFC 3339 end of the paid period, when known.
  - `reason` string, required: Idempotency reason, the Stripe EVENT id (`stripe-evt:evt_…`), unique per delivery and identical across retries of it.
  - `status` string, required: Lifecycle status as Stripe reports it: `active`, `trialing`, `past_due`, `unpaid`, `canceled` …
  - `stripe_subscription_id` string, required: The Stripe subscription (`sub_…`).

## Response `200`

Recorded (or an idempotent replay)

- SubscriptionResponse: Response for `POST /admin/identities/{email}/subscription`.
  - `billed_pence` integer, required
  - `duplicate` boolean, required
  - `email` string, required
  - `status` string, required

## Other responses

- `400`: Malformed request
- `404`: Unknown identity email

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)