Passer au contenu principal
POST
/
v1
/
invoices
Create invoice
curl --request POST \
  --url https://api.hyperline.co/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "cus_Typ0px2W0aiEtl",
  "line_items": [
    {
      "name": "Platform access",
      "unit_amount": 24000,
      "description": "Access fee for the period of November 2024",
      "units_count": 1,
      "tax_rate": 20,
      "period_start": "2024-10-13T00:00:00.000Z",
      "period_end": "2024-11-13T00:00:00.000Z",
      "display_unit_amount": true,
      "display_service_period": true,
      "product_id": "itm_KbLcWt2qm5p1S2"
    }
  ],
  "currency": "EUR",
  "status": "paid",
  "invoicing_entity_id": "ive_47484fjdhy5",
  "number": "INV-35",
  "type": "invoice",
  "document_name": "<string>",
  "reference": "V0KAHOU6J3",
  "purchase_order": "PO-12345",
  "custom_note": "Thank you for your purchase!",
  "additional_info": "This invoice must be paid within the payment delay indicated. After this period a late payment penalty of 10% will be applied.",
  "footer": "ACME (Acme SAS) is a company registered in France | SIREN N°123456",
  "tax_rate": 50,
  "tax_scheme": "auto",
  "payment_method_strategy": "external",
  "payment_method_id": "pm_1ryTrMj4TTAT1N",
  "bank_account_id": "bac_KJyPrMA1toAqRG",
  "subscription_id": "sub_amiaWZ3lzDIWaoT",
  "emitted_at": "2024-10-13T00:00:00.000Z",
  "due_at": "2024-11-12T00:00:00.000Z",
  "settled_at": "2024-10-15T14:01:56.000Z",
  "properties": {},
  "custom_properties": {},
  "transactions": [
    {
      "amount": 31500,
      "process_at": "2024-11-12T07:38:39.222Z",
      "payment_method_id": "pm_1xMpj5bwRqN7LM"
    }
  ],
  "coupons": [
    {
      "coupon_id": "cou_1eTaiytfA0i2Vb",
      "name": "Black Friday 2023",
      "discount_amount": 500,
      "line_item_indexes": [
        0,
        1
      ]
    }
  ]
}
'
{
  "id": "inv_1eTaiytfA0i2Va",
  "number": "INV-35",
  "type": "invoice",
  "document_name": null,
  "status": "paid",
  "reference": "V0KAHOU6J3",
  "purchase_order": "PO-12345",
  "currency": "EUR",
  "source": "hyperline",
  "total_amount": 24000,
  "amount_due": 0,
  "amount_paid": 24000,
  "amount_fixed": 20000,
  "amount_excluding_tax": 20000,
  "tax_rate": 123,
  "tax_amount": 4000,
  "tax_scheme": "standard",
  "discount_amount": 0,
  "conversion_rate": 1,
  "converted_amount": 24000,
  "converted_at": "2024-10-13T02:00:00.000Z",
  "payment_method_id": "pm_1ryTrMj4TTAT1N",
  "bank_account_id": "bac_KJyPrMA1toAqRG",
  "custom_note": "Thank you for your purchase!",
  "additional_info": "This invoice must be paid within the payment delay indicated. After this period a late payment penalty of 10% will be applied.",
  "footer": "ACME (Acme SAS) is a company registered in France | SIREN N°123456",
  "customer": {
    "id": "cus_Typ0px2W0aiEtl",
    "name": "Acme",
    "email": "billing@acme.com",
    "external_id": null,
    "vat_number": "<string>",
    "tax_id": "FR123456789",
    "address": {
      "name": "Acme",
      "line1": "5 rue de Paradis",
      "line2": null,
      "city": "Paris",
      "zip": "75010",
      "state": "CA",
      "country": "FR"
    }
  },
  "seller": {
    "id": "ive_47484fjdhy5",
    "name": "Name of the invoicing entity",
    "tax_id": "FR5878986578",
    "address": {
      "name": "Acme",
      "line1": "5 rue de Paradis",
      "line2": null,
      "city": "Paris",
      "zip": "75010",
      "state": "CA",
      "country": "FR"
    }
  },
  "subscription_id": "sub_amiaWZ3lzDIWaoT",
  "period_starts_at": "2024-10-13T00:00:00.000Z",
  "period_ends_at": "2024-11-13T00:00:00.000Z",
  "emitted_at": "2024-10-13T00:00:00.000Z",
  "due_at": "2024-11-12T00:00:00.000Z",
  "refunded_at": null,
  "grace_period_ended_at": null,
  "settled_at": "2024-10-15T14:01:56.000Z",
  "updated_at": "2024-10-15T14:01:56.000Z",
  "properties": null,
  "custom_properties": null,
  "original_invoice_id": null,
  "original_invoice_number": null,
  "line_items": [
    {
      "id": "ili_0FACNpeoEFkGu3",
      "name": "Platform access",
      "entry_type": "debit",
      "product_id": "itm_KbLcWt2qm5p1S2",
      "product_type": "flat_fee",
      "units_count": 1,
      "unit_amount": 24000,
      "amount": 24000,
      "amount_excluding_tax": 20000,
      "tax_rate": 20,
      "tax_rate_id": null,
      "tax_amount": 4000,
      "discount_amount": 0,
      "discount_percent": 123,
      "period_starts_at": "2024-10-13T00:00:00.000Z",
      "period_ends_at": "2024-11-13T00:00:00.000Z",
      "revenue_type": "recurring",
      "revenue_interval_count": 1,
      "revenue_interval_period": "months",
      "display_unit_amount": true,
      "display_service_period": true,
      "original_line_item_id": null
    }
  ],
  "coupons": [
    {
      "id": "cou_DKL4Xcb5VSa8CQ",
      "name": "Partner discount",
      "discount_amount": 2000,
      "discount_percent": null,
      "line_item_ids": [
        "ili_0FACNpeoEFkGu3"
      ]
    }
  ],
  "transactions": [
    {
      "id": "tra_2QdJDDUej969ev",
      "type": "subscription",
      "amount": 31500,
      "currency": "EUR",
      "customer_id": "cus_QalW2vTAdkR6IY",
      "provider_id": "<string>",
      "process_at": "2024-11-12T07:38:39.222Z",
      "refunded_at": null,
      "last_refreshed_at": null,
      "provider_fee": null,
      "chargeback": null,
      "integrations": [
        {
          "entity_id": "123456789",
          "provider_name": "stripe",
          "provider_account_id": "acc_1234567890"
        }
      ],
      "payment_method": {
        "id": "pm_1xMpj5bwRqN7LM",
        "status": "active",
        "type": "card",
        "last_4_digits": 2718,
        "expiration_date": "2027-11",
        "brand": "<string>"
      },
      "status": "settled"
    }
  ],
  "public_url": "<string>",
  "integrations": [
    {
      "entity_id": "123456789",
      "provider_name": "stripe",
      "provider_account_id": "acc_1234567890"
    }
  ]
}

