Invoice

Create invoice

Changed on Nov 3, 2026

post/invoices

Request

Base URL
https://api.helcim.com/v2
URL
https://api.helcim.com/v2/invoices
Auth
API key in header api-token

Request body

currency'CAD' | 'USD' required

The three-letter ISO 4217 currency code used for all monetary amounts in this invoice.

customerIdinteger

Unique customer ID to associate with this invoice.

The invoice type. Allowed values: ESTIMATE, QUOTE, ORDER, PURCHASE_ORDER, INVOICE, STATEMENT, REGISTRATION, CREDIT. Defaults to INVOICE if omitted.

The initial status of the invoice. Allowed values: CANCELLED, DUE, PAID, SHIPPED, COMPLETED, REFUNDED, IN_PROGRESS. Defaults to DUE if omitted.

convenienceFeeEnabledboolean

Indicates whether a convenience fee is enabled for this invoice. If not provided, the system will use the merchant's global Fee Saver settings to determine this value.

tipAmountnumber float

Optional tip amount to include. Must be greater than zero if provided.

invoiceNumberstring

Optional custom invoice number. If omitted or blank, the system will generate one automatically based on the Invoice Settings.

notesstring

Optional notes to display at the bottom of the invoice, visible to the customer.

Example request

{
  "currency": "CAD",
  "lineItems": [
    {
      "description": "Red Hat",
      "quantity": 10.5,
      "price": 10.55,
      "sku": "ITM1434"
    }
  ],
  "customerId": 123123,
  "billingAddress": {
    "name": "John Smith / Helcim",
    "street1": "21 Jump Street",
    "street2": "Suite 400",
    "city": "Calgary",
    "province": "AB",
    "country": "CAN",
    "postalCode": "H0H0H0",
    "email": "john@example.com"
  },
  "shipping": {
    "amount": 10.99,
    "details": "Canada Post 1-day shipping",
    "address": {
      "name": "John Smith / Helcim",
      "street1": "21 Jump Street",
      "street2": "Suite 400",
      "city": "Calgary",
      "province": "AB",
      "country": "CAN",
      "postalCode": "H0H0H0",
      "email": "john@example.com"
    }
  },
  "pickup": {
    "date": "2022-01-25 13:55:55",
    "name": "Jane Smith"
  },
  "tax": {
    "amount": 5.99,
    "details": "GST 5%"
  },
  "discount": {
    "amount": 10.99,
    "details": "DISC100"
  },
  "type": "INVOICE",
  "status": "DUE",
  "convenienceFeeEnabled": true,
  "tipAmount": 0.99,
  "notes": "No vegetables please"
}

Response

Successful

invoiceIdinteger

Unique ID of the invoice.

invoiceNumberstring

Invoice number. Generated if not provided during creation.

tokenstring

A system generated unique token to reference the invoice with. can be used to view the invoice online.

typestring

The type of the invoice. Possible values include: ESTIMATE, INVOICE, QUOTE, ORDER, PURCHASE_ORDER, STATEMENT, REGISTRATION, CREDIT.

statusstring

The current status of the invoice. Possible values include: CANCELLED, DUE, PAID, SHIPPED, COMPLETED, REFUNDED, APP, IN_PROGRESS, OVERDUE, FOR_APPROVAL, APPROVED.

currencystring

The three-letter ISO 4217 currency code for this invoice. Possible values include: CAD, USD.

customerIdinteger

ID of the customer associated with this invoice. Will be 0 if no customer is associated with the invoice.

dateCreatedstring date-time

The date and time when the invoice was created.

dateUpdatedstring date-time

The date and time when the invoice was last updated.

datePaidstring date-time

The date and time when the invoice was paid, if applicable.

dateIssuedstring date-time

The date and time when the invoice was issued.

amountnumber float

The total amount of the invoice.

amountPaidnumber float

The total amount that has been paid towards this invoice.

amountDuenumber float

The remaining balance due for this invoice.

tipAmountnumber float

The tip amount applied to this invoice.

depositAmountnumber float

The deposit for items on the invoice, e.g bottle fees.

convenienceFeenumber float

The total convenience fee applied to this invoice.

convenienceFeeEnabledboolean

Indicates whether a convenience fee was enabled for this invoice.

surchargingFeenumber float

The total surcharging fee applied to this invoice.

notesstring

Notes visible to the customer at the bottom of the invoice.

Example response

{
  "invoiceId": 28658838,
  "invoiceNumber": "INV1000",
  "token": "4e71b0b71b032e8bd95097",
  "type": "INVOICE",
  "status": "DUE",
  "currency": "CAD",
  "customerId": 15301549,
  "billingAddress": {
    "name": "John Smith / Helcim",
    "street1": "21 Jump Street",
    "street2": "Suite 400",
    "city": "Calgary",
    "province": "AB",
    "country": "CAN",
    "postalCode": "H0H0H0",
    "email": "john@example.com"
  },
  "shipping": {
    "amount": 10.99,
    "details": "Canada Post 1-day shipping",
    "address": {
      "name": "John Smith / Helcim",
      "street1": "21 Jump Street",
      "street2": "Suite 400",
      "city": "Calgary",
      "province": "AB",
      "country": "CAN",
      "postalCode": "H0H0H0",
      "email": "john@example.com"
    }
  },
  "pickup": {
    "date": "2022-01-25 13:55:55",
    "name": "Jane Smith"
  },
  "tax": {
    "amount": 5.99,
    "details": "GST 5%"
  },
  "discount": {
    "amount": 10.99,
    "details": "DISC100"
  },
  "lineItems": [
    {
      "description": "Red Hat",
      "quantity": 10.5,
      "price": 10.55,
      "sku": "ITM1434"
    }
  ],
  "dateCreated": "2025-06-20 13:05:03",
  "dateUpdated": "2025-06-20 13:05:03",
  "datePaid": "0000-00-00 00:00:00",
  "dateIssued": "2025-06-20 13:05:03",
  "amount": 127.48,
  "amountDue": 127.48,
  "tipAmount": 0.99,
  "orderFields": [
    {
      "displayName": "Table Number",
      "value": "44B"
    }
  ],
  "notes": "No vegetables please"
}

Changes

Nov 3, 202695aef350fef4 Revision changes
- breaking
  the // request property format changed from no format to float
- breaking
  the // request property format changed from no format to float
- breaking
  the // request property format changed from no format to float
- breaking
  the // request property format changed from no format to float
- breaking
  removed the required property // from the response with the status
- warning
  removed the request property //

Operation history