---
title: "Create invoice"
method: POST
path: "/invoices"
tags: ["Invoice"]
---

# Create invoice

`POST /invoices`

## Request body

- InvoiceUpsertRequest
  - `currency` 'CAD' | 'USD', required — The three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code used for all monetary amounts in this invoice.
  - `lineItems` LineItem[], required — A list of line items to include in the invoice. Must contain at least 1 item and no more than 100.
    - `sku` string
    - `description` string, required — The description of the item or product.
    - `quantity` number, required — Quantity of the item.
    - `price` number, required — Unit price of the item.
    - `total` number, required — Total amount based on quantity and price of the item.
    - `taxAmount` number — Tax amount on the item.
    - `discountAmount` number — Discount amount on the item.
  - `customerId` integer — Unique customer ID to associate with this invoice.
  - `billingAddress` Address
    - `name` string, required — Contact Name or Business Name
    - `street1` string, required
    - `street2` string
    - `city` string
    - `province` string — 2 letter abbreviation of the province (AB, BC, CA). Required field if country is CAN or USA.
    - `country` string — 3-letter abbreviation of the country (CAN, USA)
    - `postalCode` string, required
    - `phone` string — 10 to 15 digits phone number.
    - `email` string
  - `shipping` Shipping
    - `amount` number, float, required — The total shipping amount for the invoice.
    - `details` string, required — A description of the shipping method. This information appears on the invoice.
    - `address` Address, required
      - `name` string, required — Contact Name or Business Name
      - `street1` string, required
      - `street2` string
      - `city` string
      - `province` string — 2 letter abbreviation of the province (AB, BC, CA). Required field if country is CAN or USA.
      - `country` string — 3-letter abbreviation of the country (CAN, USA)
      - `postalCode` string, required
      - `phone` string — 10 to 15 digits phone number.
      - `email` string
  - `pickup` Pickup
    - `date` string, required — The scheduled pickup date and time in the format: `YYYY-MM-DD HH:MM:SS`.
    - `name` string — Read-only. Derived from the linked customer's contact name (empty when no customer is linked to the invoice). A `name` supplied in a create or update request is ignored — only `date` is writable. To change the displayed pickup name, update the linked customer's contact name.
  - `tax` Tax
    - `amount` number, float, required — The total tax amount applied at the invoice level. This does not include item-level taxes.
    - `details` string, required — A description of the tax or tax breakdown.
  - `discount` Discount
    - `amount` number, float, required — The total discount amount applied at the invoice level. This does not include item-level discounts.
    - `details` string, required — A description or code identifying the discount.
  - `type` 'ESTIMATE' | 'QUOTE' | 'ORDER' | 'PURCHASE_ORDER' | 'INVOICE' | 'STATEMENT' | 'REGISTRATION' | 'CREDIT' — The invoice type. Allowed values: ESTIMATE, QUOTE, ORDER, PURCHASE_ORDER, INVOICE, STATEMENT, REGISTRATION, CREDIT. Defaults to `INVOICE` if omitted.
  - `status` 'CANCELLED' | 'DUE' | 'PAID' | 'SHIPPED' | 'COMPLETED' | 'REFUNDED' | 'IN_PROGRESS' — The initial status of the invoice. Allowed values: CANCELLED, DUE, PAID, SHIPPED, COMPLETED, REFUNDED, IN_PROGRESS. Defaults to `DUE` if omitted.
  - `convenienceFeeEnabled` boolean — 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.
  - `tipAmount` number, float — Optional tip amount to include. Must be greater than zero if provided.
  - `invoiceNumber` string — Optional custom invoice number. If omitted or blank, the system will generate one automatically based on the Invoice Settings.
  - `notes` string — Optional notes to display at the bottom of the invoice, visible to the customer.

## Response `200`

Successful

