Migrate from Legacy Invoices

Native invoices use the same /invoices paths as legacy invoices, but have a different request format and lifecycle. This guide maps the fields and actions you need to change when migrating an integration.

The shared paths route to native invoices from Api-Version-Date: 2026-10-24. The native examples below use Api-Version-Date: 2026-11-02-1, with the current variant field names and customer-locking rules. Send that header on each native request. Keep legacy calls on an earlier released version, such as 2026-10-15-1. API versions explains how headers override credential pins.

What changes

	Legacy invoices	Native invoices
ID	`inv_`	`pay_`, the same as the invoice’s payment
What you bill	One plan, with optional labels that add up to its price	1 to 50 items, each an existing variant or one found or created inline
Create	Finalizes in one call, unless `save_as_draft` or `automatically_finalizes_at` is set	Always saves a draft. You then issue or send it.
Amounts	The plan’s price	`subtotal`, `buyer_fee_amount`, `tax_amount`, `total`, `amount_due`
Payment page	`pay_online_url`, a URL	`checkout_link`, a signed token used to open checkout
Past due	`status: past_due`	`overdue: true` on an `open` or `uncollectible` invoice
Webhooks	`invoice.*`	Payment events for the invoice’s `pay_` ID

The native API doesn’t list or retrieve legacy inv_ invoices. Keep reading existing legacy invoices with the earlier API version. Creating a native invoice creates a separate bill. It doesn’t convert or settle a legacy invoice.

Before you migrate

Check these differences before moving a flow. Keep it on the legacy API if it needs a feature the native API doesn’t provide.

Legacy feature	Native behavior
`invoice.*` webhooks	Native invoices use payment events. Some legacy events have no direct counterpart. See Map webhooks.
Mark an invoice paid after collecting money outside Whop	There is no native `mark_paid` endpoint.
Delete a draft	There is no native `DELETE /invoices/{id}`. Voiding keeps the invoice record and number.
`plan.payment_method_configuration`	The invoice request doesn’t accept this field. Configure the existing variant or account’s payment methods instead.
Free trials and initial fees on recurring plans	From `2026-11-11`, the invoice adds the initial fee. Earlier versions bill the renewal price, so add the fee as a one-time item. The trial doesn’t delay this invoice.
`subscription_billing_anchor_at`	The native invoice request doesn’t accept a billing anchor.
Arbitrary `line_items` labels, fractional quantities, or negative credits	Native lines bill variants. Quantities must be positive integers, and labels come from product or variant titles. Rebuild the charges rather than copying the breakdown.
Reusing the legacy invoice’s `current_plan.id`	Native invoices reject variants tied to legacy invoices. Use a separate variant or create one inline.

Map the create request

A legacy create sends one plan and, optionally, labels that split its price. A native create sends an item for each billed variant. These examples set a combined item price of 19.99 USD. The existing native variant represents the 15 USD setup charge. The 4.99 USD service fee is a custom one-time charge without a product. Both APIs accept prices in currency units. Use 4.99 for 4.99 USD. Sending 499 bills 499 USD.

{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"collection_method": "send_invoice",
	"due_date": "2026-12-01T00:00:00Z",
	"plan": {
		"plan_type": "one_time",
		"initial_price": 19.99,
		"currency": "usd"
	},
	"line_items": [
		{ "label": "Setup", "quantity": 1, "unit_price": 15 },
		{ "label": "Service fee", "quantity": 1, "unit_price": 4.99 }
	]
}

{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"due_at": "2026-12-01T00:00:00Z",
	"items": [
		{ "variant_id": "plan_xxxxxxxxxxxxx", "quantity": 1 },
		{
			"variant": {
				"title": "Service fee",
				"billing_type": "one_time",
				"initial_price": 4.99,
				"currency": "usd"
			}
		}
	]
}

The native request creates a draft. Send it with POST /invoices/{id}/send to issue and email it. member_id identifies a customer (mber_), not a subscription (mem_).

Legacy field	Native field	Notes
`account_id`	`account_id`	The account issuing the invoice.
`plan`	`items`	Each item takes `variant_id` or inline `variant`, plus an optional `quantity`. All items use the same currency.
`product`, `product_id`	`items[].variant.product`, `items[].variant.product_id`	Use one of the two. Inline `product` requires `external_identifier` and `title`. A recurring variant needs a product. A one-time custom charge can omit it.
`line_items`	`items`	Rebuild billed lines as variants. `quantity` defaults to 1. Values above 1 require a variant that allows multiple quantities.
`collection_method`	`payment_method_id`, then issue or send	Set a saved method for an automatic charge, or omit it for payment through checkout. See Issue, send, and charge.
`save_as_draft`	None	Create always saves a draft.
`automatically_finalizes_at`	`send_at` on Send Invoice	Delays issuance until the scheduled send. `charge_at` delays a saved-method charge, not issuance.
`due_date`	`due_at`	Send an ISO 8601 timestamp.
`charge_buyer_fee`	`buyer_fee_percentage`	Map `false` to `0`, and the legacy `true` fee to `5`. Other nonzero percentages must be between 5 and 100, with at most two decimal places.
`payment_method_id`, `payment_token_id`	`payment_method_id`	One of the customer’s saved payment methods, prefixed `payt_`. Setting it requires `payment:charge`.
`member_id`, `email_address`, `customer_name`	Same on create	Choose `member_id` or `email_address`, not both. Native invoices also take `recipient_emails`, independently of the billed customer.
`mailing_address_id`, `billing_address`	Same names, narrower address input	Choose one. An inline address needs `line1`, `city`, `postal_code`, and `country`. It also accepts `name`, `line2`, `state`, and `phone`. It doesn’t accept the legacy `tax_id_type` or `tax_id_value` fields.
`subscription_billing_anchor_at`	None	No invoice request field for a billing anchor.
None	`memo`, `metadata`	`memo` shows on the email, PDF, and checkout. `metadata` stores string key-value pairs.

