Create an invoice
Creates a persisted invoice in draft status, freezes issuer and customer snapshots, and calculates exact line and total amounts. Currency, language, and due date may use company defaults.
POST
/v1/companies/{company_id}/invoicesAuthorization
AuthorizationBearer token (JWT) · headerrequiredWorkOS AuthKit user, service, or agent access token
Path parameters
company_idstring<uuid>requiredHeader parameters
idempotency-keystringrequiredmin length 8 · max length 255 · matches ^[\u0021-\u007E]+$
Request body
requiredapplication/jsoncurrencystringmatches ^[A-Z]{3}$
customer_idstring<uuid>requireddue_datestring<date>external_referencestringmin length 1 · max length 255
issue_datestring<date>requiredlanguagestringmatches ^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$
linesobject[]requiredmin items 1 · max items 100
Show propertiesHide properties
Array of
objectdescriptionstringrequiredmin length 1 · max length 500
quantitystringrequiredmatches ^(?!0(?:\.0{1,3})?$)(?:0|[1-9]\d{0,8})(?:\.\d{1,3})?$
tax_rate_bpsintegerrequiredmin 0 · max 10000
unitstringmin length 1 · max length 32
unit_amount_minorintegerrequiredmin 0 · max 9007199254740991
notesstringmax length 5000
purchase_order_referencestringmin length 1 · max length 255
termsstringmax length 5000
Responses
201Draft invoice created or idempotently replayed
company_idstring<uuid>requiredcreated_atstring<date-time>requiredcurrencystringrequiredmatches ^[A-Z]{3}$
customerobjectrequiredShow propertiesHide properties
addressobjectrequiredShow propertiesHide properties
citystringrequiredmin length 1 · max length 120
country_codestringrequiredmatches ^[A-Z]{2}$
line_1stringrequiredmin length 1 · max length 200
line_2stringmax length 200
postal_codestringrequiredmin length 1 · max length 32
regionstringmax length 120
emailstring<email>idstring<uuid>requiredidentifiersobject[]max items 20 · default: []
Show propertiesHide properties
Array of
objectcountry_codestringmatches ^[A-Z]{2}$
schemestringrequiredmatches ^[a-z][a-z0-9._-]{0,63}$
valuestringrequiredmin length 1 · max length 200
namestringrequiredmin length 1 · max length 200
schema_versionintegerrequiredcustomer_idstring<uuid>requiredcustomer_namestringrequiredmin length 1 · max length 200
due_datestring<date> | nullrequiredexternal_referencestringmin length 1 · max length 255
idstring<uuid>requiredissue_datestring<date>requiredissued_atstring<date-time> | nullrequiredissuerobjectrequiredShow propertiesHide properties
addressobjectrequiredShow propertiesHide properties
citystringrequiredmin length 1 · max length 120
country_codestringrequiredmatches ^[A-Z]{2}$
line_1stringrequiredmin length 1 · max length 200
line_2stringmax length 200
postal_codestringrequiredmin length 1 · max length 32
regionstringmax length 120
emailstring<email>idstring<uuid>requiredidentifiersobject[]max items 20 · default: []
Show propertiesHide properties
Array of
objectcountry_codestringmatches ^[A-Z]{2}$
schemestringrequiredmatches ^[a-z][a-z0-9._-]{0,63}$
valuestringrequiredmin length 1 · max length 200
legal_namestringrequiredmin length 1 · max length 200
schema_versionintegerrequiredtrading_namestringmin length 1 · max length 200
languagestringrequiredmatches ^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$
linesobject[]requiredmin items 1
Show propertiesHide properties
Array of
objectdescriptionstringrequiredmin length 1 · max length 500
net_amount_minorintegerrequiredmin 0 · max 9007199254740991
positionintegerrequiredquantitystringrequiredmatches ^(?!0(?:\.0{1,3})?$)(?:0|[1-9]\d{0,8})(?:\.\d{1,3})?$
tax_amount_minorintegerrequiredmin 0 · max 9007199254740991
tax_rate_bpsintegerrequiredmin 0 · max 10000
total_amount_minorintegerrequiredmin 0 · max 9007199254740991
unitstringmin length 1 · max length 32
unit_amount_minorintegerrequiredmin 0 · max 9007199254740991
notesstringmax length 5000
numberstring | nullrequiredpurchase_order_referencestringmax length 255
statusstringrequiredAllowed:
draftissuedvoidsubtotal_minorintegerrequiredmin 0 · max 9007199254740991
tax_minorintegerrequiredmin 0 · max 9007199254740991
termsstringmax length 5000
total_minorintegerrequiredmin 0 · max 9007199254740991
updated_atstring<date-time>requiredversionintegerrequiredvoid_reasonstring | nullrequiredvoided_atstring<date-time> | nullrequired400Malformed request
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired401Authentication failed
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired403Permission denied
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired404Resource not found
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired409Request conflict
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired413Request body is too large
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired415Unsupported media type
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired422Request validation failed
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequired500Unexpected server error
errorobjectrequiredShow propertiesHide properties
codestringrequireddetailsobject[]Show propertiesHide properties
Array of
objectmessagestringrequiredpathstringrequiredmessagestringrequiredrequest_idstringrequiredRequest
curl -X POST "/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "idempotency-key: stringst" \
-H "Content-Type: application/json" \
-d '{
"currency": "string",
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"due_date": "2019-08-24",
"external_reference": "string",
"issue_date": "2019-08-24",
"language": "string",
"lines": [
{
"description": "string",
"quantity": "string",
"tax_rate_bps": 10000,
"unit": "string",
"unit_amount_minor": 9007199254740991
}
],
"notes": "string",
"purchase_order_reference": "string",
"terms": "string"
}'const response = await fetch("/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_TOKEN",
"idempotency-key": "stringst",
"Content-Type": "application/json"
},
body: JSON.stringify({
"currency": "string",
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"due_date": "2019-08-24",
"external_reference": "string",
"issue_date": "2019-08-24",
"language": "string",
"lines": [
{
"description": "string",
"quantity": "string",
"tax_rate_bps": 10000,
"unit": "string",
"unit_amount_minor": 9007199254740991
}
],
"notes": "string",
"purchase_order_reference": "string",
"terms": "string"
})
});import requests
response = requests.post(
"/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices",
headers={
"Authorization": "Bearer YOUR_TOKEN",
"idempotency-key": "stringst",
"Content-Type": "application/json"
},
json={
"currency": "string",
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"due_date": "2019-08-24",
"external_reference": "string",
"issue_date": "2019-08-24",
"language": "string",
"lines": [
{
"description": "string",
"quantity": "string",
"tax_rate_bps": 10000,
"unit": "string",
"unit_amount_minor": 9007199254740991
}
],
"notes": "string",
"purchase_order_reference": "string",
"terms": "string"
},
)Response
{
"company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
"created_at": "2019-08-24T14:15:22Z",
"currency": "string",
"customer": {
"address": {
"city": "string",
"country_code": "string",
"line_1": "string",
"line_2": "string",
"postal_code": "string",
"region": "string"
},
"email": "user@example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"identifiers": [],
"name": "string",
"schema_version": 0
},
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"customer_name": "string",
"due_date": "2019-08-24",
"external_reference": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"issue_date": "2019-08-24",
"issued_at": "2019-08-24T14:15:22Z",
"issuer": {
"address": {
"city": "string",
"country_code": "string",
"line_1": "string",
"line_2": "string",
"postal_code": "string",
"region": "string"
},
"email": "user@example.com",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"identifiers": [],
"legal_name": "string",
"schema_version": 0,
"trading_name": "string"
},
"language": "string",
"lines": [
{
"description": "string",
"net_amount_minor": 9007199254740991,
"position": 0,
"quantity": "string",
"tax_amount_minor": 9007199254740991,
"tax_rate_bps": 10000,
"total_amount_minor": 9007199254740991,
"unit": "string",
"unit_amount_minor": 9007199254740991
}
],
"notes": "string",
"number": "string",
"purchase_order_reference": "string",
"status": "draft",
"subtotal_minor": 9007199254740991,
"tax_minor": 9007199254740991,
"terms": "string",
"total_minor": 9007199254740991,
"updated_at": "2019-08-24T14:15:22Z",
"version": 0,
"void_reason": "string",
"voided_at": "2019-08-24T14:15:22Z"
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}{
"error": {
"code": "string",
"details": [
{
"message": "string",
"path": "string"
}
],
"message": "string",
"request_id": "string"
}
}