List expenses

Credentials

Retrieve expense records for a seller with optional date filtering and pagination.

Seller identification: Same rules as the upload endpoint — provide sellerId alone, or socialId + email.

Date filtering: valueDateStart and valueDateEnd filter on the expense value date (not creation date). Dates must be ISO format (YYYY-MM-DD) and valueDateStart must be ≤ valueDateEnd.

Pagination: Defaults to page=0, limit=10. Maximum limit=500.

Order of returned items is not guaranteed.

Parameters

Name In Type Required Description
sellerId query string no Seller UUID (use this OR socialId + email)
socialId query integer no Seller ID number, digits only, sent as a number (must be paired with email).
email query string no Seller email address (must be paired with socialId)
valueDateStart query string no Filter expenses from this value date (inclusive, YYYY-MM-DD)
valueDateEnd query string no Filter expenses up to this value date (inclusive, YYYY-MM-DD)
page query integer no Page number (zero-based). Minimum 0, default 0.
limit query integer no Items per page. Positive number, at most 500; use a whole-number item count. Default 10.

Code samples

curl

curl -X GET 'https://<partner_domain>.keep.co.il/api/public/expenses' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'

Node.js

const response = await fetch("https://<partner_domain>.keep.co.il/api/public/expenses", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

Python

import requests

response = requests.get(
    "https://<partner_domain>.keep.co.il/api/public/expenses",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)

PHP

<?php

$ch = curl_init('https://<partner_domain>.keep.co.il/api/public/expenses');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;

Responses

200 — Expenses retrieved successfully (success)

Field Type Description
payload object
payload.total integer Total number of matching expenses
payload.page integer Current page number
payload.limit integer Items per page
payload.items array
payload.items[].id string Expense record UUID
payload.items[].capturedDate string Timestamp when the expense was captured
payload.items[].valueDate string Expense value date
payload.items[].sellerId string Seller UUID
payload.items[].totalAmount number Total expense amount
payload.items[].vatAmount number VAT amount
payload.items[].currency string Currency code
payload.items[].bookkeeperRevisionStatus string Bookkeeper revision status
payload.items[].docRegulationId string Document regulation ID
payload.items[].docType string Document type
{
  "payload": {
    "total": 1,
    "page": 0,
    "limit": 10,
    "items": [
      {
        "id": "50c6b740-874a-4f54-9669-9a60024be4ed",
        "capturedDate": "2024-06-20T09:35:36.326Z",
        "valueDate": "2024-06-20T00:00:00.000Z",
        "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
        "totalAmount": 15200,
        "vatAmount": 2209,
        "currency": "ILS",
        "bookkeeperRevisionStatus": "approved-and-classified",
        "docRegulationId": "1262",
        "docType": "invrec"
      }
    ]
  }
}

400 — Bad Request (error)

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

401 — Unauthorized (error)

Field Type Description
statusCode integer
message string
{
  "statusCode": 401,
  "message": "Unauthorized"
}

403 — The seller does not belong to your partner account. Message: Forbidden. Also returned, with the message Forbidden resource, when the access token has no scope this endpoint accepts. (error)

Field Type Description
statusCode integer HTTP status code
message string Error message
error string Error type: Forbidden. Present only with the message Forbidden resource.
{
  "statusCode": 403,
  "message": "Forbidden"
}

422 — Unprocessable Entity. Message: Could not resolve seller — the identifiers match no seller. (error)

Field Type Description
statusCode integer HTTP status code
message string Error message(s)
error string Error type
{
  "statusCode": 422,
  "message": "Bad seller configuration. Please contact support!",
  "error": "Unprocessable Entity"
}