Autorisations

​
Authorization
string
header
requis

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corps

application/json

Create invoice payload

​
customer_id
string
requis

Customer ID.

Exemple:

"cus_Typ0px2W0aiEtl"

​
line_items
object[]
requis
Minimum array length: 1
​
currency
enum<string>

Currency code of the invoice. See ISO 4217.

Options disponibles:
EUR,
AED,
AFN,
XCD,
ALL,
AMD,
AOA,
ARS,
USD,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
XOF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
NOK,
BWP,
BYR,
BZD,
CAD,
CDF,
XAF,
CHF,
NZD,
CLP,
CNY,
COP,
CRC,
CUP,
CVE,
ANG,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
MAD,
ERN,
ETB,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRO,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
XPF,
NGN,
NIO,
NPR,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
SSP,
STD,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
UYU,
UZS,
VEF,
VND,
VUV,
WST,
YER,
ZAR,
ZMW,
ZWL
Exemple:

"EUR"

​
status
enum<string>
défaut:paid

Current invoice status.

  • draft: Invoice is in draft mode (not finalized yet).
  • open: Invoice for the current billing period, which will be issued at the end of the period (used for invoices with usage-based data).
  • grace_period: Invoice is in a review period after being issued for the billing period and before becoming due for payment.
  • to_pay: Invoice is awaiting payment.
  • partially_paid: Invoice is partially paid.
  • paid: Invoice is fully paid.
  • voided: Invoice has been voided and is no longer valid.
  • closed: Invoice was not issued and has been discarded.
  • error: Invoice failed to be paid.
  • archived: A previous version of an invoice.
  • charged_on_parent: Invoice is charged on the parent customer.
  • pending_parent_concat: Invoice is pending invoices concatenation on the parent customer to be grouped.
  • uncollectible: Invoice is uncollectible (bad debt).
