Create invoice

Authorization

Send one of these on every request. See Authentication for how to get credentials.

• API key

  Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

• Bearer token

Headers

• X-Idempotency-Key string

Request body

application/json;charset=UTF-8

• companyEntityId string · uuid

  ID of the company entity

• invoiceNumber string

  Unique invoice number. If not provided, one will be generated automatically when the invoice is opened.

• description string

  Invoice description

• currency string

• paymentType string

  Payment type for the invoice

  • AIRWALLEX - Payment via Airwallex. A payment link will be displayed on the invoice
  • BANK_TRANSFER - Payment via bank transfer. Bank information will be displayed on the invoice
  • DIRECT_DEBIT - Payment via direct debit. A notice that the amount will be collected automatically will be displayed on the invoice
  • STRIPE - Payment via Stripe. A payment link will be sent to the customer

  ⚠️ This enum is not exhaustive; new values may be added in the future.

  One of AIRWALLEX BANK_TRANSFER DIRECT_DEBIT STRIPE

• payeeBankAccountId string · uuid

  ID of the bank account where money should be sent to

• invoiceDate string · date

  Date the invoice was issued

• postingDate string · date

  Date the invoice is posted to the ledger (drives GL, VAT and revenue recognition). Defaults to the invoice date when omitted.

• dueDate string · date

  Date the invoice payment is due

• customerId string · uuid

  ID of the customer

• invoiceTemplateId string · uuid

  ID of the invoice template

• netTerms integer · int32

  Number of days from the invoice date to when the invoice is due. Setting this will automatically calculate the due date

• poNumber string

  Purchase order number

• reference string

  Reference number for cross-referencing with procurement and invoicing workflows

• invoiceTemplateAdditionalText string

  Text that will be added to the additional text section of the invoice template

• areLinesWithTax boolean

  Whether the invoice line amounts are inclusive of tax. True means tax is included in the line amount, false means tax will be added on top

• localCurrencyFxRate number

  Custom foreign exchange rate for the ledger's local currency. If not provided, Light uses official ECB rates

• groupCurrencyFxRate number

  Custom foreign exchange rate for the ledger's group currency. If not provided, Light uses official ECB rates

• lines array of object

  List of invoice line items to create

  • productId string · uuid

    ID of the product

  • quantity number

    Quantity of the product

  • taxCodeId string · uuid

    ID of the tax code to apply to this line

  • accountId string · uuid

    ID of the ledger account for this line

  • discount object

    Discount to apply to this line (can be percentage or amount-based)

    • type string

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of PERCENTAGE AMOUNT

  • priceOverwrite integer · int64

    Price overwrite in smallest denomination. If not provided, the product's default price will be used

  • productNameOverwrite string

    Product name overwrite. If not provided, the product's default name will be used

  • taxAmountOverwrite integer · int64

    Tax amount override in smallest denomination. Bypasses tax calculation and sets the exact tax amount for this line.

    Requirements: The line must have a valid amount (product price or priceOverwrite must be set).

    The taxAmount field in the response will reflect this override value.

    Amounts use smallest denomination. Examples: GBP 42.15 = 4215, JPY 12345 = 12345, BHD 7.321 = 7321.

  • avataxCode string

    Avalara tax code. Used when the invoice tax engine is AVATAX

  • billingStart string · date

    Start of the billing period for this line

  • billingEnd string · date

    End of the billing period for this line

  • accrualTemplateId string · uuid

    ID of the accrual/amortization template to apply to this line

  • accrualStartDate string · date

    Start date for accrual/amortization

  • accrualEndDate string · date

    End date for accrual/amortization

  • customProperties array of object

    List of custom properties to set on the invoice or line

    • groupId string · uuid

      ID of the custom property group.

    • valueIds array of string · uuid

      IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.

    • inlineValues array of string

      Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.

• customProperties array of object

  List of custom properties to set on the invoice or line

  • groupId string · uuid

    ID of the custom property group.

  • valueIds array of string · uuid

    IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.

  • inlineValues array of string

    Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.

Response

• id string · uuid

  Unique identifier for the object

• companyId string · uuid

  ID of the company

