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 and depositAmount parameters can be used to update Tip or Deposit values on an invoice with a status 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

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": []
}