Shop

The Shop extension sells products through Stripe Checkout, PayPal, or both. Visitors pay on Stripe’s or PayPal’s own pages, so card details never touch your site. It suits a small catalog of products, tickets, or donations with fixed prices. Visitors can put several products in a basket, choose quantities, and pay for everything at once, or buy a single product straight away.

Setting up

1. Create a Stripe account, a PayPal business account, or both.
2. Install and activate Shop under Extensions (see Extensions).
3. In its Settings:
   • Payment providers: Stripe, PayPal, or Stripe and PayPal. With both, visitors see Pay by card and Pay with PayPal buttons. For PayPal’s settings, see PayPal below.
   • Stripe secret key: from the Stripe dashboard, Developers → API keys. Use a test key (sk_test_…) while trying it out. A restricted key works too: it needs write access to Checkout Sessions, read access to Events, and, for a fixed tax rate, write access to Tax Rates.
   • Currency: US dollar, Euro, Pound sterling, Canadian dollar, or Australian dollar.
   • Tax: No tax, Stripe Tax, or A fixed percentage.
     • Stripe Tax works out the right tax for each customer’s address. Turn it on in the Stripe dashboard first, and add where you’re registered to collect tax, or checkout fails.
     • A fixed percentage adds the same rate to every product (not to shipping). Set Tax rate (%), such as 20, and Tax name, such as VAT.
     • PayPal can’t use Stripe Tax: while Tax is Stripe Tax, PayPal isn’t offered. A fixed percentage works with both.
   • Prices include tax: on if your prices already include tax (usual for VAT); off to add tax on top at checkout.
   • Shipping per item: charged for each item bought, such as 2.50 (two mugs cost twice this). Leave it empty or 0 for free shipping.
   • Countries you ship to: two-letter country codes, such as US, CA, GB. Customers enter a shipping address in one of these when their order has anything that ships. It’s required if shipping costs anything.
   • Shipping name: what customers see at checkout, such as Standard delivery.
   • Message after paying: shown on the thank-you page.
4. For Stripe, add a webhook pointing to https://<your site>/api/v1/ext/shop/webhook with the events checkout.session.completed and checkout.session.async_payment_succeeded. Without it, card payments still record, but slower methods such as bank debits won’t.

Upgrading from Shop 1.0

The update asks you to approve a new permission, cookies, which the basket needs. Your settings, Stripe key, products, and orders are kept.

PayPal

Choose How PayPal is connected:

• With API credentials (recommended). In PayPal Developer, open Apps & Credentials, create an app, and copy its Client ID and Secret into PayPal client ID and PayPal client secret. Then add a webhook to the app pointing to https://<your site>/api/v1/ext/shop/paypal/webhook, with the events Checkout order approved and Payment capture completed.
• With just my PayPal email address. Enter the email of your PayPal business account in PayPal email address. Payments are recorded when PayPal’s payment notification arrives at https://<your site>/api/v1/ext/shop/paypal/ipn. If paid orders never appear, turn on Instant payment notifications in your PayPal account’s notification settings.

Set PayPal environment to Sandbox to try it with PayPal’s test accounts (from PayPal Developer → Sandbox accounts) before switching to Live. Sandbox credentials only work with Sandbox.

Which to choose:

	API credentials	Just an email
Setup	A PayPal developer app (client ID and secret) and a webhook	Only your PayPal email
When the payment is checked	Before anything is charged: the shop confirms the amount and the shipping country with PayPal, then takes the payment	After the payment: PayPal tells the shop, and the shop checks it matches the order
Wrong country or a changed amount	Refused; nothing is charged	The money arrives, but the payment is listed under Orders → Needs review for you to check and refund in PayPal
Thank-you page	Shows the order straight away	Says PayPal will email a receipt; the order appears once PayPal confirms it
PayPal’s view	Current integration	Older integration PayPal still supports, but no longer recommends for new sites

The extension’s Health line points out setup problems, such as PayPal turned on without credentials, or PayPal with Stripe Tax.

Products

Open Products from the Shop extension’s page. Under Add or change a product, enter:

• Code: a short ID with lowercase letters, digits, and hyphens, such as print-a3. Saving an existing code changes that product.
• Name, Price (from 0.50), and an optional Description.
• Shipping per item (optional): leave it empty to use the store’s amount, enter this product’s own amount, or 0 for things that don’t ship, such as downloads and tickets. An order with nothing that ships skips shipping and the address altogether.

A product keeps the currency that was set when it was saved. If you change the currency later, save each product again.

Product options

A product can come in options such as sizes or colors. In Products, fill in Options, one option per line: Size: Small, Medium, Large. To charge more or less for a choice, add the difference after it: Size: Small, Medium, Large +2.00, Extra-Large +3.50 (or -1.00 to charge less).

The Buy button then shows a list for each option, and visitors must choose before adding to the basket or buying. Each choice is its own line in the basket (“Studio Center Hoodie — Size: Large”), and PayPal, Stripe, and your Orders list show the same name. Prices always come from what you saved here. Leave Options empty for products without choices. Saving a product replaces its options.

Remove a product takes it off sale; its Buy buttons then say This product isn’t available.

Selling on a page

Add a Buy button block to any page and enter the product’s Product code. The block shows the product’s name, description, price, a quantity field, and two buttons:

• Add to basket puts the product in the visitor’s basket at /shop/basket. There they can change quantities, remove items, and check out everything at once. The basket is remembered in their browser for 30 days.
• Buy now skips the basket and pays for this product alone.

You can rename either button or turn one off in the block’s settings. Tick Only the choices and the basket button for a small version that fits under a product in a list of products: just the option lists (such as Size) and the basket button. Link to /shop/basket from your menu so visitors can find their basket.

Visitors who pay land on a thank-you page that lists what they bought. If they cancel, they go back to the basket, or to the page they came from after Buy now.

Orders

Orders lists paid orders: when, the provider (Stripe or PayPal), the items and quantities, subtotal, shipping, tax, total, the customer’s email, the shipping address, and a link to the payment in Stripe or PayPal. An order is recorded only after sc-cms has checked with Stripe or PayPal that the payment went through, and the customer’s basket is emptied then.

Needs review lists payments PayPal confirmed that don’t match an order: a different amount or currency, another PayPal account, or a country you don’t ship to. They aren’t counted as orders; check them in PayPal and refund them there if needed. Refunds, receipts, and customer emails are handled in Stripe and PayPal.