zuplo 6.67.32 → 6.68.0

package/docs/articles/monetization/stripe-integration.md

@@ -0,0 +1,195 @@
+---
+title: Stripe Integration
+sidebar_label: Stripe Integration
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+Zuplo uses Stripe to handle payment processing, subscription billing, and
+invoicing. Zuplo handles metering, quota enforcement, and subscription state —
+Stripe handles money.
+
+## How it works
+
+The integration flow:
+
+1. You define plans, features, and meters in Zuplo
+2. You connect your Stripe account via the Zuplo Portal
+3. When you publish plans, corresponding Stripe Products and Prices are created
+   automatically
+4. Customers subscribe through your Developer Portal via Stripe Checkout
+5. Stripe processes the payment and creates the subscription
+6. A Zuplo subscription is created with an API key scoped to the plan's
+   entitlements
+7. As the customer uses the API, the monetization policy meters usage in real
+   time
+8. For usage-based billing, usage is tracked continuously and billed through
+   Stripe automatically
+
+Throughout this flow, Zuplo is the source of truth for access control and
+metering. Stripe is the source of truth for payment state.
+
+## Connecting your Stripe account
+
+### Via the Zuplo Portal
+
+1. Navigate to **Services → Monetization Service → Payment Provider**
+2. Click **Configure** on the Stripe card
+3. Enter a **Name** and paste your **Stripe API Key**
+4. Click **Save**
+
+The connection authorizes Zuplo to manage Stripe objects on your behalf,
+including products, prices, customers, and subscriptions.
+
+### Test mode vs. live mode
+
+Connect with a Stripe **test** key (`sk_test_...`) first to validate your
+configuration end-to-end. Test mode uses Stripe's test card numbers (e.g.,
+`4242 4242 4242 4242`) and never charges real money.
+
+When you're ready to go live, update to your live key (`sk_live_...`).
+
+:::caution
+
+Always use your Stripe **test** key while developing. Test mode and live mode
+are separate environments in Stripe. Products, customers, and subscriptions
+don't transfer between them.
+
+:::
+
+## What Zuplo creates in Stripe
+
+When you publish a plan, corresponding objects are created in Stripe
+automatically:
+
+| Zuplo concept        | Stripe object created            |
+| -------------------- | -------------------------------- |
+| Plan                 | Product                          |
+| Rate card (flat fee) | Price (recurring, fixed amount)  |
+| Rate card (per-unit) | Price (recurring, metered usage) |
+| Rate card (tiered)   | Price (recurring, tiered)        |
+| Feature entitlement  | Metadata on the Product          |
+
+You can see these in your Stripe Dashboard under **Products**. These objects are
+managed automatically — don't edit them directly in Stripe, as your changes may
+be overwritten on the next plan publish.
+
+## Subscription flow
+
+### New subscription
+
+When a customer clicks "Subscribe" in your Developer Portal:
+
+1. A Stripe Checkout Session is created with the selected plan's prices
+2. The customer is redirected to Stripe Checkout to enter payment details
+3. On successful payment, the subscription is created
+4. An API key is generated scoped to the subscription's plan entitlements
+5. The customer is redirected back to the Developer Portal, where they can
+   immediately see their subscription, usage dashboard, and API key
+
+### Plan changes (upgrades/downgrades)
+
+When a customer changes their plan through the Developer Portal:
+
+1. The Stripe Subscription is updated with the new plan's prices
+2. Charges are prorated automatically
+3. The customer's entitlements update immediately
+4. The API key remains the same; its associated quota changes in real time
+
+Upgrades take effect immediately. Downgrades take effect at the next billing
+cycle.
+
+### Cancellation
+
+When a customer cancels:
+
+1. The subscription is set to cancel at the end of the current billing period
+   (by default)
+2. The customer retains access until their current billing period ends
+3. At period end, access is revoked and the API key stops working
+
+## Proration
+
+When customers upgrade or downgrade mid-billing-period, charges are prorated
+automatically. Upgrades are charged the prorated difference for the remainder of
+the billing period. Downgrades result in a prorated credit applied to the next
+invoice.
+
+## Usage-based billing
+
+For plans with usage-based pricing (per-unit, tiered, pay-as-you-go), usage is
+tracked in real time by the `MonetizationInboundPolicy`. Each API request
+increments the meter immediately. At the end of the billing period, usage is
+billed through Stripe automatically.
+
+You don't need to implement usage reporting or run any batch jobs.
+
+## Handling failed payments
+
+When Stripe fails to collect payment, access is determined by the subscription's
+payment status. By default, a 3-day grace period allows continued access while
+Stripe retries the payment.
+
+| Payment status  | Default behavior                                 |
+| --------------- | ------------------------------------------------ |
+| `paid`          | Full access                                      |
+| `not_required`  | Full access (free plans)                         |
+| `pending`       | Full access (within grace period)                |
+| `failed`        | Access blocked after grace period (configurable) |
+| `uncollectible` | Access blocked                                   |
+
+The grace period is configurable via `zuplo_max_payment_overdue_days` metadata
+on the plan or customer (default: 3 days).
+
+## Customer portal
+
+Stripe provides a hosted Customer Portal where customers can update their
+payment method, view invoices, and manage their subscription. The Developer
+Portal links to this from the subscription management page.
+
+To enable the Stripe Customer Portal:
+
+1. Configure the Customer Portal in your
+   [Stripe Dashboard → Settings → Billing → Customer Portal](https://dashboard.stripe.com/settings/billing/portal)
+2. Enable the features you want (update payment method, view invoices, cancel
+   subscription)
+3. The Developer Portal automatically includes a "Manage Billing" link that
+   opens the Stripe Customer Portal
+
+## Testing
+
+### Test card numbers
+
+Use Stripe's test card numbers to simulate different scenarios:
+
+| Card number           | Scenario                                 |
+| --------------------- | ---------------------------------------- |
+| `4242 4242 4242 4242` | Successful payment                       |
+| `4000 0000 0000 3220` | Requires 3D Secure authentication        |
+| `4000 0000 0000 0341` | Attaches to customer but fails on charge |
+| `4000 0000 0000 9995` | Declined (insufficient funds)            |
+
+### Verifying the integration
+
+After connecting Stripe and publishing plans:
+
+1. Open your Developer Portal
+2. Subscribe to a plan using test card `4242 4242 4242 4242`
+3. Verify in Stripe Dashboard:
+   - Customer created
+   - Subscription active
+   - Product and Price match your plan
+4. Make API requests and verify:
+   - Requests succeed within quota
+   - `403 Forbidden` returned when quota exceeded (hard limit plans)
+   - Usage visible in the Developer Portal dashboard
+5. Cancel the subscription and verify:
+   - Access revoked after billing period
+   - Stripe subscription shows canceled

package/docs/articles/monetization/subscription-lifecycle.md

@@ -0,0 +1,298 @@
+---
+title: Subscription Lifecycle
+sidebar_label: Subscription Lifecycle
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+This guide covers the full lifecycle of a customer subscription: creation,
+trials, upgrades, downgrades, cancellation, and reactivation.
+
+## Subscription states
+
+| Status      | API access | Description                                       |
+| ----------- | ---------- | ------------------------------------------------- |
+| `active`    | Yes        | Subscription is active and payment is current     |
+| `inactive`  | No         | Subscription is not yet active or was deactivated |
+| `canceled`  | No         | Subscription has been canceled                    |
+| `scheduled` | No         | Subscription is scheduled for future activation   |
+
+:::note
+
+Access is also governed by payment status. If a payment is overdue beyond the
+grace period (default 3 days, configurable via `zuplo_max_payment_overdue_days`
+metadata), access is blocked even for active subscriptions.
+
+:::
+
+## Creating subscriptions
+
+### Self-serve (Developer Portal)
+
+The standard path. Customer signs up in the Developer Portal, picks a plan,
+completes Stripe Checkout, and gets their API key immediately.
+
+1. Customer visits the pricing page
+2. Clicks "Subscribe" on their chosen plan
+3. Completes Stripe Checkout (enters payment details)
+4. Redirected back to the Developer Portal
+5. Subscription is active, API key is generated
+
+### Programmatic (API)
+
+Create subscriptions directly via the API for cases where the checkout happens
+outside the Developer Portal (custom frontend, sales-assisted onboarding,
+internal tooling):
+
+```bash
+curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions \
+  -H "Authorization: Bearer {API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customerId": "cus_abc123",
+    "planKey": "pro",
+    "stripeCustomerId": "cus_stripe_xyz"
+  }'
+```
+
+The `customerId` is the user's identifier in your auth system (Auth0 user ID,
+etc.). The `stripeCustomerId` is the customer's ID in Stripe.
+
+## Free trials
+
+Trials are modeled as the first phase of a multi-phase plan. No special trial
+API is needed.
+
+### How trials work
+
+1. Customer subscribes to a plan that has a trial phase
+2. The subscription is activated with the trial phase's entitlements (e.g.,
+   1,000 requests)
+3. When the trial phase duration expires:
+   - The subscription transitions to the next phase (the paid phase)
+   - Stripe charges the customer for the first paid period
+   - Entitlements update to the paid phase's rate cards
+4. If payment fails at trial end, access depends on the payment grace period
+   configuration
+
+### Trial configuration example
+
+**14-day trial with automatic conversion to paid:**
+
+```json
+{
+  "key": "pro-trial",
+  "name": "Pro with Free Trial",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "trial",
+      "name": "14-Day Free Trial",
+      "duration": "P2W",
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": null,
+          "price": null,
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": false
+          }
+        }
+      ]
+    },
+    {
+      "key": "default",
+      "name": "Pro Monthly",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "tiered",
+            "mode": "graduated",
+            "tiers": [
+              {
+                "upToAmount": "50000",
+                "flatPrice": { "type": "flat", "amount": "99.00" },
+                "unitPrice": null
+              },
+              {
+                "flatPrice": null,
+                "unitPrice": { "type": "unit", "amount": "0.50" }
+              }
+            ]
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 50000,
+            "isSoftLimit": true
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+This plan gives customers a 14-day trial with 1,000 requests (hard limit, no
+billing). When the trial ends, they automatically transition to the paid Pro
+phase at $99/month with 50,000 requests and overage billing. No cron jobs, no
+webhook handlers, no transition code.
+
+### What happens when a trial expires
+
+If the plan has a paid phase after the trial:
+
+- Stripe charges the customer automatically
+- On success: subscription transitions to the paid phase with paid entitlements
+- On failure: access depends on the payment grace period configuration
+
+If the customer cancels during the trial:
+
+- They retain trial access until the trial period ends
+- No payment is charged
+- After the trial period, access is revoked
+
+## Plan changes (upgrades and downgrades)
+
+### Customer-initiated (Developer Portal)
+
+Customers can change plans from the Subscriptions page in the Developer Portal:
+
+1. Customer clicks "Change Plan" on their active subscription
+2. Sees available plans with pricing comparison
+3. Selects the new plan
+4. Stripe handles proration (charge or credit the difference)
+5. Entitlements update immediately — the customer's quota changes in real time
+6. The API key stays the same
+
+### Programmatic (API)
+
+```bash
+curl -X PATCH https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId} \
+  -H "Authorization: Bearer {API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "planKey": "enterprise"
+  }'
+```
+
+### Proration behavior
+
+When a customer changes plans mid-billing-period, Zuplo uses
+**max-consumption-based proration** to calculate a fair credit from the old
+plan. Instead of only considering how much time has passed, the system looks at
+both elapsed time and actual quota usage, then uses whichever is greater.
+
+This prevents situations where a customer consumes most of their quota early in
+the billing period, switches plans, and receives a large time-based credit that
+does not reflect their actual usage.
+
+**Upgrade (e.g., Starter → Pro):**
+
+- New entitlements take effect immediately
+- A proration credit from the old plan appears as a line-item discount on the
+  new plan's invoice
+
+**Downgrade (e.g., Pro → Starter):**
+
+- New (lower) entitlements take effect at the next billing cycle
+- A proration credit from the old plan is applied as a discount on the next
+  invoice
+
+**Example:** A customer on Starter ($29/month, 10,000 requests) upgrades to Pro
+on day 15 of a 30-day period, having used 7,000 requests.
+
+| Factor             | Value          |
+| ------------------ | -------------- |
+| Time elapsed       | 50% (15 / 30)  |
+| Quota consumed     | 70% (7K / 10K) |
+| Max of the two     | 70%            |
+| **Credit applied** | **$8.70**      |
+
+The credit is applied once and is not carried forward to future billing cycles.
+
+### Quota reset on plan change
+
+When a customer changes plans, the quota usage counter does **not** reset. If a
+customer used 8,000 of their 10,000-request Starter quota and upgrades to Pro
+(50,000 requests), they have 42,000 remaining for the current period — not
+50,000.
+
+This prevents gaming where a customer uses up their starter quota, upgrades
+momentarily, and immediately downgrades.
+
+## Cancellation
+
+### Customer-initiated
+
+Customers can cancel from the Developer Portal subscriptions page:
+
+1. Customer clicks "Cancel Subscription"
+2. Confirmation dialog explains what happens
+3. Cancellation is scheduled for the end of the current billing period
+4. Customer retains full access until the period ends
+5. At period end, access is revoked and the API key stops working
+
+### Programmatic cancellation
+
+```bash
+curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/cancel \
+  -H "Authorization: Bearer {API_KEY}"
+```
+
+### Cancellation behavior
+
+| Scenario                     | Default behavior                           |
+| ---------------------------- | ------------------------------------------ |
+| Active subscription canceled | Access until period end, then revoked      |
+| Trial subscription canceled  | Access until trial end, no payment charged |
+| Subscription with overage    | Overage billed on final invoice            |
+
+## Reactivation
+
+A canceled subscription (scheduled for end-of-period) can be reactivated before
+the period ends:
+
+```bash
+curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/unschedule-cancelation \
+  -H "Authorization: Bearer {API_KEY}"
+```
+
+This removes the pending cancellation. The subscription continues as normal.
+
+A fully canceled subscription (past the period end) can be restored:
+
+```bash
+curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/restore \
+  -H "Authorization: Bearer {API_KEY}"
+```
+
+## Multiple subscriptions
+
+A customer can hold multiple active subscriptions simultaneously. This supports
+scenarios like:
+
+- A primary monthly subscription plus a credit pack top-up
+- Separate subscriptions for different API products
+- A team subscription and a personal subscription
+
+Each subscription generates its own API key. The customer uses the appropriate
+key for each use case.

package/docs/articles/monetization/tax-collection.md

@@ -0,0 +1,166 @@
+---
+title: Tax Collection — Enabling Stripe Tax
+sidebar_label: Tax Collection
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+Zuplo supports automatic tax collection through Stripe Tax. When enabled, taxes
+(such as VAT, sales tax, or GST) are automatically calculated and added to your
+customers' invoices.
+
+## Prerequisites
+
+- Monetization configured with Stripe connected (see
+  [Quickstart](./quickstart.md))
+- A billing profile (created automatically during initial setup)
+- Tax registrations added in Stripe for countries where you collect tax
+
+## Add tax registrations in Stripe
+
+You must add tax registrations in Stripe for every country where you are
+required to collect tax. Without a registration, Stripe Tax cannot calculate
+taxes for customers in that country.
+
+1. Go to your
+   [Stripe Tax registrations page](https://dashboard.stripe.com/tax/registrations).
+2. Click **+ Add registration** and add each country where you have a tax
+   obligation.
+
+## Find your billing profile
+
+Retrieve your billing profiles to get the billing profile ID:
+
+```bash
+curl -X GET "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/billing/profiles" \
+  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
+  -H "Content-Type: application/json"
+```
+
+The response contains an `items` array. Save the `id` from your billing profile
+as `BILLING_PROFILE_ID`.
+
+## Enable tax collection
+
+Use the PUT endpoint to update the billing profile. You need to change two
+things:
+
+1. **Set the correct supplier country** in `supplier.addresses[0].country`. Tax
+   calculation depends on your supplier country — it defines what taxes your
+   company is required to collect. Use the
+   [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
+   country code (e.g., `US`, `GB`, `DE`).
+
+2. **Enable tax collection** by setting `workflow.tax.enabled` to `true`.
+
+First, get the current billing profile to use as a base for the update:
+
+```bash
+curl -X GET "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/billing/profiles/${BILLING_PROFILE_ID}" \
+  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
+  -H "Content-Type: application/json"
+```
+
+Then update the profile with tax enabled. The key fields to change in the
+response body are:
+
+```json
+{
+  "supplier": {
+    "addresses": [
+      {
+        "country": "GB"
+      }
+    ],
+    "name": "Stripe Account"
+  },
+  "workflow": {
+    "tax": {
+      "enabled": true,
+      "enforced": false
+    }
+  }
+}
+```
+
+Send the full profile body back via PUT:
+
+```bash
+curl -X PUT "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/billing/profiles/${BILLING_PROFILE_ID}" \
+  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{ ... full billing profile body with tax enabled ... }'
+```
+
+## Tax enforcement modes
+
+The `workflow.tax` object controls how tax collection behaves:
+
+| `enabled` | `enforced` | Behavior                                                                                                                                                                                             |
+| --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `false`   | `false`    | **No tax calculation.** Stripe Tax is not used. Invoices are created without tax lines.                                                                                                              |
+| `true`    | `false`    | **Best-effort tax calculation.** Tax is calculated when possible. If it fails (e.g., no valid customer tax location or no tax registration for their country), the invoice is finalized without tax. |
+| `true`    | `true`     | **Strict tax enforcement.** Tax calculation is required. If Stripe Tax returns an error, the invoice fails and the customer cannot complete the purchase.                                            |
+
+:::tip
+
+Start with `enforced: false` (best-effort) to avoid blocking customers in
+countries where you haven't added a tax registration. You can switch to strict
+enforcement after you have registrations in place for all your target markets.
+
+:::
+
+## Tax behavior configuration
+
+You can configure whether tax is **included in the price** or **added on top of
+it** by adding a `defaultTaxConfig` to the `invoicing` section of your billing
+profile:
+
+```json
+{
+  "invoicing": {
+    "autoAdvance": true,
+    "draftPeriod": "P0D",
+    "dueAfter": "P0D",
+    "progressiveBilling": true,
+    "defaultTaxConfig": {
+      "behavior": "exclusive",
+      "stripe": {
+        "code": "txcd_10000000"
+      }
+    }
+  }
+}
+```
+
+| Setting                 | Description                                                                                                            |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `behavior: "exclusive"` | Tax is added on top of the listed price. A $9.99 plan with 20% VAT charges $11.99.                                     |
+| `behavior: "inclusive"` | Tax is included in the listed price. A $9.99 plan total stays $9.99, with tax extracted from that amount.              |
+| `stripe.code`           | The Stripe Tax code for your product category. `txcd_10000000` is the general "Software as a Service (SaaS)" category. |
+
+## Troubleshooting
+
+### Customers blocked from subscribing
+
+When `enforced` is `true` and a customer tries to subscribe from a country where
+you have not added a Stripe tax registration, they see an error and cannot
+create or upgrade subscriptions.
+
+**Fix:** Add a tax registration for the missing country in Stripe, or set
+`enforced` to `false` to use best-effort mode.
+
+### Invoices missing tax lines
+
+If tax collection is enabled but invoices don't show tax:
+
+- Verify you have a tax registration for the customer's country.
+- Check that the customer's address includes a valid country.
+- Confirm `workflow.tax.enabled` is `true` on the billing profile.