--- title: Stripe REST API Reference description: "This page documents every [REST](https://namazustudios.com/glossary/rest/) endpoint exposed by the [Stripe](stripe) [Element](https://namazustudios.com/glossary/element/). All paths are relative to the configured RS root, `dev.getelements.elements.Element.rs.root` (default `/Element/stripe/api`) — so `/stripe/payment-intent` below means `/Element/stripe/api/stripe/payment-intent` on a default deployment. Every endpoint except the webhook receiver requires…" url: "https://namazustudios.com/docs/add-ons/commerce/stripe/stripe-rest-api-reference/" updated: "2026-08-14" category: "Add-Ons / Commerce / Stripe" --- # Stripe REST API Reference This page documents every [REST](https://namazustudios.com/glossary/rest/) endpoint exposed by the [Stripe](stripe) [Element](https://namazustudios.com/glossary/element/). All paths are relative to the configured RS root, `dev.getelements.elements.Element.rs.root` (default `/Element/stripe/api`) — so `/stripe/payment-intent` below means `/Element/stripe/api/stripe/payment-intent` on a default deployment. Every endpoint except the webhook receiver requires the `session_secret` security scheme. The full OpenAPI document is served at `/api/REST/openapi.json` once the [Element](https://namazustudios.com/glossary/element/) is running. --- ## Webhook | Method | Path | Auth | Description | | --- | --- | --- | --- | | `POST` | `/stripe/webhook` | None (signature-verified) | Receives and verifies a Stripe webhook, then publishes typed and raw internal events. See [Stripe Webhooks and the Typed Event Bus](stripe-webhooks-and-events). | --- ## Customers | Method | Path | Request | Response | Description | | --- | --- | --- | --- | --- | | `PATCH` | `/stripe/customer/{customerId}` | `UpdateCustomerRequest` | `204 No Content` | Updates a customer's email and/or display [name](https://namazustudios.com/glossary/name/). `null` fields are left unchanged. | | `GET` | `/stripe/customers/search?key=&value=` | — | `CreateCustomerResponse` | Finds a customer by a [Metadata](https://namazustudios.com/glossary/metadata/) key/value pair. Returns `404` if none match. Use `key=orgId` for find-or-create. | | `POST` | `/stripe/customer/{customerId}/portal-Session?returnUrl=` | — | `CreatePortalSessionResponse` | Creates a single-use Stripe Customer Portal [Session](https://namazustudios.com/glossary/session/) URL. | `UpdateCustomerRequest(String email, String name)`. `CreateCustomerResponse(String customerId)`. `CreatePortalSessionResponse(String url)`. --- ## Payments | Method | Path | Request | Response | Description | | --- | --- | --- | --- | --- | | `POST` | `/stripe/payment-intent` | `CreatePaymentIntentRequest` | `CreatePaymentIntentResponse` | Creates a PaymentIntent for a one-off charge and returns its client secret. | `CreatePaymentIntentRequest(long amount, String currency, String customerId, String description, Map Metadata, Boolean automaticPaymentMethods, String setupFutureUsage, String idempotencyKey)` — `amount` is in the currency's smallest unit (e.g. cents); `customerId` may be `null` for guest checkouts; `setupFutureUsage` set to `"off_session"` saves the payment method for later charges. `CreatePaymentIntentResponse(String paymentIntentId, String clientSecret)`. --- ## Subscriptions | Method | Path | Request | Response | Description | | --- | --- | --- | --- | --- | | `POST` | `/stripe/customer/{customerId}/subscription` | `CreateSubscriptionRequest` | `SubscriptionStatusResponse` | Creates a recurring subscription. The customer must already have a default payment method on file. | | `GET` | `/stripe/subscription/{subscriptionId}` | — | `SubscriptionStatusResponse` | Gets the current status of a subscription. | | `DELETE` | `/stripe/subscription/{subscriptionId}` | — | `SubscriptionStatusResponse` | Immediately cancels a subscription; the customer loses access at once. Returned status is `canceled`. | | `GET` | `/stripe/customer/{customerId}/subscriptions?status=&limit=10&startingAfter=` | — | `SubscriptionListResponse` | Lists subscriptions for a customer, newest first. `status` is a Stripe status filter (e.g. `active`, `canceled`, `all`); omitted uses Stripe's default of non-canceled only. | `CreateSubscriptionRequest(String priceId, String description, Map Metadata, String idempotencyKey)` — factory `of(priceId)` covers the common case. `SubscriptionStatusResponse(String subscriptionId, String status, String currentPeriodEnd)`. `SubscriptionListResponse(List subscriptions, boolean hasMore, String nextCursor)` — pass `nextCursor` back as `startingAfter` to page. --- ## Checkout and Invoices | Method | Path | Request | Response | Description | | --- | --- | --- | --- | --- | | `POST` | `/stripe/checkout-Session` | `CreateCheckoutSessionRequest` | `CreateCheckoutSessionResponse` | Creates a Stripe-hosted Checkout [Session](https://namazustudios.com/glossary/session/) and returns its URL. | | `GET` | `/stripe/customer/{customerId}/invoices?limit=10&startingAfter=` | — | `List` | Lists invoices for a customer, newest first, with cursor pagination. | `CreateCheckoutSessionRequest(String customerId, String priceId, String successUrl, String cancelUrl, String mode, String idempotencyKey, Map Metadata)` — `mode` defaults to `subscription` if `null`; use `payment` for a one-off charge. `CreateCheckoutSessionResponse(String sessionId, String url)`. `InvoiceSummary(String id, String subscriptionId, Long amountPaid, String currency, String status, String createdAt)` — `status` is one of `draft`, `open`, `paid`, `uncollectible`, `void`. --- ## Catalogue: Products and Prices | Method | Path | Response | Description | | --- | --- | --- | --- | | `GET` | `/stripe/products?active=true&limit=100` | `List` | Lists products from the Stripe catalogue. | | `GET` | `/stripe/prices?productId=&active=true&limit=100` | `List` | Lists prices, optionally filtered by product. Cached in memory (TTL: `dev.getelements.elements.stripe.price.cache.ttl.ms`). | | `GET` | `/stripe/prices/{priceId}` | `PriceSummary` | Retrieves a single price by [id](https://namazustudios.com/glossary/id/) directly, without needing its product [id](https://namazustudios.com/glossary/id/). | `ProductSummary(String id, String name, String description, boolean active, PriceSummary defaultPrice)` — `active: false` means archived. `PriceSummary(String id, String productId, String nickname, Long unitAmount, String currency, String type, String interval)` — `unitAmount` is `null` for usage-based prices; `type` is `one_time` or `recurring`; `interval` is `day`, `week`, `month`, or `year` for recurring prices, otherwise `null`. --- ## Billing Meters | Method | Path | Request | Response | Description | | --- | --- | --- | --- | --- | | `POST` | `/stripe/meter-event` | `RecordMeterEventRequest` | `204 No Content` | Reports a usage event to a Stripe Billing Meter. Throws `NoSuchMeterException` (surfaced as an error response) if Stripe has no active meter for the given event [name](https://namazustudios.com/glossary/name/). | `RecordMeterEventRequest(String customerId, String eventName, BigDecimal value, String idempotencyKey)` — `value` must be greater than zero; a `long`-value convenience constructor exists for whole-unit usage. The `idempotencyKey` is used both as Stripe's own meter-event deduplication identifier and as the HTTP idempotency key, so retrying with the same key never double-reports usage. Note `listMeters` and both overloads of `resolvePriceForMeterEventName` — the meter-to-price join described in [Stripe → Products, Prices, and Billing Meters](stripe#h-products-prices-and-billing-meters) — are `StripeService` methods only. There is no [REST](https://namazustudios.com/glossary/rest/) endpoint for them; call them from an [Element](https://namazustudios.com/glossary/element/) that depends on the Stripe `api` module. --- ## Configuration and Event Log (Superuser) | Method | Path | Request | Response | Description | | --- | --- | --- | --- | --- | | `GET` | `/stripe/config` | — | `StripeConfig` | Returns the effective Stripe credentials with values masked (e.g. `••••1234`). | | `PUT` | `/stripe/config` | `StripeConfig` | `{"saved":true}` | Persists Stripe credentials to the database, overriding the deployment's attributes. | | `GET` | `/stripe/events?type=&limit=20&offset=0` | — | `StripeEventLogResponse` | Lists received webhook events, newest first, with type filtering and offset pagination. | `StripeConfig(String apiKey, String webhookSecret)`. `StripeEventLogResponse(List events, long total, boolean hasMore)`, where `StripeEventLogEntry(String stripeEventId, String eventType, String receivedAt)`. See [Configuring the Stripe Element](configuring-the-stripe-element) for credential precedence. --- ## [Service](https://namazustudios.com/glossary/service/)-Only Methods Not every `StripeService` capability is exposed over [REST](https://namazustudios.com/glossary/rest/). The following are reachable only by injecting `StripeService` from another [Element](https://namazustudios.com/glossary/element/) that depends on Stripe's `api` module — there is deliberately no HTTP surface for them, either because they're building blocks for server-side flows (customer/payment-method setup ahead of a charge) or because they're only meaningful to trusted server code (recording a receipt from inside the webhook handler): - `createCustomer(email, name, orgId)` - `createSetupIntent(customerId)` - `listPaymentMethods(customerId)` / `hasPaymentMethod(customerId)` - `getProduct(productId)` - `listMeters(activeOnly, limit)` - `resolvePriceForMeterEventName(eventName)` and `resolvePriceForMeterEventName(eventName, subscriptionId)` - `recordPaymentReceipt(transactionId, amount, currency, userId)` — called internally by the webhook handler; not intended to be called from arbitrary server code --- ## Related Pages - [Stripe](stripe) — [Element](https://namazustudios.com/glossary/element/) overview and core concepts - [Configuring the Stripe Element](configuring-the-stripe-element) — attributes and credential precedence - [Stripe Webhooks and the Typed Event Bus](stripe-webhooks-and-events) — the webhook endpoint and typed events in detail