Update an invoice

PATCH

/v:version/invoices/:resourceId

PATCH

/v:version/invoices/:resourceId

1 curl -X PATCH https://api.solvimon.com/v1/invoices/ \
2      -H "X-API-KEY: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "customer_id": "cst_1234567890abcdef",
6   "billing_entity_id": "be_9876543210fedcba",
7   "status": "APPROVED",
8   "on_hold": true,
9   "type": "STANDARD",
10   "invoice_date": "2024-01-15T09:30:00Z",
11   "pricing_amount_type": "EXCLUDING_TAX",
12   "periods": [
13     {
14       "period_order": 1,
15       "start_at": "2024-01-01T00:00:00Z",
16       "end_at": "2024-01-31T23:59:59Z",
17       "tax_categories": [
18         {
19           "category": "STANDARD",
20           "percentage": "5.00",
21           "name": "VAT"
22         }
23       ]
24     }
25   ],
26   "payment_acceptor_ids": [
27     "pa_abcdef1234567890"
28   ],
29   "linked_invoices_ids": [
30     "inv_1122334455667788"
31   ],
32   "purchase_order_number": "PON_007",
33   "notes": [
34     "Please make sure to read the invoice carefully."
35   ]
36 }'

1 {
2   "status": "APPROVED",
3   "on_hold": true,
4   "type": "STANDARD",
5   "invoice_date": "2024-01-15T09:30:00Z",
6   "pricing_amount_type": "EXCLUDING_TAX",
7   "periods": [
8     {
9       "period_order": 1,
10       "start_at": "2024-01-01T00:00:00Z",
11       "end_at": "2024-01-31T23:59:59Z",
12       "tax_categories": [
13         {
14           "category": "STANDARD",
15           "percentage": "5.00",
16           "name": "VAT",
17           "base_amount": {
18             "quantity": "1000.00",
19             "currency": "AED"
20           },
21           "tax_amount": {
22             "quantity": "50.00",
23             "currency": "AED"
24           },
25           "total_amount": {
26             "quantity": "1050.00",
27             "currency": "AED"
28           },
29           "local_amounts": {
30             "display": true,
31             "base_amount": {
32               "quantity": "1000.00",
33               "currency": "AED"
34             },
35             "tax_amount": {
36               "quantity": "50.00",
37               "currency": "AED"
38             },
39             "total_amount": {
40               "quantity": "1050.00",
41               "currency": "AED"
42             },
43             "used_exchange_rate": {
44               "currency": "AED",
45               "base_currency": "AED",
46               "rate_timestamp": "2024-01-15T09:30:00Z",
47               "rate": "1.0",
48               "source": "Internal"
49             }
50           },
51           "notes": [
52             "Standard VAT rate applied"
53           ],
54           "rates": [
55             {
56               "name": "Standard VAT",
57               "percentage": "5.00",
58               "tax_amount": {
59                 "quantity": "50.00",
60                 "currency": "AED"
61               }
62             }
63           ]
64         }
65       ],
66       "amount_excluding_tax": {
67         "quantity": "1000.00",
68         "currency": "AED"
69       },
70       "amount_including_tax": {
71         "quantity": "1050.00",
72         "currency": "AED"
73       },
74       "billing_period": {
75         "type": "DAY",
76         "value": 30
77       },
78       "groups": []
79     }
80   ],
81   "payment_acceptor_ids": [
82     "pa_abcdef1234567890"
83   ],
84   "linked_invoices_ids": [
85     "inv_1122334455667788"
86   ],
87   "object_type": "invoice",
88   "id": "inv_1234567890abcdef",
89   "invoice_number": "INV-2024-0001",
90   "purchase_order_number": "PON_007",
91   "platform_id": "platform_001",
92   "sales_tax_percentage": "5.00",
93   "customer": {
94     "reference": "CUST-REF-001",
95     "type": "ORGANIZATION",
96     "email": "billing@acmecorp.com",
97     "roles": [
98       "DEFAULT"
99     ],
100     "object_type": "customer",
101     "id": "cst_1234567890abcdef",
102     "created_at": "2023-12-01T10:00:00Z",
103     "parent_customer_id": "cst_parent_001",
104     "parent_customer_ids": [
105       "cst_parent_001"
106     ],
107     "status": "ACTIVE",
108     "timezone": "Asia/Dubai",
109     "notification_preferences": [
110       {
111         "type": "INVOICE",
112         "channels": [
113           {
114             "type": "EMAIL",
115             "enabled": true
116           }
117         ]
118       }
119     ],
120     "locale": "en-US",
121     "individual": {
122       "name": {
123         "first_name": "John",
124         "last_name": "Doe",
125         "infix": ""
126       },
127       "residential_address": {
128         "line1": "123 Elm Street",
129         "line2": "Suite 400",
130         "city": "Dubai",
131         "postal_code": "00000",
132         "state": "Dubai",
133         "country": "AE"
134       }
135     },
136     "organization": {
137       "legal_name": "Acme Corporation",
138       "tax_id": "AE123456789",
139       "tax_ids": [
140         {
141           "id": "taxid_001",
142           "type": "VAT_ID",
143           "tax_id_validation_result": {
144             "id": "val_001",
145             "validation_date": "2024-01-10T12:00:00Z",
146             "source": "Government Database",
147             "valid": "VALID",
148             "message": "Valid VAT ID"
149           }
150         }
151       ],
152       "registration_number": "REG-987654321",
153       "tax_exempt": false,
154       "tax_exempt_note": "",
155       "registered_address": {
156         "line1": "456 Oak Avenue",
157         "line2": "",
158         "city": "Dubai",
159         "postal_code": "00001",
160         "state": "Dubai",
161         "country": "AE"
162       },
163       "tax_registrations": [
164         {
165           "id": "taxreg_001",
166           "description": "VAT Registration",
167           "tax_id": "AE123456789",
168           "tax_ids": [
169             {
170               "id": "taxid_001",
171               "type": "VAT_ID",
172               "tax_id_validation_result": {
173                 "id": "val_001",
174                 "validation_date": "2024-01-10T12:00:00Z",
175                 "source": "Government Database",
176                 "valid": "VALID",
177                 "message": "Valid VAT ID"
178               }
179             }
180           ],
181           "registration_number": "REG-987654321",
182           "registered_address": {
183             "line1": "456 Oak Avenue",
184             "line2": "",
185             "city": "Dubai",
186             "postal_code": "00001",
187             "state": "Dubai",
188             "country": "AE"
189           }
190         }
191       ]
192     },
193     "custom_fields": [
194       {
195         "id": "cf_001",
196         "reference": "preferred_contact",
197         "value": "email",
198         "values": [
199           "email"
200         ],
201         "integration_details": {
202           "payment_gateway_variant": "ADYEN",
203           "id": "int_001",
204           "reference": "adyen_integration",
205           "adyen": {
206             "recurring_detail_reference": "rec_123456"
207           },
208           "stripe": {
209             "payment_method_id": "pm_123456789"
210           }
211         }
212       }
213     ],
214     "processing_only": false,
215     "pricing_plan_subscription_selector": {
216       "data": [
217         {
218           "field": "BILLING_ENTITY_REGISTERED_ADDRESS_COUNTRY",
219           "value": "AE"
220         }
221       ],
222       "rules": [
223         {
224           "field": "BILLING_ENTITY_REGISTERED_ADDRESS_COUNTRY",
225           "type": "EQUALS"
226         }
227       ],
228       "filters": [
229         {
230           "field": "BILLING_ENTITY_REGISTERED_ADDRESS_COUNTRY",
231           "type": "EQUALS",
232           "value": "AE"
233         }
234       ],
235       "fallback": "LATEST"
236     },
237     "linked_integrations": [
238       {
239         "id": "int_link_001",
240         "link_details": [
241           {
242             "url": "https://integration.acmecorp.com",
243             "custom_field_name": "integration_url"
244           }
245         ]
246       }
247     ]
248   },
249   "billing_entity": {
250     "reference": "BE-REF-001",
251     "default_customer_country_selector": [
252       "AE"
253     ],
254     "default_billing_currency_selector": [
255       "AED"
256     ],
257     "object_type": "billing_entity",
258     "id": "be_9876543210fedcba",
259     "created_at": "2023-11-15T08:00:00Z",
260     "status": "ACTIVE",
261     "timezone": "Asia/Dubai",
262     "legal_name": "Acme Billing Entity",
263     "tax_id": "AE987654321",
264     "tax_ids": [
265       {
266         "id": "taxid_be_001",
267         "type": "VAT_ID",
268         "tax_id_validation_result": {
269           "id": "val_be_001",
270           "validation_date": "2024-01-05T09:00:00Z",
271           "source": "Government Database",
272           "valid": "VALID",
273           "message": "Valid VAT ID"
274         }
275       }
276     ],
277     "registration_number": "REG-BE-123456",
278     "registered_address": {
279       "line1": "789 Pine Road",
280       "line2": "Floor 2",
281       "city": "Dubai",
282       "postal_code": "00002",
283       "state": "Dubai",
284       "country": "AE"
285     },
286     "email": "billing@acmebilling.com",
287     "tax_settings": {
288       "apply_local_vat_for_missing_tax_id": true
289     },
290     "tax_registrations": [
291       {
292         "id": "taxreg_be_001",
293         "description": "VAT Registration",
294         "tax_id": "AE987654321",
295         "tax_ids": [
296           {
297             "id": "taxid_be_001",
298             "type": "VAT_ID",
299             "tax_id_validation_result": {
300               "id": "val_be_001",
301               "validation_date": "2024-01-05T09:00:00Z",
302               "source": "Government Database",
303               "valid": "VALID",
304               "message": "Valid VAT ID"
305             }
306           }
307         ],
308         "registration_number": "REG-BE-123456",
309         "registered_address": {
310           "line1": "789 Pine Road",
311           "line2": "Floor 2",
312           "city": "Dubai",
313           "postal_code": "00002",
314           "state": "Dubai",
315           "country": "AE"
316         }
317       }
318     ],
319     "custom_fields": [
320       {
321         "id": "cf_be_001",
322         "reference": "billing_contact",
323         "value": "billing@acmebilling.com",
324         "values": [
325           "billing@acmebilling.com"
326         ],
327         "integration_details": {
328           "payment_gateway_variant": "STRIPE",
329           "id": "int_be_001",
330           "reference": "stripe_integration",
331           "adyen": {
332             "recurring_detail_reference": "rec_be_123456"
333           },
334           "stripe": {
335             "payment_method_id": "pm_be_123456"
336           }
337         }
338       }
339     ],
340     "linked_integrations": [
341       {
342         "id": "int_link_be_001",
343         "link_details": [
344           {
345             "url": "https://billingintegration.acme.com",
346             "custom_field_name": "billing_integration_url"
347           }
348         ]
349       }
350     ]
351   },
352   "paid": true,
353   "created_at": "2024-01-15T10:00:00Z",
354   "updated_at": "2024-01-16T12:00:00Z",
355   "delivery_date": "2024-01-16T09:00:00Z",
356   "due_date": "2024-02-15T23:59:59Z",
357   "billing_period_date": "2024-01-01T00:00:00Z",
358   "billing_currency": "AED",
359   "invoice_amount_including_tax": {
360     "quantity": "1050.00",
361     "currency": "AED"
362   },
363   "open_invoice_amount": {
364     "quantity": "0.00",
365     "currency": "AED"
366   },
367   "closed_invoice_amount": {
368     "quantity": "1050.00",
369     "currency": "AED"
370   },
371   "timezone": "Asia/Dubai",
372   "billing_period": {
373     "type": "DAY",
374     "value": 30
375   },
376   "pricing_plan_subscription_ids": [
377     "sub_00123456789"
378   ],
379   "closed_periods": [],
380   "tax_categories": [
381     {
382       "category": "STANDARD",
383       "percentage": "5.00",
384       "name": "VAT",
385       "base_amount": {
386         "quantity": "1000.00",
387         "currency": "AED"
388       },
389       "tax_amount": {
390         "quantity": "50.00",
391         "currency": "AED"
392       },
393       "total_amount": {
394         "quantity": "1050.00",
395         "currency": "AED"
396       },
397       "local_amounts": {
398         "display": true,
399         "base_amount": {
400           "quantity": "1000.00",
401           "currency": "AED"
402         },
403         "tax_amount": {
404           "quantity": "50.00",
405           "currency": "AED"
406         },
407         "total_amount": {
408           "quantity": "1050.00",
409           "currency": "AED"
410         },
411         "used_exchange_rate": {
412           "currency": "AED",
413           "base_currency": "AED",
414           "rate_timestamp": "2024-01-15T09:30:00Z",
415           "rate": "1.0",
416           "source": "Internal"
417         }
418       },
419       "notes": [
420         "Standard VAT rate applied"
421       ],
422       "rates": [
423         {
424           "name": "Standard VAT",
425           "percentage": "5.00",
426           "tax_amount": {
427             "quantity": "50.00",
428             "currency": "AED"
429           }
430         }
431       ]
432     }
433   ],
434   "tax_summary": {
435     "country_code": "AE",
436     "base_amount": {
437       "quantity": "1000.00",
438       "currency": "AED"
439     },
440     "tax_amount": {
441       "quantity": "50.00",
442       "currency": "AED"
443     },
444     "total_amount": {
445       "quantity": "1050.00",
446       "currency": "AED"
447     },
448     "local_amounts": {
449       "display": true,
450       "base_amount": {
451         "quantity": "1000.00",
452         "currency": "AED"
453       },
454       "tax_amount": {
455         "quantity": "50.00",
456         "currency": "AED"
457       },
458       "total_amount": {
459         "quantity": "1050.00",
460         "currency": "AED"
461       },
462       "used_exchange_rate": {
463         "currency": "AED",
464         "base_currency": "AED",
465         "rate_timestamp": "2024-01-15T09:30:00Z",
466         "rate": "1.0",
467         "source": "Internal"
468       }
469     },
470     "notes": [
471       "Summary of VAT applied"
472     ]
473   },
474   "dunning_actions": [],
475   "payment_actions": [],
476   "pay_invoice_link": {
477     "expiry_period": {
478       "type": "DAY",
479       "value": 7
480     },
481     "portal_url_id": "portal_001",
482     "url": "https://pay.acmecorp.com/invoice/inv_1234567890abcdef"
483   },
484   "notes": [
485     "Thank you for your business."
486   ],
487   "linked_invoices": [
488     {
489       "id": "inv_1122334455667788",
490       "link_type": "CREDIT",
491       "note": "Linked credit invoice",
492       "invoice_number": "INV-2023-0999",
493       "amount": {
494         "quantity": "200.00",
495         "currency": "AED"
496       },
497       "invoice_date": "2023-12-15T09:30:00Z"
498     }
499   ],
500   "custom_fields": [
501     {
502       "id": "cf_002",
503       "reference": "internal_notes",
504       "value": "Urgent processing required",
505       "values": [
506         "Urgent processing required"
507       ],
508       "integration_details": {
509         "payment_gateway_variant": "STRIPE",
510         "id": "int_002",
511         "reference": "stripe_integration",
512         "adyen": {
513           "recurring_detail_reference": "rec_654321"
514         },
515         "stripe": {
516           "payment_method_id": "pm_987654321"
517         }
518       }
519     }
520   ],
521   "other_custom_fields": [],
522   "credit": {
523     "note": "Credit applied for overpayment",
524     "original_invoice_id": "inv_1122334455667788",
525     "original_invoice_info": {
526       "id": "inv_1122334455667788",
527       "invoice_number": "INV-2023-0999"
528     }
529   },
530   "e_invoices": [],
531   "used_exchange_rates": [
532     {
533       "currency": "AED",
534       "base_currency": "AED",
535       "rate_timestamp": "2024-01-15T09:30:00Z",
536       "rate": "1.0",
537       "source": "Internal"
538     }
539   ],
540   "processing_only_customers": [],
541   "meter_values": [],
542   "credit_types": [],
543   "display_invoice_sub_lines_per_processing_only_customer": false,
544   "forwarded_from_customers": [],
545   "validation_result": [
546     {
547       "status": "VALID",
548       "details": "Invoice data validated successfully"
549     }
550   ],
551   "used_tax_registration": {
552     "id": "taxreg_be_001",
553     "description": "VAT Registration",
554     "tax_id": "AE987654321",
555     "tax_ids": [
556       {
557         "id": "taxid_be_001",
558         "type": "VAT_ID",
559         "tax_id_validation_result": {
560           "id": "val_be_001",
561           "validation_date": "2024-01-05T09:00:00Z",
562           "source": "Government Database",
563           "valid": "VALID",
564           "message": "Valid VAT ID"
565         }
566       }
567     ],
568     "registration_number": "REG-BE-123456",
569     "registered_address": {
570       "line1": "789 Pine Road",
571       "line2": "Floor 2",
572       "city": "Dubai",
573       "postal_code": "00002",
574       "state": "Dubai",
575       "country": "AE"
576     }
577   },
578   "footnote": "Payment due within 30 days.",
579   "approval_status": "PENDING_REVIEW",
580   "updated_to_final_at": "2024-01-16T12:00:00Z",
581   "has_usage_based_pricing": false,
582   "coupons": [],
583   "promotion_codes": [],
584   "linked_integrations": [],
585   "billing_type": "DEFAULT",
586   "auto_rescues": [],
587   "to_be_reprocessed": false
588 }

