POST
/
v1
/
invoices
/
batch
curl --request POST \
  --url https://api.hyperline.co/v1/invoices/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "customer_id": "inv_1eTaiytfA0i2Va",
    "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!",
    "tax_rate": 20,
    "tax_scheme": "auto",
    "payment_method_strategy": "external",
    "payment_method_id": "pm_1ryTrMj4TTAT1N",
    "bank_account_id": "bac_KJyPrMA1toAqRG",
    "emitted_at": "2024-10-13T00:00:00.000Z",
    "due_at": "2024-11-12T00:00:00.000Z",
    "settled_at": "2024-10-15T14:01:56.000Z",
    "line_items": [
      {
        "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",
        "product_id": "itm_KbLcWt2qm5p1S2",
        "name": "Platform access",
        "unit_amount": 24000
      }
    ],
    "batch_invoice_id": "invoice-123"
  }
]'
{
  "successes": [
    {
      "id": "inv_1eTaiytfA0i2Va",
      "number": "INV-35",
      "type": "invoice",
      "document_name": "<string>",
      "status": "paid",
      "reference": "V0KAHOU6J3",
      "purchase_order": "PO-12345",
      "original_invoice_id": "<string>",
      "original_invoice_number": "<string>",
      "currency": "EUR",
      "total_amount": 24000,
      "amount_due": 0,
      "amount_paid": 24000,
      "amount_fixed": 20000,
      "amount_excluding_tax": 20000,
      "tax_rate": 20,
      "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!",
      "customer": {
        "id": "cus_Typ0px2W0aiEtl",
        "name": "Acme",
        "email": "billing@acme.com",
        "external_id": "<string>",
        "vat_number": "FR123456789",
        "address": {
          "name": "Acme",
          "line1": "5 rue de Paradis",
          "line2": "<string>",
          "city": "Paris",
          "zip": "75010",
          "state": "<string>",
          "country": "FR"
        }
      },
      "seller": {
        "id": "ive_47484fjdhy5",
        "name": "Name of the invoicing entity",
        "tax_id": "FR5878986578",
        "address": {
          "name": "Acme",
          "line1": "5 rue de Paradis",
          "line2": "<string>",
          "city": "Paris",
          "zip": "75010",
          "state": "<string>",
          "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": "2024-10-13T02:00:00.000Z",
      "grace_period_ended_at": "2024-10-13T02:00:00.000Z",
      "settled_at": "2024-10-15T14:01:56.000Z",
      "updated_at": "2024-10-15T14:01:56.000Z",
      "line_items": [
        {
          "id": "ili_0FACNpeoEFkGu3",
          "name": "Platform access",
          "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": "<string>",
          "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"
        }
      ],
      "transactions": [
        {
          "id": "tra_2QdJDDUej969ev",
          "type": "subscription",
          "amount": 31500,
          "currency": "EUR",
          "customer_id": "cus_QalW2vTAdkR6IY",
          "provider_id": "pi_xxxxxxxxxx",
          "process_at": "2024-11-12T07:38:39.222Z",
          "refunded_at": "2024-10-13T02:00:00.000Z",
          "last_refreshed_at": "2024-10-13T02:00:00.000Z",
          "provider_fee": {
            "amount": 24000,
            "currency": "EUR",
            "exchange_rate": 123
          },
          "chargeback": {
            "amount": 31500,
            "last_chargeback_at": "2024-10-13T10:00:01.860Z"
          },
          "payment_method_type": "card",
          "payment_method": {
            "id": "pm_1xMpj5bwRqN7LM",
            "status": "active",
            "type": "card",
            "last_4_digits": 2718,
            "expiration_date": "2026-11",
            "brand": "visa"
          },
          "status": "settled"
        }
      ],
      "coupons": [
        {
          "id": "cou_DKL4Xcb5VSa8CQ",
          "name": "Partner discount",
          "discount_amount": 2000,
          "discount_percent": 123,
          "line_item_ids": [
            "ili_0FACNpeoEFkGu3"
          ]
        }
      ],
      "batch_invoice_id": "invoice-123"
    }
  ],
  "errors": [
    {
      "error": "<any>",
      "batch_invoice_id": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json · object[]
Create invoices payload
​
customer_id
string
required

Customer ID.

Example:

"inv_1eTaiytfA0i2Va"

​
line_items
object[]
required
​
batch_invoice_id
string
required

A unique identifier for the invoices in the batch

Example:

"invoice-123"

​
currency
enum<string>

Currency code of the invoice. See ISO 4217.

Available options:
EUR,
AED,
AFN,
XCD,
ALL,
AMD,
AOA,
ARS,
USD,
AUD,
AWG,
AZN,
BAM,
BBD,
BDT,
XOF,
BGN,
BHD,
BIF,
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"

​
status
enum<string>
default: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.
Available options:
to_pay,
paid,
draft
Example:

"paid"

​
invoicing_entity_id
string

ID of the invoicing entity attached to the invoice.

Example:

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

Example:

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

"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 generated by Hyperline to ease reconciliation with payment. Useful for bank transfer.

Example:

"V0KAHOU6J3"

​
purchase_order
string

Reference to the purchase order linked to the invoice.

Example:

"PO-12345"

​
custom_note
string

Custom note added to the invoice.

Example:

"Thank you for your purchase!"

​
tax_rate
number

Tax rate of the invoice.

Required range: 0 <= x <= 100
Example:

20

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

​
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.
Available options:
current,
external
Example:

"external"

​
payment_method_id
string

ID of the payment method used to pay the invoice.

Example:

"pm_1ryTrMj4TTAT1N"

​
bank_account_id
string

ID of the bank account displayed on the invoice.

Example:

"bac_KJyPrMA1toAqRG"

​
emitted_at
string

Emission date of the invoice.

Example:

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

​
due_at
string

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"

​
settled_at
string

Date the invoice was fully paid.

Example:

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

Response

201 - application/json
​
successes
object[]
required
​
errors
object[]
required