Options disponibles:
to_pay,
paid,
draft
Exemple:

"paid"

​
invoicing_entity_id
string

ID of the invoicing entity attached to the invoice.

Exemple:

"ive_47484fjdhy5"

​
number
string

Invoice number. If specified, the invoice will be considered as imported from an external source and the number will not be generated by Hyperline. You are responsible for avoiding duplicates and ensuring it does not impact the numbering sequence in Hyperline.

Exemple:

"INV-35"

​
type
enum<string>

Type of the invoice.

  • invoice: Legal invoice to be paid by your customer.
  • credit_note: Legal credit note cancelling an invoice and refunding your customer.
  • document: Custom document with no legal value. Can be generated from a subscription to meet specific needs.
Options disponibles:
invoice,
credit_note,
document
Exemple:

"invoice"

​
document_name
string

If the invoice is of type document you can give it a custom name (displayed on the final PDF).

​
reference
string

Unique identifier to ease reconciliation with payment. Useful for bank transfer.

Exemple:

"V0KAHOU6J3"

​
purchase_order
string

Reference to the purchase order linked to the invoice.

Exemple:

"PO-12345"

​
custom_note
string

Custom note added to the invoice.

Exemple:

"Thank you for your purchase!"

​
additional_info
string

Additional information added to the invoice. If not defined, it will be inherited from the invoicing entity's settings.

Exemple:

"This invoice must be paid within the payment delay indicated. After this period a late payment penalty of 10% will be applied."

​
footer
string

Footer added to the invoice. If not defined, it will be inherited from the invoicing entity's settings.

Exemple:

"ACME (Acme SAS) is a company registered in France | SIREN N°123456"

​
tax_rate
number
obsolète

Deprecated field, please use line_items[].tax_rate.

Plage requise: 0 <= x <= 100
​
tax_scheme
enum<string>
défaut:auto

Tax scheme of the invoice.

  • auto: Tax is automatically computed and applied.
  • not_eligible: Tax collection is disabled for the invoice.
Options disponibles:
auto,
not_eligible
Exemple:

"auto"

​
payment_method_strategy
enum<string>

Payment method strategy used to charge the invoice. Only applies to to_pay status.

  • current: Use the current default payment method of the customer.
  • external: Manage the payment of the invoice outside of Hyperline.
Options disponibles:
current,
external
Exemple:

"external"

​
payment_method_id
string

ID of the default payment method used to pay the invoice. Transactions related to the invoice may use different payment methods.

Exemple:

"pm_1ryTrMj4TTAT1N"

​
bank_account_id
string

ID of the bank account displayed on the invoice. Transactions related to the invoice may use different bank accounts.

Exemple:

"bac_KJyPrMA1toAqRG"

​
subscription_id
string

ID of the subscription related to the invoice.

Exemple:

"sub_amiaWZ3lzDIWaoT"

​
emitted_at
string<date-time>

Issue date of the invoice.

Exemple:

"2024-10-13T00:00:00.000Z"

​
due_at
string<date-time>

Due date of the invoice. Computed from the issue date and the payment delay configured in your settings.

Exemple:

"2024-11-12T00:00:00.000Z"

​
settled_at
string<date-time>

Date the invoice was fully paid.

Exemple:

"2024-10-15T14:01:56.000Z"

​
properties
object

Key/value pairs to store any metadata useful in your context.

​
custom_properties
object

Values for custom properties defined for the invoice entity, keyed by slug.

​
transactions
object[]
​
coupons
(Coupon amount · object | Inline coupon · object)[]

Réponse

201 - application/json
​
id
string
requis

Invoice ID.

Exemple:

"inv_1eTaiytfA0i2Va"

​
number
string
requis

Invoice number. Generated by Hyperline using the sequential numbering and format defined in your settings.

Exemple:

"INV-35"

​
type
enum<string>
requis

Type of the invoice.

  • invoice: Legal invoice to be paid by your customer.
  • credit_note: Legal credit note cancelling an invoice and refunding your customer.
  • document: Custom document with no legal value. Can be generated from a subscription to meet specific needs.
Options disponibles:
invoice,
credit_note,
document,
child_invoice_ref,
child_creditnote_ref
Exemple:

"invoice"

​
document_name
string | null
requis

If the invoice is of type document you can give it a custom name (displayed on the final PDF).

Exemple:

null

