Why a Renewal Invoice May Use Manual Collection After a Hosted Payment Page Payment – Recurly

When you create a purchase or invoice line item by referencing an item_code, Recurly uses the catalog item relationship for product-level configuration such as revenue recognition and accounting setup. If you also need customer-specific text on the invoice, it is important to understand the difference between metadata, catalog item text, and visible invoice line-item text.

Key takeaway: Line item custom fields can store additional data and can be read through API responses, but they do not automatically become visible description text on the invoice PDF your customer receives.

What Custom Fields Can Do

You can attach custom_fields to line items through the Purchase API. Those values are metadata. They can be useful for reporting, reconciliation, fulfillment, or downstream systems that read Recurly API responses.

Line item custom fields can be read from related API calls, including:

Line item retrieval
Purchase retrieval
Invoice retrieval

What Custom Fields Do Not Do Automatically

Custom fields on line items do not automatically replace the customer-facing invoice line-item description on the invoice PDF. If your goal is to show customer-specific selections such as size, format, configuration, or fulfillment notes directly on the PDF line item, do not assume that adding a line item custom field will make that text visible to the customer.

Options to Consider

Option	Use when	Important limitation
Line item custom fields	You need metadata available through API responses or reporting workflows.	They do not automatically display as visible invoice PDF description text.
Catalog item name or description	The customer-facing text is stable for every purchase of that item.	Changing catalog item text is shared and can affect all future invoices that reference that item.
Invoice template customization	You need invoice presentation changes and your site supports the required template configuration.	Template capabilities depend on your invoice template setup and should be tested before relying on them.

Preserving Product-Level Revenue Recognition

If product-level revenue recognition rules, liability accounting codes, or revenue accounting codes are configured on the item, continue referencing the catalog item when creating the purchase. Building a manual charge without referencing the catalog item can bypass item-level configuration and fall back to other defaults.

Use custom fields for additional metadata, but keep the item relationship intact when the product's configured revenue or accounting treatment is important.

Recommended Approach

Use item_code when the invoice line item should inherit item-level configuration.
Use line item custom fields for metadata that does not need to be visible on the customer PDF.
Use item name or description only for text that should apply broadly to that catalog item.
Test invoice template behavior separately if customer-visible custom field display is required.

For more about custom fields, see Custom fields.