Requires the INVOICE.UPDATE permission.

Authentication

X-API-KEYstring

API Key authentication via header

AuthorizationBearer

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

Path parameters

versionstringRequiredDefaults to 1

version

resourceIdstringRequiredDefaults to

The ID of the resource to be requested.

Request

This endpoint expects an object.

customer_idstringRequired

id of the customer, can only be provided for a one-off invoice, and is mandatory in that case

billing_entity_idstringRequired

id of the billing entity, can only be provided for a one-off invoice. If not provided, the default of the platform will be used

statusstringRequired

on_holdbooleanRequired

typeenumRequired

Allowed values:

invoice_datedatetimeRequired

pricing_amount_typeenumRequired

Indicates whether the amounts provided, e.g. from the pricing plan, are including or excluding tax.

Allowed values:

periodslist of objectsRequired

Periods that are applicable for this invoice, use either periods or groups for summation, groups will be removed in later version

payment_acceptor_idslist of stringsRequired

linked_invoices_idslist of stringsRequiredDeprecated

Can currently only be used for ‘ONE_OFF_CREDIT’ invoices, indicates original invoices that this invoice links to

purchase_order_numberstring or nullOptional

sales_tax_percentagestring or nullOptional

Sales tax percentage. Needs to be present if both customer and billing entity are US-based. Optional if one of them is US-based

