Wiki source code of 3. Invoice-service

Last modified by Rasmus Enekvist on 2026/04/07 09:49
Show last authors
1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 Integrate to **PayEx Invoice service API **
6 )))
7 )))
8
9 (% id="HChangelog" %)
10 = Changelog =
11
12 2025-11-06
13
14 * Correction of documentation for Invoices resource, these are not any changes of the api, only the documentation .
15 ** Response for POST Credit and Debit invoice expects to respond with the resource created and __not a link to the invoice-api.__
16 ** Specified **invoiceNotes** & **InvoiceReason.invoiceReasonDescription **with RegEx Pattern
17
18 2026-04-21
19
20 * Allow marking a invoice as blocked from invoice purchase
21 ** Added property BlockPurchase
22
23 == Introduction ==
24
25 This API is used to create new invoices on existing customers
26
27 [[image:1615196225210-926.png||height="100" width="390"]]
28
29
30 Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
31
32 The below route is an example of a route towards resource1Id
33 //lf-api.payex.com/ledger/**{Subdomain}**/v1/**{LedgerNumber}**/resource1/**{resource1Id}**//
34
35 (% class="table-bordered table-striped" %)
36 |=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description
37 |(% style="width:604px" %)Subdomain|(% style="width:2790px" %)In this part of the API it will be **invoice-service**
38 |(% style="width:604px" %)LedgerNumber|(% style="width:2790px" %)The ledger identifier/number at PayEx
39 |(% style="width:604px" %)InvoiceNo|(% style="width:2790px" %)Identifier of resource invoice
40
41 (% class="wikigeneratedid" %)
42 Routes that occurs in examples of this documentation will use the following identifiers
43
44 (% class="table-bordered table-striped" %)
45 |=(% style="width: 488px;" %)Resource|=(% style="width: 2271px;" %)Identifier
46 |(% style="width:488px" %)LedgerNumber|(% style="width:2271px" %)XXX
47 |(% style="width:488px" %)Invoices|(% style="width:2271px" %)NNN
48
49 == ==
50
51 == Invoices ==
52
53 This resource is used to create new invoices, both debit invoices and credit invoices
54
55 (% class="box infomessage" %)
56 (((
57 Batches of multiple invoices should be processed sequentially towards the API. Each API call is intended for the creation of a single invoice
58 )))
59
60 ==== Example of a new debit invoice ====
61
62 {{code language="http" title="**Request**"}}
63 POST /ledger/invoice-service/v1/XXX/invoices HTTP/1.1
64 Host: -
65 Authorization: Bearer <Token>
66 Content-Type: application/json
67
68 {
69 "customerNo": "2992682",
70 "invoiceNo": "0000003",
71 "invoiceDate": "2021-05-15",
72 "preferredDueDate": "2021-06-15",
73 "externalInvoiceId": "900003",
74 "currency": "NOK",
75 "invoiceAddress": {
76 "addressee": "Annie Testsson",
77 "streetAddress": "Teststreet 1",
78 "zipCode": "50000",
79 "city": "Testcity",
80 "coAddress": "CO Bengtsson",
81 "countryCode": "SE"
82 },
83 "distribution": null,
84 "invoiceReason": {
85 "invoiceReasonCode": "CAS",
86 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
87 },
88 "BlockPurchase": false,
89 "legalMonetaryTotal": {
90 "payableAmount": 97.99,
91 "vatInclusiveAmount": 98.01,
92 "vatExclusiveAmount": 98.01
93 },
94 "referenceInfo": {
95 "invoicePeriod": {
96 "startDate": "2021-04-07",
97 "endDate": "2021-04-25"
98 },
99 "deliveryInfo": {
100 "deliveryDate": "2021-04-27",
101 "deliveryAddress": {
102 "addressee": "Namn på mottagre",
103 "streetAddress": "Testgatan 789",
104 "zipCode": "11111",
105 "city": "Sthlm",
106 "coAddress": "C/O Andersson",
107 "countryCode": "SE"
108 }
109 },
110 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
111 "salesOrderReference": "Lorem ipsum dolor sit amet",
112 "buyerReference": "Lorem ipsum dolor sit amet",
113 "invoicedObjectIdentifier": "Lorem ipsum do",
114 "contractReference": "Lorem ipsum dolor sit amet",
115 "despatchReference": "Lorem ipsum dolor sit amet",
116 "receiptReference": "Lorem ipsum dolor sit amet",
117 "tenderReference": "Lorem ipsum dolor sit amet",
118 "projectReference": "Lorem ipsum dolor sit amet"
119 },
120 "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
121 "invoiceSpecification": {
122 "inclVat": true,
123 "roundingAmount": -0.01,
124 "invoiceLines": [
125 {
126 "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
127 "amount": 98.0,
128 "datePeriod": {
129 "StartDate": "2021-04-21",
130 "EndDate": "2021-04-25"
131 },
132 "gTIN": "156789123",
133 "itemObjectIdentifier": "itemObjectIdentifier",
134 "quantity": 1,
135 "unit": "ANN",
136 "unitPrice": 98.0,
137 "vatCategoryCode": "AE",
138 "vatRate": 10
139 },
140 {
141 "itemDescription": "Lorem ipsum dolor sit amet",
142 "amount": 0.01
143 }
144 ],
145 "invoiceVatSpecification": {
146 "vatSubTotal": [
147 {
148 "taxableAmount": 98.01,
149 "vatAmount": 0.0,
150 "vatRate": 1,
151 "vatCategoryCode": "Z"
152 }
153 ]
154 },
155 "taxCurrencyVatSpecification": {
156 "vatSubTotal": [
157 {
158 "taxableAmount": 50.0,
159 "vatAmount": 5.5,
160 "vatRate": 1.0,
161 "vatCategoryCode": "O"
162 }
163 ],
164 "taxCurrencyCode": "GBP",
165 "exchangeRate": 1.55
166 },
167 "taxReduction": {
168 "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
169 "taxReductionAmount": 0.01
170 }
171 }
172 }
173 {{/code}}
174
175 ==== Example of a new credit invoice ====
176
177 {{code language="http" title="**Request**"}}
178 POST /ledger/invoice-service/v1/XXX/invoices HTTP/1.1
179 Host: -
180 Authorization: Bearer <Token>
181 Content-Type: application/json
182
183 {
184 "customerNo": "2992682",
185 "invoiceNo": "000004",
186 "invoiceDate": "2021-05-17",
187 "externalInvoiceId": "900004",
188 "currency": "SEK",
189 "invoiceAddress": {
190 "addressee": "Annie Testsson",
191 "streetAddress": "Teststreet 1",
192 "zipCode": "50000",
193 "city": "Testcity",
194 "coAddress": "CO Bengtsson",
195 "countryCode": "SE"
196 },
197 "distribution": null,
198 "invoiceReason": {
199 "invoiceReasonCode": "CAS",
200 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
201 },
202 "legalMonetaryTotal": {
203 "payableAmount": -88.0,
204 "vatInclusiveAmount": -88.01,
205 "vatExclusiveAmount": -88.01
206 },
207 "referenceInfo": {
208 "invoicePeriod": {
209 "startDate": "2021-04-07",
210 "endDate": "2021-04-25"
211 },
212 "deliveryInfo": {
213 "deliveryDate": "2021-04-27",
214 "deliveryAddress": {
215 "addressee": "Name of recipient",
216 "streetAddress": "Teststreet 789",
217 "zipCode": "11111",
218 "city": "Testcity",
219 "coAddress": "C/O Andersson",
220 "countryCode": "SE"
221 }
222 },
223 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
224 "salesOrderReference": "Lorem ipsum dolor sit amet",
225 "buyerReference": "Lorem ipsum dolor sit amet",
226 "invoicedObjectIdentifier": "Lorem ipsum do",
227 "contractReference": "Lorem ipsum dolor sit amet",
228 "despatchReference": "Lorem ipsum dolor sit amet",
229 "receiptReference": "Lorem ipsum dolor sit amet",
230 "tenderReference": "Lorem ipsum dolor sit amet",
231 "projectReference": "Lorem ipsum dolor sit amet",
232 "debitInvoiceReferences": [
233 {
234 "debitInvoiceReference": "InvoiceNo xxxx"
235 }
236 ]
237 },
238 "InvoiceNote": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
239 "invoiceSpecification": {
240 "inclVat": true,
241 "roundingAmount": 0.01,
242 "invoiceLines": [
243 {
244 "itemDescription": "Description of item 1",
245 "amount": -88.01
246 }
247 ],
248 "invoiceVatSpecification": {
249 "vatSubTotal": [
250 {
251 "taxableAmount": -88.01,
252 "vatAmount": 0.0,
253 "vatRate": 1,
254 "vatCategoryCode": "Z"
255 }
256 ]
257 },
258 "taxCurrencyVatSpecification": {
259 "vatSubTotal": [
260 {
261 "taxableAmount": 50.0,
262 "vatAmount": 5.5,
263 "vatRate": 1.0,
264 "vatCategoryCode": "O"
265 }
266 ],
267 "taxCurrencyCode": "GBP",
268 "exchangeRate": 1.55
269 }
270 }
271 }
272 {{/code}}
273
274 {{code language="http" title="**Response**"}}
275 HTTP/1.1 200 OK
276 Host: -
277 Authorization: Bearer <Token>
278 Content-Type: application/json
279
280 {
281 "customerNo" : "900",
282 "invoiceNo" : "0000001",
283 "invoiceDate": "2021-05-15",
284 "preferredDueDate": "2021-06-15",
285 "externalInvoiceId": "900001",
286 "currency": "SEK",
287 "invoiceAddress": {
288 "addressee": "Annie Testsson",
289 "streetAddress": "Teststreet 1",
290 "zipCode": "50000",
291 "city": "Testcity",
292 "coAddress": "CO Bengtsson",
293 "countryCode": "SE"
294 },
295 "distribution": null,
296 "invoiceReason": {
297 "invoiceReasonCode": "CAS",
298 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
299 },
300 "BlockPurchase": false,
301 "legalMonetaryTotal": {
302 "payableAmount": 88.00,
303 "vatInclusiveAmount": 98.01,
304 "vatExclusiveAmount": 98.01
305 },
306 "referenceInfo": {
307 "invoicePeriod": {
308 "startDate": "2021-04-07",
309 "endDate": "2021-04-25"
310 },
311 "deliveryInfo": {
312 "deliveryDate": "2021-04-27",
313 "deliveryAddress": {
314 "addressee": "Namn på mottagre",
315 "streetAddress": "Testgatan 789",
316 "zipCode": "11111",
317 "city": "Sthlm",
318 "coAddress": "C/O Andersson",
319 "countryCode": "SE"
320 }
321 },
322 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
323 "salesOrderReference": "Lorem ipsum dolor sit amet",
324 "buyerReference": "Lorem ipsum dolor sit amet",
325 "invoicedObjectIdentifier": "Lorem ipsum do",
326 "contractReference": "Lorem ipsum dolor sit amet",
327 "despatchReference": "Lorem ipsum dolor sit amet",
328 "receiptReference": "Lorem ipsum dolor sit amet",
329 "tenderReference": "Lorem ipsum dolor sit amet",
330 "projectReference": "Lorem ipsum dolor sit amet"
331 },
332 "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
333 "invoiceSpecification": {
334 "inclVat": true,
335 "roundingAmount": -0.01,
336 "invoiceLines": [
337 {
338 "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
339 "amount": 98.00,
340 "datePeriod": {
341 "StartDate": "2021-04-21",
342 "EndDate": "2021-04-25"
343 },
344 "gTIN": "156789123",
345 "itemObjectIdentifier": "itemObjectIdentifier",
346 "quantity": 8,
347 "unit": "ANN",
348 "unitPrice": 10.00,
349 "vatCategoryCode": "AE",
350 "vatRate": 10
351 },
352 {
353 "itemDescription": "Lorem ipsum dolor sit amet",
354 "amount": 0.01
355 }
356 ],
357 "invoiceVatSpecification": {
358 "vatSubTotal": [
359 {
360 "taxableAmount": 98.01,
361 "vatAmount": 0.00,
362 "vatRate": 1,
363 "vatCategoryCode": "Z"
364 }
365 ]
366 },
367 "taxCurrencyVatSpecification": {
368 "vatSubTotal": [
369 {
370 "taxableAmount": 50.00,
371 "vatAmount": 5.50,
372 "vatRate": 1.00,
373 "vatCategoryCode": "O"
374 }
375 ],
376 "taxCurrencyCode": "GBP",
377 "exchangeRate": 1.55
378 },
379 "taxReduction": {
380 "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
381 "taxReductionAmount": 10
382 }
383
384 },
385 "@id": "/ledger/invoice-service/v1/XXX/invoices/NNN"
386 }
387 {{/code}}
388
389
390 ==== Get single "create-invoice" request ====
391
392 {{code language="http" title="**Request**"}}
393 GET /ledger/invoice-service/v1/XXX/invoices/NNN HTTP/1.1
394 Host: -
395 Authorization: Bearer <Token>
396 Content-Type: application/json
397
398 {{/code}}
399
400 {{code language="http" title="**Response**"}}
401 HTTP/1.1 200 OK
402 Host: -
403 Authorization: Bearer <Token>
404 Content-Type: application/json
405
406 {
407 "customerNo" : "900",
408 "invoiceNo" : "0000001",
409 "invoiceDate": "2021-05-15",
410 "preferredDueDate": "2021-06-15",
411 "externalInvoiceId": "900001",
412 "currency": "SEK",
413 "invoiceAddress": {
414 "addressee": "Annie Testsson",
415 "streetAddress": "Teststreet 1",
416 "zipCode": "50000",
417 "city": "Testcity",
418 "coAddress": "CO Bengtsson",
419 "countryCode": "SE"
420 },
421 "distribution": null,
422 "invoiceReason": {
423 "invoiceReasonCode": "CAS",
424 "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
425 },
426 "BlockPurchase": false,
427 "legalMonetaryTotal": {
428 "payableAmount": 88.00,
429 "vatInclusiveAmount": 98.01,
430 "vatExclusiveAmount": 98.01
431 },
432 "referenceInfo": {
433 "invoicePeriod": {
434 "startDate": "2021-04-07",
435 "endDate": "2021-04-25"
436 },
437 "deliveryInfo": {
438 "deliveryDate": "2021-04-27",
439 "deliveryAddress": {
440 "addressee": "Namn på mottagre",
441 "streetAddress": "Testgatan 789",
442 "zipCode": "11111",
443 "city": "Sthlm",
444 "coAddress": "C/O Andersson",
445 "countryCode": "SE"
446 }
447 },
448 "purchaseOrderReference": "Lorem ipsum dolor sit amet",
449 "salesOrderReference": "Lorem ipsum dolor sit amet",
450 "buyerReference": "Lorem ipsum dolor sit amet",
451 "invoicedObjectIdentifier": "Lorem ipsum do",
452 "contractReference": "Lorem ipsum dolor sit amet",
453 "despatchReference": "Lorem ipsum dolor sit amet",
454 "receiptReference": "Lorem ipsum dolor sit amet",
455 "tenderReference": "Lorem ipsum dolor sit amet",
456 "projectReference": "Lorem ipsum dolor sit amet"
457 },
458 "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
459 "invoiceSpecification": {
460 "inclVat": true,
461 "roundingAmount": -0.01,
462 "invoiceLines": [
463 {
464 "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
465 "amount": 98.00,
466 "datePeriod": {
467 "StartDate": "2021-04-21",
468 "EndDate": "2021-04-25"
469 },
470 "gTIN": "156789123",
471 "itemObjectIdentifier": "itemObjectIdentifier",
472 "quantity": 8,
473 "unit": "ANN",
474 "unitPrice": 10.00,
475 "vatCategoryCode": "AE",
476 "vatRate": 10
477 },
478 {
479 "itemDescription": "Lorem ipsum dolor sit amet",
480 "amount": 0.01
481 }
482 ],
483 "invoiceVatSpecification": {
484 "vatSubTotal": [
485 {
486 "taxableAmount": 98.01,
487 "vatAmount": 0.00,
488 "vatRate": 1,
489 "vatCategoryCode": "Z"
490 }
491 ]
492 },
493 "taxCurrencyVatSpecification": {
494 "vatSubTotal": [
495 {
496 "taxableAmount": 50.00,
497 "vatAmount": 5.50,
498 "vatRate": 1.00,
499 "vatCategoryCode": "O"
500 }
501 ],
502 "taxCurrencyCode": "GBP",
503 "exchangeRate": 1.55
504 },
505 "taxReduction": {
506 "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
507 "taxReductionAmount": 10
508 }
509
510 },
511 "@id": "/ledger/invoice-service/v1/XXX/invoices/NNN"
512 }
513 {{/code}}
514
515 ==== ====
516
517 (% id="HAccountresourceproperties" %)
518 ==== Invoice resource properties ====
519
520 (% class="box infomessage" %)
521 (((
522 For basic string properties, all characters included in "Basic Latin" and "Latin-1 Supplement" are generally supported unless otherwise stated in below table
523 )))
524
525 (% class="table-bordered table-striped" %)
526 |=(% style="width: 561.984px;" %)Property|=(% style="width: 1px;" %)Data type|=(% style="width: 213px;" %)Format|=(% style="width: 88px;" %)Required|=(% style="width: 792px;" %)Description
527 |(% style="width:561.984px" %)customerNo|(% style="width:1px" %)string|(% style="width:213px" %)MinLength: 1
528 MaxLength: 15*
529 numeric, 1-9 |(% style="width:88px" %)Yes|(% style="width:792px" %)The unique identifier of the customer
530 MaxLength may differ depending on configuration
531 KID (Norway)
532 |(% style="width:561.984px" %)(((
533 invoiceNo
534 )))|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 15
535 Regex pattern:(((
536 [A-Za-z0-9\-]+
537 )))|(% style="width:88px" %)Yes|(% style="width:792px" %)Your unique identifier/invoice number of the invoice
538 |(% style="width:561.984px" %)invoiceDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
539 |(% style="width:561.984px" %)**invoiceAddress**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)(((
540 Optional invoice address. Only used if different from customer name and legal address
541 )))
542 |(% style="width:561.984px" %) addressee|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)Yes|(% style="width:792px" %)Full name of addressee
543 |(% style="width:561.984px" %) streetAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)Street address
544 |(% style="width:561.984px" %) zipCode|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 9|(% style="width:88px" %)Yes|(% style="width:792px" %)Zipcode conforming to country standard
545 |(% style="width:561.984px" %) city|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 27|(% style="width:88px" %)Yes|(% style="width:792px" %)City
546 |(% style="width:561.984px" %) coAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)Care of address
547 |(% style="width:561.984px" %) countryCode|(% style="width:1px" %)string|(% style="width:213px" %)ISO 3166-1 alpha-2|(% style="width:88px" %)Yes|(% style="width:792px" %)Country code according to ISO 3166
548 |(% style="width:561.984px" %)preferredDueDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)No|(% style="width:792px" %)(((
549 Used if a specific duedate is preferred. Number of days between distributiondate, wich it set by PayEx based on invoicedate and processingdate, and preferred due date must exceed minimum payment terms for the specific country. Else minimum paymentterms for the country will be used. Number of days between distributiondate, which is set by PayEx based on invoicedate and processingdate, and preferred due date, can not exceed maximum paymentterms (default 60 days), if true an ERROR is created and the customer and its invoices will be rejected.
550 )))
551 |(% style="width:561.984px" %)externalInvoiceId|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50
552 Regex pattern:
553 ^[a-zA-Z0-9äåöÄÅÖ/_ -.]*$|(% style="width:88px" %)No|(% style="width:792px" %)Additional external unique invoice identfier in accountsreceivable
554 |(% style="width:561.984px" %)distribution|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)(((
555 * **Postal**
556 * **Email**
557 * **EInvoiceB2B **//(some optional fields will be required if this is set*)//
558 * **ArchiveOnly **//(available 2023-04-19)//
559
560 If no distribution is set, [[default distribution priority >>doc:Main.Invoicing.invoice-service.invoice-service-apis.Invoice layout.WebHome||queryString="#HStandarddistributionorderofpriority"]]order will apply.
561 )))
562 |(% style="width:561.984px" %)currency|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)Valid currency supported in Your accountsreceivable
563 |(% style="width:561.984px" %)(((
564 __**invoiceReason**__
565 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)
566 |(% style="width:561.984px" %) invoiceReasonCode|(% style="width:1px" %)string|(% style="width:213px" %)[[UNCL7161>>https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/]]|(% style="width:88px" %)No|(% style="width:792px" %)Invoice reason code according to format UNCL7161
567 |(% style="width:561.984px" %) invoiceReasonDescription|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 200
568 Regex pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF]*$|(% style="width:88px" %)Yes|(% style="width:792px" %)Description of the reason for the invoice
569 |(% style="width:561.984px" %)BlockPurchase|(% style="width:1px" %)bool|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)If true, this specific invoice will be excluded from invoice purchase by the contracted factoring company, if any. Does not affect other invoices for the same customer.
570 |(% style="width:561.984px" %)(((
571 ==== __**legalMonetaryTotal**__ ====
572 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
573 Contains total amount and currency of the invoice. Positive amount is used for debit invoice. Negative amount is used for credit invoice
574 )))
575 |(% style="width:561.984px" %) PayableAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
576 Max size: 100000000
577 Min size: -100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)Total amount to by payed. LegalMonetary.VatInclusiveAmount + Invoicespecification.Roundingamount - InvoiceSpecification.TaxReductionAmount
578 |(% style="width:561.984px" %) VatInclusiveAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
579 Max size: 100000000
580 Min size: -100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)Total amount inclusive of Vat. Equals sum of InvoiceSpecification.InvoiceVatSpecification.VatSubTotal.TaxableAmount + VatAmount
581 |(% style="width:561.984px" %) VatExclusiveAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
582 Max size: 100000000
583 Min size: -100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)Total amount exclusive of Vat. Equals sum of InvoiceSpecification.InvoiceVatSpecification.VatSubTotal.TaxableAmount
584 |(% style="width:561.984px" %)(((
585 ==== __**referenceInfo**__ ====
586 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Containing invoice reference information
587 |(% style="width:561.984px" %)**__invoicePeriod__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional invoiceperiod. Used in EDI
588 |(% style="width:561.984px" %) startDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
589 |(% style="width:561.984px" %) endDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
590 |(% style="width:561.984px" %)**__deliveryInfo__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional deliveryinformation of product/service invoiced. Also used in EDI
591 |(% style="width:561.984px" %) deliveryDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)No|(% style="width:792px" %)
592 |(% style="width:561.984px" %)**__deliveryAddress__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)
593 |(% style="width:561.984px" %) addressee|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)Yes|(% style="width:792px" %)
594 |(% style="width:561.984px" %) streetAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)
595 |(% style="width:561.984px" %) zipCode|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 9|(% style="width:88px" %)Yes|(% style="width:792px" %)
596 |(% style="width:561.984px" %) city|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 27|(% style="width:88px" %)Yes|(% style="width:792px" %)
597 |(% style="width:561.984px" %) coAddress|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 72|(% style="width:88px" %)No|(% style="width:792px" %)
598 |(% style="width:561.984px" %) countryCode|(% style="width:1px" %)string|(% style="width:213px" %)ISO 3166-1 alpha-2|(% style="width:88px" %)Yes|(% style="width:792px" %)
599 |(% style="width:561.984px" %) purchaseOrderReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional unique purchase order reference issued by the Buyer. Used in EDI
600 |(% style="width:561.984px" %) salesOrderReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional sales order reference issued by Seller. Used in EDI
601 |(% style="width:561.984px" %) buyerReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference of who ordered the products/services. Example being the name of the person ordering, employee number or a code identifying this person or department/group. Your ref is often used for internal routing at recipient, and hence it is important to fill this element with the correct values according to the need of the recipient. Used in EDI
602 |(% style="width:561.984px" %) invoicedObjectIdentifier|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional identifier for an object on which the invoice is based, given by the Seller. Examples may be a subscription number, telephone number, meter point, vehicle, person etc., as applicable. Used in EDI
603 |(% style="width:561.984px" %) contractReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a purchase contract. Used in EDI
604 |(% style="width:561.984px" %) despatchReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a despatch advice. Used in EDI
605 |(% style="width:561.984px" %) receiptReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a receipt advice. Used in EDI
606 |(% style="width:561.984px" %) tenderReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to the tenderer or lot, in most cases the Procurement Procedure Identifier. Used in EDI
607 |(% style="width:561.984px" %) projectReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional reference to a project. Used in EDI
608 |(% style="width:561.984px" %) debitInvoiceReferences|(% style="width:1px" %)list|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)If creditinvoice, optional reference to debit invoice. Used in EDI
609 |(% style="width:561.984px" %) debitInvoiceReference|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)Yes|(% style="width:792px" %)Reference to debit invoice
610 |(% style="width:561.984px" %)invoiceNote|(% style="width:1px" %)string|(% style="width:213px" %)(((
611 MaxLength: 250
612
613 Regex pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF]*$
614 )))|(% style="width:88px" %)No|(% style="width:792px" %)A textual note that gives unstructured information that is relevant to the Invoice as a whole
615 |(% style="width:561.984px" %)(((
616 ==== __**invoiceSpecification**__ ====
617 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
618 Contains the specification of the invoice
619 )))
620 |(% style="width:561.984px" %) inclVat|(% style="width:1px" %)bool|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)If True, invoiceLine.amount must include Vat. If False, invoiceLine.amount must exclude Vat. EDI-distribution requires an excl vat InvoiceSpecification
621 | roundingAmount|decimal|Fraction digits: 2
622 Max size: 0.99
623 Min size: -0.99|No|Roundingamount +- 0.99
624 not affected by VAT
625 |(% style="width:561.984px" %)(((
626 **__invoiceLines__**
627 )))|(% style="width:1px" %)list|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)
628 |(% style="width:561.984px" %) itemDescription|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 250
629 |(% style="width:88px" %)Yes|(% style="width:792px" %)Mandatory description of the invoiced item/service
630 |(% style="width:561.984px" %) amount|(% style="width:1px" %)decimal|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)Mandatory amount rounded to two decimals. inclusive or exclusive of vat dependends of setting of the boolean attribute Invoicespecification.InclVat
631 //Sum of the amounts of all invoiceLines must equal to legalMonetaryTotal.VatInclusiveAmount or VatExclusiveAmount, depending on Invoicespecification.InclVat true/false.//
632 |(% style="width:561.984px" %)__**datePeriod**__|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional date/period
633 |(% style="width:561.984px" %) startDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)Yes|(% style="width:792px" %)
634 |(% style="width:561.984px" %) endDate|(% style="width:1px" %)date|(% style="width:213px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:88px" %)No|(% style="width:792px" %)
635 |(% style="width:561.984px" %) gtin|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 15|(% style="width:88px" %)No|(% style="width:792px" %)Optional global trade item identifier (GS1 GTIN)
636 |(% style="width:561.984px" %) itemObjectIdentifier|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 50|(% style="width:88px" %)No|(% style="width:792px" %)Optional identifier for an object on which the invoiceitem is based, given by the Seller. Examples may be a subscription number, telephone number, meter point, vehicle, person etc., as applicable. Used in EDI
637 |(% style="width:561.984px" %) quantity|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 5
638 Max size: 100000000
639 Min size: -100000000|(% style="width:88px" %)No*|(% style="width:792px" %)//*This field is required if distribution is set to EInvoiceB2B//
640 Optional quantity with up to 5 decimals
641 |(% style="width:561.984px" %) unit|(% style="width:1px" %)string|(% style="width:213px" %)UNECERec20 |(% style="width:88px" %)No*|(% style="width:792px" %)(((
642 //*This field is required if distribution is set to EInvoiceB2B//
643 Optional unit of quantity according to UNECERec20 code list:
644
645 (((
646 * **C62 **//- Used for unit-less count (pcs)//
647 * **KGM **//- Kilogram//
648 * **GRM **//- Gram//
649 * **AD **//- Byte//
650 * **2P **//- Kilobyte//
651 * **4L **//- Megabyte//
652 * **E34 **//- Gigabyte//
653 * **E35 **//- Terabyte//
654 * **SEC **//- Seconds//
655 * **MIN **//- Minutes//
656 * **DAY**// - Day//
657 * **WEE**// - Week//
658 * **MON **//- Month//
659 * **ANN **//- Year//
660 * **DZN** – Dozen, A unit of count defining the number of units in multiples of 12.
661 * **KMT** – Kilometer
662 * **MTR** – Meter
663 * **DMT** – Decimeter
664 * **CMT** – Centimeter
665 * **MMT** – Millimeter
666 * **MTK** – Square meter
667 * **MTQ** – Cubic meter
668 * **LTR** – Liter
669 * **DLT** – Deciliter
670 * **CLT** – Centiliter
671 * **MLT** – Milliliter
672 * **TNE** – Tonne (metric ton)
673 * **HUR** – Hour
674 * **KWH** – Kilowatt hour
675 * **E48** – Service unit, A unit of count defining the number of service units (service unit: defined period / property / facility / utility of supply).
676 * **E51** – Job, A unit of count defining the number of jobs.
677 * **E53** – Test, A unit of count defining the number of tests.
678 * **IE** – Person, A unit of count defining the number of persons.
679 * **XPX** – Pallet
680 * **XPK** – Package
681 * **LS** – Lump sum
682 )))
683 )))
684 |(% style="width:561.984px" %) unitPrice|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 5
685 Max size: 100000000
686 Min size: 0|(% style="width:88px" %)No*|(% style="width:792px" %)//*This field is required if distribution is set to EInvoiceB2B//
687 Optional unitprice with up to 5 decimals. Inclusive or exclusive of vat dependent of setting of the boolean attribute Invoicespecification.InclVat
688 |(% style="width:561.984px" %) vatCategoryCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Optional VatCategoryCode according to UN/CEFACT code list 5305, D.16B(((
689 * **AE **-// VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee//
690 * **E **- //Exempt from tax: Code specifying that taxes are not applicable//
691 * **S **- //Standard rate: Code specifying the standard rate//
692 * **Z** - //Zero rated goods: Code specifying that the goods are at a zero rate//
693 * **G** - //Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged//
694 * **O** - //Services outside scope of tax: Code specifying that taxes are not applicable to the services//
695 * **K** - //VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area//
696 )))
697 |(% style="width:561.984px" %) vatRate|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
698 Max size: 100.00
699 Min size: 0.00|(% style="width:88px" %)No|(% style="width:792px" %)Optional valid VatRate
700 |(% style="width:561.984px" %)(((
701 **__invoiceVatSpecifications__**
702 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)Is specified once per distinct combination of VatCategoryCode and VatRate. Each combination must match sum of corresponding InvoiceLines
703 |(% style="width:561.984px" %) vatSubTotal|(% style="width:1px" %)list|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)VatSubTotal is specified once per combination of VatCategoryCode and VatRate
704 |(% style="width:561.984px" %) taxableAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
705 Min size: -100000000
706 Max size: 100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)
707 |(% style="width:561.984px" %) vatAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
708 Min size: -100000000
709 Max size: 100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)
710 |(% style="width:561.984px" %) vatRate|(% style="width:1px" %)decimal|(% style="width:213px" %)percentage
711 min: 0.00
712 max: 100.00|(% style="width:88px" %)Yes|(% style="width:792px" %)vatRate in percentage
713 |(% style="width:561.984px" %) vatCategoryCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
714 Valid values:
715
716 * **AE **-// VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee//
717 * **E **- //Exempt from tax: Code specifying that taxes are not applicable//
718 * **S **- //Standard rate: Code specifying the standard rate//
719 * **Z** - //Zero rated goods: Code specifying that the goods are at a zero rate//
720 * **G** - //Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged//
721 * **O** - //Services outside scope of tax: Code specifying that taxes are not applicable to the services//
722 * **K** - //VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area//
723 )))
724 |(% style="width:561.984px" %)(((
725 **__taxCurrencyVatSpecification__**
726 )))|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Used if seller tax currency is other than invoice currency
727 |(% style="width:561.984px" %)**vatSubTotal**|(% style="width:1px" %)list|(% style="width:213px" %)required 1-10 items|(% style="width:88px" %)Yes|(% style="width:792px" %)VatSubTotal is specified once per combination of VatCategoryCode and VatRate
728 |(% style="width:561.984px" %) taxableAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)amount|(% style="width:88px" %)Yes|(% style="width:792px" %)
729 |(% style="width:561.984px" %) vatAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)amount|(% style="width:88px" %)Yes|(% style="width:792px" %)
730 |(% style="width:561.984px" %) vatRate|(% style="width:1px" %)decimal|(% style="width:213px" %)percentage
731 min: 0.00
732 max: 100.00|(% style="width:88px" %)Yes|(% style="width:792px" %)vatRate in percentage
733 |(% style="width:561.984px" %) vatCategoryCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)(((
734 Valid values:
735
736 * **AE **-// VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee//
737 * **E **- //Exempt from tax: Code specifying that taxes are not applicable//
738 * **S **- //Standard rate: Code specifying the standard rate//
739 * **Z** - //Zero rated goods: Code specifying that the goods are at a zero rate//
740 * **G** - //Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged//
741 * **O** - //Services outside scope of tax: Code specifying that taxes are not applicable to the services//
742 * **K** - //VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area//
743 )))
744 |(% style="width:561.984px" %) taxCurrencyCode|(% style="width:1px" %)string|(% style="width:213px" %) |(% style="width:88px" %)Yes|(% style="width:792px" %)The tax currency code of the seller
745 |(% style="width:561.984px" %) exchangeRate|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 5
746 Min size: 0.00001|(% style="width:88px" %)Yes|(% style="width:792px" %)ExchangeRate used to calculate vat in seller tax currency
747 |(% style="width:561.984px" %)**__taxReduction__**|(% style="width:1px" %)object|(% style="width:213px" %) |(% style="width:88px" %)No|(% style="width:792px" %)Taxreduction used for Reversed Tax and ROT/RUT
748 |(% style="width:561.984px" %) taxReductionDescription|(% style="width:1px" %)string|(% style="width:213px" %)MaxLength: 250|(% style="width:88px" %)Yes|(% style="width:792px" %)
749 |(% style="width:561.984px" %) taxReductionAmount|(% style="width:1px" %)decimal|(% style="width:213px" %)Fraction digits: 2
750 Min size: 0,01
751 Max size: 100000000|(% style="width:88px" %)Yes|(% style="width:792px" %)
752
753 (% id="HBills" %)
754 == ==
755
756 (% id="H-1" %)
757 ==== Problems ====
758
759 All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
760 The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
761 Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.
762
763 Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation
764
765 === Example ===
766
767 {{code language="http" title="**Response**"}}
768 HTTP/1.1 400 Error
769 Content-Type: application/problem+json
770
771 {
772 "Type" : "ledger/invoice-service/v1/problems/validation",
773 "Title" : "A validation error occurred",
774 "Status" : 400,
775 "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
776 "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
777 "Problems" : [
778 {
779 "amount" : "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
780 }
781 ]
782 }
783 {{/code}}
784
785 === Problem types ===
786
787 (% class="box infomessage" %)
788 (((
789 Note, each problem typecode is preceded by "ledger.invoice-service." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.invoice-service.validation".
790 )))
791
792 (% class="table-bordered table-striped" %)
793 |=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description
794 |(% style="width:537px" %)validation|(% style="width:172px" %)400|(% style="width:796px" %)occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
795 |(% style="width:537px" %)invoice-not-found|(% style="width:172px" %)404|(% style="width:796px" %)