Skip to main content
POST
Create Invoice

Yetkilendirmeler

Authorization
string
header
gerekli

An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Scopes

invoice:create
payment:charge

Başlıklar

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Örnek:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Örnek:

"2026-11-17"

Gövde

application/json
account_id
string
gerekli

The issuing account.

Örnek:

"biz_xxxxxxxxxxxxxx"

items
object[]
gerekli

The variants being invoiced, all in the same currency. Each variant may appear once. Use quantity for multiple units. A recurring variant must belong to a product. Its first invoice charges initial_price plus renewal_price. Later invoices charge only renewal_price. When the variant has trial_period_days, the first invoice charges only initial_price. Paying it starts the trial, and the first renewal is billed when the trial ends. A customer who already had a subscription to the variant gets no trial, so paying starts a paid billing period immediately. Renewal invoices never start a trial. When the trial leaves nothing due, issuing or sending needs a payment_method_id or the send_invoice collection method. The subscription uses the collection_method the invoice was sent or issued with. A finite payment count includes the first paid invoice. With several items, every item that has a product must be a regular product, and all items need compatible payment, tax, access, and trial settings.

Required array length: 1 - 50 elements
Örnek:
billing_address
object | null

Create a billing address linked to this member.

buyer_fee_percentage
number

The buyer's adjustable fee in percentage points, with at most two decimal places: 0 for none, or between 5 and 100. The account keeps it, and Whop waives its take rate on the invoice.

Gerekli aralık: 0 <= x <= 100
Örnek:

5

customer_name
string | null

The contact name when creating an email-only member.

due_at
string<date-time> | null

When payment is due, as an ISO 8601 timestamp.

email_address
string | null

Resolve or create the member for this email, creating a Whop user when none exists. Mutually exclusive with member_id.

Örnek:

"marcus@shinetime.example"

mailing_address_id
string | null

An address associated with the member. Mutually exclusive with billing_address.

member_id
string | null

The billed customer, a member of the account, prefixed mber_. It can't change once the draft is created. Changing email recipients does not change this buyer.

Örnek:

"mber_xxxxxxxxxxxxxx"

memo
string | null

A note to the customer, shown on the invoice email, PDF, and checkout page with its line breaks kept. Trimmed; null or blank clears it. Can be updated on draft, open, or uncollectible invoices.

Maximum string length: 1000
Örnek:

"Thanks for your business. Payment terms: net 30."

metadata
object

Up to 50 caller-owned string key/value pairs. The invoice_memo key is reserved and ignored; set memo instead.

Örnek:
payment_method_configuration
object | null

The payment methods the customer can choose from when paying through the invoice's checkout link, in the shape a variant or checkout configuration takes. It takes precedence over the invoice's variants and the account, and changes neither. Send both lists. null uses its variants' payment methods. Can be updated on drafts.

payment_method_id
string | null

A saved payment method belonging to the member, prefixed payt_. Sending or issuing the invoice charges this method at the charge_at passed to that call, otherwise on due_at, or right away when there is no due_at or it has passed. Sending also emails the invoice now when the charge is later; issuing does not. Setting it needs payment:charge.

Örnek:

"payt_xxxxxxxxxxxxxx"

recipient_emails
string<email>[]

Email addresses saved for invoice delivery, independent of the billed customer. Saving them sends no email. Defaults to the customer email when omitted on create. Can be updated on draft, open, or uncollectible invoices.

Maximum array length: 50
subscription_starts_at
string<date-time> | null

When the first billing period of the invoice's recurring items starts, as an ISO 8601 timestamp in the future. Renewals count from this moment. null starts the period when the invoice is paid. Needs a recurring item. Can be updated on drafts. A start date replaces a variant's free trial, and the invoice bills the full price.

Örnek:

"2026-01-01T12:00:00.000Z"

time_zone
string | null

The IANA time zone for the dates on the invoice's email and PDF. Set it so the due date reads as the day you picked. When omitted, a new invoice uses the time zone Whop has for the user creating it, else UTC. Can be updated on drafts.

Örnek:

"America/New_York"

Yanıt

invoice created

account_id
string
gerekli
Örnek:

"biz_xxxxxxxxxxxxxx"

amount_due
object
gerekli
billing_address
object | null
gerekli
buyer_fee_amount
object
gerekli
buyer_fee_percentage
number
gerekli
Örnek:

0

A signed link that opens this invoice in a checkout session so the buyer can pay it. Pass it as link to POST /checkout_sessions. Present while the invoice is open. null in any other status, for an invoice billed to a business buyer, and for an invoice whose membership was canceled. Also null unless you have payment:charge, or invoice:create or invoice:update on an invoice with no payment_method_id.