For native versions before 2026-10-27-2, use plan_id, plan, and plan_type instead of variant_id, variant, and billing_type. The response’s line items use plan_id on those older versions too.

Keep issued amounts locked

PATCH /invoices/{id} edits a draft’s items and billing details. Sending items replaces the entire list using the variants’ current prices. Omitting it keeps the saved items and prices.

Cancel a scheduled send before editing items or billing details.
From 2026-11-02-1, you can’t replace or clear a draft’s assigned customer. A draft without a customer can still take one. Void the draft before creating a new invoice for someone else.
email_address and customer_name are create-only inputs.
Issued amounts and items are locked. An update containing only memo and/or recipient_emails is allowed on draft, open, and uncollectible invoices, including a scheduled draft.

Issue, send, and charge

A legacy create chooses collection behavior with collection_method. Native invoices use separate calls after creating the draft:

Issue it with POST /invoices/{id}/issue to calculate final tax and open it for payment without sending the initial invoice email.
Or send it with POST /invoices/{id}/send. This issues the draft. It emails the recipients unless it charges a saved method immediately. Sending an open invoice emails it again. send_at schedules a draft’s send. POST /invoices/{id}/unschedule cancels that schedule.
Charge a saved method by setting payment_method_id on the draft. For a positive total, issue or send charges at a future charge_at, otherwise a future due_at, otherwise immediately. charge_at must be in the future and can’t precede send_at.

Sending a draft that charges immediately skips the initial invoice email. Sending with a later charge emails it now. A failed automatic charge can trigger a payment-link email even when you used Issue Invoice. Charge a saved payment method explains the flow. An open response doesn’t confirm payment. Wait for payment.succeeded before fulfilling. To charge or retry an open invoice, use Charge Invoice. Issuing or sending it again doesn’t start another charge. For a recurring variant, collection_method on Issue Invoice or Send Invoice controls renewals. charge_automatically collects future payments automatically. send_invoice creates and emails a new invoice each period. It doesn’t replace payment_method_id for collecting the first invoice. See Invoice a subscription.

Map the response

Legacy field	Native field	Notes
`id` (`inv_`)	`id` (`pay_`)	`object` is `invoice`. The same ID identifies the payment.
`current_plan` price	`subtotal`, `buyer_fee_amount`, `tax_amount`, `total`, `amount_due`	Money objects contain a decimal-string `amount`, `currency`, `decimals`, and `display_decimals`. `totals_status` is `estimated` on a draft and `final` otherwise.
`company.id`	`account_id`	Retrieve the account by ID.
`product.id`, `current_plan.id`	`line_items[].product_id`, `line_items[].variant_id`	Each billed line identifies its product and variant. A custom charge can have no product.
`member.id`	`member_id`	Customer ID, prefixed `mber_`. Requires `member:basic:read`.
`user`	No top-level user field	Retrieve the member to find its user. `membership_id` (`mem_`) identifies a membership, not the customer.
`mailing_address`	`billing_address`, `mailing_address_id`	The inline address remains an object.
`payment.id`	The invoice’s own `id`	Retrieve payment details with `GET /payments/{id}` using the same `pay_` ID.
`number`	`number`, `invoice_prefix`	The formatted number and account prefix.
`due_date`	`due_at`	ISO 8601 timestamp or `null`.
`automatically_finalizes_at`	`scheduled_send_at`	`scheduled_charge_at` shows a planned saved-method charge. `scheduled_collection_method` shows the renewal collection choice for a scheduled send.
`charge_buyer_fee`	`buyer_fee_percentage`, `buyer_fee_amount`	The percentage and its calculated amount.
`customer_name`, `email_address`	Same	Plus `recipient_emails`. These fields are permission-gated.
`pay_online_url`	`checkout_link`	A signed token, not a URL. See Open the invoice checkout.
`line_items`	`line_items`	Lines have `variant_id`, `product_id`, `label`, `description`, `quantity`, `unit_amount`, `subtotal`, `discount_amount`, and `tax_amount`.
`status`	`status`, `overdue`	See Map statuses.
`payment_processing`	`status`, plus the payment details	Handle `pending` while payment settles. `paid_at` records payment completion. It isn’t a processing flag.
`fetch_invoice_token`	No direct equivalent	Use authenticated invoice reads, `checkout_link` for checkout, and Generate Invoice PDF for the PDF.
None	`paid_at`, `memo`, `metadata`	Payment completion time, the customer note, and your metadata.

