v49

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-081445491.8 MB

Invoice

Create a one-off invoice

This endpoint is used to create a one-off invoice for a customer.

post/invoices

Request body

metadataobject nullable

User-specified key/value pairs for the resource. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

customer_idstring nullable

The id of the Customer to create this invoice for. One of customer_id and external_customer_id are required.

external_customer_idstring nullable

The external_customer_id of the Customer to create this invoice for. One of customer_id and external_customer_id are required.

currencystring required

An ISO 4217 currency string. Must be the same as the customer's currency if it is set.

memostring nullable

An optional memo to attach to the invoice. If no memo is provided, we will attach the default memo

will_auto_issueboolean

When true, this invoice will be submitted for issuance upon creation. When false, the resulting invoice will require manual review to issue. Defaulted to false.

invoice_datestring date-time required

Optional invoice date to set. Must be in the past, if not set, invoice_date is set to the current time in the customer's timezone.

net_termsinteger nullable

The net terms determines the due date of the invoice. Due date is calculated based on the invoice or issuance date, depending on the account's configured due date calculation method. A value of '0' here represents that the invoice is due on issue, whereas a value of '30' represents that the customer has 30 days to pay the invoice. Do not set this field if you want to set a custom due date.

auto_collectionboolean nullable

Determines whether this invoice will automatically attempt to charge a saved payment method, if any. If not specified, the invoice inherits the customer's auto_collection setting.

Example request

{
  "customer_id": "4khy3nwzktxv7",
  "external_customer_id": "external-customer-id",
  "currency": "USD",
  "memo": "An optional memo for my invoice.",
  "line_items": [
    {
      "start_date": "2023-09-22",
      "end_date": "2023-09-22",
      "quantity": 1,
      "name": "Line Item Name",
      "item_id": "4khy3nwzktxv7",
      "model_type": "unit"
    }
  ],
  "discount": {
    "applies_to_price_ids": [
      "h74gfhdjvn7ujokd",
      "7hfgtgjnbvc3ujkl"
    ],
    "percentage_discount": 0.15
  }
}

Response

Created

metadataobject required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

voided_atstring date-time nullable required

If the invoice has a status of void, this gives a timestamp when the invoice was voided.

paid_atstring date-time nullable required

If the invoice has a status of paid, this gives a timestamp when the invoice was paid.

issued_atstring date-time nullable required

If the invoice has been issued, this will be the time it transitioned to issued (even if it is now in a different state.)

scheduled_issue_atstring date-time nullable required

If the invoice is in draft, this timestamp will reflect when the invoice is scheduled to be issued.

issue_failed_atstring date-time nullable required

If the invoice failed to issue, this will be the last time it failed to issue (even if it is now in a different state.)

sync_failed_atstring date-time nullable required

If the invoice failed to sync, this will be the last time an external invoicing provider sync was attempted. This field will always be null for invoices using Orb Invoicing.

payment_failed_atstring date-time nullable required

If payment was attempted on this invoice but failed, this will be the time of the most recent attempt.

payment_started_atstring date-time nullable required

If payment was attempted on this invoice, this will be the start time of the most recent attempt. This field is especially useful for delayed-notification payment mechanisms (like bank transfers), where payment can take 3 days or more.

amount_duestring required

This is the final amount required to be charged to the customer and reflects the application of the customer balance to the total of the invoice.

created_atstring date-time required

The creation time of the resource in Orb.

currencystring required

An ISO 4217 currency string or credits

due_datestring date-time nullable required

When the invoice payment is due. The due date is null if the invoice is not yet finalized.

idstring required

invoice_pdfstring nullable required

The link to download the PDF representation of the Invoice.

invoice_numberstring required

Automatically generated invoice number to help track and reconcile invoices. Invoice numbers have a prefix such as RFOBWG. These can be sequential per account or customer.

totalstring required

The total after any minimums and discounts have been applied.

status'issued' | 'paid' | 'synced' | 'void' | 'draft' required

invoice_source'subscription' | 'partial' | 'one_off' required

hosted_invoice_urlstring nullable required

A URL for the customer-facing invoice portal. This URL expires 60 days after the link is generated, or 30 days after the invoice's due date — whichever is later.

will_auto_issueboolean required

This is true if the invoice will be automatically issued in the future, and false otherwise.

eligible_to_issue_atstring date-time nullable required

If the invoice has a status of draft, this will be the time that the invoice will be eligible to be issued, otherwise it will be null. If auto-issue is true, the invoice will automatically begin issuing at this time.

