# Issuing Invoices

Issuing invoices requires invoicing to be enabled in your terminal.

If the invoice module was enabled during [Hyp onboarding](/creditguard/introduction/prerequisites-and-requirements.md), you can start working with the invoicing API immediately. Otherwise, follow the steps in [Enabling Invoicing in the Terminal](/creditguard/documents-and-invoicing/enabling-invoicing.md) before you begin.

To generate an invoice for a regular debit transaction, send a [standard Hyp API request](/creditguard/introduction/request-and-response-general-structure.md) and, in the `int_in` parameter, include an XML payload for the `addCgInvoice` command. The XML payload should look like this:

```xml
<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>addCgInvoice</command>
        <addCgInvoice>
            <invoiceAtranId>119284861</invoiceAtranId>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <invoice>
                <invoiceCreationMethod>wait</invoiceCreationMethod>
                <invoiceSubject>Invoice for your purchase</invoiceSubject>
                <invoiceItemCode>12345</invoiceItemCode>
                <invoiceItemDescription>Item description</invoiceItemDescription>
                <invoiceItemQuantity>1</invoiceItemQuantity>
                <invoiceItemPrice>12500</invoiceItemPrice>
                <companyInfo>Invoice recipient</companyInfo>
                <mailTo>example@acme.io</mailTo>
                <isItemPriceWithTax>1</isItemPriceWithTax>
                <ccDate>2025-08-07</ccDate>
            </invoice>
        </addCgInvoice>
    </request>
</ashrait>
```

The `language` element under `request` determines the language of the invoice, which can be either Hebrew (`HEB`) or English (`ENG`).

The `command` element should be set to `addCgInvoice`, and the `addCgInvoice` element must contain the following child elements:

