Subscription Box / Recurring Physical Delivery
The recurring physical delivery pattern: customer subscribes to receive a box on a fixed cadence (weekly, biweekly, monthly), pays at each delivery cycle, and expects to be able to skip individual deliveries, pause for a few weeks, or send the subscription as a gift. The pricing math is simpler than most software billing - the operational complexity lives in the lifecycle controls (skip, pause, gift) and the integration with shipping/fulfillment.
Real-world examples. HelloFresh, Blue Apron, BarkBox, Dollar Shave Club, Birchbox, FabFitFun, Stitch Fix, Loot Crate, Trade Coffee, MeUndies, Native Deodorant Subscribe & Save. Common shape: $20-100 per box, monthly or biweekly cadence, ability to skip/pause/cancel from a self-serve portal, gift option with prepaid duration, address book for delivery, holiday hold periods.
The shape of the problem
Despite looking like "the simplest possible subscription," subscription boxes have a distinct operational shape:
- Skip is not pause. Skipping one delivery means: no charge, no shipment, no allowance change to the next cycle. Pausing means: no deliveries until resumed, billing also halted. The distinction matters because cancellations from "I tried to skip but you charged me" are an avoidable churn driver.
- Gift subscriptions. A gift is paid up front by Person A but consumed by Person B, who may not even have an account at purchase time. The billing system has to track "this subscription has N prepaid cycles remaining" without a recurring payment method.
- Address management for fulfillment. Each delivery needs the current shipping address - and the cutoff for changing the address before the next box ships is meaningful (HelloFresh-style "edit your box by Wednesday for next Monday's delivery").
- Holiday hold periods. Many customers want to pause around the holidays without cancelling. A first-class "hold until
<date>" reduces friction vs forcing them to remember to resume. - Inventory-coupled pricing. Some boxes are flat-priced regardless of contents; some adjust price based on which curated items the customer selected.
- Shipping as a separate concern. Shipping cost varies by region and may be free above a certain box price; tax may apply to the box but not to shipping (or vice versa).
Kontier blueprint
| Concern | Kontier primitive |
|---|---|
| Recurring delivery + billing | A plan with price_cadence_unit: week (or month); the subscription bills on the plan's cadence |
| Skip a delivery | A subscription.apply_for_a_while change that makes the lines free for one week |
| Pause / resume | POST /v1/subscriptions/{id}/pause and /resume; status PAUSED while paused |
| Holiday hold-until-date | A subscription.set_status change with kind: pause at the start date and another with kind: resume at the return date |
| Gift subscription | A fixed-length phase ending in stop, funded by a price-reduction credit on the recipient's wallet |
| Address per cycle | Custom field shipping_address on the subscription |
| Region-based shipping | A country_code-scoped price on a separate "shipping" product |
| Tax differences (box vs shipping) | Per-product tax_category |
Build it
IDs in the examples are placeholders: use the id each create call returns.
1. Define the box product
Code
Notice tax categories differ: in many EU jurisdictions, food gets the reduced VAT rate while shipping carries the standard rate. Kontier stamps each line with the correct rate at finalize.
2. Create the plan with weekly cadence
The cadence is the plan's price_cadence_unit: every price on the plan covers one week.
Code
Attach both products to the plan (POST /v1/plans/{id}/products with each product_id), then price them. plan_version: 0 stages the price on the plan's working draft until the first publish.
Code
Publish the two products and then the plan; publishing is a change:
Code
3. Subscribe with shipping address
Define a custom field for the shipping address on the subscription entity (one-time setup):
Code
Then create the subscription, author its first revision, and start it:
Code
Code
Code
Code
PATCH replaces the stored custom_fields map, so send every field you want to keep when the customer changes their address.
4. Skip next week's delivery
A skip is "this week costs nothing, then everything goes back to how it was". That is a change with an ending: subscription.apply_for_a_while states a free price on the deal's lines from an instant, for a duration, and then lets the earlier value apply again.
Code
The phase in force is split at from; the week from 23 November bills both lines at zero, and the following week bills normally. Add "match": { "product_id": "…" } to the payload to free only one line (for example, keep charging shipping). Your fulfillment system reads the same revision (GET /v1/subscriptions/{id}/revisions/live) to know that no box ships that week. See Scheduling for previewing a change (POST /v1/changes/preview) and cancelling one (DELETE /v1/changes/{id}).
5. Pause for a holiday
Pause now, resume later:
Code
While paused, the subscription's status is PAUSED and the phase clocks are frozen. The resume shifts the remaining phases by the paused time and publishes that as a new revision, then the status returns to ACTIVE. A draft revision left open across the pause blocks the resume.
To book the whole hold in advance, schedule both ends as changes with subscription.set_status:
Code
Send a second change with "kind": "resume" and the return date. at is a wall clock read in zone, so the pause lands at midnight Berlin time.
6. Gift subscription (12 weeks prepaid)
Person A buys a 12-week gift for Person B:
Code
A PROMOTION credit is not cash: it opens a discount lot that each invoice drafted for the customer draws on before tax, naming the reason on the discount. 12 weeks × (€49.95 + €4.99) = €659.28.
Then subscribe the recipient for exactly the gift's length. A phase with a 12-week duration and then: "stop" ends the subscription when it runs out:
Code
(Create the subscription and activate it as in step 3.) If the recipient wants to keep going after the gift, cut the live revision at the gift's end (POST /v1/subscriptions/{id}/revisions/cut with at set to that instant), write the whole draft with PUT /v1/subscriptions/{id}/revisions/draft: the gift phases as they are, with then: "next" on the last one, then an open-ended paid phase. Publish the draft.
Variations
- Subscribe & Save (e-commerce). Combine with an API platform pattern for a la carte add-ons - customer subscribes to the base box but can add one-time items per delivery.
- Curated personalization. Use custom fields on the subscription to store preferences (
spice_level,dietary_restrictions) that drive your fulfillment system; the billing layer doesn't care what's in the box. - First box discount. State a lower agreed price on the first phase only, then
resetit on the next: a two-phase revision where phase 0 lasts one week. Or use a promotion. - Annual prepay discount. Add a second plan with
price_cadence_unit: year; a customer switches at any period boundary by cutting the live revision there and continuing on the annual plan's lines. - Box-of-the-month with rotating contents. The pricing model stays the same; SKU rotation lives entirely outside Kontier (in your fulfillment system).
- Cancellation save flow. Offer a few weeks at a lower agreed price with
subscription.apply_for_a_while(attribute: price,price_kind: agreed) instead of an immediate cancel. A cancel itself isPOST /v1/subscriptions/{id}/cancelwithwhennow,atorperiod_end.
What you don't have to build
- Per-cycle billing automation on a weekly or monthly cadence
- Skips that bill nothing and restore themselves (
subscription.apply_for_a_while) - Pause/resume that freezes the deal without losing it, now or booked in advance (
subscription.set_status) - Gift subscriptions that end on their own (a phase with
then: stop) and are paid for by price-reduction credit - Country-scoped shipping prices (
country_codeon the price) - Mixed tax categories on a single invoice (food reduced + shipping standard)
Next steps
- Subscriptions - revisions, phases, pause / resume / cancel
- Scheduling - changes that run at a later instant
- Wallets - prepaid balances and price-reduction credit
- Promotions - first-box discount codes and welcome offers
- Custom Fields - shipping address and personalization