Credit Invoices are Recurly’s modern approach to credit memos / credit notes. When enabled, credits issued to a customer are represented as their own credit invoice, separate from charge invoices. This separation helps finance teams maintain cleaner gross numbers, improves auditability, and simplifies customer-facing invoices.
Key takeaway: Once Credit Invoices are enabled, credits are no longer “mixed into” charge invoices as the only representation. Credits produce a dedicated credit invoice record and can introduce new event types and objects for downstream systems.
What Changes When Credit Invoices Are Enabled
- Separate invoices for credits (credit invoices vs. charge invoices).
- Credit payments become a first-class concept to track usage of a credit balance.
- Additional options for refunds (e.g., refund to credit balance and/or refund credit payments back to original payment method, depending on configuration and eligibility).
- Potential updates required for webhooks, API consumers, exports/reporting, and integrations (especially accounting systems).
Support tip: Treat Credit Invoices like a platform shift. Validate all downstream dependencies (webhooks, API parsing, exports, and accounting mappings) in a sandbox before enabling in production.
Issuing Credits and Refund Options
Common ways credits appear
- Refunds may generate a credit invoice, depending on site configuration and the refund path chosen.
- One-off credits can be issued (e.g., courtesy credits) and tracked independently.
- Credit balance usage can be applied toward invoices; this is typically represented via a credit payment object and related records.
Important: If you have integrations that assume “invoices are always charges,” update them to handle both
charge_invoice and credit_invoice types (or equivalent flags/fields in your payloads/responses).Webhook Impact
Once Credit Invoices are enabled, webhook behavior can change. At a high level:
- New notification families may be introduced for charge invoices and credit invoices.
- Credit activity can generate additional notification types related to credit invoices and credit payments.
- Dunning-related notifications may include an updated invoice block structure when the feature is enabled.
Best practice: Ensure webhook consumers are resilient:
- Do not hard-code assumptions about invoice “shape”
- Be tolerant of new fields/blocks
- Implement idempotency (duplicate deliveries can occur)
API Impact
Credit Invoices can affect API responses and workflows:
- The invoices collection/array may include charge invoices, credit invoices, or both.
- Invoice objects may return additional attributes needed to distinguish type and interpret totals/balances.
- Refund workflows can produce credit invoices; some failure scenarios may result in credits instead.
- Credit invoices may be voidable (where applicable), and credit usage can create a credit payment object.
Implementation tip: If you maintain an internal “Invoice” model, introduce a type discriminator and update any “net revenue” calculations to avoid double-counting credits or misclassifying them as charges.
Exports & Reporting Impact
If your reporting relies on legacy invoice exports, you may need to adjust your export strategy. In many Credit Invoice implementations, legacy invoice exports can be deprecated in favor of exports that reflect adjustments and separate credit activity more explicitly.
What to review:
- Any scheduled exports used by Finance/RevOps
- Data warehouse jobs that assume “invoice = charge”
- BI dashboards that calculate gross vs. net
QuickBooks Online (QBO) Integration Considerations
If you sync Recurly to QuickBooks Online, Credit Invoices can change how credits are represented (e.g., Credit Memos) and can surface common QBO validation errors if prefixes, naming, or allocations aren’t configured correctly.
Common QBO pitfalls related to credit invoices / credit memos
| Symptom / Error | Likely Cause | What to Do |
|---|---|---|
| Duplicate Document # | Credit memo number collides with an invoice number (or another credit memo). | In Recurly QBO settings, set a Credit Memo Number Prefix that is different from the Invoice Number Prefix. Then re-run sync. |
| Credit note allocation missing | Credit memo exists but isn’t allocated/applied in QBO the way it is in Recurly. | For isolated cases, manually create and allocate the credit note in QBO and then ignore the error in Recurly (if appropriate for your workflow). |
| Business Validation Error: Amount received + credits... | Often seen when credits were deleted/changed after syncing, or when invoice-credit relationships can’t be represented cleanly without Credit Invoices enabled. | Avoid deleting carry-forward credits after sync. If you have invoices with credits applied and you’re not yet using Credit Invoices, consider enabling Credit Invoices and re-testing the sync behavior in a sandbox. |
Accounting warning: If you enable Credit Invoices in production without validating QBO behavior, you may see increased sync errors (duplication, allocation issues, or validation errors). Always test in a sandbox and consider starting with a fresh QBO instance when launching.
Troubleshooting
1) Downstream system doesn’t recognize credit invoices
- Confirm your integration supports both credit and charge invoice types.
- Update any parsing logic that expects one invoice schema.
- Verify whether your system should ingest credit invoices as negative revenue, separate documents, or adjustments.
2) Webhook consumers failing after enablement
- Check whether you need to subscribe to new event types or handle new payload blocks.
- Verify your endpoint can safely ignore unknown fields.
- Confirm idempotency protections are in place (duplicate deliveries can happen).
3) QBO errors spike after enabling
- Check prefixes for invoice vs. credit memo numbering to prevent collisions.
- Audit display name configuration and uniqueness rules in QBO.
- If you have unresolved historical issues, consider cleaning/merging duplicates in QBO before syncing.
Escalate to Support when: You can reproduce a mismatch between Recurly credit invoice behavior and documented sync behavior, or you observe repeatable webhook/API payload issues that break backwards compatibility unexpectedly.
Go-Live Checklist
- Enable and test in sandbox (API, webhooks, exports, accounting sync).
- Update any API integrations to handle credit invoice types and new objects.
- Update webhook handlers for new invoice/credit event families and payload differences.
- Update reporting and ETL for export/reporting changes (gross vs. net logic).
- Validate QBO settings (prefixes, naming uniqueness, allocation behavior).
- Review any third-party integrations that ingest invoices, credits, or refunds.
Comments
0 comments
Please sign in to leave a comment.