# List sales orders

Operation ID: `salesOrders`

Group: Accounting › Sales Orders

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/salesOrders)

`GET /accounting/sales-orders`

Read-only: Reads and returns; changes nothing.

Lists sales orders. Each sales order is returned with its header fields, amounts, and customer and entity ids. For the customer record, the addresses, and the external identifiers, use GET accounting/sales-orders/:id. The products and their priced lines are the salesOrderProducts and salesOrderProductLines collections. To filter by purchase order or external identifier, use POST accounting/sales-orders/search.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · v1 | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Query surface

- `id` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `orderNumber` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `orderType` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `approvalStatus` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `invoiceStatus` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `bookDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between
- `serviceStartDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between
- `serviceEndDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between
- `currency` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `isEvergreen` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between
- `salesChannel` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `customerId` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `entityId` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `lastModifiedDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between
- Orderable: id, orderNumber, orderType, approvalStatus, bookDate, serviceStartDate, serviceEndDate, currency, isEvergreen, term, lastModifiedDate
- Selectable: id, orderNumber, orderType, approvalStatus, invoiceStatus, bookDate, signDate, salesEffectiveDate, serviceStartDate, serviceEndDate, currency, isEvergreen, isPayAsYouGoOnly, term, totalContract, invoicedAmount, oneTimeDiscountAmount, oneTimeDiscountAllocation, exchangeRate, functionalCurrency, functionalTotalContract, functionalInvoicedAmount, purchaseOrder, salesChannel, customerId, customerName, customerNumber, entityId, entityName, entityNumber, salesArrangement, lastModifiedDate
- `page[size]` — Page size
- `page[cursor]` — Opaque continuation cursor

## Response

`200` Success

Under `data`, an array of salesOrdersRow:

| Field | Type | Required | Filter | Sort | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | string | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | yes | The unique identifier for the sales order. |
| `orderNumber` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | yes | The sales order number. Unique within the tenant. Example: 'SO-1042'. |
| `orderType` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | yes | The type of the sales order. Possible values: 'new', 'upsell', 'earlyRenewal', 'renewal', 'replacement'. |
| `approvalStatus` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | yes | The approval status of the sales order. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'. |
| `invoiceStatus` | "notStarted" \| "notStartedOnHold" \| "inProgress" \| "inProgressOnHold" \| "complete" \| "completeModified" \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | How far the order has been invoiced, derived from its invoice plan lines. This is NOT approvalStatus, which says where the order sits in the approval lifecycle: an approved order is usually notStarted, and a fully invoiced one is still approved. Evaluated now, not as of a date. |
| `bookDate` | date | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | The date the sales order was booked. Format YYYY-MM-DD. |
| `signDate` | date \| null | no | no | no | Date the contract was signed by customer and company (YYYY-MM-DD). One of four dates an order carries: bookDate is when it was booked into the system, signDate when it was signed, salesEffectiveDate when the contract legally takes effect, and serviceStartDate when delivery begins. A report about when business was won reads bookDate or signDate; one about when revenue or service starts reads the other two. |
| `salesEffectiveDate` | date \| null | no | no | no | Legal effective date of the contract (YYYY-MM-DD), which can be earlier than signDate: a contract signed in May may take effect retroactively from the previous December. |
| `serviceStartDate` | date | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | The first day of the order's service period. Format YYYY-MM-DD. |
| `serviceEndDate` | date \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | The last day of the order's service period. Absent when isEvergreen is true. Format YYYY-MM-DD. |
| `currency` | string | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | yes | The currency of the order. Format ISO 4217, for example 'USD'. |
| `isEvergreen` | boolean | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | Whether the order is evergreen, meaning at least one of its subscriptions has no end date and keeps billing until it is canceled. |
| `isPayAsYouGoOnly` | boolean \| null | no | no | no | True when every line on the order is pay-as-you-go usage, which is why such an order has no fixed term to invoice or recognise on a schedule. |
| `term` | decimal \| null | no | no | yes | The length of the order's term, in months. Absent when isEvergreen is true. |
| `totalContract` | decimal \| null | no | no | no | Total contract value in the order currency (see `currency`): the sum of the products' totals less the order-level oneTimeDiscountAmount. Already net of that discount — subtracting it again double-counts it. |
| `invoicedAmount` | decimal \| null | no | no | no | Amount already invoiced against the contract value, in the order currency (see `currency`): the products' invoiced amounts plus every negative invoice line raised against the order, so it is net of credits and can fall as well as rise. totalContract minus invoicedAmount is what remains to be billed. |
| `oneTimeDiscountAmount` | decimal \| null | no | no | no | Lump-sum discount applied to the whole order, in the order currency (see `currency`). Already deducted from totalContract. |
| `oneTimeDiscountAllocation` | "firstInvoice" \| "alignToInvoiceFrequency" \| "custom" \| null | no | no | no | How the lump-sum discount is spread across the products. |
| `exchangeRate` | decimal \| null | no | no | no | Rate from the order currency to the legal entity's functional currency, as stored on the order. Absent when no conversion is recorded; the functional figures then carry the order-currency amount unchanged. |
| `functionalCurrency` | string \| null | no | no | no | The legal entity's functional currency as a 3-letter ISO 4217 code — the currency functionalTotalContract and functionalInvoicedAmount are in. The order's own amounts are in `currency` instead. |
| `functionalTotalContract` | decimal \| null | no | no | no | Total contract value in the entity's functional currency (see `functionalCurrency`): totalContract at exchangeRate. Where no exchange rate is stored the order's own amount is carried over unchanged, so a sum across orders can mix converted and unconverted figures — check exchangeRate, or group by currency, before presenting one total across currencies. |
| `functionalInvoicedAmount` | decimal \| null | no | no | no | Amount already invoiced, in the entity's functional currency (see `functionalCurrency`) — the functional twin of invoicedAmount, net of credits in the same way, with the same caution as functionalTotalContract. |
| `purchaseOrder` | string \| null | no | no | no | The customer's own purchase-order reference as recorded on the order. Free text — not validated, not unique, absent where the customer issued none. Returned only — it can be neither filtered nor sorted on, because it names a customer-owned document. |
| `salesChannel` | "salesAssisted" \| "selfServe" \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | How the order was sold. |
| `customerId` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | The customer this order is for. |
| `customerName` | string \| null | no | no | no | The name of the customer this order is for. See name on GET accounting/customers/:id. |
| `customerNumber` | string \| null | no | no | no | The customer number of the customer this order is for. See customerNumber on GET accounting/customers/:id. Example: 'CUS-789012'. |
| `entityId` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | The legal entity that owns the order. |
| `entityName` | string \| null | no | no | no | The name of the legal entity that owns this sales order. See entityName on GET base/entities. |
| `entityNumber` | string \| null | no | no | no | The number of the legal entity that owns this sales order. See entityNumber on GET base/entities. |
| `salesArrangement` | string \| null | no | no | no | The number of the sales arrangement this order belongs to. No endpoint returns sales arrangements. |
| `lastModifiedDate` | date-time | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | The date and time the sales order last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Changes to product lines do not update it. |

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "orderNumber": "<orderNumber>",
      "orderType": "<orderType>",
      "approvalStatus": "<approvalStatus>",
      "invoiceStatus": "notStarted",
      "bookDate": "2026-01-15",
      "signDate": "2026-01-15",
      "salesEffectiveDate": "2026-01-15",
      "serviceStartDate": "2026-01-15",
      "serviceEndDate": "2026-01-15",
      "currency": "<currency>",
      "isEvergreen": true,
      "isPayAsYouGoOnly": true,
      "term": "19.99",
      "totalContract": "19.99",
      "invoicedAmount": "19.99",
      "oneTimeDiscountAmount": "19.99",
      "oneTimeDiscountAllocation": "firstInvoice",
      "exchangeRate": "19.99",
      "functionalCurrency": "<functionalCurrency>",
      "functionalTotalContract": "19.99",
      "functionalInvoicedAmount": "19.99",
      "purchaseOrder": "<purchaseOrder>",
      "salesChannel": "salesAssisted",
      "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "customerName": "<customerName>",
      "customerNumber": "<customerNumber>",
      "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "entityName": "<entityName>",
      "entityNumber": "<entityNumber>",
      "salesArrangement": "<salesArrangement>",
      "lastModifiedDate": "2026-01-15T09:30:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "<nextCursor>"
  }
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error