• contractId string · uuid

  ID of the contract, if this is invoice is linked to a contract

• companyEntityId string · uuid

  ID of the entity

• amount integer · int64

  Total invoice amount in smallest denomination, with discounts and tax applied

• paymentType string

  Payment type for the invoice

  • AIRWALLEX - Payment via Airwallex. A payment link will be displayed on the invoice
  • BANK_TRANSFER - Payment via bank transfer. Bank information will be displayed on the invoice
  • DIRECT_DEBIT - Payment via direct debit. A notice that the amount will be collected automatically will be displayed on the invoice
  • STRIPE - Payment via Stripe. A payment link will be sent to the customer

  ⚠️ This enum is not exhaustive; new values may be added in the future.

  One of AIRWALLEX BANK_TRANSFER DIRECT_DEBIT STRIPE

• payeeBankAccountId string · uuid

  ID of the bank account where money should be sent to

• invoiceDate string · date

  Date the invoice was issued

• effectiveInvoiceDate string · date

  The invoice date shown to customers; falls back to the posting date when the invoice date is not set

• postingDate string · date

  Date the invoice is posted to the ledger (drives GL, VAT and revenue recognition)

• dueDate string · date

  Date the invoice payment is due

• netTerms integer · int32

  Number of days from the invoice date to when the invoice is due. Updating this field will automatically set the invoice due date

• customerId string · uuid

  ID of the customer

• invoiceTemplateId string · uuid

  ID of the invoice template

• invoiceTemplateAdditionalText string

  Text that will added to the additional text section of the invoice template

• invoiceNumber string

  Invoice number. This number is guaranteed to be unique and sequential per entity. By default Light will generate this number when the invoice is opened, but you can provide your own custom number when creating or updating a draft invoice

• type string

  Who raised the invoice

  • STANDARD - The company raised the invoice
  • SELF_BILLED - The customer issued the invoice on the company's behalf and sent it in

  ⚠️ This enum is not exhaustive; new values may be added in the future.

  One of STANDARD SELF_BILLED

• state string

  The invoice state

  • CREATED - The invoice document was received and is waiting to be parsed. Next valid state is DRAFT
  • DRAFT - The invoice is in draft and can be modified. Next valid states are OPEN_IN_PROGRESS or ARCHIVED
  • OPEN_IN_PROGRESS - The invoice is being opened. Next valid state is OPEN or DRAFT
  • OPEN - The invoice is open. Next valid states are PAYMENT_PENDING, PARTIALLY_PAID, PAID or ARCHIVED
  • PAYMENT_PENDING - The payment was initiated by Light and is waiting to be collected. Next valid state is PAID
  • PARTIALLY_PAID - The invoice is partially paid. Next valid state is PAID
  • PAID - The invoice is fully paid
  • REVERSED - The invoice was reversed by a credit note and reissued as a new invoice; it is locked and cannot be modified
  • ARCHIVED - The invoice is archived and cannot be modified

  ⚠️ This enum is not exhaustive; new values may be added in the future.

  One of CREATED DRAFT OPEN_IN_PROGRESS OPEN PAYMENT_PENDING PARTIALLY_PAID PAID REVERSED ARCHIVED

• openedAt string · date-time

  Timestamp when the invoice was opened

• poNumber string

  Purchase order number

• reference string

  Reference number for cross-referencing with procurement and invoicing workflows

• description string

  Description of the invoice

• currency string

• taxEngineName string

  Name of the tax engine to be used

  • AVATAX - Avalara AvaTax will be used for tax calculations
  • LIGHT - Light built-in tax engine will be used for tax calculations
  • SPHERE - Sphere tax engine will be used for tax calculations

  ⚠️ This enum is not exhaustive; new values may be added in the future.

  One of AVATAX LIGHT SPHERE

• areLinesWithTax boolean

  Whether the invoice line amount is inclusive of tax or not. True means tax is already included in the line amount and will not be added on top, false means tax will be added on top of the line amount

• localCurrencyFxRate number

  Custom foreign exchange rate for the ledger's local currency. If not provided Light uses official ECB rates