Country	Type	Description
Albania	al_tin	Albania Tax Identification Number
Andorra	ad_nrt	Andorran NRT Number
Angola	ao_tin	Angola Tax Identification Number
Argentina	ar_cuit	Argentinian Tax ID Number
Armenia	am_tin	Armenia Tax Identification Number
Aruba	aw_tin	Aruba Tax Identification Number
Australia	au_abn	Australian Business Number (AU ABN)
Australia	au_arn	Australian Taxation Office Reference Number
Austria	eu_vat	European VAT Number
Azerbaijan	az_tin	Azerbaijan Tax Identification Number
Bahamas	bs_tin	Bahamas Tax Identification Number
Bahrain	bh_vat	Bahraini VAT Number
Bangladesh	bd_bin	Bangladesh Business Identification Number
Barbados	bb_tin	Barbados Tax Identification Number
Belarus	by_tin	Belarus TIN Number
Belgium	eu_vat	European VAT Number
Benin	bj_ifu	Benin Tax Identification Number (Identifiant Fiscal Unique)
Bolivia	bo_tin	Bolivian Tax ID
Bosnia and Herzegovina	ba_tin	Bosnia and Herzegovina Tax Identification Number
Brazil	br_cnpj	Brazilian CNPJ Number
Brazil	br_cpf	Brazilian CPF Number
Bulgaria	bg_uic	Bulgaria Unified Identification Code
Bulgaria	eu_vat	European VAT Number
Burkina Faso	bf_ifu	Burkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique)
Cambodia	kh_tin	Cambodia Tax Identification Number
Cameroon	cm_niu	Cameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique)
Canada	ca_bn	Canadian BN
Canada	ca_gst_hst	Canadian GST/HST Number
Canada	ca_pst_bc	Canadian PST Number (British Columbia)
Canada	ca_pst_mb	Canadian PST Number (Manitoba)
Canada	ca_pst_sk	Canadian PST Number (Saskatchewan)
Canada	ca_qst	Canadian QST Number (Québec)
Cape Verde	cv_nif	Cape Verde Tax Identification Number (Número de Identificação Fiscal)
Chile	cl_tin	Chilean TIN
China	cn_tin	Chinese Tax ID
Colombia	co_nit	Colombian NIT Number
Congo-Kinshasa	cd_nif	Congo (DR) Tax Identification Number (Número de Identificação Fiscal)
Costa Rica	cr_tin	Costa Rican Tax ID
Croatia	eu_vat	European VAT Number
Croatia	hr_oib	Croatian Personal Identification Number (OIB)
Cyprus	eu_vat	European VAT Number
Czech Republic	eu_vat	European VAT Number
Denmark	eu_vat	European VAT Number
Dominican Republic	do_rcn	Dominican RCN Number
Ecuador	ec_ruc	Ecuadorian RUC Number
Egypt	eg_tin	Egyptian Tax Identification Number
El Salvador	sv_nit	El Salvadorian NIT Number
Estonia	eu_vat	European VAT Number
Ethiopia	et_tin	Ethiopia Tax Identification Number
European Union	eu_oss_vat	European One Stop Shop VAT Number for non-Union scheme
Faroe Islands	fo_vat	Faroe Islands VAT Number
Finland	eu_vat	European VAT Number
France	eu_vat	European VAT Number
Georgia	ge_vat	Georgian VAT
Germany	de_stn	German Tax Number (Steuernummer)
Germany	eu_vat	European VAT Number
Gibraltar	gi_tin	Gibraltar Tax Identification Number
Greece	eu_vat	European VAT Number
Guinea	gn_nif	Guinea Tax Identification Number (Número de Identificação Fiscal)
Hong Kong	hk_br	Hong Kong BR Number
Hungary	eu_vat	European VAT Number
Hungary	hu_tin	Hungary Tax Number (adószám)
Iceland	is_vat	Icelandic VAT
India	in_gst	Indian GST Number
Indonesia	id_npwp	Indonesian NPWP Number
Ireland	eu_vat	European VAT Number
Israel	il_vat	Israel VAT
Italy	eu_vat	European VAT Number
Italy	it_cf	Italian Codice Fiscale Number
Japan	jp_cn	Japanese Corporate Number (Hōjin Bangō)
Japan	jp_rn	Japanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)
Japan	jp_trn	Japanese Tax Registration Number (Tōroku Bangō)
Kazakhstan	kz_bin	Kazakhstani Business Identification Number
Kenya	ke_pin	Kenya Revenue Authority Personal Identification Number
Kyrgyzstan	kg_tin	Kyrgyzstan Tax Identification Number
Laos	la_tin	Laos Tax Identification Number
Latvia	eu_vat	European VAT Number
Liechtenstein	li_uid	Liechtensteinian UID Number
Liechtenstein	li_vat	Liechtenstein VAT Number
Lithuania	eu_vat	European VAT Number
Luxembourg	eu_vat	European VAT Number
Malaysia	my_frp	Malaysian FRP Number
Malaysia	my_itn	Malaysian ITN
Malaysia	my_sst	Malaysian SST Number
Malta	eu_vat	European VAT Number
Mauritania	mr_nif	Mauritania Tax Identification Number (Número de Identificação Fiscal)
Mexico	mx_rfc	Mexican RFC Number
Moldova	md_vat	Moldova VAT Number
Montenegro	me_pib	Montenegro PIB Number
Morocco	ma_vat	Morocco VAT Number
Nepal	np_pan	Nepal PAN Number
Netherlands	eu_vat	European VAT Number
New Zealand	nz_gst	New Zealand GST Number
Nigeria	ng_tin	Nigerian Tax Identification Number
North Macedonia	mk_vat	North Macedonia VAT Number
Northern Ireland	eu_vat	Northern Ireland VAT Number
Norway	no_vat	Norwegian VAT Number
Norway	no_voec	Norwegian VAT on e-commerce Number
Oman	om_vat	Omani VAT Number
Paraguay	py_ruc	Paraguayan RUC Number
Peru	pe_ruc	Peruvian RUC Number
Philippines	ph_tin	Philippines Tax Identification Number
Poland	eu_vat	European VAT Number
Poland	pl_nip	Polish Tax ID Number
Portugal	eu_vat	European VAT Number
Romania	eu_vat	European VAT Number
Romania	ro_tin	Romanian Tax ID Number
Russia	ru_inn	Russian INN
Russia	ru_kpp	Russian KPP
Saudi Arabia	sa_vat	Saudi Arabia VAT
Senegal	sn_ninea	Senegal NINEA Number
Serbia	rs_pib	Serbian PIB Number
Singapore	sg_gst	Singaporean GST
Singapore	sg_uen	Singaporean UEN
Slovakia	eu_vat	European VAT Number
Slovenia	eu_vat	European VAT Number
Slovenia	si_tin	Slovenia Tax Number (davčna številka)
South Africa	za_vat	South African VAT Number
South Korea	kr_brn	Korean BRN
Spain	es_cif	Spanish NIF Number (previously Spanish CIF Number)
Spain	eu_vat	European VAT Number
Sri Lanka	lk_vat	Sri Lanka VAT Number
Suriname	sr_fin	Suriname FIN Number
Sweden	eu_vat	European VAT Number
Switzerland	ch_uid	Switzerland UID Number
Switzerland	ch_vat	Switzerland VAT Number
Taiwan	tw_vat	Taiwanese VAT
Tajikistan	tj_tin	Tajikistan Tax Identification Number
Tanzania	tz_vat	Tanzania VAT Number
Thailand	th_vat	Thai VAT
Turkey	tr_tin	Turkish Tax Identification Number
Uganda	ug_tin	Uganda Tax Identification Number
Ukraine	ua_vat	Ukrainian VAT
United Arab Emirates	ae_trn	United Arab Emirates TRN
United Kingdom	gb_vat	United Kingdom VAT Number
United States	us_ein	United States EIN
Uruguay	uy_ruc	Uruguayan RUC Number
Uzbekistan	uz_tin	Uzbekistan TIN Number
Uzbekistan	uz_vat	Uzbekistan VAT Number
Venezuela	ve_rif	Venezuelan RIF Number
Vietnam	vn_tin	Vietnamese Tax ID Number
Zambia	zm_tin	Zambia Tax Identification Number
Zimbabwe	zw_tin	Zimbabwe Tax Identification Number

memostring nullable required

Free-form text which is available on the invoice PDF and the Orb invoice portal.

{"stackTrail":"components:schemas:DEPRECATED_InvoiceLevelDiscount","oasType":"schema","type":"unknown","title":"DEPRECATED_InvoiceLevelDiscount"}

minimum_amountstring nullable required

maximum_amountstring nullable required

subtotalstring required

The total before any discounts and minimums are applied.

invoice_datestring date-time required

The scheduled date of the invoice

v49

Create a one-off invoice

Request body

Example request

Response

Supported Tax ID Countries and Types