{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/invoicexml-com/json-schema/invoicexml-com-create-invoice-email-request-schema.json", "title": "CreateInvoiceEmailRequest", "description": "Envelope of the `/v1/create/{format}/email` endpoints: the same `invoice` and\n`options` as `/v1/create/{format}`, plus the `email` that carries the\ncreated file to its recipient.", "x-generated": "2026-10-30", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/invoicexml-com-openapi.json#/components/schemas/CreateInvoiceEmailRequest", "required": [ "email", "invoice" ], "type": "object", "properties": { "email": { "oneOf": [ { "type": "null" }, { "description": "Sender, recipients and, optionally, the subject and text of the email.", "$ref": "#/$defs/EmailMessage" } ] }, "invoice": { "oneOf": [ { "type": "null" }, { "description": "The invoice document itself (BT-first EN 16931 model).", "$ref": "#/$defs/InvoiceDocument" } ] }, "options": { "description": "Optional rendering / processing settings. Defaults apply when omitted.", "$ref": "#/$defs/InvoiceOptions" } }, "$defs": { "AdditionalSupportingDocument": { "type": "object", "properties": { "reference": { "type": [ "null", "string" ] }, "schemeId": { "type": [ "null", "string" ] }, "documentTypeCode": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "externalUri": { "type": [ "null", "string" ] }, "attachment": { "type": [ "null", "string" ], "format": "byte" }, "attachmentMimeCode": { "type": [ "null", "string" ] }, "attachmentFilename": { "type": [ "null", "string" ] } } }, "BuyerContact": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "phone": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] } } }, "BuyerElectronicAddress": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "BuyerIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "BuyerLegalRegistration": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "BuyerParty": { "required": [ "name", "postalAddress" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "tradingName": { "type": [ "null", "string" ] }, "postalAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/BuyerPostalAddress" } ] }, "contact": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/BuyerContact" } ] }, "identifiers": { "type": "array", "items": { "$ref": "#/$defs/BuyerIdentifier" } }, "legalRegistration": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/BuyerLegalRegistration" } ] }, "vatIdentifier": { "type": [ "null", "string" ] }, "electronicAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/BuyerElectronicAddress" } ] } } }, "BuyerPostalAddress": { "required": [ "country" ], "type": "object", "properties": { "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "line3": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "postCode": { "type": [ "null", "string" ] }, "countrySubdivision": { "type": [ "null", "string" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/CountryCode" } ] } } }, "CountryCode": { "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string", "x-enum-varnames": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "x-enum-descriptions": [ "Andorra", "United Arab Emirates", "Afghanistan", "Antigua and Barbuda", "Anguilla", "Albania", "Armenia", "Angola", "Antarctica", "Argentina", "American Samoa", "Austria", "Australia", "Aruba", "Aland Islands", "Azerbaijan", "Bosnia and Herzegovina", "Barbados", "Bangladesh", "Belgium", "Burkina Faso", "Bulgaria", "Bahrain", "Burundi", "Benin", "Saint Barthelemy", "Bermuda", "Brunei Darussalam", "Bolivia", "Bonaire, Sint Eustatius and Saba", "Brazil", "Bahamas", "Bhutan", "Bouvet Island", "Botswana", "Belarus", "Belize", "Canada", "Cocos (Keeling) Islands", "Congo, Democratic Republic of the", "Central African Republic", "Congo", "Switzerland", "Cote d'Ivoire", "Cook Islands", "Chile", "Cameroon", "China", "Colombia", "Costa Rica", "Cuba", "Cabo Verde", "Curacao", "Christmas Island", "Cyprus", "Czechia", "Germany", "Djibouti", "Denmark", "Dominica", "Dominican Republic", "Algeria", "Ecuador", "Estonia", "Egypt", "Western Sahara", "Eritrea", "Spain", "Ethiopia", "Finland", "Fiji", "Falkland Islands (Malvinas)", "Micronesia, Federated States of", "Faroe Islands", "France", "Gabon", "United Kingdom", "Grenada", "Georgia", "French Guiana", "Guernsey", "Ghana", "Gibraltar", "Greenland", "Gambia", "Guinea", "Guadeloupe", "Equatorial Guinea", "Greece", "South Georgia and the South Sandwich Islands", "Guatemala", "Guam", "Guinea-Bissau", "Guyana", "Hong Kong", "Heard Island and McDonald Islands", "Honduras", "Croatia", "Haiti", "Hungary", "Indonesia", "Ireland", "Israel", "Isle of Man", "India", "British Indian Ocean Territory", "Iraq", "Iran", "Iceland", "Italy", "Jersey", "Jamaica", "Jordan", "Japan", "Kenya", "Kyrgyzstan", "Cambodia", "Kiribati", "Comoros", "Saint Kitts and Nevis", "Korea, Democratic People's Republic of", "Korea, Republic of", "Kuwait", "Cayman Islands", "Kazakhstan", "Lao People's Democratic Republic", "Lebanon", "Saint Lucia", "Liechtenstein", "Sri Lanka", "Liberia", "Lesotho", "Lithuania", "Luxembourg", "Latvia", "Libya", "Morocco", "Monaco", "Moldova", "Montenegro", "Saint Martin (French part)", "Madagascar", "Marshall Islands", "North Macedonia", "Mali", "Myanmar", "Mongolia", "Macao", "Northern Mariana Islands", "Martinique", "Mauritania", "Montserrat", "Malta", "Mauritius", "Maldives", "Malawi", "Mexico", "Malaysia", "Mozambique", "Namibia", "New Caledonia", "Niger", "Norfolk Island", "Nigeria", "Nicaragua", "Netherlands", "Norway", "Nepal", "Nauru", "Niue", "New Zealand", "Oman", "Panama", "Peru", "French Polynesia", "Papua New Guinea", "Philippines", "Pakistan", "Poland", "Saint Pierre and Miquelon", "Pitcairn", "Puerto Rico", "Palestine, State of", "Portugal", "Palau", "Paraguay", "Qatar", "Reunion", "Romania", "Serbia", "Russian Federation", "Rwanda", "Saudi Arabia", "Solomon Islands", "Seychelles", "Sudan", "Sweden", "Singapore", "Saint Helena, Ascension and Tristan da Cunha", "Slovenia", "Svalbard and Jan Mayen", "Slovakia", "Sierra Leone", "San Marino", "Senegal", "Somalia", "Suriname", "South Sudan", "Sao Tome and Principe", "El Salvador", "Sint Maarten (Dutch part)", "Syrian Arab Republic", "Eswatini", "Turks and Caicos Islands", "Chad", "French Southern Territories", "Togo", "Thailand", "Tajikistan", "Tokelau", "Timor-Leste", "Turkmenistan", "Tunisia", "Tonga", "Turkiye", "Trinidad and Tobago", "Tuvalu", "Taiwan, Province of China", "Tanzania, United Republic of", "Ukraine", "Uganda", "United States Minor Outlying Islands", "United States", "Uruguay", "Uzbekistan", "Holy See", "Saint Vincent and the Grenadines", "Venezuela", "Virgin Islands, British", "Virgin Islands, U.S.", "Viet Nam", "Vanuatu", "Wallis and Futuna", "Samoa", "Yemen", "Mayotte", "South Africa", "Zambia", "Zimbabwe" ] }, "CurrencyCode": { "enum": [ "EUR", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "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", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VED", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWG" ], "type": "string", "x-enum-varnames": [ "EUR", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "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", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VED", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWG" ], "x-enum-descriptions": [ "Euro", "UAE dirham", "Afghan afghani", "Albanian lek", "Armenian dram", "Netherlands Antillean guilder", "Angolan kwanza", "Argentine peso", "Australian dollar", "Aruban florin", "Azerbaijani manat", "Bosnia and Herzegovina convertible mark", "Barbados dollar", "Bangladeshi taka", "Bulgarian lev", "Bahraini dinar", "Burundian franc", "Bermudian dollar", "Brunei dollar", "Boliviano", "Brazilian real", "Bahamian dollar", "Bhutanese ngultrum", "Botswana pula", "Belarusian ruble", "Belize dollar", "Canadian dollar", "Congolese franc", "Swiss franc", "Chilean peso", "Renminbi (Chinese yuan)", "Colombian peso", "Costa Rican colon", "Cuban peso", "Cape Verdean escudo", "Czech koruna", "Djiboutian franc", "Danish krone", "Dominican peso", "Algerian dinar", "Egyptian pound", "Eritrean nakfa", "Ethiopian birr", "Fiji dollar", "Falkland Islands pound", "Pound sterling", "Georgian lari", "Ghanaian cedi", "Gibraltar pound", "Gambian dalasi", "Guinean franc", "Guatemalan quetzal", "Guyanese dollar", "Hong Kong dollar", "Honduran lempira", "Haitian gourde", "Hungarian forint", "Indonesian rupiah", "Israeli new shekel", "Indian rupee", "Iraqi dinar", "Iranian rial", "Icelandic krona", "Jamaican dollar", "Jordanian dinar", "Japanese yen", "Kenyan shilling", "Kyrgyzstani som", "Cambodian riel", "Comoro franc", "North Korean won", "South Korean won", "Kuwaiti dinar", "Cayman Islands dollar", "Kazakhstani tenge", "Lao kip", "Lebanese pound", "Sri Lankan rupee", "Liberian dollar", "Lesotho loti", "Libyan dinar", "Moroccan dirham", "Moldovan leu", "Malagasy ariary", "Macedonian denar", "Myanmar kyat", "Mongolian togrog", "Macanese pataca", "Mauritanian ouguiya", "Mauritian rupee", "Maldivian rufiyaa", "Malawian kwacha", "Mexican peso", "Malaysian ringgit", "Mozambican metical", "Namibian dollar", "Nigerian naira", "Nicaraguan cordoba", "Norwegian krone", "Nepalese rupee", "New Zealand dollar", "Omani rial", "Panamanian balboa", "Peruvian sol", "Papua New Guinean kina", "Philippine peso", "Pakistani rupee", "Polish zloty", "Paraguayan guarani", "Qatari riyal", "Romanian leu", "Serbian dinar", "Russian ruble", "Rwandan franc", "Saudi riyal", "Solomon Islands dollar", "Seychelles rupee", "Sudanese pound", "Swedish krona", "Singapore dollar", "Saint Helena pound", "Sierra Leonean leone", "Somali shilling", "Surinamese dollar", "South Sudanese pound", "Sao Tome and Principe dobra", "Salvadoran colon", "Syrian pound", "Swazi lilangeni", "Thai baht", "Tajikistani somoni", "Turkmenistan manat", "Tunisian dinar", "Tongan pa'anga", "Turkish lira", "Trinidad and Tobago dollar", "New Taiwan dollar", "Tanzanian shilling", "Ukrainian hryvnia", "Ugandan shilling", "United States dollar", "Uruguayan peso", "Uzbekistani sum", "Venezuelan digital bolivar", "Venezuelan sovereign bolivar", "Vietnamese dong", "Vanuatu vatu", "Samoan tala", "CFA franc BEAC", "East Caribbean dollar", "CFA franc BCEAO", "CFP franc", "Yemeni rial", "South African rand", "Zambian kwacha", "Zimbabwe Gold" ] }, "DeliveryInformation": { "type": "object", "properties": { "receiverName": { "type": [ "null", "string" ] }, "locationIdentifier": { "type": [ "null", "string" ] }, "locationIdentifierSchemeId": { "type": [ "null", "string" ] }, "actualDeliveryDate": { "type": [ "null", "string" ], "format": "date" }, "deliveryAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/DeliveryPostalAddress" } ] } } }, "DeliveryPostalAddress": { "type": "object", "properties": { "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "line3": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "postCode": { "type": [ "null", "string" ] }, "countrySubdivision": { "type": [ "null", "string" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/CountryCode" } ] } } }, "DocumentLevelAllowance": { "type": "object", "properties": { "amount": { "type": [ "null", "number" ], "format": "double" }, "baseAmount": { "type": [ "null", "number" ], "format": "double" }, "percentage": { "type": [ "null", "number" ], "format": "double" }, "vatCategoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/VatCategoryCode" } ] }, "vatRate": { "type": [ "null", "number" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "DocumentLevelCharge": { "type": "object", "properties": { "amount": { "type": [ "null", "number" ], "format": "double" }, "baseAmount": { "type": [ "null", "number" ], "format": "double" }, "percentage": { "type": [ "null", "number" ], "format": "double" }, "vatCategoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/VatCategoryCode" } ] }, "vatRate": { "type": [ "null", "number" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "DocumentTotals": { "type": "object", "properties": { "sumOfLineNetAmounts": { "type": [ "null", "number" ], "format": "double" }, "sumOfAllowances": { "type": [ "null", "number" ], "format": "double" }, "sumOfCharges": { "type": [ "null", "number" ], "format": "double" }, "taxBasisTotalAmount": { "type": [ "null", "number" ], "format": "double" }, "taxTotalAmount": { "type": [ "null", "number" ], "format": "double" }, "taxTotalAmountInAccountingCurrency": { "type": [ "null", "number" ], "format": "double" }, "grandTotalAmount": { "type": [ "null", "number" ], "format": "double" }, "paidAmount": { "type": [ "null", "number" ], "format": "double" }, "roundingAmount": { "type": [ "null", "number" ], "format": "double" }, "duePayableAmount": { "type": [ "null", "number" ], "format": "double" } } }, "EmailMessage": { "required": [ "from", "to" ], "type": "object", "properties": { "from": { "type": [ "null", "string" ], "description": "The sender address, for example `invoices@yourcompany.com`. Any address on one of\nthe account's verified sending domains; add and verify the domain on the Verified\nemail domains page of your dashboard first." }, "fromName": { "maxLength": 100, "minLength": 0, "type": [ "null", "string" ], "description": "Optional display name of the sender, for example `Your Company Billing`. At most\n100 characters, no line breaks." }, "to": { "type": [ "null", "string" ], "description": "The recipient's email address. One address." }, "cc": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional addresses that receive a visible copy, for example your accounting inbox.\ncc and bcc hold at most 2 addresses together." }, "bcc": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Optional addresses that receive a hidden copy. cc and bcc hold at most 2 addresses\ntogether." }, "replyTo": { "type": [ "null", "string" ], "description": "Optional address the recipient's replies go to, when it differs from the sender, for\nexample your accounts receivable team. Any domain." }, "subject": { "maxLength": 200, "minLength": 0, "type": [ "null", "string" ], "description": "Optional subject, at most 200 characters, no line breaks. When omitted the subject is\nthe document type and its number, for example `Invoice 2026-0042` or\n`Credit note 2026-0043`." }, "message": { "maxLength": 10000, "minLength": 0, "type": [ "null", "string" ], "description": "Optional plain-text message, at most 10,000 characters, sent exactly as given in any\nlanguage. When omitted a short English text is sent: \"Hello, Please find attached\ninvoice 2026-0042. Kind regards\" (credit note for a credit note)." } }, "description": "The email that carries the invoice to its recipient: who sends it, who receives it and,\noptionally, the subject and the text. The invoice file itself is attached by the API.\nThe sender address must be on one of the account's verified sending domains. Nothing\nin this object is stored." }, "InvoiceDocument": { "required": [ "invoiceNumber", "currency", "seller", "buyer", "lines" ], "type": "object", "properties": { "invoiceNumber": { "type": [ "null", "string" ] }, "issueDate": { "type": [ "null", "string" ], "format": "date" }, "dueDate": { "type": [ "null", "string" ], "format": "date" }, "typeCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/InvoiceTypeCode" } ] }, "currency": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/CurrencyCode" } ] }, "taxCurrency": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/CurrencyCode" } ] }, "specificationId": { "type": [ "null", "string" ] }, "businessProcessType": { "type": [ "null", "string" ] }, "buyerReference": { "type": [ "null", "string" ] }, "contractReference": { "type": [ "null", "string" ] }, "purchaseOrderReference": { "type": [ "null", "string" ] }, "despatchAdviceReference": { "type": [ "null", "string" ] }, "notes": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "The note text, without a subject code." }, { "$ref": "#/$defs/InvoiceNote" } ], "description": "A note, either as plain text or as an object that adds a subject code." } }, "vatPointDateCode": { "type": [ "null", "string" ] }, "supportingDocuments": { "type": "array", "items": { "$ref": "#/$defs/AdditionalSupportingDocument" } }, "precedingInvoiceReferences": { "type": "array", "items": { "$ref": "#/$defs/PrecedingInvoiceReference" } }, "seller": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/SellerParty" } ] }, "buyer": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/BuyerParty" } ] }, "delivery": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/DeliveryInformation" } ] }, "invoicingPeriod": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/InvoicingPeriod" } ] }, "paymentDetails": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/PaymentDetails" } ] }, "totals": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/DocumentTotals" } ] }, "vatBreakdowns": { "type": "array", "items": { "$ref": "#/$defs/VatBreakdown" } }, "lines": { "minItems": 1, "type": "array", "items": { "$ref": "#/$defs/InvoiceLine" } }, "allowances": { "type": "array", "items": { "$ref": "#/$defs/DocumentLevelAllowance" } }, "charges": { "type": "array", "items": { "$ref": "#/$defs/DocumentLevelCharge" } }, "hasReasonOnlyVatBreakdowns": { "type": "boolean" } } }, "InvoiceLine": { "required": [ "quantity", "priceDetails", "vatInformation", "item" ], "type": "object", "properties": { "lineId": { "type": [ "null", "string" ] }, "lineNote": { "type": [ "null", "string" ] }, "objectIdentifier": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/LineObjectIdentifier" } ] }, "quantity": { "type": [ "null", "number" ], "format": "double" }, "unitCode": { "type": [ "null", "string" ] }, "lineNetAmount": { "type": [ "null", "number" ], "format": "double" }, "buyerOrderLineReference": { "type": [ "null", "string" ] }, "lineBuyerAccountingReference": { "type": [ "null", "string" ] }, "linePeriod": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/InvoiceLinePeriod" } ] }, "priceDetails": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/PriceDetails" } ] }, "vatInformation": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/LineVatInformation" } ] }, "item": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ItemInformation" } ] }, "allowances": { "type": "array", "items": { "$ref": "#/$defs/LineAllowance" } }, "charges": { "type": "array", "items": { "$ref": "#/$defs/LineCharge" } } } }, "InvoiceLinePeriod": { "type": "object", "properties": { "startDate": { "type": [ "null", "string" ], "format": "date" }, "endDate": { "type": [ "null", "string" ], "format": "date" } } }, "InvoiceNote": { "required": [ "note" ], "type": "object", "properties": { "note": { "type": "string", "description": "The note text." }, "subjectCode": { "type": [ "null", "string" ], "description": "UNTDID 4451 text subject code qualifying the note, for example PMT (recovery costs), PMD (late-payment penalties), AAB (discount terms) or TXD (tax statement)." } }, "description": "A note with a subject code that qualifies what it is about." }, "InvoiceOptions": { "type": "object", "properties": { "profile": { "pattern": "^(?i:en16931|peppol-bis-3|nlcius|ehf|xrechnung|pint)$", "type": [ "null", "string" ], "description": "UBL CIUS profile for `/v1/create/ubl`. Selects the CustomizationID\nstamped into the document and the matching validation rule set, so the\ninvoice always declares exactly what it was validated against.\nAccepted values: `en16931`, `peppol-bis-3`, `nlcius`,\n`ehf`, `xrechnung`, `pint`. Defaults to\n`peppol-bis-3` when omitted. Other create endpoints ignore this\nfield." }, "syntax": { "pattern": "^(?i:ubl|cii)$", "type": [ "null", "string" ], "description": "XML syntax to produce, for `/v1/create/xrechnung`. XRechnung is a\nsyntax-neutral CIUS that exists in two interchangeable syntaxes;\n`ubl` (UBL 2.1, the default and the syntax most German receivers\nsee in practice) or `cii` (UN/CEFACT Cross Industry Invoice).\nThe German rules (BR-DE) and the declared specification identifier\n(BT-24) are identical in both. Other create endpoints ignore this\nfield." }, "rules": { "type": [ "null", "array" ], "items": { "type": "string" }, "description": "Extra national rule sets to validate ON TOP of the pipeline the\ndocument's declared profile selects, without changing the stamped\nspecification identifier (BT-24). Accepted values: `br-fr` (the\nFrench CTC mandate's BR-FR Flux 2 rules, the same set the\nPlateformes Agréées and the PPF apply to every domestic invoice).\nAvailable on `/v1/create/facturx`, `/v1/create/cii` and\n`/v1/create/ubl`; other create endpoints reject it with a clear\n400 rather than silently skipping a compliance check. On the CII\nfamily it requires at least the BASIC profile. Violations surface as\nordinary 4001 findings carrying the official BR-FR-* rule ids." }, "language": { "oneOf": [ { "type": "null" }, { "description": "Language of the invoice: `EN`, `DE` or `FR` (case-insensitive);\ndefaults to `EN` when omitted. On the hybrid endpoints it\nlocalises the labels and date formatting of the rendered PDF. On every\ncreate endpoint, XML ones included, it also words the texts the API\nstates on the caller's behalf when the document leaves them empty: the\npayment terms (BT-20) fallback and the VAT exemption reason text (BT-120)\ndefaulted for the reverse charge, intra-Community, export and\nout-of-scope categories. Caller-supplied text always wins; the option\nnever changes structure, codes or validation.", "$ref": "#/$defs/PdfLanguage" } ] }, "validationLanguage": { "enum": [ "en", "de", "fr" ], "type": [ "null", "string" ], "description": "Language of the validation findings: `en`, `de` or `fr`; defaults to\n`en` when omitted. Words the `message` of every finding in the\n`errors` and `warnings` arrays; rule ids, codes, fields and `raw` stay\nthe same, and so do the problem's `title` and `detail`. Independent of\n`language`, which words the invoice itself. Any other value is refused with a\n4002 finding on this field.", "default": "en" }, "brandColor": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": [ "null", "string" ], "description": "Primary brand colour applied to PDF headings and accent backgrounds\n(document title, table header, totals box, section headers).\nHex format `#RRGGBB`. When omitted the renderer uses its default.\nBody text is never recoloured so legibility is preserved regardless of brand." }, "pdfUrl": { "maxLength": 2048, "minLength": 0, "type": [ "null", "string" ], "description": "Optional public URL of a PDF to use as the visual layer of the hybrid output. When\nsupplied, `/v1/create/facturx` and `/v1/create/zugferd` download this PDF and\nembed the generated CII XML into it instead of rendering the invoice template; in that\ncase `language`, `brandColor`, `logo` and `logoUrl` are ignored (they only affect\nthe rendered template). The XML endpoints (ubl / cii / xrechnung) ignore this field.\nMust be an absolute http/https URL to a publicly reachable PDF of at most 20 MB." }, "logoUrl": { "maxLength": 2048, "minLength": 0, "type": [ "null", "string" ], "description": "Optional public URL of the seller's logo, printed top-left on the rendered invoice\ntemplate of `/v1/create/facturx` and `/v1/create/zugferd`. PNG or JPEG,\nat most 2 MB and 4 megapixels, at an absolute http/https URL that is publicly\nreachable. The image is re-encoded so only its pixel data reaches the PDF, scaled to\nfit a 170 x 48 pt box with the aspect ratio preserved. To send the image itself\ninstead, use `logo`; a request may carry one of the two, not both. Ignored when\n`pdfUrl` supplies the visual layer, and by the XML endpoints." }, "logo": { "type": [ "null", "string" ], "description": "Optional seller logo as the image file itself, for a logo that is not at a public URL:\nprinted top-left on the rendered invoice template of `/v1/create/facturx` and\n`/v1/create/zugferd`, exactly as a `logoUrl` would be. The PNG or JPEG file\nas plain base64, without a `data:` prefix; at most 2 MB once decoded and 4\nmegapixels. A request may carry `logo` or `logoUrl`, not both. Ignored when\n`pdfUrl` supplies the visual layer, and by the XML endpoints.", "format": "byte" }, "includeAdvancedProperties": { "type": [ "null", "boolean" ], "description": "When true, the rendered PDF gains an \"Electronic invoice details\" section\nat the bottom listing the technical properties that do not appear on a\nclassic invoice layout: specification identifier (BT-24), business process\n(BT-23), party identifiers with schemes (BT-29/BT-46), legal registrations\n(BT-30/BT-47), electronic addresses (BT-34/BT-49), supporting documents\n(BG-24, metadata only, never the base64 payload), and line-level references\nand identifiers. Defaults to false so the created PDF keeps the familiar\ninvoice layout. Only affects the rendered template of\n`/v1/create/facturx` and `/v1/create/zugferd`; ignored when\n`pdfUrl` supplies the visual layer, and by the XML endpoints." }, "includeQrCode": { "type": [ "null", "boolean" ], "description": "When true, the payment section of the rendered PDF carries an EPC QR code (known in\nGermany as GiroCode) that banking apps turn into a pre-filled SEPA credit transfer:\nIBAN (BT-84), BIC (BT-86), payee (BT-85, else the seller name BT-27), the amount due\n(BT-115) and the payment reference (BT-83, else the invoice number BT-1). The code\nprints when the invoice is in EUR, BT-84 is a valid IBAN, the payment means (BT-81)\nis a credit transfer (`30`, `42` or `58`) and money is due; credit\nnotes and self-billed invoices never carry one. On any other invoice the option\nchanges nothing. Defaults to false. Only affects the rendered template of\n`/v1/create/facturx` and `/v1/create/zugferd`; ignored when\n`pdfUrl` supplies the visual layer, and by the XML endpoints." } }, "description": "Processing and rendering options that travel alongside the invoice in the\n`/v1/create/*` request envelope. None of them is an EN 16931 Business\nTerm; the invoice content itself lives in `invoice`." }, "InvoiceTypeCode": { "enum": [ "261", "326", "380", "381", "383", "384", "386", "389", "875", "876", "877" ], "type": "string", "x-enum-varnames": [ "SelfBilledCreditNote", "PartialInvoice", "Invoice", "CreditNote", "DebitNote", "CorrectedInvoice", "PrepaymentInvoice", "SelfBilledInvoice", "PartialConstructionInvoice", "PartialFinalConstructionInvoice", "FinalConstructionInvoice" ], "x-enum-descriptions": [ "Self-billed credit note", "Partial invoice", "Commercial invoice", "Credit note", "Debit note", "Corrected invoice", "Prepayment invoice", "Self-billed invoice", "Partial construction invoice", "Partial final construction invoice", "Final construction invoice" ] }, "InvoicingPeriod": { "type": "object", "properties": { "startDate": { "type": [ "null", "string" ], "format": "date" }, "endDate": { "type": [ "null", "string" ], "format": "date" } } }, "ItemAttribute": { "required": [ "name", "value" ], "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "ItemClassification": { "required": [ "identifier", "schemeId", "schemeVersion" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] }, "schemeVersion": { "type": [ "null", "string" ] } } }, "ItemInformation": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "description": { "type": [ "null", "string" ] }, "sellerIdentifier": { "type": [ "null", "string" ] }, "buyerIdentifier": { "type": [ "null", "string" ] }, "standardIdentifier": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/ItemStandardIdentifier" } ] }, "classifications": { "type": "array", "items": { "$ref": "#/$defs/ItemClassification" } }, "attributes": { "type": "array", "items": { "$ref": "#/$defs/ItemAttribute" } }, "countryOfOrigin": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/CountryCode" } ] } } }, "ItemStandardIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "LineAllowance": { "type": "object", "properties": { "amount": { "type": [ "null", "number" ], "format": "double" }, "baseAmount": { "type": [ "null", "number" ], "format": "double" }, "percentage": { "type": [ "null", "number" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "LineCharge": { "type": "object", "properties": { "amount": { "type": [ "null", "number" ], "format": "double" }, "baseAmount": { "type": [ "null", "number" ], "format": "double" }, "percentage": { "type": [ "null", "number" ], "format": "double" }, "reason": { "type": [ "null", "string" ] }, "reasonCode": { "type": [ "null", "string" ] } } }, "LineObjectIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "LineVatInformation": { "type": "object", "properties": { "categoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/VatCategoryCode" } ] }, "rate": { "type": [ "null", "number" ], "format": "double" } } }, "PaymentDetails": { "type": "object", "properties": { "paymentMeansCode": { "type": [ "null", "string" ], "description": "UNTDID 4461 payment means code, for example \"30\" (credit transfer) or \"58\" (SEPA credit transfer). Any code from the UNTDID 4461 list is accepted. The code is also accepted as a JSON number (30) or by its readable name (\"CreditTransfer\") and is always returned as the code string." }, "paymentMeansText": { "type": [ "null", "string" ] }, "remittanceInformation": { "type": [ "null", "string" ] }, "paymentAccountIdentifier": { "type": [ "null", "string" ] }, "paymentAccountName": { "type": [ "null", "string" ] }, "bic": { "type": [ "null", "string" ] }, "mandateReference": { "type": [ "null", "string" ] }, "paymentTerms": { "type": [ "null", "string" ] } } }, "PdfLanguage": { "enum": [ "EN", "DE", "FR" ], "type": "string", "x-enum-varnames": [ "EN", "DE", "FR" ], "x-enum-descriptions": [ "EN", "DE", "FR" ] }, "PrecedingInvoiceReference": { "type": "object", "properties": { "reference": { "type": [ "null", "string" ] }, "issueDate": { "type": [ "null", "string" ], "format": "date" } } }, "PriceDetails": { "type": "object", "properties": { "netPrice": { "type": [ "null", "number" ], "format": "double" }, "discountAmount": { "type": [ "null", "number" ], "format": "double" }, "grossPrice": { "type": [ "null", "number" ], "format": "double" }, "priceBaseQuantity": { "type": [ "null", "number" ], "format": "double" }, "priceBaseUnit": { "type": [ "null", "string" ] } } }, "SellerContact": { "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "phone": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] } } }, "SellerElectronicAddress": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "SellerIdentifier": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "SellerLegalRegistration": { "required": [ "identifier", "schemeId" ], "type": "object", "properties": { "identifier": { "type": "string" }, "schemeId": { "type": [ "null", "string" ] } } }, "SellerParty": { "required": [ "name", "postalAddress" ], "type": "object", "properties": { "name": { "type": [ "null", "string" ] }, "tradingName": { "type": [ "null", "string" ] }, "postalAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/SellerPostalAddress" } ] }, "contact": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/SellerContact" } ] }, "identifiers": { "type": "array", "items": { "$ref": "#/$defs/SellerIdentifier" } }, "legalRegistration": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/SellerLegalRegistration" } ] }, "vatIdentifier": { "type": [ "null", "string" ] }, "taxRegistrationIdentifier": { "type": [ "null", "string" ] }, "additionalLegalInformation": { "type": [ "null", "string" ] }, "electronicAddress": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/SellerElectronicAddress" } ] } } }, "SellerPostalAddress": { "required": [ "country" ], "type": "object", "properties": { "line1": { "type": [ "null", "string" ] }, "line2": { "type": [ "null", "string" ] }, "line3": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "postCode": { "type": [ "null", "string" ] }, "countrySubdivision": { "type": [ "null", "string" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/CountryCode" } ] } } }, "VatBreakdown": { "type": "object", "properties": { "taxableAmount": { "type": [ "null", "number" ], "format": "double" }, "taxAmount": { "type": [ "null", "number" ], "format": "double" }, "categoryCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/$defs/VatCategoryCode" } ] }, "rate": { "type": [ "null", "number" ], "format": "double" }, "exemptionReasonText": { "type": [ "null", "string" ] }, "exemptionReasonCode": { "type": [ "null", "string" ] } } }, "VatCategoryCode": { "enum": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M" ], "type": "string", "x-enum-varnames": [ "S", "Z", "E", "AE", "K", "G", "O", "L", "M" ], "x-enum-descriptions": [ "Standard rate", "Zero rated goods", "Exempt from tax", "VAT reverse charge", "VAT exempt for EEA intra-community supply of goods and services", "Free export item, VAT not charged", "Services outside scope of tax", "Canary Islands general indirect tax", "Tax for production, services and importation in Ceuta and Melilla" ] } } }