Recipes

ORBCART 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 },
],

minimumSubtotal counts the goods before discounts, in minor units of the Channel's currency. 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, publishStandardRates } 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 publishStandardRates(env, { on: today, rates: { DE: "19" } });
});

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