Understanding Billing Automation

Zubs automates the entire billing cycle process for your subscriptions, handling everything from creating orders to processing payments without manual intervention. This guide explains how automated billing works and what happens behind the scenes.

Overview

Billing automation ensures that:

• Customers are charged on schedule
• Orders are created automatically
• Payment failures are handled gracefully
• Reminder emails are sent before billing
• Subscriptions continue without manual work

---

How Billing Cycles Work

What is a Billing Cycle?

A billing cycle is a single instance of a recurring subscription charge. Each subscription creates multiple billing cycles over time.

Example:

• Customer subscribes on January 1st for monthly delivery
• January 1st: First billing cycle (order #0)
• February 1st: Second billing cycle (order #1)
• March 1st: Third billing cycle (order #2)
• And so on...

Each billing cycle creates a new order in Shopify with the subscription products and current pricing.

Billing Cycle Timeline

Here's what happens during each billing cycle:

Days Before Billing (e.g., Day -5 to -7)

Upcoming Order Reminder

• Automated system identifies subscriptions with upcoming billing
• Reminder emails sent based on your configuration (default: 5 days before)
• Customers can make changes: skip, reschedule, edit products

Configuration: Set reminder timing in Settings → Notification Settings

Billing Day (Day 0)

Billing Cycle Selection

• System identifies all subscriptions scheduled to bill today
• Checks for any pending customer changes (skips, reschedules)
• Creates draft order in Shopify with subscription products
• Processes payment through customer's saved payment method
• Marks order as paid if successful
• Triggers fulfillment process
• Updates next billing date for the subscription
• Shopify sends order confirmation email to customer
• Records billing attempt in system logs
• Handles any failures (see Payment Failure Handling guide)

Auto-Skip Feature

The auto-skip feature allows certain billing cycles to be automatically skipped instead of charged. This is essential for build-a-box subscriptions where customers choose items each cycle.

A billing cycle is automatically skipped when either:

1. All products are main products only -- the cycle contains only the shell product (tagged zubs-main-product) and no additional items. There is nothing meaningful to ship.
2. Below minimum order threshold -- a custom.minimum_order_amount_for_cycle metafield is configured on the main product variant, and the cycle's total value (all line items + shipping) is below that threshold. The total is measured before discounts -- a subscription or introductory discount never pushes a cycle below the minimum.

Fail-safe behavior: If the threshold metafield is missing or cannot be read, the cycle is charged (not skipped). This conservative default prevents accidental skips due to configuration errors.

Use cases:

• Skip build-a-box orders where customers didn't select any items
• Automatically skip cycles that don't meet a minimum order value
• Prevent charging for orders with insufficient value to fulfill

Configuration: See the Build-a-Box Subscriptions guide for complete setup instructions, including how to configure the minimum order threshold metafield.

---

Billing Schedule

When Billing Happens

Daily Processing:

• Billing automation runs once per day, typically processes in the morning (timezone based)
• All subscriptions due that day are processed in a batch

---

Subscription Frequencies

Zubs supports multiple billing frequencies that you configure when creating subscription plans:

Supported Frequencies

A frequency is defined by a numeric multiplier and a unit:

Units: day, week, month

Examples:

• every 4 days
• every 3 weeks
• every 2 months

---

Payment Processing

Payment Flow

1. Payment method retrieval

   • System fetches customer's saved payment method from Shopify
   • Validates card is not expired and ensures sufficient details for processing

2. Authorization

   • Amount is authorized against the payment method
   • Authorization happens before order finalization
   • Prevents inventory allocation without payment

3. Capture

   • If authorization succeeds, payment is captured immediately
   • Funds are transferred from customer to your account
   • Order is marked as paid

4. Confirmation

   • Customer receives order confirmation email
   • Fulfillment process begins
   • Next billing date is updated

Payment Failure Handling

When a payment fails, Zubs automatically handles recovery. See the Payment Failure Handling guide for complete details.

Quick summary:

• Configurable retry attempts (0-10 times)
• Configurable days between retries (1-14 days)
• Actions after all retries fail (skip, pause, or cancel)
• Automatic customer notifications

Configuration: Settings → General Settings → Billing Failure Settings

---

Order Creation

Order Contents

Each billing cycle creates a new order containing:

Products:

• All recurring subscription products at current quantities
• Any one-time products customer added for this order
• Any product swaps or changes made by customer

Pricing:

• Current subscription price (or original price if price updates disabled)
• Applied discounts (subscription discount, discount codes, retention discounts)
• Shipping costs (based on customer's shipping address). On a prepaid subscription one order covers several deliveries, so its shipping covers all of them — expect more than a single delivery's postage.
• Taxes (calculated based on location)

Shipping:

• Customer's current shipping address
• Shipping method from subscription plan
• Any address updates made by customer

Order tags:

Zubs automatically adds tags to subscription orders to help you identify, filter, and report on different order types. These tags are added when the order is created and can be used in Shopify's order filters, reports, and automations.

Tag	When Applied
zubs-subscription	All orders created from a subscription
zubs-first-order	The first order of a subscription
zubs-recurring-order	All orders after the first one
zubs-ship-now	Orders triggered by the "Ship Now" feature
zubs-prepaid	Orders from prepaid subscriptions

zubs-subscription is added to every order that originates from a subscription contract. Use this tag to distinguish subscription orders from one-time purchases in your reports and fulfillment workflows.

zubs-first-order identifies the initial order when a customer first subscribes. This is useful for tracking new subscriber acquisition, triggering welcome flows, or applying first-order-specific fulfillment logic.

zubs-recurring-order is applied to all subsequent orders after the first. Use this to identify returning subscriber orders and measure retention.

zubs-ship-now marks orders that were triggered when a customer used the Ship Now feature to receive their next order immediately. This helps distinguish scheduled orders from customer-initiated early shipments.

zubs-prepaid identifies orders from prepaid subscriptions where the customer paid upfront for multiple deliveries. These orders have different billing and delivery intervals (for example, billed every 3 months but delivered monthly).

tip

Zubs also tags customers automatically based on their subscription status. See Customer tags below.

Order vs Subscription

Important distinction:

• Subscription = The ongoing agreement (contract)
• Order = A single transaction from a billing cycle

Example:

• 1 subscription creates 12 orders over 12 months (if monthly)
• Subscription ID stays the same
• Each order has a unique order ID
• Orders are linked to the parent subscription

---

Inventory Management

Inventory Checks

Before creating each order, the system verifies:

• Products are in stock
• Sufficient quantity available
• Products are not archived or deleted
• Variants are still active

Out of Stock Handling

If a product is out of stock at billing time:

1. Initial attempt fails

   • Order creation is blocked
   • No charge is processed
   • Inventory failure retry logic begins

2. Retry logic (configured in General Settings)

   • System retries after configured days
   • Checks if inventory is restocked
   • Attempts to create order again

3. After all retries fail

   • Takes configured action (skip, pause, or cancel)
   • Customer is notified
   • Next billing cycle proceeds as normal (if skipped)

Configuration: Settings → General Settings → Billing Failure Settings → Not enough inventory

Making changes to subscriptions:

• Customers can not add products to a subscription that are currently out of stock
• Customers can modify their existing subscription to remove products that are currently out of stock

---

Troubleshooting

Subscription Not Billed on Expected Date

Possible causes:

1. Subscription was paused
2. Customer skipped the order
3. Customer rescheduled the billing date
4. Payment failed and is in retry cycle
5. Inventory was out of stock

How to check:

1. Open the subscription in Zubs merchant portal
2. View recent activity log
3. Check next billing date

Orders Billed at Wrong Time

Possible causes:

1. Timezone misconfiguration
2. Customer changed frequency
3. "Ship Now" was used (bills the current order early; later orders keep their dates)
4. Date calculation edge case (month-end dates)

Solution:

• Verify subscription next billing date is correct
• Check subscription activity log for changes
• Contact support if dates don't make sense

Billing Seems Slow or Delayed

Normal behavior:

• Billing processes in batches throughout the morning
• Large batches take longer (thousands of subscriptions)
• Some subscriptions process earlier than others in the batch

Action: Contact support to review billing performance

Need help? Contact support if you have questions about billing automation or need assistance troubleshooting billing issues.

---

Customer tags

In addition to order tags (see above), Zubs automatically tags customers in Shopify based on their subscription status. These tags are added and removed as subscriptions are created and cancelled, so they always reflect the customer's current state.

Tag	When Applied
zubs-active-subscriber	The customer has at least one active subscription
zubs-inactive-subscriber	The customer has no active subscriptions (all cancelled)

The two tags are mutually exclusive — Zubs removes one before adding the other, so a customer always has at most one of them.

zubs-active-subscriber is added when a new subscription is created. Use this tag to identify current subscribers in Shopify's customer filters, build targeted marketing segments, or trigger automations in Shopify Flow.

zubs-inactive-subscriber is added when a subscription is cancelled and the customer has no remaining active subscriptions. This is useful for building win-back campaigns, tracking churn in customer segments, or triggering re-engagement flows.