Stripe

​

At a glance

npx @deploybaseline/cli start --service stripe

import { createEmulator } from "@deploybaseline/cli";

const stripe = await createEmulator({ service: "stripe" });
// stripe.url is http://localhost:4000

{
  "stripe": {
    "customers": [
      {
        "email": "[email protected]",
        "name": "Test Customer"
      }
    ],
    "products": [
      {
        "name": "Pro Plan",
        "description": "Monthly pro subscription"
      }
    ],
    "prices": [
      {
        "product_name": "Pro Plan",
        "currency": "usd",
        "unit_amount": 2000,
        "recurring": {
          "interval": "month"
        }
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service stripe

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  host: "localhost",
  port: 4009,
  protocol: "http",
});

curl http://localhost:4009/v1/customers \
  -H "Authorization: Bearer sk_test_baselined"

​

Requests

• Idempotency. A POST with an Idempotency-Key header (1 to 255 characters) saves its result for 24 hours. A retry with the same key and the same parameters gets the saved response back with Idempotent-Replayed: true and Original-Request: <first request id>, without running the endpoint again, so no second object or event is created. The same key with other parameters, or on another endpoint, gets a 400 idempotency_error (Stripe.errors.StripeIdempotencyError in stripe-node). A retry while the first request is still running gets a 409 idempotency_key_in_use. A request that fails validation (a 4xx other than 402) is not saved, so the key can be retried with fixed parameters. stripe-node adds a key to every POST on its own.
• Request IDs. Every response carries a Request-Id: req_... header (lastResponse.requestId in stripe-node).
• Expand. expand[] works on query strings and request bodies, including create and update calls. Lists take data.<field>, e.g. expand[]=data.customer. A field that cannot be expanded returns 400 This property cannot be expanded (<field>).
• Metadata. Updates merge metadata into what is stored. Set a key to "" to remove it, or send metadata="" to clear all keys. Metadata values always stay strings.
• Form values. Booleans sent as true / false are decoded, so active=false stores a boolean.

​

Customers

• POST /v1/customers — Create customer
• GET /v1/customers/:id — Retrieve customer
• POST /v1/customers/:id — Update customer
• DELETE /v1/customers/:id — Delete customer
• GET /v1/customers — List customers

​

Customer balance

• POST /v1/customers/:id/balance_transactions — Adjust customer balance: by amount (negative is credit) in currency, with description and metadata
• GET /v1/customers/:id/balance_transactions/:txn — Retrieve balance transaction
• POST /v1/customers/:id/balance_transactions/:txn — Update balance transaction: description, metadata
• GET /v1/customers/:id/balance_transactions — List balance transactions: the ledger, newest first (filter by invoice)

​

Payment methods

• POST /v1/payment_methods — Create payment method: a card from a test token (type=card, card[token]=tok_visa; billing_details, metadata optional)
• GET /v1/payment_methods/:id — Retrieve payment method
• POST /v1/payment_methods/:id — Update payment method: billing_details, metadata, or card[exp_month] / card[exp_year] (attached payment methods only)
• POST /v1/payment_methods/:id/attach — Attach payment method: to a customer
• POST /v1/payment_methods/:id/detach — Detach payment method: from its customer
• GET /v1/payment_methods — List payment methods: customer, type; without customer, unattached ones
• GET /v1/customers/:id/payment_methods — List a customer’s payment methods
• GET /v1/customers/:id/payment_methods/:pm — Retrieve a customer’s payment method

​

Setup intents

• POST /v1/setup_intents — Create setup intent: customer, payment_method, usage default off_session, confirm, return_url, description, metadata
• GET /v1/setup_intents/:id — Retrieve setup intent
• POST /v1/setup_intents/:id — Update setup intent: customer, payment_method, description, metadata
• POST /v1/setup_intents/:id/confirm — Confirm setup intent: payment_method, return_url optional
• POST /v1/setup_intents/:id/cancel — Cancel setup intent: cancellation_reason optional
• GET /v1/setup_intents — List setup intents: filter by customer, payment_method

​

Customer sessions

• POST /v1/customer_sessions — Create customer session

​

Payment intents

• POST /v1/payment_intents — Create payment intent
• GET /v1/payment_intents/:id — Retrieve payment intent
• POST /v1/payment_intents/:id — Update payment intent
• POST /v1/payment_intents/:id/confirm — Confirm payment intent
• POST /v1/payment_intents/:id/capture — Capture payment intent: an authorized one (amount_to_capture optional)
• POST /v1/payment_intents/:id/cancel — Cancel payment intent: cancellation_reason optional
• GET /v1/payment_intents — List payment intents

​

Test cards

​

3D Secure

curl -X POST http://localhost:4009/_stripe/3ds/pi_xxx \
  -H "Accept: application/json" -d "outcome=complete"

​

Charges

• GET /v1/charges/:id — Retrieve charge
• GET /v1/charges — List charges

​

Refunds

• POST /v1/refunds — Create refund: of a captured payment, by payment_intent or charge (amount, reason, metadata optional)
• GET /v1/refunds/:id — Retrieve refund
• POST /v1/refunds/:id — Update refund metadata
• POST /v1/refunds/:id/cancel — Cancel refund: refunds succeed at once here, so this returns Stripe’s error for a refund that is not pending
• GET /v1/refunds — List refunds: filter by charge, payment_intent

​

Balance

• GET /v1/balance — Retrieve balance: available and pending funds per currency
• GET /v1/balance_transactions/:id — Retrieve balance transaction: expand[]=source
• GET /v1/balance_transactions — List balance transactions: filter by type, source, currency, created

​

Disputes

• GET /v1/disputes/:id — Retrieve dispute
• POST /v1/disputes/:id — Update dispute: stage or submit evidence, update metadata
• POST /v1/disputes/:id/close — Close dispute: accept it
• GET /v1/disputes — List disputes: filter by charge, payment_intent

​

Connect

• POST /v1/accounts — Create connected account: type (standard, the default, express, or custom) or controller (stripe_dashboard[type] of full, express, or none), country, email, business_type, business_profile, capabilities, tos_acceptance, external_account, metadata
• GET /v1/accounts/:id — Retrieve connected account
• POST /v1/accounts/:id — Update connected account
• DELETE /v1/accounts/:id — Delete connected account
• GET /v1/accounts — List connected accounts
• GET /v1/account — Retrieve current account: the account in Stripe-Account, or the platform (acct_baseline) without it
• POST /v1/account_links — Create account link: hosted onboarding (account_onboarding, or account_update for Custom accounts) with refresh_url and return_url
• POST /v1/accounts/:id/login_links — Create login link: an Express dashboard link, for onboarded Express accounts
• POST /v1/transfers — Create transfer
• GET /v1/transfers/:id — Retrieve transfer
• POST /v1/transfers/:id — Update transfer: description, metadata
• GET /v1/transfers — List transfers: filter by destination, transfer_group
• GET /v1/application_fees/:id — Retrieve application fee
• GET /v1/application_fees — List application fees: filter by charge

• Direct charge (with Stripe-Account): the charge is the account’s. application_fee_amount is taken out of its balance transaction (fee_details lists stripe_fee and application_fee) and paid to the platform as an application fee (application_fee.created).
• Destination charge (transfer_data[destination]): the charge is the platform’s. The amount, or transfer_data[amount], is transferred to the account (transfer.created, the charge’s transfer), and application_fee_amount comes back to the platform out of the account’s payment. The destination must be onboarded with transfers (insufficient_capabilities_for_transfer). application_fee_amount without either returns 400, as does combining it with transfer_data[amount].
• Separate charges and transfers: POST /v1/transfers needs that much available platform balance (balance_insufficient; pay with pm_card_bypassPending to skip the pending period), or a source_transaction charge, whose funds it waits for.

​

Products

• POST /v1/products — Create product
• GET /v1/products/:id — Retrieve product
• GET /v1/products — List products

​

Prices

• POST /v1/prices — Create price: unit_amount required; recurring, lookup_key, nickname optional
• GET /v1/prices/:id — Retrieve price
• GET /v1/prices — List prices: filter by product, active, type, lookup_keys[]

​

Coupons and promotion codes

• POST /v1/coupons — Create coupon: percent_off or amount_off with currency, duration (once, repeating with duration_in_months, or forever), max_redemptions, redeem_by, applies_to[products][], id (otherwise a random code), name
• GET /v1/coupons/:id — Retrieve coupon: expand[]=applies_to shows its products
• POST /v1/coupons/:id — Update coupon: name or metadata (other fields cannot change)
• DELETE /v1/coupons/:id — Delete coupon: discounts already made from it keep applying
• GET /v1/coupons — List coupons
• POST /v1/promotion_codes — Create promotion code: for a coupon (promotion[coupon], or coupon for older clients) with code (otherwise random), customer, expires_at, max_redemptions, active, and restrictions (first_time_transaction, minimum_amount with minimum_amount_currency)
• GET /v1/promotion_codes/:id — Retrieve promotion code
• POST /v1/promotion_codes/:id — Update promotion code: active, metadata
• GET /v1/promotion_codes — List promotion codes: filter by active, code, coupon, customer

• A subscription’s discounts apply to each of its invoices. Without its own discounts, a subscription uses the customer’s discount. Invoices take the subscription’s or customer’s discounts unless discounts is given (discounts="" opts out).
• Percentages come off the discountable lines; amount_off comes off up to their total. Several discounts apply in order. Each invoice line reports its share in discount_amounts, and the invoice reports total_discount_amounts, discounts, and total. Proration lines and invoice items with discountable=false are not discounted, and applies_to limits a coupon to its products.
• once applies to the first invoice with something to discount. repeating applies to invoices made within duration_in_months of the discount’s start (the end), so on a test clock a three-month coupon covers three monthly renewals. forever never ends. A discount that has ended is removed when the next invoice finalizes, with customer.discount.deleted.
• Previews (create_preview) apply the same discounts and accept discounts to try one out.

​

Tax rates

• POST /v1/tax_rates — Create tax rate: display_name, percentage, inclusive (all required), country, state, jurisdiction, tax_type, description, active
• GET /v1/tax_rates/:id — Retrieve tax rate
• POST /v1/tax_rates/:id — Update tax rate: anything but percentage and inclusive; active: false archives it
• GET /v1/tax_rates — List tax rates: filter by active, inclusive

​

Invoices

• POST /v1/invoices — Create invoice: a draft for a customer. pending_invoice_items_behavior=include takes the customer’s pending items (the default, as on Stripe, is exclude). With subscription, it takes only that subscription’s pending items; without it, only items not tied to a subscription
• POST /v1/invoices/create_preview — Preview invoice: without making it (see Invoice previews)
• GET /v1/invoices/:id — Retrieve invoice
• POST /v1/invoices/:id — Update invoice: a draft (description, metadata, auto_advance, collection_method, days_until_due, due_date, default_payment_method). Open invoices take only metadata and auto_advance; others only metadata
• DELETE /v1/invoices/:id — Delete draft invoice: its items go back to pending
• POST /v1/invoices/:id/finalize — Finalize invoice: a draft
• POST /v1/invoices/:id/pay — Pay invoice: an open, uncollectible, or draft one (payment_method, off_session, paid_out_of_band)
• POST /v1/invoices/:id/send — Send invoice: a send_invoice invoice (finalizes a draft first)
• POST /v1/invoices/:id/void — Void invoice: an open or uncollectible one
• POST /v1/invoices/:id/mark_uncollectible — Mark invoice uncollectible: an open one
• GET /v1/invoices/:id/lines — List invoice lines: paginated
• GET /v1/invoices — List invoices: filter by customer, subscription, status, collection_method, created

​

Invoice items

• POST /v1/invoiceitems — Create invoice item: for a customer, priced by amount (negative for a credit), unit_amount_decimal with quantity, pricing[price], or price_data. invoice puts it on a draft invoice; otherwise it waits as pending
• GET /v1/invoiceitems/:id — Retrieve invoice item
• POST /v1/invoiceitems/:id — Update invoice item: amount, quantity, pricing, period, description, or metadata
• DELETE /v1/invoiceitems/:id — Delete invoice item
• GET /v1/invoiceitems — List invoice items: filter by customer, invoice, pending

​

Automatic collection

• A draft finalizes an hour after it was created (automatically_finalizes_at), and a charge_automatically invoice is charged off-session right away.
• After a manual finalize, the first charge is an hour later (next_payment_attempt).
• A failed charge (including no payment method) sends invoice.payment_failed and retries 3, 5, and 7 days after the previous attempt, four attempts in all. After the last, next_payment_attempt is null and the invoice stays open. The retry days can be changed in seed config (billing.retry_days).
• A send_invoice invoice sends invoice.overdue once its due_date passes.
• auto_advance: false on an open invoice stops collection; setting it back schedules a charge an hour later.

​

Invoice previews

• subscription alone previews the next renewal, with the pending items it would take.
• subscription with subscription_details (items, proration_behavior, proration_date, billing_cycle_anchor, trial_end, cancel_at, cancel_at_period_end, cancel_now) previews a change. With always_invoice, a new cycle, or cancel_now, it is the invoice made at once; otherwise it is the next renewal with the change’s prorations on it.
• customer with subscription_details[items] previews the first invoice of a new subscription.
• customer alone previews an invoice of the customer’s pending items.

​

Credit notes

• POST /v1/credit_notes — Create credit note: credit a finalized invoice by lines or amount, with refund_amount, credit_amount, out_of_band_amount, refunds, reason, memo, metadata
• GET /v1/credit_notes/preview — Preview credit note: the same, without issuing it
• GET /v1/credit_notes/preview/lines — Preview credit note lines
• GET /v1/credit_notes/:id — Retrieve credit note
• GET /v1/credit_notes/:id/lines — List credit note lines
• POST /v1/credit_notes/:id — Update credit note: memo or metadata
• POST /v1/credit_notes/:id/void — Void credit note
• GET /v1/credit_notes — List credit notes: filter by invoice, customer

​

Subscriptions

• POST /v1/subscriptions — Create subscription: for a customer with items (each a recurring price or price_data, with quantity)
• GET /v1/subscriptions/:id — Retrieve subscription
• POST /v1/subscriptions/:id — Update subscription: change items, quantities, trial, anchor, cancellation, collection, payment method, or metadata
• DELETE /v1/subscriptions/:id — Cancel subscription: now (invoice_now, prorate, cancellation_details)
• POST /v1/subscriptions/:id/pause — Pause subscription: type=subscription
• POST /v1/subscriptions/:id/resume — Resume subscription: a paused one (billing_cycle_anchor, proration_behavior, payment_behavior)
• GET /v1/subscriptions — List subscriptions: filter by customer, price, status, collection_method, test_clock

• allow_incomplete (the default) charges the default card. On success the subscription is active; on a decline it stays incomplete with the invoice open.
• error_if_incomplete returns the card’s 402 error and creates nothing when the charge would fail.
• default_incomplete leaves the subscription incomplete so the client pays it: expand latest_invoice.confirmation_secret and confirm it with Stripe.js.

• create_prorations (the default) creates pending invoice items: a credit for the unused time on what was last billed and a charge for the remaining time on the new items, prorated to the second (proration_date sets the time). They are billed on the next invoice.
• always_invoice invoices the prorations at once and collects them.
• none changes the items without prorations.

const sub = await stripe.subscriptions.create({
  customer: customer.id,
  items: [{ price: price.id, quantity: 2 }],
  trial_period_days: 14,
});
await stripe.subscriptions.update(sub.id, {
  items: [{ id: sub.items.data[0].id, quantity: 3 }],
  proration_behavior: "always_invoice",
});

​

Subscription items

• POST /v1/subscription_items — Add subscription item: to a subscription (price or price_data, quantity, proration_behavior)
• GET /v1/subscription_items/:id — Retrieve subscription item
• POST /v1/subscription_items/:id — Update subscription item: change its price or quantity
• DELETE /v1/subscription_items/:id — Delete subscription item: a subscription keeps at least one item
• GET /v1/subscription_items?subscription= — List subscription items: a subscription’s items

​

Test clocks

• POST /v1/test_helpers/test_clocks — Create test clock: at frozen_time (name optional; customer moves an existing customer onto it, and then the time cannot be in the past)
• GET /v1/test_helpers/test_clocks/:id — Retrieve test clock
• POST /v1/test_helpers/test_clocks/:id/advance — Advance test clock: move it forward to frozen_time
• DELETE /v1/test_helpers/test_clocks/:id — Delete test clock: with its customers and their invoices
• GET /v1/test_helpers/test_clocks — List test clocks

const clock = await stripe.testHelpers.testClocks.create({ frozen_time: 1767225600 });
const customer = await stripe.customers.create({ test_clock: clock.id, payment_method: "pm_card_visa",
  invoice_settings: { default_payment_method: "pm_card_visa" } });
// ... create an auto-advancing invoice, then:
await stripe.testHelpers.testClocks.advance(clock.id, { frozen_time: 1767225600 + 3600 });

​

Checkout

• POST /v1/checkout/sessions — Create Checkout session
• GET /v1/checkout/sessions/:id — Retrieve Checkout session
• POST /v1/checkout/sessions/:id/expire — Expire Checkout session
• GET /v1/checkout/sessions — List Checkout sessions: filter by customer, status, payment_status
• GET /checkout/:id — Hosted checkout page: HTML
• POST /checkout/:id/complete — Complete payment flow

​

Events

• GET /v1/events — List events: newest first. Filter by type (exact, or a wildcard such as customer.*), types[] (up to 20 exact types, not with type), created (exact or gt, gte, lt, lte), and delivery_success
• GET /v1/events/:id — Retrieve event

​

Webhooks

​

Webhook endpoints

• POST /v1/webhook_endpoints — Create webhook endpoint: url and enabled_events required; description, metadata, api_version optional
• GET /v1/webhook_endpoints/:id — Retrieve webhook endpoint
• POST /v1/webhook_endpoints/:id — Update webhook endpoint: url, enabled_events, description, metadata, or disabled
• DELETE /v1/webhook_endpoints/:id — Delete webhook endpoint
• GET /v1/webhook_endpoints — List webhook endpoints

​

Deliveries and event types

• Webhooks configured with a secret include Stripe-Signature: t=<timestamp>,v1=<signature>, signed over <timestamp>.<raw body>
• Each event is a full Stripe event object: id (evt_...), object: "event", api_version (2026-09-30.endive), created, livemode: false, pending_webhooks, type, data.object, and request with the id and idempotency_key of the API call that caused it. *.updated events include data.previous_attributes with the old values of the fields that changed.
• customer.created, customer.updated, customer.deleted
• product.created, price.created
• payment_method.attached, payment_method.detached, payment_method.updated
• setup_intent.created, setup_intent.requires_action, setup_intent.succeeded, setup_intent.setup_failed, setup_intent.canceled
• payment_intent.created, payment_intent.requires_action, payment_intent.amount_capturable_updated, payment_intent.succeeded, payment_intent.payment_failed, payment_intent.canceled
• charge.succeeded (the full charge object) when a payment intent is confirmed, charge.failed, charge.captured, charge.refunded
• refund.created, refund.updated
• charge.dispute.created, charge.dispute.updated, charge.dispute.closed, charge.dispute.funds_withdrawn, charge.dispute.funds_reinstated
• account.updated (to Connect endpoints, with account), application_fee.created, transfer.created, transfer.updated
• invoiceitem.created, invoiceitem.deleted
• invoice.created, invoice.updated, invoice.deleted, invoice.finalized, invoice.sent, invoice.paid, invoice.payment_succeeded, invoice.payment_failed, invoice.payment_action_required, invoice.voided, invoice.marked_uncollectible, invoice_payment.paid
• invoice.overdue when a send_invoice invoice passes its due date
• invoice.upcoming three days before a subscription renews
• customer.subscription.created, customer.subscription.updated, customer.subscription.deleted (when a subscription is canceled or expires), customer.subscription.trial_will_end, customer.subscription.paused, customer.subscription.resumed
• test_helpers.test_clock.created, test_helpers.test_clock.advancing, test_helpers.test_clock.ready, test_helpers.test_clock.deleted
• customer.updated also fires when finalizing or voiding an invoice changes the customer balance
• checkout.session.completed when a checkout session is completed
• checkout.session.expired when a checkout session expires

​

Seed config

{
  "stripe": {
    "customers": [
      {
        "email": "[email protected]",
        "name": "Test Customer"
      }
    ],
    "products": [
      {
        "name": "Pro Plan",
        "description": "Monthly pro subscription"
      }
    ],
    "prices": [
      {
        "product_name": "Pro Plan",
        "currency": "usd",
        "unit_amount": 2000,
        "recurring": {
          "interval": "month"
        }
      }
    ],
    "coupons": [
      {
        "id": "LAUNCH25",
        "percent_off": 25,
        "duration": "repeating",
        "duration_in_months": 3
      }
    ],
    "promotion_codes": [
      {
        "code": "SPRING",
        "coupon": "LAUNCH25",
        "first_time_transaction": true
      }
    ],
    "tax_rates": [
      {
        "id": "txr_sales",
        "display_name": "Sales tax",
        "percentage": 8.25
      }
    ],
    "accounts": [
      {
        "id": "acct_shop",
        "type": "express",
        "business_name": "Shop"
      }
    ],
    "billing": {
      "retry_days": [3, 5, 7],
      "after_final_retry": "cancel"
    },
    "webhooks": [
      {
        "url": "http://localhost:3000/api/webhooks/stripe",
        "events": ["*"],
        "secret": "whsec_test"
      }
    ]
  }
}

• recurring: optional; omit for a one-time price
• coupons: optional; percent_off or amount_off (with currency)
• duration: once (the default), repeating, or forever
• promotion_codes: optional; customer-facing codes for seeded coupons
• first_time_transaction: optional restrictions
• tax_rates: optional; id, display_name, percentage, inclusive
• accounts: optional; connected accounts, onboarded unless onboarded: false
• type: standard (the default), express, or custom
• billing: optional; Stripe’s automatic collection settings
• retry_days: days between payment retries (the default)
• after_final_retry: subscription after the last retry: cancel, unpaid, or past_due

​

Limits

• Connect: transfer reversals, refunds of application fees (refund_application_fee, reverse_transfer), payouts, persons and external account objects, and automatic billing (auto_advance, wall clock renewals) for connected accounts outside their own requests.
• Coupons: discounts on single invoice items or invoice lines (400 parameter_unknown) and currency_options.
• Tax: Stripe Tax (automatic_tax[enabled]=true returns 400) and flat amount rates.
• Credit notes: shipping_cost and line tax_amounts.
• Invoices: hosted invoice pages and PDFs (hosted_invoice_url and invoice_pdf are null).
• Subscriptions: Stripe Tax, metered and tiered prices, subscription schedules, billing thresholds, pending_if_incomplete, trial_from_plan, and backdate_start_date. They return 400 parameter_unknown rather than being ignored.

​

Conformance