> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vendor Advances API

> Retrieve advances for a specific vendor by its identifier

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

## Request

**Content-Type:** `application/json`

### Path Parameters

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `id`      | string | Yes      | The unique identifier of the Vendor to retrieve |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.pazy.io/v1.0/vendor/vendor_identifier/advances \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch(
    "https://api.pazy.io/v1.0/vendor/vendor_identifier/advances",
    {
      method: "GET",
      headers: {
        Authorization: "Api-Key YOUR_API_KEY",
      },
    },
  );

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/vendor/vendor_identifier/advances"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                                      | Type    | Description                                                     |
| ------------------------------------------ | ------- | --------------------------------------------------------------- |
| `ok`                                       | boolean | Indicates whether the request was successful                    |
| `data`                                     | object  | Contains the vendor advances response data                      |
| `data.advances`                            | array   | List of advances entries associated with the vendor             |
| `data.advances[].id`                       | string  | Unique identifier for the advance                               |
| `data.advances[].dateCreated`              | string  | ISO 8601 timestamp of when the advance was created              |
| `data.advances[].paymentReason`            | string  | Reason for the payment e.g. `ADVANCE`, `PURCHASE_ORDER_ADVANCE` |
| `data.advances[].matchingState`            | string  | Matching status of the advance e.g. `MATCHED`, `UNMATCHED`      |
| `data.advances[].currency`                 | string  | Currency code for the advance e.g. `INR`                        |
| `data.advances[].paymentRequest`           | object  | Associated payment request                                      |
| `data.advances[].tax`                      | object  | Tax details associated with the advance                         |
| `data.advances[].amount`                   | object  | Breakdown of advance amounts                                    |
| `data.advances[].amount.totalAmount`       | number  | Total amount of the advance                                     |
| `data.advances[].amount.amountSettled`     | number  | Amount that has been settled                                    |
| `data.advances[].amount.pendingAmount`     | number  | Amount still pending settlement                                 |
| `data.advances[].syncStatus`               | string  | Sync status with external systems e.g. `NOT_SYNCED`, `SYNCED`   |
| `data.advances[].invoices`                 | array   | List of invoices linked to this advance                         |
| `data.advances[].invoices[].id`            | string  | Unique identifier for the invoice                               |
| `data.advances[].invoices[].invoiceNo`     | string  | Human-readable invoice number                                   |
| `data.advances[].invoices[].amountSettled` | number  | Amount settled against this invoice                             |
| `data.advances[].invoices[].currency`      | string  | Currency code for the invoice                                   |
| `data.advances[].user`                     | object  | Information about the user associated with the advance          |
| `data.advances[].user.id`                  | string  | Unique identifier for the user                                  |
| `data.advances[].user.name`                | string  | Name of the user                                                |
| `data.context`                             | object  | Additional context for the advances                             |
| `data.context.count`                       | number  | The total number of advances                                    |

### Response Example

```json theme={null}
{
    "ok": true,
    "data": {
        "advances": [
            {
                "id": "<advanceId>",
                "dateCreated": "2025-05-21T08:22:42.483Z",
                "paymentReason": "PURCHASE_ORDER_ADVANCE",
                "matchingState": "UNMATCHED",
                "currency": "INR",
                "paymentRequest": {
                    "slug": "<paymentRequestId>",
                    "sequenceNo": "615"
                },
                "tax": {
                    "TDS": {
                        "amount": "0"
                    }
                },
                "amount": {
                    "totalAmount": 123,
                    "amountSettled": 0,
                    "pendingAmount": 123
                },
                "syncStatus": "NOT_SYNCED",
                "invoices": [],
                "user": {
                    "id": "<userId>",
                    "name": "John Doe"
                }
            },
            {
                "id": "<advanceId>",
                "dateCreated": "2025-05-16T04:31:06.683Z",
                "paymentReason": "ADVANCE",
                "matchingState": "PARTIALLY_MATCHED",
                "currency": "INR",
                "paymentRequest": null,
                "tax": {
                    "TDS": {
                        "amount": "800"
                    }
                },
                "amount": {
                    "totalAmount": 19200,
                    "amountSettled": 37.2,
                    "pendingAmount": 19162.8
                },
                "syncStatus": "NOT_SYNCED",
                "invoices": [
                    {
                        "id": "<invoiceId>",
                        "invoiceNo": "004",
                        "amountSettled": 37.2,
                        "currency": "INR"
                    }
                ],
                "user": {
                    "id": "<userId>",
                    "name": "John Doe"
                }
            }
        ],
        "context": {
            "count": 2,
            "isVendorAdvancesEnabled": true,
            "accountingName": "TALLY",
            "baseCurrency": "INR"
        }
    }
}
```

## Error Responses

### Missing Vendor ID

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Vendor ID is required"
  }
}
```

### Vendor Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VENDOR_NOT_FOUND",
    "message": "Vendor not found"
  }
}
```

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: You can only view your own vendors or vendors where you are the vendor owner"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

## Best Practices

### Access Control

* Only vendors you created or where you are the vendor owner are accessible (unless you have admin or auditor role)
* Use the vendor `id` returned from the vendor creation endpoint to retrieve advances