Update an invoice
The Update invoice endpoint can be used to update existing invoice
objects within the Helcim system based on the invoiceId
parameter. The invoiceId
is found in the object returned by responses from the Create invoice and Get invoices endpoints.
Request type
It is important to note that this is a PUT request, not a PATCH request. For this reason any existing values you would like to retain should be included in your update request.
Update invoice requests
The Update invoice endpoint takes a single path parameter value of invoiceId
and a range of body parameters, in order to update the relevant invoice
object in the Helcim system.
The body parameters this endpoint will accept, include:
- The
invoiceNumber
parameter can be used to update the invoice number from either the default generated Helcim system value, or the value passed in a Create invoice request. - The
tipAmount
anddepositAmount
parameters can be used to update Tip or Deposit values on an invoice with astatus
of DUE. - The
currency
value can be used to update an invoice to CAD or USD, for Canadian based merchants who are set up to process in both currencies. - The
billingAddress
object can be used to update the billing address details for the invoice, so long as it is linked to an existing customer in the Helcim system.
Review Update Invoice API Reference
// Example Update invoice request
const options = {
method: 'PUT',
headers: {
accept: 'application/json',
'content-type': 'application/json',
'api-token': 'YOUR_API_TOKEN'
},
body: JSON.stringify({
billingAddress: {
name: 'Helcim Test',
street1: '123 Test Street',
postalCode: 'H0H0H0',
country: 'CAN',
province: 'AB',
city: 'Calgary',
phone: '4031231234',
email: '[email protected]'
}
})
};
fetch('https://api.helcim.com/v2/invoices/39570387', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
Updating an invoice status
status
The Update invoice endpoint can be used to change the invoice status
to one of the available values outlined in the API Reference documentation.
Updating an invoices status to PAID can only be completed by processing full payment of the invoice amount
through the Payment API or HelcimPay.js. The Helcim system will automatically update the status
to PAID once this requirement is met.
While an invoice is only partially paid, or after a partial or full refund has been processed against an invoice, the invoice will have a status
of DUE. If an invoice has been refunded and there is no intent to process another payment against that invoice, it can be set to a status
of CANCELLED using the Update invoice endpoint.
The Helcim user interface may show other visual statuses such as OVERDUE. A visual status such as this is only displayed in the Helcim UI to assist with invoice management within our platform, but the inherent status
of the invoice is still DUE.
Potential responses
A request to the Update invoice endpoint will return either:
- A JSON response containing the updated
invoice
object with relevant changes. - An
error
response indicating the reason for the error.
// Example Update invoice response
{
"invoiceId": 39570387,
"invoiceNumber": "INV1479",
"token": "762efa0e7ae8868b392a7e",
"tipAmount": 10,
"depositAmount": 0,
"notes": "The tip and address should disappear",
"dateCreated": "2024-07-16 12:10:37",
"dateUpdated": "2024-07-16 13:24:54",
"datePaid": "0000-00-00 00:00:00",
"dateIssued": "2024-07-16 12:10:37",
"status": "DUE",
"customerId": 22898209,
"amount": 60,
"currency": "CAD",
"type": "INVOICE",
"convenienceFee": 0,
"orderFields": [],
"billingAddress": {
"name": "Helcim Test",
"street1": "123 Test Street",
"street2": "",
"city": "Calgary",
"province": "AB",
"country": "CAN",
"postalCode": "H0H0H0",
"phone": "4031231234",
"email": "[email protected]"
},
"shipping": {
"amount": 0,
"details": "",
"address": []
},
"pickup": [],
"tax": {
"amount": 0,
"details": ""
},
"discounts": {
"amount": 0,
"details": ""
},
"lineItems": []
}
Updated 3 months ago