Why API-Created Subscriptions Sometimes Do Not Generate an Immediate Invoice

Overview

A common issue merchants encounter when using the Recurly API is that creating a subscription does not always result in an immediate invoice or charge, even when one is expected.

This article explains why this happens, how to diagnose it, and how to ensure subscriptions bill correctly when created via the API.

What Merchants Expect vs. What Happens

Expected Behavior

When calling the subscription creation endpoint, merchants often expect:

• An invoice to be generated immediately
• A charge attempt to occur right away

Actual Behavior

In some cases:

• The subscription is created successfully
• No invoice is generated immediately
• Billing is deferred to a future date

Root Cause

The most common cause is the interaction between collection_method, starts_at, and trial-related settings in the API request.

Common Pitfall Scenario

The following request creates a valid subscription, but billing is deferred:

POST /subscriptions
{
  "plan_code": "gold",
  "currency": "USD",
  "account": {
    "code": "acct_123"
  },
  "collection_method": "manual",
  "starts_at": "2026-05-01T00:00:00Z"
}

Outcome:

• The subscription is created
• No invoice is generated immediately
• Billing occurs on the future starts_at date

Key Fields That Impact Immediate Billing

collection_method

• automatic attempts to collect payment automatically when billing occurs
• manual creates a manual collection workflow and does not auto-collect

starts_at

• If set to a future date, the subscription is scheduled
• No invoice is created until the subscription actually starts

Trial Settings

• If the plan includes a trial, billing is deferred until the trial ends
• If trial_ends_at is set, invoice timing follows that date

How to Diagnose

1. Review the subscription object and confirm whether the state is future or active.
2. Check whether starts_at was set to a future date.
3. Confirm whether the plan or request includes a trial period.
4. Verify the value of collection_method.
5. Review the account’s invoices to confirm whether an invoice exists but is pending future billing.

How to Ensure Immediate Billing

To generate an invoice right away, use a request like the following:

POST /subscriptions
{
  "plan_code": "gold",
  "currency": "USD",
  "account": {
    "code": "acct_123"
  },
  "collection_method": "automatic"
}

For immediate billing, make sure:

• starts_at is not set to a future date
• No trial period is configured
• The account has valid billing information

Best Practices

• Explicitly decide whether the subscription should start now or later
• Avoid setting starts_at unless scheduling is intentional
• Validate billing information before creating subscriptions with automatic collection
• Log request and response payloads during implementation and troubleshooting
• Test common subscription scenarios in sandbox before going live

Summary

If a subscription created via API does not generate an immediate invoice, the most common reasons are:

• A future starts_at date
• Trial configuration
• Manual collection settings

Understanding how these fields affect billing timing can help prevent confusion during implementation and reduce confusion related to “missing” invoices.