Billing Cycles & Use Cases

Billing Cycles

The system calculates next_payment_date automatically based on the interval and billing cycle parameters.

Interval	Description	`billing_cycle.day`	`billing_cycle.month`
daily	Every day	N/A	N/A
weekly	Every week	Day of week (1=Monday, 7=Sunday)	N/A
monthly	Every month	Day of month (1-31)	N/A
quarterly	Every 3 months	Day of month (1-31)	Base month (1-12)
semiannual	Every 6 months	Day of month (1-31)	Base month (1-12)
yearly	Every year	Day of month (1-31)	Month (1-12)

Practical Use Cases

Below are common scenarios demonstrating how to configure the API for different business models. See our Direct Debit Management page for further details on how to use each endpoint.

Case 1: Monthly Subscription

Scenario: A gym charges $500 MXN monthly on the 1st of each month.

// 1. Create the direct debit
POST /api/direct-debits
{
  "customer_id": "customer_123",
  "is_recurring": true,
  "amount": 500.00,
  "currency": "MXN",
  "status": "created",
  "interval": "monthly",
  "frequency": 1,
  "concept": "Gym Membership",
  "billing_cycle": {
    "day": 1
  }
}

// System calculates: next_payment_date = 2026-01-01

Case 2: Quarterly Payment

Scenario: A software company charges $3,000 MXN each quarter on the 15th of the first month of the quarter (January, April, July, October).

POST /api/direct-debits
{
  "customer_id": "customer_456",
  "is_recurring": true,
  "amount": 3000.00,
  "currency": "MXN",
  "status": "created",
  "interval": "quarterly",
  "frequency": 1,
  "concept": "Software License",
  "billing_cycle": {
    "day": 15,
    "month": 1 // January as base month
  }
}

// System calculates next dates: 2026-01-15, 2026-04-15, 2026-07-15, 2026-10-15

Case 3: Weekly Payment

Scenario: A streaming service charges $99 MXN every Friday.

POST /api/direct-debits
{
  "customer_id": "customer_789",
  "is_recurring": true,
  "amount": 99.00,
  "currency": "MXN",
  "status": "created",
  "interval": "weekly",
  "frequency": 1,
  "concept": "Streaming Premium",
  "billing_cycle": {
    "day": 5 // 5 = Friday (1=Monday, 7=Sunday)
  }
}

Case 4: Scheduled One-Time Charge

Scenario: A one-time charge of $10,000 MXN scheduled for March 31, 2026.

POST /api/direct-debits
{
  "customer_id": "customer_101",
  "is_recurring": false,
  "amount": 10000.00,
  "currency": "MXN",
  "status": "created",
  "concept": "Payment for professional services",
  "next_payment_date": "2026-03-31T00:00:00.000Z"
}