Skip to content

invoice.created

POST

Invoice created (invoice.created). Sent to an installation granted read_invoices.

webhook-id
required
string
/^msg_[0-9a-z]{26}$/

The message id, the same on every attempt: deduplicate on it.

webhook-timestamp
required
integer

Seconds since the epoch at this attempt; refuse one too far from now.

webhook-signature
required
string

v1, + base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body} with the signing secret (Standard Webhooks).

Media typeapplication/json
object
type
required

The webhook type.

string
Allowed value: invoice.created
timestamp
required

When the event happened, UTC with six fractional digits (2026-11-13T09:30:00.123456Z).

string format: date-time
organization
required

The organization it happened in (org_...).

string
/^org_[0-9a-z]{26}$/
data
required
InvoiceResource
object
id
required

The invoice’s public id (inv_...).

string
/^inv_[0-9a-z]{26}$/
order_id
required

The order it was issued for (ord_...); null once that order is deleted.

string | null
/^ord_[0-9a-z]{26}$/
kind
required

invoice, or storno: the credit note reversing an invoice in full (negative totals and quantities). New values may appear: treat one you do not know as such.

string
reversed_invoice_id
required

For a storno, the invoice it reverses (inv_...); null for an invoice.

string | null
/^inv_[0-9a-z]{26}$/
status
required

pending (asked, waiting its turn), submitting (the invoicing software is being asked now), failed (refused or never sent, see error_code; may be asked again), needs_attention (outcome unknown: a document may exist at the vendor, a person checks it in the app), issued (numbered, final), cancelled (issued, then cancelled at the vendor), reversed (issued, then reversed by an issued storno), discarded (no document came of it). New values may appear: treat one you do not know as such.

string
error_code
required

Why it is failed or needs_attention, a stable code: order_refused, account_unavailable, not_supported, credentials_rejected, rate_limited, invalid_data, vendor_rejected, not_sent, outcome_unknown, document_unread. Null in any other status. New codes may appear. New values may appear: treat one you do not know as such.

string | null
error_message
required

The code’s meaning, in English; the app shows the merchant the full reason in their language.

string | null
vendor_message
required

The invoicing software’s own words when it answered, as it sent them, in its language: for display only, never to parse.

string | null
series
required

The series as the invoicing software numbered it (e.g. FCT); null until issued.

string | null
number
required

The number inside the series, a string with its leading zeros (e.g. 0042); null until issued.

string | null
issue_date
required

The document’s date, a plain day in the organization’s calendar; until issued, the day it was asked for.

string format: date
due_date
required

The payment due day; null for a storno or without one.

string | null format: date
integration_id
required

The invoicing account it goes through (int_...); null once that integration is removed.

string | null
/^int_[0-9a-z]{26}$/
currency
required

ISO 4217.

string
prices_include_tax
required

Whether the lines’ unit prices include tax.

boolean
totals
required

Net (without tax) + tax = total; negative on a storno.

object
net
required
object
amount
required
string
currency
required
string
tax
required
object
amount
required
string
currency
required
string
total
required
object
amount
required
string
currency
required
string
buyer
required

The buyer as invoiced, in the v1 address shape (first_name and last_name null: an invoice names the buyer whole; company = the name for a company buyer), plus its fiscal code and trade register number. The seller is the organization itself and is not copied on the invoice.

object
name
required
string | null
first_name
required
string | null
last_name
required
string | null
company
required
string | null
email
required
string | null
phone
required
string | null
address_line_1
required
string | null
address_line_2
required
string | null
city
required
string | null
region
required
string | null
region_code
required
string | null
postal_code
required
string | null
country_code
required
string | null
locality_code
required
string | null
tax_id
required
string | null
registration_number
required
string | null
lines
required

The lines by position, at most 250 (MAX_LINES); lines_count is the full count.

Array<object>
object
kind
required

New values may appear: treat one you do not know as such.

string
code
required

The product code (the store’s SKU); null without one.

string | null
name
required
string
quantity
required

A decimal string, trailing zeros trimmed (2, 1.5); negative on a storno.

string
unit
required
string
unit_price
required

With tax when the invoice’s prices_include_tax.

object
amount
required
string
currency
required
string
tax_rate
required

A percentage as a decimal string (21.0000 = 21%).

string
net
required

After discounts: net + tax = total.

object
amount
required
string
currency
required
string
tax
required
object
amount
required
string
currency
required
string
total
required
object
amount
required
string
currency
required
string
lines_count
required

How many lines the invoice has.

integer
created_at
required
string format: date-time
updated_at
required
string format: date-time

Gone: no more webhooks are sent to this URL until its partner turns them back on.

Received. Any other answer is retried on the schedule.