Copy page

Business models

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).

Kontorion blueprint

Concern	Kontorion primitive
Recurring delivery + billing	Subscription with billing_interval: "monthly" (or another supported cadence)
Skip a delivery	Not yet wired as a scheduled change — see note below. Today: POST /v1/subscriptions/{id}/pause before the cycle, then resume after
Pause / resume	Imperative POST /v1/subscriptions/{id}/pause and /resume (a billing-mode shift; status stays ACTIVE, the active phase flips to a paused phase and back)
Gift subscription	Prepaid wallet credit + zero-amount recurring price + auto-debit from wallet
Address per cycle	Custom field shipping_address on the subscription
Holiday hold-until-date	POST /v1/subscriptions/{id}/pause now, then POST .../resume on the return date (the scheduled resume is not yet wired — see note below)
Region-based shipping	Per-country_code price on a separate "shipping" product
Tax differences (box vs shipping)	Per-product tax_category

Build it

1. Define the box product

Code
curl -X POST https://api.kontorion.eu/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "name": "HelloFresh Family Box (4 meals/wk)",
    "type": "FIXED_CHARGE",
    "tax_category": "REDUCED"
  }'

curl -X POST https://api.kontorion.eu/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "name": "Shipping",
    "type": "FIXED_CHARGE",
    "tax_category": "DEFAULT"
  }'

Notice tax categories differ: in many EU jurisdictions, food gets the reduced VAT rate while shipping carries the standard rate. Kontorion stamps each line with the correct rate at finalize.

2. Create the plan with weekly cadence

Code
curl -X POST https://api.kontorion.eu/v1/plans \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "name": "Family Weekly" }'

curl -X POST https://api.kontorion.eu/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "product_id": "prod_family_box",
    "plan_id": "plan_family_weekly",
    "list_price": { "value": "49.95", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "tiers": [{ "up_to": null, "unit_amount": "49.95" }]
  }'

curl -X POST https://api.kontorion.eu/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "product_id": "prod_shipping",
    "plan_id": "plan_family_weekly",
    "list_price": { "value": "4.99", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "country_code": "DE",
    "tiers": [{ "up_to": null, "unit_amount": "4.99" }]
  }'

curl -X POST https://api.kontorion.eu/v1/prices \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "product_id": "prod_shipping",
    "plan_id": "plan_family_weekly",
    "list_price": { "value": "6.99", "currency": "EUR" },
    "currency": "EUR",
    "billing_interval": "monthly",
    "billing_interval_count": 1,
    "country_code": "AT",
    "tiers": [{ "up_to": null, "unit_amount": "6.99" }]
  }'

3. Subscribe with shipping address

Define a custom field for shipping address on the subscription entity (one-time setup):

Code
curl -X POST https://api.kontorion.eu/v1/custom-fields \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "entity_types": ["SUBSCRIPTION"],
    "key": "shipping_address",
    "display_name": "Shipping address",
    "field_type": "STRING"
  }'

Then create the subscription:

Code
curl -X POST https://api.kontorion.eu/v1/subscriptions \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "customer_id": "cust_emma",
    "plan_id": "plan_family_weekly",
    "billing_interval": "monthly",
    "items": [
      { "product_id": "prod_family_box", "quantity": 1 },
      { "product_id": "prod_shipping",   "quantity": 1 }
    ],
    "custom_fields": {
      "shipping_address": "Hauptstr. 12, 10115 Berlin, DE"
    }
  }'

4. Skip next week's delivery

Roadmap note. A first-class single-cycle "skip" primitive is not yet wired. The SUBSCRIPTION scheduled-change release hook currently dispatches only change_type: "version_bump"; any other change type (including skip_cycle) is rejected with unsupported subscription scheduled change type. There is no skip_cycle change type in the API today.

Until a dedicated skip lands, model a single-cycle skip with the imperative pause/resume endpoints: pause before the cycle boundary so no invoice or fulfillment trigger is produced, then resume in time for the following cycle.

