Skip to main content

Paydays

Paydays​

Paydays define how and when APIO calculates the charge date for a subscription.
The payday determines the first charge date and all subsequent charges, based on the subscription’s billing cycle and charging policy.

APIO calculates paydays deterministically to ensure predictable billing, reconciliation, and customer communication.

How Paydays Work​

When a subscription is created, APIO evaluates:

  • The billing cycle (weekly, monthly, yearly, etc.)
  • The selected charge policy
  • Any configured charge day rules

Based on these parameters, APIO determines:

  • When the first charge occurs
  • The schedule for future recurring charges

Charge Policies​

APIO supports two charge policies for subscriptions:

Instant Charge​

With Instant Charge, the subscription is charged immediately upon creation.

  • The first charge is generated at subscription creation time
  • Subsequent charges follow the billing cycle
  • Commonly used for paid plans that require immediate access

Charge Days​

With Charge Days, the first charge is deferred and calculated based on predefined calendar rules.

This policy allows businesses to align billing with accounting, payroll, or operational schedules.

Charge Days can be defined using one or more of the following dimensions.

Charge Day Rules​

Days of the Week​

Define allowed weekdays when charges can occur.

Examples:

  • Every Tuesday

APIO will select the next valid weekday according to the billing cycle.

Days of the Month​

Define a range of days within a month when charges are allowed.

Examples:

  • From the 15th to the 20th of each month

If the calculated billing date falls outside the range, APIO moves the charge to the next valid day.

Days of the Year​

Define a range of days within the year when charges are allowed.

Examples:

  • From day 200 to 210 of the year

This is commonly used for annual or seasonal billing strategies.

Combining Rules​

Charge Day rules can be combined to create advanced billing behaviors.

Examples:

  • The first Tuesday of every month
  • Any weekday between the 15th and 20th
  • The first Monday within days 200–210 of the year

APIO evaluates all configured rules and selects the earliest valid date that satisfies every condition.

Trial Days​

Trial Days allow you to delay the first charge of a subscription by a fixed number of days.

When trial days are configured:

  • The subscription starts immediately
  • No charges are generated during the trial period
  • The initial payday is moved forward by the number of trial days
  • After the trial ends, normal payday rules apply

Example:

  • Subscription created on March 1
  • Trial days: 14
  • Billing cycle: monthly
  • First charge: March 15

Trial days are applied before evaluating charge policies and charge day rules.

Expiration and Subscription Duration​

Subscriptions in APIO can be created with or without an expiration.

Subscriptions Without Expiration​

  • The subscription remains active indefinitely
  • Charges continue until the customer cancels the subscription
  • No expiration date is calculated

This is the default behavior.

Subscriptions With Expiration​

A subscription only has an expiration date when a fixed number of billing cycles is defined.

When a cycle limit is provided:

  • APIO calculates the expiration date based on:
    • The first payday
    • The billing cycle interval
    • The total number of cycles
  • The subscription expires automatically after the final charge is completed

Example:

  • Billing cycle: monthly
  • Total cycles: 6
  • Expiration date: one day before the payday of the 7th period

If no cycle limit is defined, the subscription will not expire automatically, even if trial days are used.

Subsequent Charges​

Once the first payday is determined:

  • Future charges follow the billing cycle interval
  • Charge Day rules continue to apply
  • If a calculated date is invalid, APIO automatically adjusts to the next valid valid date

Best Practices​

  • Use Instant Charge for immediate-access plans
  • Use Charge Days to align billing with operational schedules
  • Apply Trial Days for onboarding or promotional periods
  • Define cycle limits only when a fixed-duration subscription is required
  • Clearly communicate billing rules and trial periods to customers

Paydays provide flexible yet predictable control over subscription charging behavior in APIO.