• groupCurrencyFxRate number

  Custom foreign exchange rate for the ledger's group currency. If not provided Light uses official ECB rates

• lines array of object

  List of invoice line items. This is only returned when fetching a single invoice by id

  • id string · uuid

    Unique identifier for the object

  • companyId string · uuid

    ID of the company

  • invoiceReceivableId string · uuid

    ID of the invoice receivable this line belongs to

  • productId string · uuid

    ID of the product

  • quantity number

    Quantity of the product

  • taxCodeId string · uuid

    ID of the tax code

  • accountId string · uuid

    ID of the ledger account

  • discount object

    Discount to apply to this line (can be percentage or amount-based)

    • type string

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of PERCENTAGE AMOUNT

  • discountAmount integer · int64

    Discount amount in smallest denomination

  • netAmount integer · int64

    Net amount in smallest denomination after discount but before tax

  • taxAmount integer · int64

    Tax amount in smallest denomination

  • avataxCode string

    Avalara tax code. Used when the invoice tax engine is AVATAX

  • billingStart string · date

    Start of the billing period

  • billingEnd string · date

    End of the billing period

  • priceOverwrite integer · int64

    Custom product price in smallest denomination. This overrides the default product's price

  • productNameOverwrite string

    Custom product name. This overrides the default product's name

  • createdAt string · date-time

    Timestamp when the line was created

  • updatedAt string · date-time

    Timestamp when the line was last updated

  • accrualTemplateId string · uuid

    ID of the accrual template

  • accrualStartDate string · date

    Start date for accrual

  • accrualEndDate string · date

    End date for accrual

  • customProperties array of object

    List of custom properties associated with the line

    • groupId string · uuid

      ID of the custom property group

    • groupInternalName string

      Internal name of the custom property group

    • values array of object

      List of values. Note that this will be a single value unless the group input type supports multiple values

      • id string · uuid

        Unique identifier for the object

      • groupId string · uuid

        ID of the custom property group

      • groupInternalName string

        Internal name of the custom property group

      • companyId string · uuid

        ID of the company

      • internalName string

        Internal name of the custom property value

      • label string

        Label of the custom property value

      • context string

        Context/description of the custom property value

      • createdAt string · date-time

        Timestamp when the custom property value was created

      • updatedAt string · date-time

        Timestamp when the custom property value was last updated

• customProperties array of object

  List of custom properties associated with the invoice

  • groupId string · uuid

    ID of the custom property group

  • groupInternalName string

    Internal name of the custom property group

  • values array of object

    List of values. Note that this will be a single value unless the group input type supports multiple values

    • id string · uuid

      Unique identifier for the object

    • groupId string · uuid

      ID of the custom property group

    • groupInternalName string

      Internal name of the custom property group

    • companyId string · uuid

      ID of the company

    • internalName string

      Internal name of the custom property value

    • label string

      Label of the custom property value

    • context string

      Context/description of the custom property value

    • createdAt string · date-time

      Timestamp when the custom property value was created

    • updatedAt string · date-time

      Timestamp when the custom property value was last updated

• externalSource object

  The external system where this product was synced from

  • name string

    The name of the external source

    • CHARGEBEE - Data synced from Chargebee
    • HUBSPOT - Data synced from HubSpot
    • SALESFORCE - Data synced from Salesforce
    • STRIPE - Data synced from Stripe

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of CHARGEBEE HUBSPOT SALESFORCE STRIPE

  • externalId string

    The ID of the object in the external source system

• createdAt string · date-time

  Timestamp when the invoice was created

• updatedAt string · date-time

  Timestamp when the invoice was last updated

• updatedBy string · uuid

  ID of the user who last updated the invoice

• failureContext object

  Failure context when vendor onboarding fails.

  • name string

    The error name

  • type string

    The error type

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of BAD_REQUEST UNAUTHORIZED FORBIDDEN NOT_FOUND CONFLICT UNPROCESSABLE_CONTENT

  • errors array of object

    List of errors providing details about what went wrong

    • type string

      A string code identifying the error type

    • message string

      A human-readable message providing more details about the error

    • path array of string

      Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object

    • context object

      Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error