customerobject or nullOptional

billing_entityobject or nullOptional

paidboolean or nullOptional

due_datedatetime or nullOptional

invoice_amount_including_taxobject or nullOptional

Amount value of the meter value, will be set when type == AMOUNT

open_invoice_amountobject or nullOptional

Amount value of the meter value, will be set when type == AMOUNT

closed_invoice_amountobject or nullOptional

Amount value of the meter value, will be set when type == AMOUNT

billing_periodobject or nullOptional

Optional delivery window configuration that limits when outbound emails may be sent.

tax_summaryobject or nullOptional

pay_invoice_linkobject or nullOptional

noteslist of strings or nullOptional

custom_fieldslist of objects or nullOptional

creditobject or nullOptional

reprocessobjectOptional

used_tax_registrationobject or nullOptional

The tax registrations that are used to calculate the tax for this invoice. If empty, the billing entity was used

linked_integrationslist of objects or nullOptional

billing_typeenum or nullOptional

Allowed values:

Response

statusstring

on_holdboolean

typeenum

Allowed values:

invoice_datedatetime

pricing_amount_typeenum

Indicates whether the amounts provided, e.g. from the pricing plan, are including or excluding tax.

Allowed values:

periodslist of objects

Periods that are applicable for this invoice, use either periods or groups for summation, groups will be removed in later version

