Logto Cloud

Logto Cloud service package.

Local Development Guides

Stripe Subscription Development

This section covers setting up Stripe for local subscription debugging.

After completing the Cloud configuration and seeding the database, the logto_skus table will contain all Logto SKUs. Before starting debugging, you need to create corresponding products in Stripe for each SKU and sync the associations to the local stripe_products table via webhooks.

Stripe Prerequisites

1. Register and log in to a Stripe account (https://stripe.com/).
2. Install Stripe CLI (official documentation: https://docs.stripe.com/stripe-cli).

Configure Environment Variables

Prepare the following in your local environment:

• STRIPE_API_KEY: Switch to Test mode in Stripe Console, copy the secret key from the "For developers" section under "Get started with Stripe" on the homepage for local testing.
• STRIPE_WEBHOOK_SECRET:
  1. First configure STRIPE_API_KEY, then run stripe login to log in to Stripe CLI.
  2. Execute pnpm cli stripe listen --target localhost:3003/api/webhook/stripe in the packages/cloud directory to forward Stripe webhook events to your local environment (modify --target accordingly if using a custom port or address).
  3. The terminal will output Your webhook signing secret is ${WEBHOOK_SECRET}, add this value to your environment variables.
  4. If Cloud is currently running, restart it (or wait for automatic reload in development mode) to load the latest variables.

Associate Logto SKUs with Stripe Products

Once environment variables are ready, you can use one of the following two methods to create and associate Stripe products for each SKU. Both methods will write products to the local stripe_products table via webhooks.

[!NOTE] Default SKUs are already seeded in the logto_skus table. If you need to add a new SKU, you must insert the record into logto_skus first before creating its corresponding Stripe product.

Method 1: Using Project CLI (Recommended)

1. Find the target sku id in the database's logto_skus table.

2. Run the command to create a product in the packages/cloud directory. For example, to create a product named "Pro Plan 202509" with a unit price of 1600 ($16) for the SKU whose ID is pro-202509:

   pnpm cli stripe upsert-product --skuId "pro-202509" --name "Pro Plan 202509" --unitPrice "1600"

3. After execution, the Stripe product will sync to the local database via webhook. Check the stripe_products table to confirm the record has been written.

[!TIP] You can use AI to generate the complete set of upsert-product commands and execute them in batch.

Method 2: Create via Stripe Console

1. Find the target sku id in the database's logto_skus table.
2. In Stripe Console's Test mode, create a new product with:
   • Product name: e.g., "Pro Plan 202509"
   • Pricing: Set up monthly recurring pricing (or one-time for add-ons)
   • Metadata: Crucially, add a metadata field with key logtoSkuId and value matching the SKU ID from step 1 (e.g., pro-202509)
3. Keep stripe listen running. The product creation event will be forwarded to your local webhook endpoint and automatically sync to the stripe_products table.
4. Verify the record in the stripe_products table to confirm the association.

[!IMPORTANT] The webhook relies on the logtoSkuId metadata field to associate the Stripe product with the corresponding Logto SKU. Without this metadata, the webhook will fail.

Once all SKU product associations are complete, you can develop and debug Subscription-related features locally.