To download a PDF, call POST /invoices/{id}/generate_pdf for a short-lived link.

Open the invoice checkout

checkout_link contains the invoice ID and a signed token separated by a .. Pass the entire value as link to POST /checkout_sessions to open a session for this invoice. For a customer-facing URL, follow Build the hosted checkout URL. The field is present only while checkout is available: the invoice must be open. Business buyers and canceled memberships can’t use this checkout. Your key needs payment:charge, or invoice:create/invoice:update when the invoice has no saved payment method. It’s null on a draft, paid, void, or uncollectible invoice, and for business buyers.

Map statuses

Legacy `status`	Native
`draft`	`draft`
`open`	`open`
`past_due`	`open` or `uncollectible`, with `overdue: true`
`paid`	`paid`
`uncollectible`	`uncollectible`
`void`	`void`

Native invoices can also return authorized, pending, or unresolved. Don’t treat every status outside the legacy enum as paid or failed. Statuses and lifecycle explains them.

Map endpoints

Legacy	Native
`GET /invoices`	List Invoices, with an `overdue` filter
`GET /invoices/{id}`	Retrieve Invoice
`POST /invoices`	Create Invoice, which saves a draft
`PATCH /invoices/{id}`	Update Invoice, subject to the draft and issued-invoice rules above
`POST /invoices/{id}/resend`	Send Invoice
`POST /invoices/{id}/void`	Void Invoice
`POST /invoices/{id}/mark_uncollectible`	Mark an invoice uncollectible
`DELETE /invoices/{id}`	No equivalent. Void the draft to cancel it while keeping its record.
`POST /invoices/{id}/mark_paid`	No equivalent
None	Issue Invoice, Cancel Scheduled Send, Charge Invoice, List Invoice Sends, Generate Invoice PDF

Map webhooks

Native invoices send payment events for their pay_ ID. The invoice.* events describe legacy invoices.

Legacy event	Native behavior
`invoice.created`	`payment.created` when a draft is issued, not when it’s created
`invoice.paid`	`payment.succeeded`
`invoice.past_due`	Read or filter on `overdue`. There is no matching past-due payment event.
`invoice.voided`, `invoice.marked_uncollectible`	Read the invoice’s `status`. There is no direct payment-event replacement for these transitions.

Payment events also cover payments unrelated to invoices. Match the event’s payment ID to the native invoice IDs you store. Webhooks shows how to fulfill from payment.succeeded.

Permissions

Operation	Required permission
Create a draft without a saved payment method	`invoice:create` or `payment:charge`
Update a draft without a saved payment method or scheduled send	`invoice:update`, `invoice:create`, or `payment:charge`
Send or schedule a draft without a saved payment method, or cancel its scheduled send	`invoice:update`, `invoice:create`, or `payment:charge`
Set a saved payment method, write an invoice that has one, issue, charge, void, or mark uncollectible	`payment:charge`
Update a scheduled draft, or update or resend an issued invoice	`payment:charge`
List, retrieve, generate a PDF, or list email sends	`payment:basic:read`
Supply an inline `variant`	Also `plan:create`
Create or update an inline `product`	Also `access_pass:create` or `access_pass:update`, respectively

member:basic:read exposes customer names and member/membership IDs. member:email:read exposes email_address and recipient_emails. Payment method and address fields require payment:basic:read.

Migration checklist

Check Before you migrate for workflows that need to stay on the legacy API.
Pin native calls to a released version matching their field names, such as 2026-11-02-1 for these examples.
Build items from eligible variants, checking quantities, prices, currency, and product requirements.
Replace the legacy one-call create with create, then issue or send. Choose saved-method charges for the first invoice and a collection method for renewals.
Map due dates, scheduled sends, and buyer fees according to their behavior, not just their field names.
Keep native pay_ and legacy inv_ IDs distinct. Keep legacy reads on the earlier version.
Read amounts from money objects, and open checkout using the signed checkout_link.
Handle overdue and the additional payment statuses.
Fulfill from payment.succeeded for the invoice’s payment ID.
Grant the permissions your flow uses, including inline variant/product and customer-read permissions.

Next steps

Invoices guide

Create, issue, send, and collect native invoices.

Invoices API reference

Every native invoice endpoint and field.

Legacy invoice API

The endpoints your current integration calls.

API versions

How Api-Version-Date and version pins work.

​What changes

​Before you migrate

​Map the create request

​Keep issued amounts locked

​Issue, send, and charge

​Map the response

​Open the invoice checkout

​Map statuses

​Map endpoints

​Map webhooks

​Permissions

​Migration checklist

​Next steps

Invoices guide

Invoices API reference

Legacy invoice API

API versions

What changes

Before you migrate

Map the create request

Keep issued amounts locked

Issue, send, and charge

Map the response

Open the invoice checkout

Map statuses

Map endpoints

Map webhooks

Permissions

Migration checklist

Next steps