Code
# Pause before the 2025-04-21 cycle so it produces no invoice / no shipment
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_emma/pause \
  -H "Authorization: Bearer sk_live_..."

# Resume in time for the next cycle
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_emma/resume \
  -H "Authorization: Bearer sk_live_..."

Paused subscriptions emit no invoices, so the skipped cycle is neither billed nor fulfilled. The cycle after the resume bills normally.

5. Pause for a holiday

Code
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_emma/pause \
  -H "Authorization: Bearer sk_live_..."

# When the holiday is over, resume explicitly
curl -X POST https://api.kontorion.eu/v1/subscriptions/sub_emma/resume \
  -H "Authorization: Bearer sk_live_..."

Paused subscriptions emit no invoices. Pause is a billing-mode shift, not a lifecycle state change: status stays ACTIVE and the active phase flips to a paused phase, then back on resume.

Roadmap note. There is no auto-release for a scheduled resume yet. The SUBSCRIPTION scheduled-change release hook dispatches only change_type: "version_bump", so scheduling a resume change would be rejected at release time. To hold until a fixed date today, pause now and call POST /v1/subscriptions/{id}/resume on the return date (e.g. from your own scheduler).

6. Gift subscription (3 months prepaid)

Person A buys a 3-month gift for Person B's email:

Code
# Create the recipient customer
curl -X POST https://api.kontorion.eu/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "email": "recipient@example.com", "name": "Gift recipient", "preferred_currency": "EUR" }'

# Person A pays $X, credit posts to recipient's wallet
curl -X POST https://api.kontorion.eu/v1/wallets \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "customer_id": "cust_recipient", "currency": "EUR" }'

curl -X POST https://api.kontorion.eu/v1/wallets/wal_recipient/credit \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "amount": "149.85",
    "source": "PROMOTION",
    "reason": "3-month gift from cust_giver"
  }'

# Recipient activates the subscription; invoices auto-draw from wallet
curl -X POST https://api.kontorion.eu/v1/subscriptions \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "customer_id": "cust_recipient",
    "plan_id": "plan_family_weekly",
    "billing_interval": "monthly",
    "items": [
      { "product_id": "prod_family_box", "quantity": 1 },
      { "product_id": "prod_shipping",   "quantity": 1 }
    ],
    "metadata": { "gift_expires_at": "2025-07-15T00:00:00Z" }
  }'

When the wallet runs out, the subscription either auto-cancels (if no payment method on file) or auto-converts to paying via the recipient's added payment method.

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.
• Trial first box discount. Use a promotion with effects: [{ "kind": "fixed_discount", "amount": "20.00", "currency": "EUR" }] for a 20-off welcome offer. (There's no "first invoice only" effect flag; scope the discount via the effect's scope and cap redemptions per customer with max_redemptions_per_customer: 1 so it lands once.)
• Annual prepay discount. Add an annual price to the same plan; offer customers a 12-week prepay at 15% off via the scheduled change flow at any cycle boundary.
• Box-of-the-month with rotating contents. The pricing model stays the same; SKU rotation lives entirely outside Kontorion (in your fulfillment system).
• Loyalty rewards. Use a promotion with anniversary conditions to credit the wallet on the 12th delivery as a "thanks for being a customer" gesture.

What you don't have to build

• Per-cycle billing automation on weekly/biweekly cadence
• Pause/resume that suppresses billing and fulfillment without losing the subscription (use it to model a single-cycle skip; a first-class skip_cycle and an auto-releasing scheduled resume are on the roadmap, not yet wired)
• Wallet-funded gift subscription auto-debit
• Per-region shipping price selection (country_code filter on price)
• Mixed tax categories on a single invoice (food reduced + shipping standard)
• Cancellation save flow (offer a scheduled change for "downgrade to monthly" instead of immediate cancel)

Next steps

• Subscriptions - lifecycle states (pause / resume / cancel)
• Scheduled Changes - deferred version_bump flows (plan/version changes at a future cycle boundary)
• Wallets - prepaid balances for gift subscriptions
• Promotions - first-box discount codes and welcome offers
• Custom Fields - shipping address and personalization