# List documents

Building with an AI agent? Start at https://docs.payme.io/agents.md

- Sandbox: `GET https://sandbox.payme.io/api/documents`
- Production: `GET https://live.payme.io/api/documents`

## Credentials

- Header `PayMe-Merchant-Key` (API key)
- Header `PayMe-Partner-Key` (optional): Partners only: your partner key. The seller must belong to you (error `20`).

> ⚠️ **This API is deprecated** and is no longer recommended for use. For questions, contact partners@payme.io. 

## Overview

Lists the seller's documents, a page at a time. Send the seller's MPL in the `PayMe-Merchant-Key` header. The seller's invoicing service must be active; otherwise every documents call returns error `703` (HTTP 403).

Environment | Example
---|---
`Sandbox` | `https://sandbox.payme.io/api/documents?limit=5&field=createdAt&sort=desc`
`Production` | `https://live.payme.io/api/documents?limit=5&field=createdAt&sort=desc`

Each item has the fields of [Get a document](/payments/invoices/show-generated-document-by-id), except `doc_url`. To open a document, call [Get a document](/payments/invoices/show-generated-document-by-id) with its `doc_id`. Other top-level fields, such as paging details, come from the invoicing service as they are.

### Errors

| HTTP | Code | When |
|---|---|---|
| `400` | `1` | A partner key was sent, but no seller. `status_additional_info` is `seller_payme_id`.  |
| `400` | `20` | The seller doesn't belong to this partner. `status_additional_info` is `Merchant-Seller inconsistency`.  |
| `403` | `703` | The invoicing service isn't active for this seller.  |
| `500` | `1` | No credential was sent at all. `status_additional_info` is `payme_client_key`.  |
| `500` | `251` | The seller key is unknown.  |
| `500` | `163` | The seller isn't active.  |
| `500` | `200` | The partner key is unknown.  |
| `500` | `201` | The partner isn't active.  |
| `500` | `1001` | The invoicing service returned an error. `status_additional_info` carries its code and details. |
| `503` | `1001` | The invoicing service didn't answer in time. |

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number. Omit it for the first page. |
| `limit` | query | integer | no | Documents per page. |
| `field` | query | string | no | Field to sort by, for example `createdAt`. |
| `sort` | query | string | no | Sort order: `asc` or `desc`. |
| `from` | query | string | no | Return documents from this date. |
| `to` | query | string | no | Return documents up to this date. |
| `PayMe-Merchant-Key` | header | string | yes | The seller's MPL. On a GET request this header is the only way to name the seller. |
| `PayMe-Partner-Key` | header | string | no | Partners only: your partner key. The seller must belong to you (error `20`). |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/documents' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  -H 'PayMe-Partner-Key: <PayMe-Partner-Key>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/documents", {
  method: "GET",
  headers: {
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    "PayMe-Partner-Key": "<PayMe-Partner-Key>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/documents",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
        "PayMe-Partner-Key": "<PayMe-Partner-Key>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/documents');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
        'PayMe-Partner-Key: <PayMe-Partner-Key>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — A page of documents. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `items` | array | The documents on this page. |
| `items[].doc_id` | string | The document's job ID. Use it with [Get a document](/payments/invoices/show-generated-document-by-id). |
| `items[].doc_num` | string | The document number, once the invoicing service has assigned one. |
| `items[].doc_status` | string | Status of the document job, when the invoicing service returns one. |
| `items[].doc_type` | integer | Document type. See [Document types](/payments/codes-statuses/document-types). |
| `items[].buyer_name` | string | Buyer name on the document. |
| `items[].buyer_address` | string | Buyer address on the document, if sent. |
| `items[].doc_date` | string | Document date. |
| `items[].due_date` | string | Payment due date, if sent. |
| `items[].pay_date` | string | Payment date, if sent. |
| `items[].currency` | string | ISO 4217 currency code of the document. |
| `items[].language` | string | Document language. |
| `items[].doc_title` | string | Title printed at the top of the document. |
| `items[].doc_comments` | string | Comments printed on the document. |
| `items[].exchange_rate` | number | Exchange rate used on the document. |
| `items[].vat_rate` | number | VAT rate applied to the document. |
| `items[].discount` | number | Discount applied to the document. |
| `items[].total_excluding_vat` | number | Total before VAT. |
| `items[].total_sum_after_discount` | number | Total after the discount. |
| `items[].total_sum_including_vat` | number | Total including VAT. |
| `items[].total_vat` | number | Total VAT. |
| `items[].total_paid` | number | Total paid on this document. |
| `items[].total_paid_including_vat` | number | Total paid, including VAT. |
| `items[].items` | array | Document lines. |
| `items[].items[].description` | string | Line description. |
| `items[].items[].quantity` | integer | Quantity. |
| `items[].items[].unit_price` | number | Unit price before VAT. |
| `items[].items[].unit_price_with_vat` | number | Unit price including VAT. |
| `items[].items[].vat_exempt` | boolean | `true` if the line is exempt from VAT. |
| `items[].items[].currency` | string | ISO 4217 currency code of the line. |
| `items[].items[].exchange_rate` | number | Exchange rate of the line's currency. |
| `items[].cash` | object | Cash payment recorded on the document. |
| `items[].cash.sum` | number | Amount paid in cash. |
| `items[].cheques` | array | Cheques recorded on the document. |
| `items[].cheques[].sum` | number | Cheque amount. |
| `items[].cheques[].date` | string | Cheque date. |
| `items[].cheques[].bank` | number | Bank code. |
| `items[].cheques[].branch` | number | Branch number. |
| `items[].cheques[].account` | string | Account number. |
| `items[].cheques[].number` | string | Cheque number. |
| `items[].bank_transfer` | object | Bank transfer recorded on the document. |
| `items[].bank_transfer.sum` | number | Amount transferred. |
| `items[].bank_transfer.date` | string | Transfer date. |
| `items[].bank_transfer.account` | string | Account number. |
| `items[].paypal` | object | PayPal payment recorded on the document. |
| `items[].paypal.sum` | number | Amount paid with PayPal. |
| `items[].paypal.date` | string | Payment date. |
| `items[].paypal.transaction_id` | string | PayPal transaction ID. |
| `items[].paypal.buyer_name` | string | Payer name. |
| `items[].credit_card` | object | Card payment recorded on the document. It holds no card number or CVV. |
| `items[].credit_card.sum` | number | Amount paid by card. |
| `items[].credit_card.installments` | integer | Number of installments. |
| `items[].credit_card.first_payment` | number | Amount of the first installment. |
| `items[].credit_card.type` | string | Card brand. |
| `items[].credit_card.expiry` | string | Card expiry, `MMYY`. |
| `items[].credit_card.buyer_name` | string | Card holder's name. |
| `items[].credit_card.buyer_social_id` | string | Card holder's national ID. |
| `items[].credit_card.auth_number` | string | Authorization number of the card payment. |

```json
{
  "status_code": 0,
  "items": [
    {
      "doc_id": "fa397fce-aee6-4c6d-ae9c-273ae1e3a317",
      "doc_type": 400,
      "buyer_name": "Israel Israeli",
      "doc_date": "2026-11-09",
      "currency": "ILS",
      "language": "he",
      "doc_title": "Receipt for order 1001",
      "total_paid": 140,
      "items": [
        {
          "description": "Monthly plan",
          "quantity": 1,
          "unit_price": 140,
          "vat_exempt": false,
          "currency": "ILS"
        }
      ],
      "cash": {
        "sum": 40
      },
      "credit_card": {
        "sum": 100,
        "installments": 1,
        "type": "Visa",
        "expiry": "1230",
        "buyer_name": "Israel Israeli",
        "auth_number": "0123456"
      },
      "doc_num": "10023",
      "doc_status": "completed"
    }
  ]
}
```

### 400 — Bad request. See the error table. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}
```

### 403 — The invoicing service isn't active for this seller (`703`). (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Action is not permitted",
  "status_additional_info": "Invoicing Service was not properly activated. Operation not permitted",
  "status_error_code": 703,
  "session": "FhT3aXe7"
}
```

### 500 — Credentials or the invoicing service failed. See the error table. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "payme_client_key",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}
```