How do I connect my billing destination?

Prerequisites

• An active Stripe account with at least one product and meter configured.
• A restricted Stripe secret key (rk_live_…) with Meter events: write.
• The meter ID you want CMD+K to push to (e.g. mtr_abc123).

Setup

1. Open Monetize → Billing destinations.
2. Click Add destination and pick Stripe.
3. Paste the restricted key and meter ID; click Test — we send a $0 dry-run event.
4. Save. Forwarding starts on the next widget interaction.

Paddle

Paddle Billing has no live meter-event API, so the Paddle destination works on an accrue-then-charge cycle: CMD+K accumulates each customer's usage per calendar month (UTC) and, once the month closes, creates one one-time charge on the customer's Paddle subscription (effective_from: next_billing_period). The daily flush runs at 00:30 UTC; the destination row also has a Flush now button.

1. In Paddle, create a per-unit price for usage (e.g. $0.01 per 1k tokens) and copy its pri_… id.
2. Create a Paddle API key with subscription write access.
3. Add destination → Paddle → pick sandbox/live, paste the key, map your meter to the price and set units-per-charge (e.g. 1000 tokens per unit, rounded up).
4. Set the customer ID template so it resolves to each customer's sub_… subscription id.
5. Click Test — for Paddle this verifies the API key without creating any charge.

• Scheduled cancellations — Paddle discards queued charges when a subscription is set to cancel at period end — use Flush now before cancelling a customer.
• Billing anchor — Charges land on the customer's next Paddle invoice, so a closed month can appear one invoice later than the usage month.

Event shape

The adapter forwards one event per billable widget turn:

{
  "event_name": "cmdk_tokens",
  "payload": {
    "stripe_customer_id": "cus_xxx",
    "value": "1280"
  },
  "identifier": "cmdk_evt_01HXXXX"
}

• stripe_customer_id — looked up from your end-user's external_id mapping you provide via JWT or assistant config.
• value — unit you meter on — tokens, characters, or 1 per turn. Configurable per assistant.
• identifier — deterministic per turn; Stripe deduplicates retries automatically.