> ## Documentation Index > Fetch the complete documentation index at: https://docs.smartcp.org/llms.txt > Use this file to discover all available pages before exploring further. # List > Returns a paginated invoice list with optional filtering and sorting. ## OpenAPI ````yaml https://logistics.api.smartcp.org/openapi/invoices.openapi.json GET /invoices openapi: 3.0.3 info: title: SmartCP Logistics Invoices API version: 1.0.0 description: >- Invoice listing and PDF download endpoints for the SmartCP Logistics public REST API. servers: - url: https://logistics.api.smartcp.org/v1 description: Production security: - bearerAuth: [] directoryHeader: [] paths: /invoices: get: summary: List description: Returns a paginated invoice list with optional filtering and sorting. operationId: listInvoices parameters: - name: page in: query description: 'Page number. Default: `1`.' schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: 'Number of results per page. Default: `250`, maximum: `500`.' schema: type: integer minimum: 1 maximum: 500 default: 250 - name: period in: query description: Predefined date range filter. schema: type: string enum: - cur_month - prev_month - last_30_days - last_60_days - last_90_days - custom - name: period_by in: query description: Invoice date field used together with `period`. schema: type: string enum: - added_date - issue_date - service_date - payment_term - payment_date - name: from in: query description: Start date for `period=custom` in `YYYY-MM-DD` format. schema: type: string format: date - name: to in: query description: End date for `period=custom` in `YYYY-MM-DD` format. schema: type: string format: date - name: type in: query description: >- Comma-separated invoice types. Available options: `s` - sales invoices, `c` - correcting invoices, `p` - purchase invoices. schema: type: string example: s,c - name: status in: query description: >- Comma-separated invoice statuses. Available options: `issued`, `paid`, `semipaid`, `overdue`. schema: type: string example: issued,overdue - name: branch in: query description: Comma-separated branch IDs. schema: type: string example: 1,2 - name: customer in: query description: Comma-separated customer VAT numbers. schema: type: string example: PL1234567890,DE123456789 - name: customer_name in: query description: Partial customer name. schema: type: string - name: customer_country in: query description: Customer country code. schema: type: string example: pl - name: nr in: query description: >- Search by invoice number, related order number, or invoice item text. schema: type: string - name: sort_by in: query description: 'Sort field. Default: `issue_date`.' schema: type: string enum: - issue_date - service_date - payment_term - payment_date - nr - amount_gross - amount_net - amount_tax - customer_name - added_time default: issue_date - name: sort_dir in: query description: 'Sort direction. Default: `desc`.' schema: type: string enum: - asc - desc default: desc responses: '200': description: Invoice list returned content: application/json: schema: allOf: - $ref: '#/components/schemas/BaseSuccessResponse' - type: object properties: data: $ref: '#/components/schemas/InvoiceListResponseData' example: status: 200 message: OK data: invoices: - id: 1045 nr: FV/2026/05/1045 type: s status: issued branch_id: 1 issue_date: 1778457600 service_date: 1778457600 payment_term: 1779062400 payment_date: null customer_name: ACME Logistics customer_vat: PL1234567890 customer_country: pl currency: EUR amount_net: 1000 amount_tax: 230 amount_gross: 1230 paid: 0 left_to_pay: 1230 orders: - type: t nr: Tour 4036230 cmr: CMR-2026-105 tasks: [] files: [] contacts: [] correct_of: null added_time: 1778486400 pagination: page: 1 per_page: 250 total: 1 total_pages: 1 '401': $ref: '#/components/responses/UnauthorizedResponse' '422': $ref: '#/components/responses/ValidationErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsResponse' components: schemas: BaseSuccessResponse: type: object required: - status - message - data properties: status: type: integer example: 200 message: type: string example: OK data: nullable: true InvoiceListResponseData: type: object required: - invoices - pagination properties: invoices: type: array items: $ref: '#/components/schemas/InvoiceListItem' pagination: $ref: '#/components/schemas/Pagination' InvoiceListItem: type: object required: - id - nr - type - status - currency - amount_net - amount_tax - amount_gross - paid - left_to_pay - orders properties: id: type: integer example: 1045 nr: type: string example: FV/2026/05/1045 type: type: string description: >- Invoice type code. Common values: `s` - sales invoice, `c` - correcting invoice, `p` - purchase invoice. example: s status: type: string enum: - issued - paid - semipaid - overdue example: issued branch_id: type: integer nullable: true example: 1 issue_date: type: integer nullable: true description: Unix timestamp. example: 1778457600 service_date: type: integer nullable: true description: Unix timestamp. example: 1778457600 payment_term: type: integer nullable: true description: Unix timestamp. example: 1779062400 payment_date: type: integer nullable: true description: Unix timestamp. example: null customer_name: type: string nullable: true example: ACME Logistics customer_vat: type: string nullable: true example: PL1234567890 customer_country: type: string nullable: true example: pl currency: type: string example: EUR amount_net: type: number format: float example: 1000 amount_tax: type: number format: float example: 230 amount_gross: type: number format: float example: 1230 paid: type: number format: float example: 0 left_to_pay: type: number format: float example: 1230 orders: type: array items: $ref: '#/components/schemas/InvoiceOrder' correct_of: type: integer nullable: true example: null added_time: type: integer nullable: true description: Unix timestamp. example: 1778486400 Pagination: type: object required: - page - per_page - total - total_pages properties: page: type: integer example: 1 per_page: type: integer example: 250 total: type: integer example: 1240 total_pages: type: integer example: 5 StringErrorResponse: type: object required: - status - message - data properties: status: type: integer example: 401 message: type: string example: Authentication failed data: nullable: true example: null InvoiceOrder: type: object required: - type - nr - tasks - files - contacts properties: type: type: string enum: - t - f description: '`t` for transport orders, `f` for forwarding orders.' example: t nr: type: string nullable: true example: Tour 4036230 cmr: type: integer nullable: true description: >- Transport order CMR flag. `1` means a CMR is available, `0` means it is not available. example: 1 tasks: type: array items: $ref: '#/components/schemas/OrderTaskSummary' files: type: array items: $ref: '#/components/schemas/OrderFileSummary' contacts: type: array items: $ref: '#/components/schemas/OrderContactSummary' OrderTaskSummary: type: object required: - type - location - country - date - time_from - time_to properties: type: type: string nullable: true example: load location: type: string nullable: true example: Warsaw country: type: string nullable: true example: pl date: type: integer nullable: true description: Unix timestamp. example: 1778457600 time_from: type: string nullable: true example: '08:00' time_to: type: string nullable: true example: '10:00' OrderFileSummary: type: object required: - name - extension - link - category properties: name: type: string nullable: true example: CMR.pdf extension: type: string nullable: true example: pdf link: type: string nullable: true example: https://s1.smartcp.org/uploads/orders/CMR.pdf category: type: string nullable: true example: POD OrderContactSummary: type: object required: - name - email - phone properties: name: type: string nullable: true example: John Doe email: type: string nullable: true example: john.doe@example.com phone: type: string nullable: true example: +48 600 700 800 responses: UnauthorizedResponse: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/StringErrorResponse' example: status: 401 message: Authentication failed data: null ValidationErrorResponse: description: Validation failed content: application/json: schema: $ref: '#/components/schemas/StringErrorResponse' example: status: 422 message: The given data was invalid. data: null TooManyRequestsResponse: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/StringErrorResponse' example: status: 429 message: Too Many Attempts. data: null securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: Client API key sent as a bearer token. directoryHeader: type: apiKey in: header name: X-Client-Directory description: >- Client directory identifier. Legacy `directory` header is still accepted for backward compatibility. ````