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	Scheduled change of type skip_cycle for the next cycle
Pause / resume	Subscription lifecycle PAUSED / ACTIVE
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	Scheduled change with scheduled_at = resume_date
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_type": "subscription",
    "key": "shipping_address",
    "label": "Shipping address",
    "data_type": "string",
    "is_required": true
  }'

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

Code
curl -X POST https://api.kontorion.eu/v1/scheduled-changes \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "entity_type": "SUBSCRIPTION",
    "entity_id": "sub_emma",
    "scheduled_at": "2025-04-21T00:00:00Z",
    "change_type": "skip_cycle",
    "change_payload": {}
  }'

The next cycle starting 2025-04-21 produces no invoice and no fulfillment trigger. The cycle after that resumes normally.

5. Pause for a holiday

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

# Auto-resume on July 15
curl -X POST https://api.kontorion.eu/v1/scheduled-changes \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "entity_type": "SUBSCRIPTION",
    "entity_id": "sub_emma",
    "scheduled_at": "2025-07-15T00:00:00Z",
    "change_type": "resume",
    "change_payload": {}
  }'

Paused subscriptions emit no invoices. The scheduled resume transitions back to ACTIVE automatically on the date.

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": { "value": "149.85", "currency": "EUR" },
    "source": "gift",
    "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: [{ type: "amount_off", value: { "value": "20.00", "currency": "EUR" }, applies_to: "first_invoice" }] for a 20-off welcome offer.
• 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
• Skip-this-cycle without losing the subscription
• Pause-with-resume-date for holiday holds
• 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 - skip and pause-until-date flows
• Wallets - prepaid balances for gift subscriptions
• Promotions - first-box discount codes and welcome offers
• Custom Fields - shipping address and personalization