> ## Documentation Index > Fetch the complete documentation index at: https://docs.alvys.com/llms.txt > Use this file to discover all available pages before exploring further. # Search carrier settlement statements > Search finalized carrier settlement statements in Alvys with paginated POST filters by date range, carrier, statement number, and amount. The Search Carrier Settlement Statements endpoint returns a paged list of finalized carrier settlement statements (the "Statements" tab), each with its per-trip breakdown, line items, payments, and totals. It mirrors the in-app carrier "Statements List and Items" report and is intended for external reporting. Only settled statements are returned - deleted and failed statements are excluded. Each statement identifies its payee (the carrier directly, or a factoring company when the carrier is factored). For carriers, `Failed` and `Deleted` are lifecycle statuses, so those statements are excluded from the export. This differs from driver settlement statements, where a `Failed` status reflects a downstream step failure on an otherwise-finalized statement, which is returned. This endpoint requires the `carrier:read` scope. ### Request Parameters The following parameter is required in the URL path: | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------- | | version | String | Yes | The version of the API being requested. | ### Request Body | Parameter | Type | Required | Description | | ------------------------ | ------------------ | -------- | ----------------------------------------------------------------------------------------------------- | | Page | Number | Yes | The page number for pagination (starts from 0). | | PageSize | Number | Yes | The number of results per page. Must be greater than 0 and cannot exceed 100. | | StatementDateRange | Object | Yes | The inclusive statement-date window to filter on. Both bounds are treated as whole UTC calendar days. | | StatementDateRange.Start | String (Date-Time) | Yes | Start of the range (inclusive). | | StatementDateRange.End | String (Date-Time) | Yes | End of the range (inclusive). Required - an open-ended range is rejected. | | CarrierId | String (UUID) | No | Filter to a single carrier. | | SubsidiaryId | String (UUID) | No | Filter to a single subsidiary. | ### Example CURL Request Use the current API version number and replace the Authorization header value with your actual Bearer token: ```bash theme={null} curl --location 'https://integrations.alvys.com/api/p/v1/carrier-settlement-statements/search' \ --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ....' \ --header 'Content-Type: application/json' \ --data-raw '{ "Page": 0, "PageSize": 50, "StatementDateRange": { "Start": "2026-06-01T00:00:00Z", "End": "2026-06-30T00:00:00Z" }, "CarrierId": "6c7f5ee3-f44c-4c19-92bf-89cfbd5d87a0" }' ``` ### Response Parameters The response is a paged envelope. Each item is a finalized statement. Monetary values are objects of the form `{ "Amount": , "Currency": }`. | Parameter | Type | Description | | ----------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- | | Page | Number | The current page number. | | PageSize | Number | The number of items per page. | | Total | Number | The total number of matching statements across all pages. | | Items | Array of Objects | The statements on this page. | | Items\[].Number | Number | The statement number. | | Items\[].Status | String | The statement status (e.g. `Processed`, `Paid`). | | Items\[].StatementDate | String (Date-Time) | The statement date. | | Items\[].RemittanceDate | String (Date-Time) | The scheduled remittance date. Null if not set. | | Items\[].SubsidiaryId | String | The subsidiary the statement belongs to. | | Items\[].Payee | Object | Who gets paid: `Type` (`Carrier` or `FactoringCompany`), `Id`, `Name`, `McNumber`, `DotNumber`. | | Items\[].RemitTo | String | The resolved remit-to name. Null if not set. | | Items\[].PaymentProvider | String | The payment provider (e.g. `Standard`, `TriumphPay`). | | Items\[].NetAmount | Money | The statement net (payable) amount. | | Items\[].PaidAmount | Money | The amount paid so far. | | Items\[].RemainingAmount | Money | The amount still outstanding. | | Items\[].Trips | Array of Objects | Per-trip breakdown. | | Items\[].Trips\[].TripId | String | The stable unique trip identifier (always present). | | Items\[].Trips\[].TripNumber | String | The trip number. | | Items\[].Trips\[].LoadNumber | String | The load number. | | Items\[].Trips\[].Origin / Destination | String | Trip origin and destination. Null if not set. | | Items\[].Trips\[].PickedUpAt / DeliveredAt | String (Date-Time) | Pickup and delivery timestamps. Null if not set. | | Items\[].Trips\[].InvoiceNumber / InvoiceDueDate | String | Carrier invoice number and due date. Null if not set. | | Items\[].Trips\[].NetAmount / LineHaulAmount / AccessorialsAmount | Money | Trip-level totals. | | Items\[].Trips\[].Items | Array of Objects | Trip line items: `Description`, `Type`, `Amount`, `AccountingTag`. | | Items\[].Payments | Array of Objects | Recorded payments: `Id`, `Amount`, `PaymentDate`, `PaymentMethod`, `ReferenceNumber`, `CheckNumber`. | ### Example Response ```json theme={null} { "Page": 0, "PageSize": 50, "Total": 1, "Items": [ { "Number": 1042, "Status": "Processed", "StatementDate": "2026-06-15T12:00:00+00:00", "RemittanceDate": "2026-06-20T00:00:00+00:00", "SubsidiaryId": "a1b2c3d4-0000-0000-0000-000000000001", "Payee": { "Type": "Carrier", "Id": "6c7f5ee3-f44c-4c19-92bf-89cfbd5d87a0", "Name": "Acme Carrier", "McNumber": "MC123456", "DotNumber": "4204692" }, "RemitTo": "Acme Carrier LLC", "PaymentProvider": "Standard", "NetAmount": { "Amount": 1150.00, "Currency": 840 }, "PaidAmount": { "Amount": 0.00, "Currency": 840 }, "RemainingAmount": { "Amount": 1150.00, "Currency": 840 }, "Trips": [ { "TripId": "b2c3d4e5-1111-2222-3333-444455556666", "TripNumber": "TRIP-1", "LoadNumber": "L-55021", "Origin": "Chicago, IL", "Destination": "Atlanta, GA", "PickedUpAt": "2026-06-12T09:00:00+00:00", "DeliveredAt": "2026-06-14T16:00:00+00:00", "InvoiceNumber": "INV-1042", "InvoiceDueDate": "2026-07-14T00:00:00+00:00", "NetAmount": { "Amount": 1150.00, "Currency": 840 }, "LineHaulAmount": { "Amount": 1000.00, "Currency": 840 }, "AccessorialsAmount": { "Amount": 150.00, "Currency": 840 }, "Items": [ { "Description": "Line Haul", "Type": "LineHaul", "Amount": { "Amount": 1000.00, "Currency": 840 }, "AccountingTag": "Carrier Rate" }, { "Description": "Detention", "Type": "Accessorial", "Amount": { "Amount": 150.00, "Currency": 840 }, "AccountingTag": "Detention" } ] } ], "Payments": [] } ] } ```
### Rate Limits All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the Rate Limits section. This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. ## OpenAPI ````yaml POST /api/p/v{version}/carrier-settlement-statements/search openapi: 3.0.1 info: title: Alvys description: >- Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests. contact: name: Alvys Support url: https://www.alvys.com/resources/contact/ version: v1 servers: - url: https://integrations.alvys.com description: Public API Server - url: https://api.alvys.com/ description: Public API Server security: - Public: [] tags: - name: Authentication description: Obtain an OAuth 2.0 access token for the Alvys Public API. - name: Carrier Settlement Statements description: >- Search carrier settlement statements and retrieve a single statement by number. - name: Carriers description: Read carrier records, search carriers, and manage carrier documents. - name: Customers description: Create, read, update, delete, and search customer records. - name: Deductions description: >- Create one-time deductions and search or delete existing deduction records. - name: DispatchPreferences description: Dispatch preferences endpoints for reading dispatch rules and preferences. - name: Driver Settlement Statements description: >- Search driver settlement statements and retrieve a single statement by number. - name: Drivers description: >- Read driver records, search drivers and driver events, and manage driver documents. - name: Fuel description: Read and search fuel transactions. - name: Invoices description: >- Read invoices, create carrier invoices, and record carrier and customer payments. - name: Loads description: Read, update, search loads, and manage load documents and notes. - name: Locations description: Read and search company location details. - name: Maintenance description: Read and search maintenance records. - name: Tenders description: Create, accept, reject, cancel, update, and search inbound EDI tenders. - name: Tolls description: Read and search toll transactions. - name: Trailers description: Read trailers, search trailer events, and manage trailer documents. - name: Trips description: >- Read, search trips, manage trip documents, and record stop appointments, arrivals, and departures. - name: Trucks description: Read trucks, search truck events, and manage truck documents. - name: Users description: List and search users. - name: Visibility description: >- Read inbound and outbound visibility history and search outbound visibility errors. - name: Webhooks description: >- Create, read, update, delete, enable, disable, verify, test, and rotate secrets for webhook subscriptions; read event types, delivery logs, and health metrics. paths: /api/p/v{version}/carrier-settlement-statements/search: post: tags: - Carrier Settlement Statements summary: Search carrier settlement statements parameters: - name: version in: path description: API version (e.g., 1.0) required: true schema: type: string default: '1.0' example: '1.0' requestBody: content: application/json-patch+json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementSearchRequest application/json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementSearchRequest text/json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementSearchRequest application/*+json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementSearchRequest responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/Alvys.Helpers.PagedResponse1Alvys.Models.Settlements.CarrierSettlementStatementResponse '400': description: Bad Request content: application/json: schema: $ref: >- #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' security: - Public: [] components: schemas: Alvys.Models.Settlements.CarrierSettlementStatementSearchRequest: required: - Page - PageSize - StatementDateRange type: object properties: Page: type: integer format: int32 PageSize: type: integer format: int32 StatementDateRange: allOf: - $ref: '#/components/schemas/Alvys.Models.Period' CarrierId: type: string nullable: true SubsidiaryId: type: string nullable: true additionalProperties: false Alvys.Helpers.PagedResponse1Alvys.Models.Settlements.CarrierSettlementStatementResponse: required: - Items - Page - PageSize - Total type: object properties: Page: type: integer format: int32 PageSize: type: integer format: int32 Facets: type: object additionalProperties: type: array items: $ref: '#/components/schemas/Alvys.Helpers.ResultSetFacetItem' nullable: true Total: type: integer format: int64 Items: type: array items: $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementResponse additionalProperties: false Microsoft.AspNetCore.Mvc.ValidationProblemDetails: required: - Errors type: object properties: Errors: type: object additionalProperties: type: array items: type: string Type: type: string nullable: true Title: type: string nullable: true Status: type: integer format: int32 nullable: true Detail: type: string nullable: true Instance: type: string nullable: true additionalProperties: {} Microsoft.AspNetCore.Mvc.ProblemDetails: type: object properties: Type: type: string nullable: true Title: type: string nullable: true Status: type: integer format: int32 nullable: true Detail: type: string nullable: true Instance: type: string nullable: true additionalProperties: {} Alvys.Models.Period: required: - Start type: object properties: Start: type: string format: date-time End: type: string format: date-time nullable: true additionalProperties: false Alvys.Helpers.ResultSetFacetItem: required: - Count - Value type: object properties: Value: type: string Count: type: integer format: int64 additionalProperties: false Alvys.Models.Settlements.CarrierSettlementStatementResponse: required: - NetAmount - Number - PaidAmount - Payee - PaymentProvider - Payments - RemainingAmount - StatementDate - Status - SubsidiaryId - Trips type: object properties: Number: type: integer format: int32 Status: type: string StatementDate: type: string format: date-time RemittanceDate: type: string format: date-time nullable: true SubsidiaryId: type: string Payee: allOf: - $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementResponsePayeeDto RemitTo: type: string nullable: true PaymentProvider: type: string NetAmount: allOf: - $ref: '#/components/schemas/Alvys.Money' PaidAmount: allOf: - $ref: '#/components/schemas/Alvys.Money' RemainingAmount: allOf: - $ref: '#/components/schemas/Alvys.Money' Trips: type: array items: $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementResponseTripDto Payments: type: array items: $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementResponsePaymentDto additionalProperties: false Alvys.Models.Settlements.CarrierSettlementStatementResponsePayeeDto: required: - Id - Name - Type type: object properties: Type: type: string Id: type: string Name: type: string McNumber: type: string nullable: true DotNumber: type: string nullable: true additionalProperties: false Alvys.Money: required: - Amount type: object properties: Amount: type: number format: double Currency: type: integer format: int32 nullable: true additionalProperties: false Alvys.Models.Settlements.CarrierSettlementStatementResponseTripDto: required: - AccessorialsAmount - Items - LineHaulAmount - LoadNumber - NetAmount - TripId - TripNumber type: object properties: TripId: type: string TripNumber: type: string LoadNumber: type: string Origin: type: string nullable: true Destination: type: string nullable: true PickedUpAt: type: string format: date-time nullable: true DeliveredAt: type: string format: date-time nullable: true InvoiceNumber: type: string nullable: true InvoiceDueDate: type: string format: date-time nullable: true NetAmount: allOf: - $ref: '#/components/schemas/Alvys.Money' LineHaulAmount: allOf: - $ref: '#/components/schemas/Alvys.Money' AccessorialsAmount: allOf: - $ref: '#/components/schemas/Alvys.Money' Items: type: array items: $ref: >- #/components/schemas/Alvys.Models.Settlements.CarrierSettlementStatementResponseLineItemDto additionalProperties: false Alvys.Models.Settlements.CarrierSettlementStatementResponsePaymentDto: required: - Amount - Id - PaymentDate type: object properties: Id: type: string Amount: allOf: - $ref: '#/components/schemas/Alvys.Money' PaymentDate: type: string format: date-time PaymentMethod: type: string nullable: true ReferenceNumber: type: string nullable: true CheckNumber: type: string nullable: true additionalProperties: false Alvys.Models.Settlements.CarrierSettlementStatementResponseLineItemDto: required: - AccountingTag - Amount - Description - Type type: object properties: Description: type: string Type: type: string Amount: allOf: - $ref: '#/components/schemas/Alvys.Money' AccountingTag: type: string additionalProperties: false securitySchemes: Public: type: http scheme: bearer bearerFormat: JWT description: >- OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as `Authorization: Bearer `. ````