Invoices

The invoice object

An invoice object can be created as a record of an intended or completed payment. With the invoice you can create a detailed record of payments with more information about your products, services, and customers, than a standard transaction receipt.

An invoice stores a number of core details, including:

• Unique invoiceId, invoiceNumber, and token values, that can be used to retrieve and update invoices, or link them to payments through HelcimPay.js or the Payment API.
• Information on the amount due on the invoice, including any tipAmount or depositAmount.
• Information on the status and type of invoice, as well as any customerId if the invoice is linked to a customer object.
• An array of lineItems objects used to create an itemized invoice of products and services.
• Sub-objects that provide information on custom order fields, billing and shipping address details, as well as pickup details, tax information, and discounts applied to the invoice.

// Example invoice object

{
  "invoiceId": 43596371,
  "invoiceNumber": "INV1791",
  "token": "4d86fb15661a10181c0eb5",
  "tipAmount": 0,
  "depositAmount": 0,
  "notes": "Example invoice",
  "dateCreated": "2024-12-06 04:22:04",
  "dateUpdated": "2024-12-06 04:22:05",
  "datePaid": "2024-12-06 04:22:05",
  "dateIssued": "2024-12-06 04:22:04",
  "status": "PAID",
  "customerId": 15424437,
  "amount": 52.5,
  "currency": "CAD",
  "type": "INVOICE",
  "convenienceFee": 0,
  "orderFields": [
    {
      "displayName": "Customer Tier",
      "value": "Elite"
    }
  ],
  "billingAddress": {
      "name": "John Smith",
      "street1": "123 Example Street",
      "street2": "Suite 120",
      "city": "Calgary",
      "province": "Alberta",
      "country": "Canada",
      "postalCode": "H0H 0H0",
      "phone": "1232345678",
      "email": "[email protected]"
    },
  "shipping": {
    "amount": 0,
    "details": "",
    "address": {
      "name": "John Smith",
      "street1": "123 Example Street",
      "street2": "Suite 120",
      "city": "Calgary",
      "province": "Alberta",
      "country": "Canada",
      "postalCode": "H0H 0H0",
      "phone": "1232345678",
      "email": "[email protected]"
    }
  },
  "pickup": {
    "date": "0000-00-00 00:00:00",
    "name": ""
  },
  "tax": {
    "amount": 2.5,
    "details": "Federal Tax Rate for Cana 5.0000% | 5.0000%"
  },
  "discounts": {
    "amount": 0,
    "details": ""
  },
  "lineItems": [
    {
      "sku": "004-SS1",
      "description": "Flannel Shirts | S ",
      "quantity": 1,
      "price": 50,
      "total": 50,
      "taxAmount": 2.5,
      "discountAmount": 0
    }
  ]
}

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 against an invoice 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 against an invoice 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.

📘

Invoice payment information

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

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.

Retrieving invoices

The Get invoices endpoint can be used to retrieve up to 100 basic invoice objects from the Helcim system based on a range of query parameters. If no query parameter is passed, the Helcim system will return the 100 most recent invoices.

The Get invoice endpoint can be used to retrieve a single detailed invoice object from the Helcim system based on the invoiceId value. The invoiceId is returned in the response from the Create invoice endpoint.

Using an invoiceNumber to retrieve an invoice

Approved Helcim payment responses will return the invoiceNumber value rather than an invoiceId.

This value can be passed as a query parameter to the Get invoices endpoint to retrieve the associated basicinvoice object, or obtain the invoiceId that can be used through the Get invoice endpoint to retrieve the detailed invoice object.

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 the Helcim platform.

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.