​
status
enum<string>
requis

Current invoice status.

  • draft: Invoice is in draft mode (not finalized yet).
  • open: Invoice for the current billing period, which will be issued at the end of the period (used for invoices with usage-based data).
  • grace_period: Invoice is in a review period after being issued for the billing period and before becoming due for payment.
  • to_pay: Invoice is awaiting payment.
  • partially_paid: Invoice is partially paid.
  • paid: Invoice is fully paid.
  • voided: Invoice has been voided and is no longer valid.
  • closed: Invoice was not issued and has been discarded.
  • error: Invoice failed to be paid.
  • archived: A previous version of an invoice.
  • charged_on_parent: Invoice is charged on the parent customer.
  • pending_parent_concat: Invoice is pending invoices concatenation on the parent customer to be grouped.
  • uncollectible: Invoice is uncollectible (bad debt).
Options disponibles:
draft,
open,
to_pay,
grace_period,
partially_paid,
paid,
voided,
closed,
error,
missing_info,
archived,
charged_on_parent,
pending_parent_concat,
uncollectible
Exemple:

"paid"

​
reference
string | null
requis

Unique identifier to ease reconciliation with payment. Useful for bank transfer.

Exemple:

"V0KAHOU6J3"

​
purchase_order
string | null
requis

Reference to the purchase order linked to the invoice.

Exemple:

"PO-12345"

​
currency
enum<string>
requis

Currency code. See ISO 4217.

Options disponibles:
EUR,
AED,
AFN,
XCD,
ALL,
AMD,
AOA,
ARS,
USD,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
BGN,
BHD,
BIF,
XOF,
BMD,
BND,
BOB,
BRL,
BSD,
BTN,
NOK,
BWP,
BYR,
BZD,
CAD,
CDF,
XAF,
CHF,
NZD,
CLP,
CNY,
COP,
CRC,
CUP,
CVE,
ANG,
CZK,
DJF,
DKK,
DOP,
DZD,
EGP,
MAD,
ERN,
ETB,
FJD,
FKP,
GBP,
GEL,
GHS,
GIP,
GMD,
GNF,
GTQ,
GYD,
HKD,
HNL,
HRK,
HTG,
HUF,
IDR,
ILS,
INR,
IQD,
IRR,
ISK,
JMD,
JOD,
JPY,
KES,
KGS,
KHR,
KMF,
KPW,
KRW,
KWD,
KYD,
KZT,
LAK,
LBP,
LKR,
LRD,
LSL,
LYD,
MDL,
MGA,
MKD,
MMK,
MNT,
MOP,
MRO,
MUR,
MVR,
MWK,
MXN,
MYR,
MZN,
NAD,
XPF,
NGN,
NIO,
NPR,
OMR,
PAB,
PEN,
PGK,
PHP,
PKR,
PLN,
PYG,
QAR,
RON,
RSD,
RUB,
RWF,
SAR,
SBD,
SCR,
SDG,
SEK,
SGD,
SHP,
SLL,
SOS,
SRD,
SSP,
STD,
SYP,
SZL,
THB,
TJS,
TMT,
TND,
TOP,
TRY,
TTD,
TWD,
TZS,
UAH,
UGX,
UYU,
UZS,
VEF,
VND,
VUV,
WST,
YER,
ZAR,
ZMW,
ZWL
Exemple:

"EUR"

​
source
enum<string>
requis

Source of the invoice. - hyperline: Invoice created by Hyperline. - api: Invoice created through the API. - other: Invoice created by an external source.

Options disponibles:
hyperline,
api,
pennylane,
chargebee,
stripe,
lago,
sequence,
other
Exemple:

"hyperline"

​
total_amount
number
requis

Sum of the amount and taxes amount of all products on the invoice. Expressed in currency's smallest unit.

Exemple:

24000

​
amount_due
number
requis

Amount still need to be paid for the invoice. Expressed in currency's smallest unit.

Exemple:

0

​
amount_paid
number
requis

Amount already paid for the invoice. Expressed in currency's smallest unit.

Exemple:

24000

​
amount_fixed
number
requis

Amount corresponding to the recurring non-variable part of the total amount. Expressed in currency's smallest unit.

Exemple:

20000

​
amount_excluding_tax
number
requis

Total amount without the taxes amount. Expressed in currency's smallest unit.

Exemple:

20000

​
tax_rate
number
requis
obsolète

Deprecated field, please use line_items[].tax_rate.

