Create an Invoice

The Create invoice endpoint can be used to create a new invoice object in the Helcim system, that can be linked to payment requests sent through the Payment API or HelcimPay.js.

Invoices created through this endpoint can also be managed directly within your Helcim account, where you can process or request payment through payment tools such as the Virtual Terminal, send Pay Now emails, or process in-person payments through the Smart Terminal API.

Create Invoice Requests

The Create invoice endpoint will allow you to create a single invoice object in the Helcim system.

The Create Invoice API Reference outlines the required and optional body parameters needed for your request. The minimum required information to create an invoice includes the currency of the invoice, in addition to a valid array of lineItem objects.

Within your invoice request, you may include additional parameters such as billingAddress, shipping, pickup, tax, or discount, to add additional detail to your invoices.

Review Create invoice API Reference

// Example create invoice request
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    'api-token': 'YOUR_API_TOKEN'
  },
  body: JSON.stringify({
    currency: 'CAD',
    lineItems: [{sku: 'ITM1434', description: 'Red Hat', quantity: 1, price: 10}]
  })
};

fetch('https://api.helcim.com/v2/invoices/', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Processing Payments for Invoices

An Invoice created through the Create invoice endpoint can be partially or fully paid through either the Payment API or HelcimPay.js, by passing the invoiceNumber in your relevant request.

Processing Through the Payment API

If processing payment through the Payment API, then the invoice must be linked to an existing customer object during creation and the cardToken used for payment must belong to that customer.

Processing Through HelcimPay.js

If processing payment through HelcimPay.js, then the invoice may be linked to a customer who can either process payment with existing stored card details, or process with a new card that will be tokenized and stored against their customer object.

If there is no customer linked to the invoice when using HelcimPay.js to process a payment, then the Helcim system will create a customer object on successful payment and link them automatically. The Helcim system will store the cardholder name, AVS details, and tokenized card details against that new customer object.

📘

Transaction Information

The Invoice API will not return associated transactions for invoices that have been partially or fully paid. The Card Transaction API can be used to pull transaction details with the invoiceNumber as a query parameter to verify transaction details for specific invoices.

Linking an Invoice to a Customer

An Invoice can be linked to an existing customer object by including the customerId value for that customer in your request. If you wish to display existing billingAddress and shipping information on the invoice, these details would need to be retrieved from the customer object and passed in your request, as these values will not be added automatically if a customer is linked.

Updating an Invoice status

The Create invoice endpoint will by default create an invoice with a status of DUE, if another status is not passed in the request. You may create an invoice with another status such as SHIPPED, COMPLETED, or CANCELLED.

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.

Including Valid lineItem Objects

The lineItem objects passed in your request are required to have a sku value in order for the items to appear on the invoice created in the Helcim system. The lineItems array will accept a maximum of 20 line item objects included in the array.

The items passed in this array are independent of any products or services currently stored in the Product and Service section within your Helcim account. The management of inventory levels for items passed in your requests when using the Invoice API, would need to be handled within your system.

Calculating the amount of an Invoice

The amount that is due on an Invoice is calculated automatically by the Helcim system. This calculation includes the following values.

• The array of lineItems objects and the sum of their total values.
• Plus the amount of any shipping object passed in the request.
• Plus the amount of any tax object passed in the request.
• Plus any tipAmount passed in the request.
• Less the amount of any discount object passed in the request.

Sending Pay Now emails for Invoices

The Invoice API does not facilitate the sending of Pay Now emails, which is functionality that is only available through the Invoicing tool within your Helcim account.

In order to allow access to Pay Now functionality for invoices you would need to integrate with a third-party email provider in order to manage email functionality, then render the Online Invoice View using the invoice objects unique token.

Potential Responses

The Create invoice endpoint will respond to all requests with either:

• A JSON response containing the invoice object created within the Helcim system.
• An error response indicating the reason for the error.

Successful Invoice Creation

A successful request will create an invoice object in the Helcim system, that will be returned in the response and contain a number of parameters for that invoice.

// Example of invoice object
{
  "invoiceId": 39547547,
  "invoiceNumber": "INV1466",
  "token": "4b9f99eb802b15a67f8153",
  "tipAmount": 0,
  "depositAmount": 0,
  "notes": "",
  "dateCreated": "2024-07-15 14:07:16",
  "dateUpdated": "2024-07-15 14:07:16",
  "datePaid": "0000-00-00 00:00:00",
  "dateIssued": "2024-07-15 14:07:16",
  "status": "DUE",
  "customerId": 0,
  "amount": 50,
  "currency": "CAD",
  "type": "INVOICE",
  "convenienceFee": 0,
  "orderFields": [],
  "billingAddress": [],
  "shipping": {
    "amount": 0,
    "details": "",
    "address": []
  },
  "pickup": [],
  "tax": {
    "amount": 0,
    "details": ""
  },
  "discounts": {
    "amount": 0,
    "details": ""
  },
  "lineItems": [
    {
      "sku": "ITM1434",
      "description": "Red Hat",
      "quantity": 1,
      "price": 50,
      "total": 50,
      "taxAmount": 0,
      "discountAmount": 0
    }
  ]
}

Unsuccessful Invoice Creation

An unsuccessful request will result in an error being returned in the response, that contains more information on the reason for the error.

// Example error response
{
  "errors": {
    "currency": "Missing required data currency"
  }
}