Hosting with 20% off when you buy through the link

Store and subscriptions

Sell items one by one and charge members monthly or yearly through Stripe: price field, checkout, orders, automatic delivery and the customer portal.

Velk sells through Stripe, the payment service, in two ways that can live on the same site:

  • The store sells content items one at a time: an e-book, a workshop seat, a consultation. A content type marked as sellable gets a price, the theme shows a buy button, and the buyer pays on Stripe's checkout page. Buying needs no account.
  • Subscriptions charge members monthly or yearly for a plan: a course area, premium articles, a client portal. They need the members area, since the account ties the person to the plan.

Card details never pass through the site: the payment happens on Stripe's page, and Stripe tells the site the result.

Ask the AI

Set up a store on the Hearth & Crumb bakery site to sell baking workshops. Each workshop is a content item with title, date, description and photo; make that type sellable, in US dollars. Put a “Book my seat” button with the price on each workshop page, one seat per purchase, and a “Sold out” switch that hides the button when a class is full. When an order is paid, e-mail the buyer the address and what to bring. Use Stripe in test mode and tell me exactly what to create in the Stripe dashboard.

The AI marks the type as sellable, sets the store currency, writes the button and the reaction to a paid order, and lists the keys and the webhook to create in Stripe. Velk counts no seats: the switch is how the bakery closes a class.

Connecting Stripe

  1. The secret key

    STRIPE_SECRET_KEY goes in .env, one key for both features. Use the test key (sk_test_…) while you build.

  2. One webhook per feature

    A webhook is the message Stripe sends to the site when a payment is confirmed. In the Stripe dashboard you create one endpoint per feature in use, at the site's address, with the events in the table below.

  3. Its signing secret

    Each endpoint has its own: STRIPE_STORE_WEBHOOK_SECRET for the store, STRIPE_WEBHOOK_SECRET for subscriptions. Since v3.7.7 a feature only turns on when its secret is set too: with the key alone, Stripe would charge and the site would never hear of it, so Velk keeps the feature off and the checkout doesn't open.

  4. The check

    Since v3.7.7 schema:validate checks the plans, the sellable types and the currency, and names a missing secret.

The two webhooks

EndpointEvents to subscribe
https://your-site/store/stripe-webhook — the storecheckout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired
https://your-site/member/stripe-webhook — subscriptionscheckout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted
What the AI runs
# checks plans, sellable types and the currency; names a missing secret $ ./bin/velk schema:validate ✓ site.json is valid.
Your local .env never goes to the server. The server's .env needs its own key and secrets: the live ones when you start charging for real.

Selling items

  • The price field comes on its own. Every item of a sellable type gets a Price field in the admin; don't ask for one. Since v3.9.1 its help names the store's currency. An item without a price can't be bought.
  • The currency is set once in site.json (store.currency, a three-letter code such as USD or EUR; BRL when absent).
  • Checkout. The buy button sends one item, or several with their quantities, to Stripe's checkout. Back on the site, the theme shows a message: paid, or canceled.
  • Buying once. Since v3.7.7 a type can refuse a second purchase of the same item (repeat_purchase off): a logged-in member who already paid for it isn't charged again, and the quantity is always one. Buyers without an account aren't tracked, so require login where it matters.

Delivery and orders

What happens after a payment is up to the theme. Velk calls a function of the theme — the payment webhook, payment_webhook in site.json — each time Stripe confirms a change: an order paid, failed or expired, a subscription started, renewed or canceled. That is where the AI writes “e-mail the e-book link” or “send the buyer to the CRM”, and e-mails go out through the SMTP settings in .env. It fires once per real change, so a Stripe retry doesn't send the e-book twice, and it runs while Stripe waits, so slow work belongs elsewhere.

In the admin, Store → Orders lists the orders with buyer, items, total, date and status (pending, paid, expired, failed), with a filter by status; each order opens with its lines and its Stripe reference. Refunds are made in the Stripe dashboard: Velk never refunds or cancels on its own, and its orders have no refunded status.

Ask the AI

E-books are bought once per member: when the logged-in member already owns one, swap its buy button for “Download”. Add a “My purchases” page listing the member's paid orders. Buying an e-book requires login.

This uses the buy-once rule on the e-book type. The download link is only as private as its address.

Ask the AI

Add paid plans to the Lotus Yoga members area: “Basic”, monthly only, and “Unlimited”, monthly or yearly, each with a short description and three features. “Library” pages open for any active plan, “Live classes” only for Unlimited. Add a pricing page with the subscribe buttons, and a “Manage subscription” button on the member's page. I'll set the prices in the admin.

The plans go in site.json with name, intervals and features. Prices don't.

Plans and subscriptions

  • Prices live in the admin. The Plans & Subscriptions screen, under Settings, has an Active switch and a price per interval for each plan, plus the currency (BRL when blank, separate from the store's). Velk creates the product and the price in Stripe on first use. A new price applies to new subscriptions; current subscribers keep the old one. Since v3.9.1 the screen follows the admin's language and has no language tabs: a price has no translation.
  • One plan per member by default: a second subscription answers already_subscribed. Since v3.7.7 members.multiple_plans allows several, one per plan.
  • The customer portal is Stripe's page where the member updates the card, changes plan or cancels. The theme shows a button to it, and you choose what it allows in the Stripe dashboard; with several plans per member, turn plan switching off there.
  • Access follows Stripe's status. A member whose card failed keeps access while Stripe retries; canceled and unpaid subscriptions lose it. Canceling at period end keeps access until that date.
  • The members list gains a Plan column, and a red “!” marks anyone with more active subscriptions than the rule allows (two tabs paying at once, say). Sort it out in Stripe.