- InvoiceResponse
  - `invoiceId` integer — Unique ID of the invoice.
  - `invoiceNumber` string — Invoice number. Generated if not provided during creation.
  - `token` string — A system generated unique token to reference the invoice with. can be used to view the invoice online.
  - `type` string — The type of the invoice. Possible values include: ESTIMATE, INVOICE, QUOTE, ORDER, PURCHASE_ORDER, STATEMENT, REGISTRATION, CREDIT.
  - `status` string — The current status of the invoice. Possible values include: CANCELLED, DUE, PAID, SHIPPED, COMPLETED, REFUNDED, APP, IN_PROGRESS, OVERDUE, FOR_APPROVAL, APPROVED.
  - `currency` string — The three-letter ISO 4217 currency code for this invoice. Possible values include: CAD, USD.
  - `customerId` integer — ID of the customer associated with this invoice. Will be 0 if no customer is associated with the invoice.
  - `billingAddress` Address
    - `name` string, required — Contact Name or Business Name
    - `street1` string, required
    - `street2` string
    - `city` string
    - `province` string — 2 letter abbreviation of the province (AB, BC, CA). Required field if country is CAN or USA.
    - `country` string — 3-letter abbreviation of the country (CAN, USA)
    - `postalCode` string, required
    - `phone` string — 10 to 15 digits phone number.
    - `email` string
  - `shipping` Shipping
    - `amount` number, float, required — The total shipping amount for the invoice.
    - `details` string, required — A description of the shipping method. This information appears on the invoice.
    - `address` Address, required
      - `name` string, required — Contact Name or Business Name
      - `street1` string, required
      - `street2` string
      - `city` string
      - `province` string — 2 letter abbreviation of the province (AB, BC, CA). Required field if country is CAN or USA.
      - `country` string — 3-letter abbreviation of the country (CAN, USA)
      - `postalCode` string, required
      - `phone` string — 10 to 15 digits phone number.
      - `email` string
  - `pickup` Pickup
    - `date` string, required — The scheduled pickup date and time in the format: `YYYY-MM-DD HH:MM:SS`.
    - `name` string — Read-only. Derived from the linked customer's contact name (empty when no customer is linked to the invoice). A `name` supplied in a create or update request is ignored — only `date` is writable. To change the displayed pickup name, update the linked customer's contact name.
  - `tax` Tax
    - `amount` number, float, required — The total tax amount applied at the invoice level. This does not include item-level taxes.
    - `details` string, required — A description of the tax or tax breakdown.
  - `discount` Discount
    - `amount` number, float, required — The total discount amount applied at the invoice level. This does not include item-level discounts.
    - `details` string, required — A description or code identifying the discount.
  - `lineItems` LineItem[] — List of line items included in this invoice.
    - `sku` string
    - `description` string, required — The description of the item or product.
    - `quantity` number, required — Quantity of the item.
    - `price` number, required — Unit price of the item.
    - `total` number, required — Total amount based on quantity and price of the item.
    - `taxAmount` number — Tax amount on the item.
    - `discountAmount` number — Discount amount on the item.
  - `dateCreated` string, date-time — The date and time when the invoice was created.
  - `dateUpdated` string, date-time — The date and time when the invoice was last updated.
  - `datePaid` string, date-time — The date and time when the invoice was paid, if applicable.
  - `dateIssued` string, date-time — The date and time when the invoice was issued.
  - `amount` number, float — The total amount of the invoice.
  - `amountPaid` number, float — The total amount that has been paid towards this invoice.
  - `amountDue` number, float — The remaining balance due for this invoice.
  - `tipAmount` number, float — The tip amount applied to this invoice.
  - `depositAmount` number, float — The deposit for items on the invoice, e.g bottle fees.
  - `convenienceFee` number, float — The total convenience fee applied to this invoice.
  - `convenienceFeeEnabled` boolean — Indicates whether a convenience fee was enabled for this invoice.
  - `surchargingFee` number, float — The total surcharging fee applied to this invoice.
  - `orderFields` OrderField[] — Any custom order fields attached to this invoice.
    - `displayName` string
    - `value` string
  - `notes` string — Notes visible to the customer at the bottom of the invoice.

## Other responses

- `default` — Failed

---

[API](https://skmtc.net/helcim/apis/the-helcim-api.md) · [All operations](https://skmtc.net/helcim/apis/the-helcim-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/helcim/the-helcim-api/versions/345052ca6578/schema)