Create income document

Credentials

Create a new income document (invoice, receipt, deal, etc.) using the new invoicing service.

More examples

Amounts are in agorot (1 ILS = 100 agorot).

Receipt (cash)

{
  "type": "receipt",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Product Sale",
      "quantity": 2,
      "itemNetPrice": 50000,
      "itemTotalPrice": 58500,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "totalAmount": 117000,
  "totalPaid": 117000,
  "originTaxDeduction": 0,
  "cash": {
    "date": "2024-01-15",
    "amount": 117000
  }
}

Invoice + Receipt (bank transfer)

{
  "type": "invrec",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Annual Subscription",
      "quantity": 1,
      "itemNetPrice": 240000,
      "itemTotalPrice": 280800,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 240000,
  "totalWithoutVatAmount": 240000,
  "vatAmount": 40800,
  "totalAmount": 280800,
  "totalPaid": 280800,
  "originTaxDeduction": 0,
  "bank-transfer": {
    "date": "2024-01-15",
    "amount": 280800,
    "bankNumber": "12",
    "branchNumber": 456,
    "accountNumber": 123456
  }
}

Receipt with multiple payments

{
  "type": "receipt",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Professional Services",
      "quantity": 10,
      "itemNetPrice": 20000,
      "itemTotalPrice": 23400,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "totalAmount": 234000,
  "totalPaid": 234000,
  "originTaxDeduction": 0,
  "cash": {
    "date": "2024-01-15",
    "amount": 34000
  },
  "cc": {
    "date": "2024-01-15",
    "amount": 200000,
    "last4Digits": "5678"
  }
}

{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-01-30",
  "docLang": "en",
  "items": [
    {
      "name": "Online Course Subscription",
      "quantity": 1,
      "itemNetPrice": 79900,
      "itemTotalPrice": 93483,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 79900,
  "totalWithoutVatAmount": 79900,
  "vatAmount": 13583,
  "totalAmount": 93483,
  "payment": {
    "isEnabled": true,
    "clientEmail": "buyer@example.com"
  }
}

Receipt with cheque

{
  "type": "receipt",
  "client": {
    "name": "Example Buyer",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Equipment Purchase",
      "quantity": 1,
      "itemNetPrice": 1500000,
      "itemTotalPrice": 1755000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "totalAmount": 1755000,
  "totalPaid": 1755000,
  "originTaxDeduction": 0,
  "cheque": {
    "date": "2024-02-15",
    "receivedDate": "2024-01-15",
    "amount": 1755000,
    "chequeNumber": 1234567,
    "bankNumber": "10",
    "branchNumber": 123,
    "accountNumber": 987654
  }
}

VAT-exempt items

{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Services (VAT exempt)",
      "quantity": 1,
      "itemNetPrice": 500000,
      "itemTotalPrice": 500000,
      "itemCurrency": "ILS",
      "isNoItemVat": true
    },
    {
      "name": "Training Materials",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 600000,
  "totalWithoutVatAmount": 600000,
  "vatAmount": 17000,
  "totalAmount": 617000
}

After the 202

The document is issued asynchronously. The 202 response gives its id and url at once; the result reaches each URL in callbacks. A callback delivery that fails is retried after 60 seconds, three attempts in all.

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

Field Type Required Description
type string yes Document type Allowed values: invoice, receipt, invrec, deal, refund, offer.
client object yes
client.name string yes Client/customer name, at most 255 characters.
client.email string no Client email address
client.phone string no Client phone number
client.socialId string no Client's social/business ID number (ת.ז. / ח.פ.). Exactly 9 digits. Required when the document total is 23,600 ILS or more.
currency string yes Document currency (currently only ILS supported)
docValueDate string yes Document value date
dueDate string no Payment due date (optional).
title string no Document title (optional), at most 255 characters.
docLang string yes Document language Allowed values: he, en.
items array yes Document line items
items[].name string yes Item name/description, at most 255 characters.
items[].quantity number yes Item quantity, at least 1.
items[].itemNetPrice number yes Item net price (before VAT)
items[].itemTotalPrice number no Item total price (calculated). Required for invoice, invrec, deal, refund and offer.
items[].itemSumNetTotalPrice number no Item sum net total price (quantity * itemNetPrice)
items[].itemCurrency string yes Item currency
items[].isNoItemVat boolean no VAT exempt flag (true = no VAT for this item). Required for invoice, invrec, deal, refund and offer.
bankDetails object no Bank account details for payment
bankDetails.bankName string no Bank name
bankDetails.branchNumber number no Branch number
bankDetails.accountNumber number no Account number
bankDetails.accountName string no Account holder name
bankDetails.IBAN string no IBAN number
subTotal number no Subtotal before discount. Required for invoice, invrec, deal, refund and offer.
discount number no Discount amount
totalWithoutVatAmount number no Total amount without VAT. Required for invoice, invrec, deal, refund and offer.
vatAmount number no VAT amount. Required for invoice, invrec, deal, refund and offer.
totalAmount number yes Total amount including VAT
totalPaid number no Total amount paid. Required for receipt and invrec, and must equal totalAmount.
originTaxDeduction number no Tax deduction at source (ניכוי מס במקור). Required for receipt and invrec; send 0 when there is none.
comment string no Document comments/notes, at most 255 characters.
cash object no Cash payment details
cash.date string yes Payment date
cash.amount number yes Payment amount
cc object no Credit card payment details
cc.date string yes Payment date
cc.amount number yes Payment amount
cc.last4Digits string no Last 4 digits of card
bank-transfer object no Bank transfer payment details
bank-transfer.date string yes Payment date
bank-transfer.amount number yes Payment amount
bank-transfer.bankNumber string no Bank code
bank-transfer.branchNumber integer no Branch number
bank-transfer.accountNumber integer yes Account number
cheque object no Cheque payment details
cheque.date string yes Cheque date
cheque.receivedDate string yes Date cheque was received
cheque.amount number yes Payment amount
cheque.chequeNumber number yes Cheque number
cheque.bankNumber string no Bank code
cheque.branchNumber integer no Branch number
cheque.accountNumber integer no Account number
e-wallet object no E-wallet payment details (PayPal, Bit, etc.)
e-wallet.date string yes Payment date
e-wallet.amount number yes Payment amount
e-wallet.appType string yes Wallet app name
e-wallet.nameOfPayingAccount string no
e-wallet.transactionRefNumber string no
e-wallet.additionalDetails string no At most 255 characters.
payment object no Payment link settings (for invoice/deal)
payment.isEnabled boolean yes Enable payment link
payment.clientEmail string no Email to send payment link to. One of the two is required when isEnabled is true.
payment.clientPhone string no Phone to send payment link to. One of the two is required when isEnabled is true.
callbacks object no Callback URLs for the asynchronous result. Each must be an http or https URL on a public host.
callbacks.success array no URLs called when the document is issued. Body: { "payload": <the document, as Get income document returns it> }.
callbacks.error array no URLs called when issuing fails. Body: { "document": { "id": "<id from the 202>" }, "error": <reason> }. A failed document is removed: a later Get income document with that id returns payload: null.

Request example

{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "phone": "0500000002",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 100000,
  "totalWithoutVatAmount": 100000,
  "vatAmount": 17000,
  "totalAmount": 117000,
  "comment": "Thank you for your business"
}

Code samples

curl

curl -X POST 'https://<partner_domain>.keep.co.il/seller/api/documents/income' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "phone": "0500000002",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 100000,
  "totalWithoutVatAmount": 100000,
  "vatAmount": 17000,
  "totalAmount": 117000,
  "comment": "Thank you for your business"
}'

Node.js

const response = await fetch("https://<partner_domain>.keep.co.il/seller/api/documents/income", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "type": "invoice",
    "client": {
      "name": "Example Buyer",
      "email": "buyer@example.com",
      "phone": "0500000002",
      "socialId": "123456782"
    },
    "currency": "ILS",
    "docValueDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "docLang": "he",
    "items": [
      {
        "name": "Consulting Service",
        "quantity": 1,
        "itemNetPrice": 100000,
        "itemTotalPrice": 117000,
        "itemCurrency": "ILS",
        "isNoItemVat": false
      }
    ],
    "subTotal": 100000,
    "totalWithoutVatAmount": 100000,
    "vatAmount": 17000,
    "totalAmount": 117000,
    "comment": "Thank you for your business"
  }),
});