​
tax_amount
number
requis

Tax amount of the invoice. Expressed in currency's smallest unit.

Exemple:

4000

​
tax_scheme
enum<string>
requis

Tax scheme of the invoice.

  • standard: Tax rate is resolved depending on local tax regulations.
  • exempt: No tax rate applied because the customer country doesn't require it.
  • reverse_charge: No tax rate applied because the customer is eligible to EU reverse charge.
  • manual: Tax rate has been manually specified when creating the invoice.
  • not_eligible: Tax collection is disabled for the invoice.
Options disponibles:
exempt,
standard,
reverse_charge,
manual,
not_eligible
Exemple:

"standard"

​
discount_amount
number
requis

Amount corresponding to the discounted part of the total amount. Expressed in currency's smallest unit.

Exemple:

0

​
conversion_rate
number | null
requis

Conversion rate used between the invoice currency and your accounting currency.

Exemple:

1

​
converted_amount
number | null
requis

Amount converted using the conversion rate. Expressed in currency's smallest unit.

Exemple:

24000

​
converted_at
string<date-time> | null
requis

Date of the conversion of the amount.

Exemple:

"2024-10-13T02:00:00.000Z"

​
payment_method_id
string | null
requis

ID of the default payment method used to pay the invoice. Transactions related to the invoice may use different payment methods.

Exemple:

"pm_1ryTrMj4TTAT1N"

​
bank_account_id
string | null
requis

ID of the bank account displayed on the invoice. Transactions related to the invoice may use different bank accounts.

Exemple:

"bac_KJyPrMA1toAqRG"

​
custom_note
string | null
requis

Custom note added to the invoice.

Exemple:

"Thank you for your purchase!"

​
additional_info
string | null
requis

Additional information added to the invoice. If not defined, it will be inherited from the invoicing entity's settings.

Exemple:

"This invoice must be paid within the payment delay indicated. After this period a late payment penalty of 10% will be applied."

​
footer
string | null
requis

Footer added to the invoice. If not defined, it will be inherited from the invoicing entity's settings.

Exemple:

"ACME (Acme SAS) is a company registered in France | SIREN N°123456"

​
customer
object
requis
​
seller
object
requis
​
subscription_id
string | null
requis

ID of the subscription related to the invoice.

Exemple:

"sub_amiaWZ3lzDIWaoT"

​
period_starts_at
string<date-time> | null
requis

Start date of the billing period of the invoice.

Exemple:

"2024-10-13T00:00:00.000Z"

​
period_ends_at
string<date-time> | null
requis

End date of the billing period of the invoice.

Exemple:

"2024-11-13T00:00:00.000Z"

​
emitted_at
string<date-time>
requis

Issue date of the invoice.

Exemple:

"2024-10-13T00:00:00.000Z"

​
due_at
string<date-time>
requis

Due date of the invoice. Computed from the issue date and the payment delay configured in your settings.

Exemple:

"2024-11-12T00:00:00.000Z"

​
refunded_at
string<date-time> | null
requis

Date corresponding to the refund of the invoice, previously paid. A credit note exists with an original invoice ID equals to this invoice ID.

Exemple:

null

​
grace_period_ended_at
string<date-time> | null
requis

Date the invoice grace period ended. This happens at the issue date + the grace period duration configured in your settings.

Exemple:

null

​
settled_at
string<date-time> | null
requis

Date the invoice was fully paid.

Exemple:

"2024-10-15T14:01:56.000Z"

​
updated_at
string<date-time> | null
requis

Date of the last update.

Exemple:

"2024-10-15T14:01:56.000Z"

​
properties
object
requis

Key/value pairs to store any metadata useful in your context.

Exemple:

null

​
custom_properties
object
requis

Values for custom properties defined for the invoice entity, keyed by slug.

Exemple:

null

​
original_invoice_id
string | null
requis

ID of the original invoice this entity is linked to (only used for credit note or organisation-based billing).

Exemple:

null

​
original_invoice_number
string | null
requis

Number of the original invoice this entity is linked to (only used for credit note).

Exemple:

null

​
line_items
object[]
requis

List of line items composing the invoice.

​
coupons
object[]
requis

List of coupons applied to the invoice.

​
transactions
object[]
requis

List of transactions related to the invoice.

​
public_url
string<uri>
requis

Public URL of the invoice page where the customer can pay the invoice.

​
integrations
object[]
requis