payment_acceptor_idslist of strings

linked_invoices_idslist of stringsDeprecated

Can currently only be used for ‘ONE_OFF_CREDIT’ invoices, indicates original invoices that this invoice links to

object_typestring or nullRead-only

idstring or nullRead-only

invoice_numberstring or nullRead-only

purchase_order_numberstring or null

platform_idstring or nullRead-only

sales_tax_percentagestring or null

Sales tax percentage. Needs to be present if both customer and billing entity are US-based. Optional if one of them is US-based

customerobject or null

billing_entityobject or null

paidboolean or null

created_atstring or nullRead-only

updated_atstring or nullRead-only

delivery_datestring or nullRead-only

due_datedatetime or null

billing_period_datestring or nullRead-only

billing_currencystring or nullRead-only

invoice_amount_including_taxobject or null

Amount value of the meter value, will be set when type == AMOUNT

open_invoice_amountobject or null

Amount value of the meter value, will be set when type == AMOUNT

closed_invoice_amountobject or null

Amount value of the meter value, will be set when type == AMOUNT

timezonestring or nullRead-only

billing_periodobject or null

Optional delivery window configuration that limits when outbound emails may be sent.

pricing_plan_subscription_idslist of strings or nullRead-only

closed_periodslist of objects or nullRead-only

