Skip to main content
PATCH
/
v1
/
invoices
/
{id}
Update invoice
curl --request PATCH \
  --url https://api.hyperline.co/v1/invoices/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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_scheme": "auto",
  "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": false,
      "product_id": "itm_KbLcWt2qm5p1S2"
    }
  ],
  "coupons": [
    {
      "coupon_id": "cou_1eTaiytfA0i2Vb",
      "name": "Black Friday 2023",
      "discount_amount": 500,
      "line_item_indexes": [
        0,
        1
      ]
    }
  ],
  "payment_method_type": "external",
  "payment_method_id": "pm_1ryTrMj4TTAT1N",
  "bank_account_id": "bac_KJyPrMA1toAqRG",
  "properties": {},
  "customer": {
    "name": "<string>",
    "email": "<string>",
    "tax_id": "<string>",
    "address": {
      "name": "Acme",
      "line1": "5 rue de Paradis",
      "line2": null,
      "city": "Paris",
      "zip": "75010",
      "state": "CA",
      "country": "FR"
    }
  }
}
'
{
  "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,
  "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": false,
      "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_type": "card",
      "payment_method": {
        "id": "pm_1xMpj5bwRqN7LM",
        "status": "active",
        "type": "card",
        "last_4_digits": 2718,
        "expiration_date": "2027-11",
        "brand": "visa"
      },
      "status": "settled"
    }
  ],
  "integrations": [
    {
      "entity_id": "123456789",
      "provider_name": "stripe",
      "provider_account_id": "acc_1234567890"
    }
  ],
  "public_url": "<string>"
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
id
string
required

Body

application/json

Update invoice payload

​
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.
Available options:
invoice,
credit_note,
document
Example:

"invoice"

​
document_name
string | null

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

​
reference
string | null

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

Example:

"V0KAHOU6J3"

​
purchase_order
string | null

Reference to the purchase order linked to the invoice.

Example:

"PO-12345"

​
custom_note
string | null

Custom note added to the invoice.

Example:

"Thank you for your purchase!"

​
additional_info
string | null

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

Example:

"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

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

Example:

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

​
tax_scheme
enum<string>
default:auto

Tax scheme of the invoice.

  • auto: Tax is automatically computed and applied.
  • not_eligible: Tax collection is disabled for the invoice.
Available options:
auto,
not_eligible
Example:

"auto"

​
line_items
object[]
Minimum array length: 1
​
coupons
(Coupon amount · object | Inline coupon · object)[]
​
payment_method_type
enum<string> | null
Available options:
external
​
payment_method_id
string | null

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

Example:

"pm_1ryTrMj4TTAT1N"

​
bank_account_id
string | null

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

Example:

"bac_KJyPrMA1toAqRG"

​
properties
object

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

​
customer
object

Override customer details on the invoice. Only allowed for draft or grace period invoices.

Response

​
id
string
required

Invoice ID.

Example:

"inv_1eTaiytfA0i2Va"

​
number
string
required

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

Example:

"INV-35"

​
type
enum<string>
required

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.
Available options:
invoice,
credit_note,
document,
child_invoice_ref,
child_creditnote_ref
Example:

"invoice"

​
document_name
string | null
required

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

Example:

null

​
status
enum<string>
required

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).
Available options:
draft,
open,
to_pay,
grace_period,
partially_paid,
paid,
voided,
closed,
error,
missing_info,
archived,
charged_on_parent,
pending_parent_concat,
uncollectible
Example:

"paid"

​
reference
string | null
required

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

Example:

"V0KAHOU6J3"

​
purchase_order
string | null
required

Reference to the purchase order linked to the invoice.

Example:

"PO-12345"

​
currency
enum<string>
required

Currency code. See ISO 4217.

Available options:
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
Example:

"EUR"

​
source
enum<string>
required

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

Available options:
hyperline,
api,
pennylane,
chargebee,
stripe,
lago,
sequence,
other
Example:

"hyperline"

​
total_amount
number
required

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

Example:

24000

​
amount_due
number
required

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

Example:

0

​
amount_paid
number
required

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

Example:

24000

​
amount_fixed
number
required

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

Example:

20000

​
amount_excluding_tax
number
required

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

Example:

20000

​
tax_rate
number
required
deprecated

Deprecated field, please use line_items[].tax_rate.

​
tax_amount
number
required

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

Example:

4000

​
tax_scheme
enum<string>
required

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.
Available options:
exempt,
standard,
reverse_charge,
manual,
not_eligible
Example:

"standard"

​
discount_amount
number
required

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

Example:

0

​
conversion_rate
number | null
required

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

Example:

1

​
converted_amount
number | null
required

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

Example:

24000

​
converted_at
string<date-time> | null
required

Date of the conversion of the amount.

Example:

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

​
payment_method_id
string | null
required

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

Example:

"pm_1ryTrMj4TTAT1N"

​
bank_account_id
string | null
required

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

Example:

"bac_KJyPrMA1toAqRG"

​
custom_note
string | null
required

Custom note added to the invoice.

Example:

"Thank you for your purchase!"

​
additional_info
string | null
required

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

Example:

"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
required

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

Example:

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

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

ID of the subscription related to the invoice.

Example:

"sub_amiaWZ3lzDIWaoT"

​
period_starts_at
string<date-time> | null
required

Start date of the billing period of the invoice.

Example:

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

​
period_ends_at
string<date-time> | null
required

End date of the billing period of the invoice.

Example:

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

​
emitted_at
string<date-time>
required

Emission date of the invoice.

Example:

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

​
due_at
string<date-time>
required

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

Example:

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

​
refunded_at
string<date-time> | null
required

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

Example:

null

​
grace_period_ended_at
string<date-time> | null
required

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

Example:

null

​
settled_at
string<date-time> | null
required

Date the invoice was fully paid.

Example:

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

​
updated_at
string<date-time> | null
required

Date of the last update.

Example:

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

​
properties
object
required

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

Example:

null

​
original_invoice_id
string | null
required

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

Example:

null

​
original_invoice_number
string | null
required

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

Example:

null

​
line_items
object[]
required

List of line items composing the invoice.

​
coupons
object[]
required

List of coupons applied to the invoice.

​
transactions
object[]
required

List of transactions related to the invoice.

​
integrations
object[]
required
​
public_url
string<uri>
required

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