README

A small, Stripe-only shop and donations tool for Craft CMS 5. I built it for charities, churches and small organisations that need to take donations and sell a few things, and can't justify Craft Commerce. I kept it small on purpose: when a choice is between more capable and simpler, I pick simpler.

The docs are in docs/. They cover installation, front-end templates, settings, donations, recurring donations, Gift Aid, the shop, webhooks, emails, caching with Blitz, Twig and events, privacy and troubleshooting. They also list what Small Change leaves out, so you can check that before you start.

Requirements

Craft CMS 5.0 or later
PHP 8.2 or later
MySQL 8 or PostgreSQL 13 or later
A Stripe account

Installation

composer require coyshdigital/craft-small-change
php craft plugin/install small-change

Add your Stripe keys to .env:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Then open Small Change → Settings → Stripe and check the three fields hold the environment variable references above. Small Change rejects raw keys, so they can't end up in project config.

The control panel shows a test-mode notice whenever the secret key is a test key. I read the mode from the key, so the same settings work in every environment.

Taking a donation

In Small Change → Settings → Product types create a Donation type, and give it a URI format and template if donations should have their own pages.
In Small Change → Products add a donation with suggested amounts.
Open Small Change → Settings → Templates, tick Donations, enter your site's layout (like _layouts/site) and press Install templates (or run php craft small-change/templates/install). Visit /donate. There are no routes to add; see docs/templates.md.
Point a Stripe webhook endpoint (Snapshot payload) at the address shown under Utilities → Stripe, and put its signing secret in STRIPE_WEBHOOK_SECRET. For local development see docs/local-development.md.
In your Stripe Dashboard, turn off the "Successful payments" customer email. Small Change sends its own receipt, and donors would otherwise get two.

Gift Aid is off until you enable it and give your charity's name in the settings. Small Change passes the donor's answer on to Stripe and, through events, to your own code. It doesn't store declarations, produce claims or keep the records HMRC expects you to hold, and that's on purpose. Keep those in your CRM.

Selling products

Create a Physical or Non-physical product type (Settings → Product types), then add products with a price and an optional SKU. Physical products are delivered. Non-physical ones (tickets, memberships) aren't, so they never ask for an address.
Add one or more Shipping methods: a flat price, optionally limited to some countries. A customer is offered the methods that serve their address, and if only one does, it's chosen for them.
Optionally add Discount codes: a percentage or a fixed amount, with a minimum spend, dates and a maximum number of uses. Codes discount products only. Donations are never discounted.
Optionally add Checkout fields (Small Change → Checkout fields), such as a gift message. Customers can fill in the common field types, and anything else in the layout is ignored on the public form. Donation forms have their own Donation fields.
Install the Shop templates from Small Change → Settings → Templates (product list, basket, checkout, payment and thank-you pages), then give your product type a URI format and template for product pages. See docs/templates.md.

The basket is an ordinary order held in the visitor's session. The server works out prices, delivery, discounts and totals every time the basket changes, and again before payment, so nothing the browser sends about money is used. If a price changes while someone is checking out, they're told and shown the new total before they pay. A discount code's last use is held while someone is paying and given back if they abandon the payment, so two customers can't both get it.

Dispatching is manual. Orders → Needs dispatch lists paid orders with something to post, and each order has a Mark as dispatched button.

Recurring donations

Switch on Allow monthly or yearly gifts on a donation product to offer monthly or yearly giving. Stripe owns the schedule and the card. Small Change records each payment on the order that started it, emails failures and cancellations, and emails donors a link to Stripe's customer portal so they can manage their own gift. See docs/recurring-donations.md.

Privacy

Abandoned baskets and old Stripe events are purged automatically. One command or button erases a donor's personal data (including from stored Stripe events and from Stripe) and keeps the books. See docs/privacy.md.

Development

composer install
vendor/bin/ecs check
vendor/bin/phpstan analyse
cp tests/.env.example tests/.env   # point it at an empty database
vendor/bin/codecept build
vendor/bin/codecept run unit

AI disclosure

I used AI tools to help write parts of this plugin's code, tests and documentation. The design decisions are mine, and so is the responsibility for the result. If you find something wrong, please tell me.

Support

If something doesn't work, or the docs don't cover it, open an issue at github.com/Coysh-Digital/craft-small-change or email support@coysh.digital. I'd like to hear about it.

Licence

Craft License. See LICENSE.md.

coyshdigital / craft-small-change

Package info

Security

Statistics