Subscriptions

Subscriptions represent the ongoing relationship between subscribers and subscription plans, defining what products or services a subscriber receives, how often they are billed, and the terms of the subscription agreement.

Subscriptions serve as the central entity linking subscribers, plans, subscription items (the concrete products or services within the subscription), applied discounts, and related orders.

Each subscription tracks:

• Status: Current state of the subscription (active, paused, canceled, failed, expired, or merged)
• Serial number: Unique sequential identifier within a store
• Current cycle: The billing cycle count, starting at 0 (before first billing) and incrementing with each completed billing
• Next billing date: When the next billing process will begin
• Currency code: The currency used for all pricing
• Billing and delivery policies: Inherited from the subscription plan, but can be overridden at the subscription or item level
• Delivery method: Shipping, local delivery, or pickup configuration
• Payment method: The payment method used for transactions

Subscription items

Subscription items (also referred to as subscription lines) are the individual products or services included within a subscription. Each subscription may have multiple items, allowing flexibility for subscribers to have personalized bundles or to change items over time.

Each subscription item contains:

• Product information: Title, subtitle, product and variant identifiers, SKU
• Quantity: Number of units for this item
• Pricing: Current price and total price (including discounts and taxes)
• Subscription plan: Reference to the specific subscription plan that applies to this item
• Recurring cycle limit: Optional limit on how many billing cycles this item will be included (after which it’s automatically removed)
• Billing and delivery policies: Can override the subscription-level policies for this specific item
• Pricing policy: Item-specific pricing rules (e.g., introductory pricing, cycle-based discounts)

Example: A subscription might include three items: “Premium Coffee Beans” (monthly, 2 bags), “Coffee Filters” (every 3 months, 1 pack), and “Mug Set” (one-time, 1 set with a recurring cycle limit of 1).

Subscription discounts

Subscription discounts represent special pricing or promotional offers applied to a subscription. Discounts can be applied at different levels and have various configurations:

• Target: Discounts can target:
  • Shipping: Apply to delivery/shipping costs
  • Subscription items: Apply to subscription items, either all items or specific selected items
• Value type:
  • Fixed amount: A specific dollar amount discount (e.g., $5 off)
  • Percentage: A percentage discount (e.g., 10% off)
• Recurring cycle limit: Optional limit on how many billing cycles the discount applies (e.g., first 3 cycles only)
• Title: Typically displayed as a discount code to customers

Example: A subscription might have a “WELCOME10” discount that applies 10% off all items for the first 3 cycles, and a “FREESHIP” discount that provides free shipping for all orders.

Subscription plan relationship

Subscription plans define the templates and default configurations, but the relationship between plans and subscriptions is flexible:

• Subscription level: The subscription inherits billing and delivery policies from the plan, which define the default behavior for the entire subscription
• Item level: Each subscription item can reference a specific selling plan (via sellingPlanId), allowing different items in the same subscription to follow different plan configurations
• Policy overrides: Both subscriptions and individual items can override the plan’s billing and delivery policies, providing flexibility for custom configurations

Example: A subscription might be created from a “Monthly Coffee Plan” but include items from different plans:

• Item 1: “Premium Coffee” from “Monthly Premium Plan” (bills monthly)
• Item 2: “Accessories” from “Quarterly Accessories Plan” (bills every 3 months)