Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

Free shipping and a welcome code

Free standard shipping from €50 without a code, 10 % off with WELCOME10, a code field in the bag, and a test that proves both.

You declare two promotions: standard shipping is free from €50 of goods, and the code WELCOME10 takes 10 % off. OrbCart applies both, spreads them over the Lines and shows them in the Cart, the Quote and the Order. No discount code is written by hand.

You need a Channel with a standard shipping rule, as on Shipping.

1. Declare both on the Channel

src/worker.ts
discounts: [
  // No code: applies by itself from €50 of goods. Express stays paid.
  { id: "free-shipping", scope: "shipping", percentage: 100, minimumSubtotal: 5000, methods: ["standard"] },
  { id: "welcome", code: "WELCOME10", percentage: 10 },
],

For shipping discounts, minimumSubtotal counts only shipped goods before discounts, in minor units of the Channel's currency. Services and downloads never count. If references or tags are set, only matching shipped Lines count. A Swiss Channel with the same line reads CHF 50.

2. Let the buyer enter the code

<Checkout> shows a code field already. For the bag, the kit has one that joins the Cart's queue:

app/mini-cart.tsx
import { DiscountCode } from "@orbcart/react";

<DiscountCode cart={bag.cart} onEnter={bag.enterCode} onRemove={bag.removeCode} />;

Put it below Totals in the Bag of Add to cart. Without React, call the client yourself:

await cart.enterCode("welcome10"); // any spelling

3. Prove it in a test

With the vitest.config.ts from Testing, as in Test a purchase:

test/discounts.test.ts
import { env, exports } from "cloudflare:workers";
import { createCommerce } from "@orbcart/client";
import { issueKey, publishDailyRates } from "@orbcart/runtime/testing";
import { beforeEach, expect, it } from "vitest";

const worker = (request: Request) => exports.default.fetch(request);
const shipTo = {
  name: "Anna Berg",
  line1: "Bergstraße 12",
  postalCode: "10115",
  city: "Berlin",
  country: "DE",
};

beforeEach(async () => {
  const today = new Date().toISOString().slice(0, 10);
  await publishDailyRates(env, { on: today, rates: { DE: { standard: "19", reduced: ["7"] } } });
});

it("ships a backpack for free and takes 10 % off with WELCOME10", async () => {
  const key = await issueKey(env, { kind: "publishable", channel: "de" });
  const cart = await createCommerce({ url: "https://commerce.test", key, fetch: worker }).cart();

  await cart.add("BACKPACK-30-GREEN"); // €89.90, over the threshold
  await cart.enterCode("welcome10");
  const quote = await cart.quote({ shipTo, contact: { email: "anna@example.com" } });

  expect(quote.discounts).toEqual(
    expect.arrayContaining([
      expect.objectContaining({ discount: "welcome", scope: "order" }),
      expect.objectContaining({ discount: "free-shipping", scope: "shipping" }),
    ]),
  );
});

Next

Discounts says what the buyer sees for each case, such as express chosen or a typo in the code, and has the variations: a code for free shipping, redemption limits and codes your own pricing redeems.

On this page