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
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:
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 spelling3. Prove it in a test
With the vitest.config.ts from Testing, as in
Test a purchase:
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.
Send paid Orders to your ERP
Hand every paid Order to your ERP exactly once, keep OrbCart's Line IDs there, and report shipments back so the buyer's order page shows the tracking.
A gift message, end to end
Declare a gift message once, let the buyer write it in the bag, and print it on the packing slip. Checked on the server, kept in the Quote and frozen in the Order.