A Core dna store is a set of records and an API that moves a purchase along. The shopper's journey runs through five records, and knowing which one you are looking at answers most questions about what can be changed, and where:

  1. Cart: a record found through a cookie, holding items and discount codes, in one currency.
  2. Checkout: created from the cart when the shopper starts paying. It holds the person, the addresses, the shipping choice and the totals, in the cart's currency.
  3. Invoice: the commercial document for what is owed, created at purchase.
  4. Transaction: the money moving at the payment provider: an authorisation, a capture, a refund.
  5. Order: created when the invoice is fully paid, as a new record with its own number. From then on the order is the record to change.

Checkouts, orders and quotes are the same kind of record, which is why they share so many fields and methods.

Who this guide is for

Developers building a store's templates and scripts, and the commerce implementer configuring its payments, tax and shipping. It assumes you can read Smarty or Twig (Template languages: Smarty and Twig) and know how layouts and layout areas hold content (Input types, layouts, components and images). Every template example is given in both engines.

Languages and currencies

A product is the SKU. It has one description per language, each with its own slug and so its own URL in its own language, and the default description is the one in the site's default language. Prices are one row per currency. A cart takes its currency when the first item is added, from the currency sent with that request or else the default currency, and the checkout, the order, its invoices and its refunds keep it. Names stored on cart lines are in the default language, so pages print them from the product's description in the shopper's language. Every unit says which language and currency applies where; start with Reading the right description and Prices and currencies.

The units, in order

  1. Products, prices and catalogue pages: the product, its descriptions per language and its variants, prices per currency, the category, listing and product pages, wishlists and back-in-stock requests.
  2. Carts, cookies and the cache: the cart record and its cookie, changing the cart through the API, and the cart count on a cached page.
  3. Building the checkout: the checkout and when it can be paid, the single-page checkout, addresses and shipping, discounts, donations and metadata, guest checkout and the captcha.
  4. Taking payment: the payment methods and how a payment runs, express payments, the payment-processing page and webhooks, the mock provider, and 3-D Secure, declines and retries.
  5. From payment to fulfilment: the order and its number, invoices, transactions and refunds, stock and fulfilment, the member's order screens, and the customer emails.
  6. Tax and shipping configuration: tax zones and providers, shipping methods and their templates, making a method appear at checkout, and testing both.
  7. Selling to businesses: quotes and the member quote screens, group pricing and approval before ordering, and B2B features built with custom entities and jobs.
  8. Reference: the commerce settings, and the payment, tax and shipping providers.

What the platform supplies, and what the site builds

  • The platform supplies the records, the cart and checkout API, the payment providers (Stripe, PayPal, PayPal Donate, and Mock Pay for testing), the conversion of a paid checkout into an order, the tax providers, shipping rates from each method's template, the member order and quote routes, and the $_cart template helper.
  • The site builds the cart page (carts/view.html), the checkout page (checkouts/single-page.html), the payment-processing and order-complete pages, the script that calls the API, and the templates of the member order and quote screens.
  • The site configures payment methods, shipping methods, tax providers and zones, discounts, and the customer emails, each of which is a job (Customer emails).

Seven things to design for from the start

  1. A change to the cart starts the checkout again. Adding a donation or changing a quantity on the checkout page creates the checkout again from the cart (From cart to order).
  2. On a cached page, the cart is drawn in the browser. Render the header's cart count from the API, and keep $_cart out of cached templates (The cart count on a cached page).
  3. Every checkout selects a shipping rate, a store that sells only digital goods included: give it a method that returns a free rate (What "ready for payment" requires).
  4. A payment can finish later. With Stripe, the order is created when the provider confirms the payment, so the shopper waits on a payment-processing page the site provides (The payment-processing page and webhooks).
  5. Mock Pay is for development. It takes no money, so switch every Mock Pay method off on the live account before launch (The mock provider).
  6. Stock is kept in step by the system that ships the goods, through the product editor or the Inventory API, and the product page shows what is available (Stock, fulfilment and the member's order screens).
  7. A shipping method decides in its template where it ships and what it charges (Shipping methods and their templates); Making a shipping method appear at checkout is the checklist.

Covered elsewhere