Örnek:

"pay_xxxxxxxxxxxxxx.eyJfcmFpbHMiOnsiZGF0YSI6WzEsZmFsc2VdLCJwdXIiOiJSZWNlaXB0XG5jaGVja291dF9tb3VudFxuIn19--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

created_at
string
gerekli
Örnek:

"2026-01-01T12:00:00.000Z"

customer_name
string | null
gerekli
Örnek:

"Dana"

deletable
boolean
gerekli

True when DELETE /invoices/{id} can delete this invoice. A draft qualifies unless it is scheduled or bills a subscription. A void invoice qualifies unless it collected money or still awaits a bank wire.

Örnek:

false

due_at
string | null
gerekli
Örnek:

null

email_address
string | null
gerekli
Örnek:

"marcus@shinetime.example"

id
string
gerekli
Örnek:

"pay_xxxxxxxxxxxxxx"

invoice_prefix
string | null
gerekli
Örnek:

null

line_items
object[]
gerekli
mailing_address_id
string | null
gerekli
Örnek:

null

member_id
string | null
gerekli
Örnek:

"mber_xxxxxxxxxxxxxx"

membership_id
string | null
gerekli

The membership this invoice bills, prefixed mem_. For a renewal invoice, it is the subscription that renews. For an invoice with a recurring item, it is the membership created when the invoice is issued. Null for one-off invoices, for a draft not yet issued, and without the member:basic:read permission.

Örnek:

"mem_xxxxxxxxxxxxxx"

memo
string | null
gerekli

A note to the customer, shown on the invoice email, PDF, and checkout page with its line breaks kept. null when none is set.

Örnek:

null

metadata
object
gerekli
Örnek:
number
string
gerekli
Örnek:

"#xxxxxxxx"

object
enum<string>
gerekli
Mevcut seçenekler:
invoice
Örnek:

"invoice"

overdue
boolean
gerekli
Örnek:

false

paid_at
string | null
gerekli
Örnek:

null

payment_method_configuration
object | null
gerekli

The payment methods the customer can choose from when paying through the invoice's checkout link. It takes precedence over the invoice's variants and the account. null when the invoice uses its variants' payment methods.

payment_method_id
string | null
gerekli
Örnek:

"payt_xxxxxxxxxxxxxx"

recipient_emails
string[]
gerekli

Invoice email recipients, independent of the billed customer.

scheduled_charge_at
string | null
gerekli

When the invoice's saved payment method will be charged, as an ISO 8601 timestamp. It is the charge_at the invoice was sent or issued with. Without one, it is due_at when an invoice with a payment_method_id is sent or issued before it is due. On a draft, it is the charge_at of its scheduled send. null otherwise, once the charge starts, and once the invoice is paid, void, or uncollectible.

Örnek:

null

scheduled_collection_method
enum<string> | null
gerekli

The collection_method a draft's scheduled send applies when it fires. null when the draft has no scheduled send or it was scheduled without one, and once the invoice is issued.

Mevcut seçenekler:
charge_automatically,
send_invoice,
null
Örnek:

"charge_automatically"

scheduled_send_at
string | null
gerekli
Örnek:

null

sends_on_due_date
boolean
gerekli

Whether this draft is issued automatically when its due_at arrives. Issuing it charges its payment_method_id, or emails its payment link to its recipient_emails. false for an invoice that is not a draft and for a draft with a scheduled send. false while sending the draft would fail for missing recipients or an unavailable payment link. false for a draft that had no future due_at when it was last saved. false for a draft created before 2026-11-12T22:00:00Z.

Örnek:

false

status
enum<string>
gerekli
Mevcut seçenekler:
draft,
open,
authorized,
paid,
pending,
uncollectible,
unresolved,
void
Örnek:

"open"

subscription_starts_at
string | null
gerekli

When the first billing period of the invoice's recurring items starts, as an ISO 8601 timestamp. Renewals count from this moment. null starts the period when the invoice is paid, and so does a time that has passed by then. An invoice with a start date skips its variants' free trial.

Örnek:

null

subtotal
object
gerekli
tax_amount
object | null
gerekli
time_zone
string
gerekli

The IANA time zone for the dates on the invoice's email and PDF, such as America/New_York. UTC unless one was set.

Örnek:

"UTC"

total
object
gerekli
totals_status
enum<string>
gerekli
Mevcut seçenekler:
estimated,
final
Örnek:

"final"

updated_at
string
gerekli
Örnek:

"2026-01-01T12:00:00.000Z"