* `terminalNumber`: a unique number assigned to you as a merchant during [registration](/creditguard/introduction/prerequisites-and-requirements.md).
* `invoiceAtranId`: the `tranId` of the debit transaction you want to generate an invoice for. If you don't have the `tranId`, perform an [inquire transaction](/creditguard/inquiring-transactions/overview.md) to retrieve it.
* `invoice`: the wrapper element for the invoice parameters:
  * `invoiceCreationMethod`: one of two invoice generation methods:
    * `post` initiates invoice generation and returns an immediate response confirming that generation has started. To retrieve the resulting invoice, you must later make a separate [inquiry call](/creditguard/documents-and-invoicing/invoice-inquiries.md) to fetch the invoice URL.
    * `wait` ensures that the response includes the resulting invoice URL. This may take longer but avoids the need for a separate inquiry call.
  * `invoiceSubject`: the subject of the invoice, up to 255 alphanumeric characters.
  * `invoiceItemCode`: the product identifier (מק"ט) based on the merchant's item cataloging system. Numeric, up to 500 characters.
  * `invoiceItemDescription`: item description, up to 500 alphanumeric characters.
  * `invoiceItemQuantity`: quantity of the item. Can be an integer or a decimal with two fractional places (e.g., `123.45`).
  * `invoiceItemPrice`: single item price.
  * `companyInfo`: the customer's full details, such as a personal name or company name. Up to 255 characters.
  * `mailTo`: the email address to send the invoice to.
  * `isItemPriceWithTax`: indicates whether `invoiceItemPrice` includes (`1`) or excludes (`0`) VAT. For implications of this setting, see [VAT calculation](#vat-calculation) below.
  * `ccDate`: the date (`YYYY-MM-DD`) to appear on the invoice. Must be on or after the transaction date.

The `invoice` element may also include the following optional parameters:

* Parameters that [override your invoice account details](/creditguard/documents-and-invoicing/overriding-invoice-account-details-in-the-request.md).
* `clientAddress`: the customer's address, up to 60 characters.
* `clientOsekNum`: the customer's tax registration number (ק סוע רפסמ), exactly 9 characters.
* `DocNotMaam`: indicates whether tax fields are included (`1`, default) or excluded (`0`) in the invoice.
* `DocRemark`: free-form description to include in the invoice, up to 255 characters. Supported only when `invoiceType` is set to `receipt`.
* `invoiceComments`: comments (up to 255 characters) not shown on the invoice but stored for internal records.
* `invoiceDate`: the invoice record date (`YYYY-MM-DD`) in EZcount. Defaults to the current date.
* `invoiceDiscount`: discount amount in currency subunits (e.g., agorot or cents). Mutually exclusive with `invoiceDiscountRate`. For details, see [Discount management](#discount-management).
* `invoiceDiscountRate`: discount rate as a percentage with two fractional places (e.g., `12.50`). Mutually exclusive with `invoiceDiscount`. See [Discount management](#discount-management).
* `invoiceItemMaam`: indicates whether to show an item with (`1`) or without (`0`) VAT.
* `invoiceSignature`: signature to append to the invoice.
* `invoiceTaxRate`: VAT rate for invoice calculations, specified as a percentage with two fractional places (e.g., `17.25`).
* `sendMail`: enables (`1`) or disables (`0`) sending the generated invoice by email to the customer. Defaults to `1`.
* `ua_uuid`: an EZcount identifier defining the design layout to use when generating the invoice.

## Adding multiple items to an invoice

The example above shows an invoice for a single item. However, invoices often include multiple items.

Each `addCgInvoice` command can only contain one set of the five item-related parameters:

* `invoiceItemCode`
* `invoiceItemDescription`
* `invoiceItemQuantity`
* `invoiceItemPrice`
* `invoiceItemMaam` (optional)

To list multiple items, include each value in the corresponding element and separate them with the pipe symbol (`|`). Make sure each element contains the same number of items, listed in the same order.

For example, the following request is for an invoice with three items:

```xml
<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>addCgInvoice</command>
        <addCgInvoice>
            <invoiceAtranId>119284862</invoiceAtranId>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <invoice>
                <invoiceCreationMethod>wait</invoiceCreationMethod>
                <invoiceSubject>Your vinyl store purchase</invoiceSubject>
                <invoiceItemCode>12345|12346|12347</invoiceItemCode>
                <invoiceItemDescription>Fleetwood Mac. Rumours|Alanis Morissette. Jagged Little Pill|Guns N' Roses.
                    Appetite for Destruction
                </invoiceItemDescription>
                <invoiceItemQuantity>2|1|1</invoiceItemQuantity>
                <invoiceItemPrice>11400|10400|14900</invoiceItemPrice>
                <companyInfo>Invoice recipient</companyInfo>
                <mailTo>example@acme.io</mailTo>
                <isItemPriceWithTax>1</isItemPriceWithTax>
                <ccDate>2025-08-07</ccDate>
            </invoice>
        </addCgInvoice>
    </request>
</ashrait>
```

## Validation and calculation rules for invoice parameters

Most documents generated by Hyp using the `addCgInvoice` command are fiscal documents that cannot be freely modified once issued. For this reason, Hyp enforces strict validation of key parameters to ensure accurate accounting and an exact match between the invoice and its underlying transaction.

### Amount total validation

To generate a valid invoice, the Hyp API verifies that the sum of all item totals matches the total amount paid in the transaction for which the invoice is being issued. If this check fails, the invoice is not created and EZcount returns error code `131`.

This validation applies whether the invoice contains one item or multiple items — the check always uses the sum of all (`price × quantity`) values.

The validation formula is:

```
(sum of (invoiceItemPrice × invoiceItemQuantity) for all items) = total
```

For an invoice with a single item:

```
invoiceItemPrice * invoiceItemQuantity = total
```

For an invoice with multiple items:

```
(invoiceItemPrice * invoiceItemQuantity) +
(invoiceItemPrice * invoiceItemQuantity) +
... 
= total
```

### VAT calculation

The `isItemPriceWithTax` element specifies whether the item prices in your invoice request already include VAT. This setting affects how `invoiceItemPrice` and `invoiceDiscount` are processed.

If `isItemPriceWithTax` is set to `1` (prices include VAT):

1. EZcount will subtract the VAT portion from each `invoiceItemPrice` and display item prices excluding VAT in the invoice. It will also calculate and display:
   1. The total before VAT.
   2. VAT from all items.
   3. The total after VAT.
2. The same VAT adjustment is applied to `invoiceDiscount`. For example, if `invoiceDiscount` is `1000` (₪10) and VAT is 18%, the effective discount is calculated as `1000 / 1.18 = 847.46` (≈₪8.48).

### Discount management

You can set discounts in your invoice request using either `invoiceDiscount` or `invoiceDiscountRate`, but not both in the same request.

When `invoiceDiscount` is used, the total is calculated as follows:

```
invoiceItemPrice * invoiceItemQuantity - invoiceDiscount = total
```

When `invoiceDiscountRate` is used, the total is calculated like this:

```
invoiceItemPrice * invoiceItemQuantity * (100 – invoiceDiscountRate) / 100 = total 
```

For example, if the original transaction total is ₪99 (`9900` in agorot) and you applied a 10% discount, you can represent this in the invoice request in either of the following ways:

1. Using `invoiceDiscount`:

   ```
   <invoiceDiscount>1100</invoiceDiscount>
   <invoiceItemQuantity>2|2</invoiceItemQuantity>
   <invoiceItemPrice>4000|1500</invoiceItemPrice>
   ```
2. Using `invoiceDiscountRate`:

   ```
   <invoiceDiscountRate>10.00</invoiceDiscountRate>
   <invoiceItemQuantity>2|2</invoiceItemQuantity>
   <invoiceItemPrice>4000|1500</invoiceItemPrice>
   ```

## Response structure

Here's a success response to the invoice request for three items shown in [Adding multiple items to an invoice](#adding-multiple-items-to-an-invoice) above:

```xml
<?xml version='1.0'?>
<ashrait>
    <response>
        <command>addCgInvoice</command>
        <dateTime>2025-08-07 17:51</dateTime>
        <requestId/>
        <tranId>119329000</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo/>
        <version>2000</version>
        <language>Eng</language>
        <addCgInvoice>
            <invoice>
                <invoiceCreationMethod>wait</invoiceCreationMethod>
                <invoiceResponseCode>100</invoiceResponseCode>
                <invoiceResponseName>Proper Invoice Request</invoiceResponseName>
                <invoiceDocNumber>150460</invoiceDocNumber>
                <invoiceDocUrl>
                    https://demo.ezcount.co.il/front/documents/get/6f349b47-d649-4e49-82b4-ba3f0f5fca04/copy_en
                </invoiceDocUrl>
                <invoiceAtranId>119328971</invoiceAtranId>
                <invoiceCreationDate>1754578270</invoiceCreationDate>
                <mailTo>example@acme.io</mailTo>
                <invoiceCreationCode>000</invoiceCreationCode>
            </invoice>
        </addCgInvoice>
    </response>
</ashrait>
```

This example shows a response to a request with `invoiceCreationMethod` set to `wait`, which is why it includes the `invoiceDocUrl` element containing a ready-to-use link to the generated invoice.

If `invoiceCreationMethod` is set to `post`, the response does not include the invoice link because the document may not be ready yet. In that case, you must send an [invoice inquiry](/creditguard/documents-and-invoicing/invoice-inquiries.md) using the `invoiceAtranId` value from the response to retrieve the invoice URL.

Some elements under `invoice` in the response are identical to those in the request, while others differ. The notable response-specific elements are:

* `invoiceAtranId`: the new transaction ID (`tranId`) for the invoice.
* `invoiceResponseCode`: EZcount status code (`100` indicates success).
* `invoiceResponseName`: EZcount status message.
* `invoiceDocNumber`: invoice number generated according to the numbering settings you configured during EZcount registration.
* `invoiceDocUrl`: URL to access the generated invoice.
* `invoiceCreationDate`: invoice creation time in Unix timestamp (epoch) format.

When the Hyp API returns a success response, EZcount also emails the generated invoice to the customer, unless sending is disabled in the request.

The invoice email looks like this:

![EZcount invoice email](/files/73YkZSOCOVdTmTXX3fJc)

The customer can download the invoice PDF by clicking the button in the email. Below is an example of a PDF tax invoice receipt for a purchase of three items:

![EZcount invoice PDF](/files/D1KmeTz6iM3ddY4uC7pQ)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.hyp.co.il/creditguard/documents-and-invoicing/issuing-invoices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.