fastify-xadmin

Stripe Management Routes

Admin Stripe endpoints for viewing and managing a customer's subscription and billing data — GET/POST /api/admin/stripe/:customerId.

Stripe Management Routes

Admin endpoints for reading and acting on a Stripe customer's subscription and billing state. These routes proxy authenticated Stripe API calls so admins can manage billing without leaving the admin portal.

Requires stripeSecretKey at plugin registration:

await fastify.register(xAdmin, {
  prefix: "/api/admin",
  stripeSecretKey: process.env.STRIPE_SECRET_KEY,
  requireRole: "superadmin",
});

Routes

GET   /api/admin/stripe/:customerId   Fetch customer billing summary
POST  /api/admin/stripe/:customerId   Perform a billing action on the customer

GET /api/admin/stripe/:customerId

Retrieve a Stripe customer's billing summary: customer record, active subscriptions, and recent invoices.

Usage

const response = await fetch(`/api/admin/stripe/${customerId}`, {
  headers: { Authorization: `Bearer ${adminToken}` },
});
const data = await response.json();

Path Parameters

Name	Type	Required	Description
`customerId`	`string`	Yes	Stripe customer ID (`cus_...`).

Response

{
  "customer": {
    "id": "cus_abc123",
    "email": "user@example.com",
    "name": "Alice Smith",
    "balance": 0
  },
  "subscriptions": [
    {
      "id": "sub_xyz",
      "status": "active",
      "planId": "price_monthly_pro",
      "currentPeriodEnd": "2025-05-19T00:00:00.000Z",
      "cancelAtPeriodEnd": false
    }
  ],
  "invoices": [
    {
      "id": "in_001",
      "status": "paid",
      "amountDue": 2900,
      "currency": "usd",
      "created": "2025-04-01T00:00:00.000Z",
      "hostedInvoiceUrl": "https://invoice.stripe.com/..."
    }
  ]
}

POST /api/admin/stripe/:customerId

Perform a billing action for the customer. The action field in the body determines which Stripe operation is executed.

Usage

// Cancel a subscription at period end
const response = await fetch(`/api/admin/stripe/${customerId}`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${adminToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    action: "cancel_subscription",
    subscriptionId: "sub_xyz",
  }),
});
const result = await response.json();

Path Parameters

Name	Type	Required	Description
`customerId`	`string`	Yes	Stripe customer ID (`cus_...`).

Body Fields

Field	Type	Required	Description
`action`	`string`	Yes	Action to perform. See supported actions below.
`subscriptionId`	`string`	Depends	Required for subscription-scoped actions.

Supported Actions

Action	Description
`cancel_subscription`	Cancel the subscription at the end of the current billing period (`cancel_at_period_end: true`).
`cancel_subscription_immediately`	Cancel the subscription immediately with no proration.
`reactivate_subscription`	Undo a pending cancellation (sets `cancel_at_period_end: false`).

Response

Returns the updated Stripe object for the performed action, or a confirmation object:

{ "success": true, "action": "cancel_subscription", "subscriptionId": "sub_xyz" }

AI Context

package: "@xenterprises/fastify-xadmin"
routes:
  - GET /api/admin/stripe/:customerId — billing summary (customer, subscriptions, invoices)
  - POST /api/admin/stripe/:customerId — billing actions (cancel, reactivate subscription)
requires: stripeSecretKey passed at plugin registration
env: STRIPE_SECRET_KEY
auth: requires the admin role set at plugin registration