---
title: "Get orders report"
method: GET
path: "/data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/orders"
tags: ["Sales"]
---

# Get orders report

`GET /data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/orders`

## Request

- Base URL: `https://api.codat.io`
- URL: `https://api.codat.io/data/companies/{companyId}/connections/{connectionId}/assess/commerceMetrics/orders`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/codatio/apis/lending/docs/data/companies/:companyId/connections/:connectionId/assess/commerceMetrics/orders/get.ts> (a function with typed inputs; its response is checked against the schema)

The *Get orders report* endpoint returns the number of orders, total value, and average order value for a specific company's commerce connection over one or more periods of time.

This detail helps you assess a merchant's health and advise them on performance improvement strategies. It also provides you with key insights you need to assess the credit risk of a company. 

[Learn more](https://docs.codat.io/lending/features/sales-overview#metrics) about the formulas used to calculate the order metrics.

#### Response structure

The Orders report's dimensions and measures are:

| Index         | Dimensions     |
|---------------|----------------|
|   `index` = 0 | Period         |
|   `index` = 1 | Order metrics  |

| Index         | Measures   |
|---------------|------------|
| `index` = 0   | Count      |
| `index` = 1   | Value      |

The report data then combines multiple reporting dimensions and measures and outputs the value of each combination.

## Query parameters

- `reportDate` string, required
- `periodLength` integer, required
- `numberOfPeriods` integer, required
- `periodUnit` 'Day' | 'Week' | 'Month' | 'Year', required
- `includeDisplayNames` boolean

## Response `200`

OK

- CommerceReport: ## Structure Assess reports follow a consistent structure. Reports contain four sections of information: ### 1. Report definition Information such as: 1. The report info (e.g. enhanced_profit_and_loss). 2. The display name of the report (e.g. Enhanced Profit and Loss). ### 2. Dimension info Information about the dimension contained in the reports such as: 1. The type of dimension (e.g. datetime, recordRef). 2. The display name of the dimension (e.g. Period, Category type, Category sub type). 3. The details about each item within the dimension (e.g. displayName:"Jan 2022", start:"...", end:"...", id:"...", name:"..."). ### 3. Measure info Information about the measures contained in the report such as: 1. The display name of the measure (e.g. value of account, percentage change). 2. The type of the measure (e.g. currency, percentage). 3. The unit of the measure (e.g. %, GBP). ### 4. The data for the report When the *includeDisplayName* parameter is set to *true*, it shows the *dimensionDisplayName* and *itemDisplayName* to make the data human-readable. The default setting for *includeDisplayName* is *false*. ## Displaying the report Reports can be rendered as follows (ordering is implicit rather than explicit): ![A table showing an example of how a report can be rendered](https://files.readme.io/1fa20ca-Report1.png) # Data model ## Dimensions
  - `reportInfo` object
  - `dimensions` CommerceReportDimension[] (unresolved $ref)
  - `measures` CommerceReportMeasure[] (unresolved $ref)
  - `reportData` CommerceReportComponent[] (unresolved $ref)
  - `errors` CommerceReportError[] (unresolved $ref)

## Other responses

- `400`: The request made is not valid.
- `401`: Your API request was not properly authorized.
- `402`: An account limit has been exceeded. The type of limit is described in the error property: - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request. - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan. - Your Free account is older than 365 days and has expired. Contact support@codat.io.
- `403`: You are using an outdated API key or a key not associated with that resource.
- `404`: One or more of the resources you referenced could not be found. This might be because your company or data connection id is wrong, or was already deleted.
- `429`: Too many requests were made in a given amount of time. Wait a short period and then try again.
- `500`: There is a problem with our server. Please try again later.
- `503`: The Codat API is temporarily offline for maintenance. Please try again later.

## Changes

- **2024-02-13** `2244d9343d0a`: 8 info
  - added the optional property `validation` to the response with the `400` status
  - added the optional property `validation` to the response with the `401` status
  - added the optional property `validation` to the response with the `402` status
  - added the optional property `validation` to the response with the `403` status
  - …4 more
- **2023-10-23** `799afe3f1a9f`: 6 info
  - added the non-success response with the status `400`
  - added the non-success response with the status `402`
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
  - …2 more

[Operation history](https://skmtc.dev/codatio/apis/lending/changes/data/companies/:companyId/connections/:connectionId/assess/commerceMetrics/orders/get.md)

---

[API](https://skmtc.dev/codatio/apis/lending.md) - [All operations](https://skmtc.dev/codatio/apis/lending/llms.txt) - [OpenAPI document](https://skmtc.dev/codatio/apis/lending/revisions/c81b2fd3063d?raw)