Statamic Cargo Laravel Package

Getting Started

• composer require duncanmcclean/statamic-cargo, then run the package's install/publish steps (vendor:publish for config + migrations), and php artisan migrate. Cargo stores products/variants as Statamic entries (flat file) but carts, orders and customers in the database, so both halves of setup matter.
• Look here first, in this order:
  1. config/cargo.php — currency, tax classes/rates, shipping methods, payment gateways, route registration.
  2. The products collection blueprint (installer provides a starter) — the variants field is what drives pricing/stock/SKU, so understand its shape before writing templates.
  3. database/migrations (cargo_orders, cargo_order_items, cargo_carts, cargo_customers) — this is where reporting/queries will live.
  4. The package's docs site for the Antlers tags / Blade components it registers for cart and checkout forms.
• First use case to build end-to-end: a product entry with two variants → a listing page using Cargo's product query/scope → an add-to-cart form → /cart (update quantity, remove) → /checkout with a gateway in test mode → confirm an order row exists and the order events fire. Do this in test/sandbox credentials before touching tax or shipping config.
• Set APP_URL and the Cargo routes correctly early; checkout callbacks/redirects from payment gateways break silently if the base URL is wrong.

Implementation Patterns

• Treat products as content, orders as data. Use Cargo's product/variant API for pricing and availability in templates; drop to Eloquent (or Cargo's order models) for anything order-related — dashboards, exports, customer history.
• Cart flow: resolve the current cart per request, mutate line items (add/update/remove) with variant IDs, never with raw prices submitted from the form — always re-read the variant price server-side. Recalculate totals after every mutation rather than storing a total you trust.
• Checkout: keep the checkout form a POST to Cargo's checkout handler; validate stock and price again at submission time. Redirect to your own thank-you page and look up the order by its reference/ID rather than relying on session flash data.
• Event-driven integration: Cargo dispatches order and stock events. Register listeners for order completion to send transactional email, sync to an ERP/accounting tool, or trigger webhooks. This is also where you'll want to hook in idempotency (guard against duplicate order-paid handling).
• Stock handling: variants carry stock and a track/backorder flag. Let Cargo decrement stock on order rather than writing to the variant field yourself; if you do need to adjust (refunds, manual restocks), go through the same code path so stock events still fire consistently.
• Tax classes: assign a tax class on the product and override per variant where needed (e.g. a book vs. a digital download). Keep the tax-class catalogue in config, and make the field nullable in your blueprints — v1.15.1 confirms an empty tax class is a valid state, not an error.
• Custom gateways / shipping: implement the package's gateway contract (or extend the registered gateway list in a service provider) for anything beyond the built-in options. Keep credentials in config/services.php/env, not in config/cargo.php.
• Localization & presentation: prices are formatted via Cargo's money helpers — use those in templates instead of number_format, so currency config and rounding stay consistent between cart, checkout and emails.
• Testing: write feature tests that hit the cart/checkout endpoints, assert order rows and dispatched events. Use the manual/test gateway and Event::fake() for order events so tests don't send mail or call out.

Gotchas and Tips

• Stache/content cache vs. DB state. Products live in Statamic's content layer. After changing products or variants in code/deploy, clear or warm the Stache — otherwise a cart can price against a stale variant while the order writes fresh data.
• v1.15.1 specifics worth knowing:
  • Stock events are now dispatched against the variant's stock. If you have listeners that assumed the parent product's stock (common on multi-variant products), re-audit them — they may have been over- or under-reporting availability.
  • An empty tax class now passes validation, and variants of products with no tax class now return no tax class rather than inheriting something unexpected. If you were relying on the old behaviour, orders may now calculate zero tax where they previously picked up a class — check your rates for products/variants with a blank field.
• Zero tax is silent. There's no error when no tax class resolves to a rate. Add a test that asserts expected tax on a blank-tax-class product if you sell any.
• Page caching and carts don't mix. Exclude /cart, /checkout and any account pages from full-page/CDN caching, and be careful with Statamic's static caching.
• Route collisions. Cargo registers /cart, /checkout, etc. If you already own those URLs, either disable the built-in routes in config or namespace yours — Laravel will happily let the last-registered route win in confusing ways.
• Tax-inclusive vs. exclusive pricing is a single config switch that silently changes every displayed price. Decide once, before writing templates and emails.
• Don't hand-edit order rows. Cargo's models assume line items and totals are coherent; a manual UPDATE on cargo_orders.total will drift from cargo_order_items and break refunds/reporting. Write adjustments through the API or a new order-note/refund path.
• Debugging: Event::listen('*') (or Telescope) on Cargo's events plus a look at the cargo_* tables usually explains "order placed but nothing happened". For cart weirdness, check the session/cart binding first — a cart resolved from the wrong guard (guest vs. logged-in user) is a frequent cause of "my cart emptied".
• After any Cargo upgrade, diff the published config against the package's config stub; new options (gateways, stock settings, tax behaviour) ship as config keys and won't appear in your published copy unless you merge them.
• Extension points to prefer: events/listeners for side effects, custom gateway and shipping-method classes for behaviour, and your own controller wrapping Cargo's services for bespoke endpoints — avoiding edits to published package files keeps upgrades (like this patch release) cheap.