console.log(await response.text());

Python

import requests

response = requests.post(
    "https://<partner_domain>.keep.co.il/seller/api/documents/income",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "type": "invoice",
        "client": {
            "name": "Example Buyer",
            "email": "buyer@example.com",
            "phone": "0500000002",
            "socialId": "123456782",
        },
        "currency": "ILS",
        "docValueDate": "2024-01-15",
        "dueDate": "2024-02-15",
        "docLang": "he",
        "items": [
            {
                "name": "Consulting Service",
                "quantity": 1,
                "itemNetPrice": 100000,
                "itemTotalPrice": 117000,
                "itemCurrency": "ILS",
                "isNoItemVat": False,
            },
        ],
        "subTotal": 100000,
        "totalWithoutVatAmount": 100000,
        "vatAmount": 17000,
        "totalAmount": 117000,
        "comment": "Thank you for your business",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "phone": "0500000002",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 100000,
  "totalWithoutVatAmount": 100000,
  "vatAmount": 17000,
  "totalAmount": 117000,
  "comment": "Thank you for your business"
}
BODY;

$ch = curl_init('https://<partner_domain>.keep.co.il/seller/api/documents/income');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Responses

202 — Document accepted (success)

Field Type Description
payload object
payload.id string Created document ID
payload.url string URL to download/view the document

400 — Bad Request (error)

Field Type Description
statusCode integer HTTP status code
message string Error message(s)
error string Error type 
{
  "statusCode": 400,
  "message": [
    "Validation failed"
  ],
  "error": "Bad Request"
}

401 — Unauthorized (error)

Field Type Description
statusCode integer HTTP status code
message string Error message(s)
error string Error type 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

403 — Forbidden. The seller cannot issue documents now: invoicing is not set up, the trial has ended, or the seller is closed. (error)

Field Type Description
statusCode integer HTTP status code
message string Error message(s)
error string Error type

422 — Unprocessable Entity. Messages include: the client socialId is required for documents of 23,600 ILS and above; Your invoice Israel token is invalid (with renewTokenUrl, where the seller renews the Israel Tax Authority connection); Record already exists. (error)

Field Type Description
statusCode integer HTTP status code
message string Error message(s)
error string Error type

429 — Too many requests. The body is plain text. (error)

Field Type Description
statusCode integer HTTP status code
message string Error message(s)
error string Error type