tax_categorieslist of objects or nullRead-only

tax_summaryobject or null

dunning_actionslist of objects or nullRead-only

payment_actionslist of objects or nullRead-only

pay_invoice_linkobject or null

noteslist of strings or null

linked_invoiceslist of objects or nullRead-only

custom_fieldslist of objects or null

other_custom_fieldslist of objects or nullRead-only

creditobject or null

e_invoiceslist of objects or nullRead-only

used_exchange_rateslist of objects or nullRead-only

processing_only_customerslist of objects or nullRead-only

meter_valueslist of objects or nullRead-only

credit_typeslist of objects or nullRead-only

display_invoice_sub_lines_per_processing_only_customerboolean or nullRead-only

forwarded_from_customerslist of objects or nullRead-only

validation_resultlist of objects or nullRead-only

reprocessobject

used_tax_registrationobject or null

The tax registrations that are used to calculate the tax for this invoice. If empty, the billing entity was used

footnotestring or nullRead-only

Footnote to be shown on the invoice

approval_statusenum or nullRead-only

Approval status for invoices that are associated with an approval request

Allowed values:

updated_to_final_atstring or nullRead-only

The invoice finalization date

has_usage_based_pricingboolean or nullRead-only

couponslist of objects or nullRead-only

Coupons applied to this invoice

promotion_codeslist of objects or nullRead-only

Promotion codes applied to this invoice

linked_integrationslist of objects or null

billing_typeenum or null

Allowed values:

auto_rescueslist of objects or nullRead-onlyDeprecated

to_be_reprocessedboolean or nullRead-onlyDeprecated

to_be_reprocessed_atstring or nullRead-onlyDeprecated

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error

Authentication

Path parameters

Headers

Request

Response

Errors