Payments

Sell one-time purchases and subscriptions with Dodo Payments. A purchase gives the buyer a plan (and, if you want, prepaid credits) on their account, which your pages can check.

What it is

Payments connects Arc CMS to Dodo Payments, the only payment provider Arc CMS supports. Dodo hosts the checkout page and takes the money; Arc CMS keeps the product list, records every payment, and writes the buyer's plan onto their account. It gives you:

• Products (admin): a mirror of your Dodo products, with the plan each one grants, pricing tiers and credits.
• Transactions (admin): every payment, failure and refund Dodo reports.
• A pricing page at /pricing, checkout through Dodo, and return pages at /checkout/success and /checkout/cancel.
• Member pages: Payments (/user/payments), Membership and billing (/account), and a members-only example page (/user/premium).
• Prepaid credits: a balance per person, granted by purchases and spent by your app.
• Payment emails, member notifications and admin alerts.

How an app checks what a person has paid for is on its own page: Premium entitlements. For when to use payments in an app, see Add payments and premium features.

Turn it on or off

Payments is a switchable feature, id payments, on by default. It needs no other feature. To turn it off, list it in src/custom/features.ts:

export const CUSTOM_FEATURES: FeatureChoice = {
    off: ['payments'],
};

When it is off:

• Every payments URL shows the not-found page: /pricing, /checkout/..., /account, /user/payments, /user/premium, /admin/products, /admin/transactions and /admin/settings/payments.
• Products and Transactions leave the admin menu, and the Payments card leaves Settings.
• The member area hides its Payments, Account, Premium and Plans links and does not load the plan.
• The payment Cloud Functions are not built, so a full functions deploy deletes them.

Data already in Firestore stays. The full list of feature ids is in Feature ids.

Set it up

1. In Dodo: create your products (one-time or subscription). For each pricing tier you plan to offer, create a discount code. A code's own usage limit is what caps a tier.

2. Deploy the functions (see Deploy only what changed). The webhook receiver is deployed as arccms-dodoWebhook.

3. In Dodo, add a webhook whose URL is the deployed arccms-dodoWebhook function (its URL is in the Firebase console, Functions). Copy the webhook's signing secret.

4. In Arc CMS, open Settings, Payments and fill in:

   Field	What to enter
   Enable Dodo Payments	On. With it off, checkout and test links fail.
   Mode	Test while you try it, Live for real sales.
   Test API Key, Live API Key	From Dodo. The key for the selected mode is used.
   Webhook Signing Secret	The secret from the step before.
   Success / Return URL	https://your-site/checkout/success
   Cancel URL	https://your-site/checkout/cancel

   Save, then press Test Connection. Saved keys and the secret show as dots; they are only replaced when you type a new value.

5. Open Products, New Product for each Dodo product: its name, the Dodo Product ID (prod_...), the type, and the plan it grants (Premium type such as gold, and Tier rank, higher means more access). Mark it Active to show it on the pricing page. The other fields are below.

6. Try it in Test mode. Buy from /pricing with a test card, then check Transactions and the buyer's /account page.

7. Go live: switch Mode to Live and enter the Live API Key. Settings holds one signing secret, so it must be the secret of the webhook that sends the events of the mode you use.

Product fields

Pricing tiers

Tiers give the first buyers a better price, such as "first 100 buyers get 40% off". Each tier has a label, a limit (the cumulative number of buyers it covers), a Dodo discount code, and a display percentage and price. A new buyer gets the first tier whose limit is higher than the number of confirmed buyers so far; a limit of 0 means "everyone else" and belongs last. The code is applied at checkout. Only a first purchase or a first subscription activation counts as a buyer; renewals do not.

Each tier has a Test payment link: a real Dodo checkout with that tier's code, so you can check the price. A purchase through it is marked test in Transactions and grants no plan, no credits, no email, and does not count as a buyer.

Payment emails

Settings, Payments, Payment Emails has four emails you can switch on or off and edit: Payment succeeded, Payment / renewal failed, Subscription lifecycle (trial started, past due, on hold, cancelled, expired, refunded) and Trial ending soon (sent once when a trial ends within 3 days). A test send must be confirmed before a template can be saved. The free-updates reminder (updates_ending_email) is edited in the email composer. They go through the email engine: see Email engine and Email merge tags.

Use it

What a buyer does

1. Opens /pricing, which lists the active products.

2. Presses buy. A visitor who is not signed in is sent to sign in first and comes back to /pricing. The createCheckoutSession function picks the pricing tier, and the browser goes to Dodo's checkout.

3. Pays. Dodo sends them to the Success URL. /checkout/success waits for the webhook to grant the plan (checking every 3 seconds, for about 45 seconds), then links to /account.

Members see their plan, credit balance, recent activity and full transaction history on /user/payments and /account. /user/premium opens only for a paying member; others are sent to /pricing.

What each Dodo event does

Every step is safe to repeat, so a webhook Dodo sends twice is counted once. Events that arrive out of order never undo a newer one.

Every day

Extend it

• Lock your app's features by the buyer's plan: Premium entitlements.
• Spend credits from your app with the consumeCredits callable: { amount, note }, where amount is a positive whole number. It returns { balance, spent }, or fails with failed-precondition ("Insufficient credits.") when the balance is too low. Apart from a full refund, it is the only way a balance goes down.
• React to payments in automations or your own functions: the event bus gets payment.succeeded and payment.failed. See Automations and Write your own Cloud Functions.
• Your own pricing page: read the Products collection (public) and call createCheckoutSession with { productId }; it returns { checkoutUrl, sessionId, tierApplied }. Send the browser to checkoutUrl.

Another payment provider cannot be plugged in from an app: the records are provider-neutral, but only Dodo is wired up.

What it stores

Payments stores no files. Its Cloud Functions, built only when the feature is on: createCheckoutSession, createTestCheckoutLink, testDodoConnection, consumeCredits (callables), dodoWebhook (HTTP), handlePaymentEvent (runs on each new WebhookEvents document), and the three daily scans above. All are listed in Cloud Functions; the collections in Data model.

Who can do what

People cannot write their own plan or credit fields: the rules refuse it. See Roles and claims.

Troubleshooting