Skip to main content
POST
Create credit note

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

Create credit note payload

amount_including_tax
number

Amount of the credit note. If not specified, the amount will be computed from the original invoice.

Example:

24000

status
enum<string>

Status of the credit note.

  • to_pay: Credit note is awaiting payment.
  • draft: Credit note is in draft mode (not finalized yet).
Available options:
to_pay,
draft
Example:

"to_pay"

trigger_refund
boolean

Whether to trigger a refund for the credit note amount. Defaults to false. When true, the refund is issued using refund_method.

Example:

true

refund_method
enum<string>

How the refund should be settled. Only used when trigger_refund is true. Defaults to original_payment_method.

  • wallet: Credit the customer's wallet with the refunded amount.
  • original_payment_method: Refund to the payment method used on the original invoice.
  • external: Mark the refund as settled externally (no automatic transfer).
Available options:
wallet,
original_payment_method,
external
Example:

"wallet"

Response

201 - application/json
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). Only metadata (properties, custom_note, custom_properties) can be updated in this status.
Available options:
draft,
pending_approval,
changes_requested,
open,
to_pay,
grace_period,
partially_paid,
paid,
voided,
closed,
error,
missing_info,
archived,
charged_on_parent,
pending_parent_concat,
pending_consolidation,
consolidated,
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"

origin
enum<string> | null
required

What generated the invoice, whatever the channel used to create it (see source). New values may be added. - subscription: Generated by a subscription: renewal, update, transition, cancellation, reactivation or reinstatement. - quote: Generated by a quote. - wallet: Wallet top-up, free credits granted or expiration of the remaining balance. - customer_credits: Purchase of customer credits. - invoice: Built from other invoices: a credit note correcting an invoice, a consolidated invoice or an invoice re-billed to a parent organisation. - manual: Standalone invoice or credit note created by a user, in the app or through the API. - import: Imported from an external billing provider. Null for some invoices created before October 12, 2026.

Available options:
subscription,
quote,
wallet,
customer_credits,
invoice,
manual,
import
Example:

"subscription"

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:

"2026-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:

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

period_ends_at
string<date-time> | null
required

End date of the billing period of the invoice.

Example:

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

emitted_at
string<date-time>
required

Issue date of the invoice.

Example:

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

due_at
string<date-time>
required

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

Example:

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

issuing_method
enum<string>
required

How the invoice is issued.

  • manual: Issued when finalized, by a user or by the invoicing flow.
  • scheduled: Draft finalized automatically at the start of its issue date (issued_at), in the invoice timezone.
Available options:
manual,
scheduled
Example:

"manual"

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 issue 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:

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

updated_at
string<date-time> | null
required

Date of the last update.

Example:

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

properties
object | null
required

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

Example:

null

custom_properties
object | null
required

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

Example:

null

additional_display_fields
(Standard field · object | Custom property · object | Custom text · object)[] | null
required

Ordered additional fields displayed on the invoice PDF. Invoice and customer custom properties are referenced by slug.

Maximum array length: 20
Example:

null

original_invoice_id
string | null
required

ID of the reference invoice this entity is linked to. For credit notes, this is not necessarily an invoice receiving credit; use allocations for applications.

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
(Transaction Card/debit · object | Transaction Card/debit failed · object | Transaction Transfer · object | Transaction Transfer failed · object | Transaction Wallet · object | Transaction Wallet failed · object | Transaction External · object | Transaction External failed · object)[]
required

List of transactions related to the invoice.

public_url
string<uri>
required

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

integrations
object[]
required
electronic_invoices
object[]
required

Electronic invoicing status for each applicable system. Empty for drafts or invoices without an applicable configuration.

allocations
object[]

Current invoice applications made by this credit note. Only present for credit notes.