--- updatedAt: 2026-06-30T16:05:21.000Z agentTools: projectIndex: https://docs.pelcro.com/llms.txt --- # List bills Retrieve a paginated list of bills. ## Overview Retrieve a paginated list of bills. Supports filtering by status and vendor, and sorting by date fields. **Example:** List all open bills for a specific vendor to prepare a payment batch. | Feature | Fields | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | [Filterable](https://docs.pelcro.com/reference/api-core-filtering-and-sorting) | `id`, `user_id`, `status`, `number`, `created_at`, `updated_at`, `period_start`, `period_end`, `finalized_at`, `paid_at`, `total` | | [Sortable](https://docs.pelcro.com/reference/api-core-filtering-and-sorting) | `id`, `status`, `created_at`, `updated_at`, `finalized_at`, `paid_at` | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "core-api", "version": "1.88" }, "servers": [ { "url": "https://www.pelcro.com/api/v1/core" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "Authorization", "x-bearer-format": "bearer" }, "sec1": { "type": "apiKey", "in": "query", "name": "site_id" } } }, "security": [ { "sec0": [], "sec1": [] } ], "paths": { "/bills": { "get": { "summary": "List bills", "description": "Retrieve a paginated list of bills.", "operationId": "get_invoices-1", "parameters": [ { "name": "site_id", "in": "query", "description": "The unique identifier of the site associated with your account.", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "The maximum number of objects you want returned per result set. For instance, if you set limit=10, the API will return a maximum of 10 objects in the response. (max: 100)", "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "page", "in": "query", "description": "The specific page of the result set you want to retrieve, typically used in conjunction with limit. For example, if you set page=2 and limit=10, the API will return the second page of results, containing a maximum of 10 objects starting from the 11th object.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string", "default": "Bearer eyJ***" } }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with - for descending.", "schema": { "type": "string", "enum": [ "id", "-id", "status", "-status", "created_at", "-created_at", "updated_at", "-updated_at", "finalized_at", "-finalized_at", "paid_at", "-paid_at" ] } }, { "name": "vendor_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by vendor ID." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "open", "paid" ] }, "description": "Filter by bill status." }, { "name": "filter[id]", "in": "query", "schema": { "type": "string" }, "description": "Filter by bill ID. Example: eq:42" }, { "name": "filter[user_id]", "in": "query", "schema": { "type": "string" }, "description": "Filter by vendor user ID. Example: eq:1001" }, { "name": "filter[status]", "in": "query", "schema": { "type": "string", "enum": [ "eq:draft", "eq:open", "eq:paid" ] }, "description": "Filter by bill status." }, { "name": "filter[number]", "in": "query", "schema": { "type": "string" }, "description": "Filter by bill number. Example: like:BILL-001" }, { "name": "filter[total][from]", "in": "query", "schema": { "type": "number" }, "description": "Minimum total amount." }, { "name": "filter[total][to]", "in": "query", "schema": { "type": "number" }, "description": "Maximum total amount." }, { "name": "filter[created_at][from]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Created on or after this date (YYYY-MM-DD)." }, { "name": "filter[created_at][to]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Created on or before this date (YYYY-MM-DD)." }, { "name": "filter[updated_at][from]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Updated on or after this date (YYYY-MM-DD)." }, { "name": "filter[updated_at][to]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Updated on or before this date (YYYY-MM-DD)." }, { "name": "filter[period_start][from]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Period start on or after this date (YYYY-MM-DD)." }, { "name": "filter[period_start][to]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Period start on or before this date (YYYY-MM-DD)." }, { "name": "filter[period_end][from]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Period end on or after this date (YYYY-MM-DD)." }, { "name": "filter[period_end][to]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Period end on or before this date (YYYY-MM-DD)." }, { "name": "filter[finalized_at][from]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Finalized on or after this date (YYYY-MM-DD)." }, { "name": "filter[finalized_at][to]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Finalized on or before this date (YYYY-MM-DD)." }, { "name": "filter[paid_at][from]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Paid on or after this date (YYYY-MM-DD)." }, { "name": "filter[paid_at][to]", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Paid on or before this date (YYYY-MM-DD)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "bill_number": { "type": "string", "description": "Bill number (alias for number)." }, "number": { "type": "string", "description": "Bill number." }, "status": { "type": "string", "description": "Bill status: Draft, Open, or Paid." }, "user_id": { "type": "integer", "description": "Vendor (user) ID." }, "user": { "type": "object", "description": "Vendor user details.", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" } } }, "amount_due": { "type": "integer", "description": "Amount due." }, "amount_paid": { "type": "integer", "description": "Amount paid." }, "amount_remaining": { "type": "integer", "description": "Amount remaining." }, "currency": { "type": "string", "description": "Three-letter ISO currency code." }, "paid": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "subtotal": { "type": "integer", "description": "Subtotal before tax." }, "total": { "type": "integer", "description": "Total amount." }, "footer": { "type": "string", "nullable": true }, "purchase_order": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "period_start": { "type": "string", "format": "date", "nullable": true }, "period_end": { "type": "string", "format": "date", "nullable": true }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" } } } }, "finalized_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp." }, "paid_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix timestamp." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix timestamp." }, "updated_at": { "type": "integer", "format": "int64", "description": "Unix timestamp." } } } }, "links": { "type": "object" }, "meta": { "type": "object" } } }, "examples": { "Result": { "value": { "data": [ { "id": 42, "bill_number": "BILL-00042", "number": "BILL-00042", "status": "Draft", "user_id": 1001, "user": { "id": 1001, "first_name": "Acme", "last_name": "Corp", "email": "billing@acme.com" }, "amount_due": 15000, "amount_paid": 0, "amount_remaining": 15000, "currency": "usd", "paid": false, "metadata": {}, "subtotal": 15000, "total": 15000, "footer": null, "purchase_order": null, "description": null, "period_start": "2026-04-01", "period_end": "2026-04-30", "line_items": [ { "id": 1, "description": "Consulting services", "quantity": 10, "unit_price": 100, "total": 1000, "currency": "usd" }, { "id": 2, "description": "Software license", "quantity": 1, "unit_price": 5000, "total": 5000, "currency": "usd" } ], "finalized_at": null, "paid_at": null, "created_at": 1712188800, "updated_at": 1712188800 } ], "links": { "first": "https://www.pelcro.com/api/v1/core/bills?page=1", "last": "https://www.pelcro.com/api/v1/core/bills?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "per_page": 10, "to": 1, "total": 1 } } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "examples": { "Result": { "value": { "error": { "status": 400, "message": "Invalid request, please try again." } } } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "default": 0 }, "message": { "type": "string", "example": "Invalid request, please try again." } } } } } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "examples": { "Result": { "value": { "error": "Unauthenticated." } } } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "php", "code": "use GuzzleHttp\\Client;\n\n$site_id = 0; // (int) your site id here\n$page = 1; // (int) the page number here\n \n$api_key = '' // (string) your api key here\n$uri = \"bills\";\n\n$config = [\n 'base_uri' => 'https://www.pelcro.com/api/v1/core/'\n];\n\n$client = new Client($config);\n\n$options = [\n\t'json' => [\n\t\t'site_id' => $site_id,\n\t\t'page' => $page,\n\t],\n\t'headers' => [\n\t\t'Accept' => 'application/json',\n\t\t'Authorization' => 'Bearer ' . $api_key\n\t]\n];\n\n$response = $client->request('GET', $uri, $options);" } ], "samples-languages": [ "php" ] } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ``` # Sibling pages * [Create bill](https://docs.pelcro.com/reference/create-bills.md) * [Get bill](https://docs.pelcro.com/reference/get-bill.md) * [Update bill](https://docs.pelcro.com/reference/update-bill.md) * [Delete bill](https://docs.pelcro.com/reference/api-core-delete-bill.md) * [Finalize bill](https://docs.pelcro.com/reference/api-core-finalize-bill.md) * [Mark bill as paid](https://docs.pelcro.com/reference/api-core-mark-bill-as-paid.md) * [Export bills](https://docs.pelcro.com/reference/api-core-export-bills.md)