> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics API Reference for Nymble Commerce

> REST API reference for Nymble Commerce analytics endpoints — revenue trends, order KPIs, top products, top customers, and sales rep performance metrics.

The Analytics API provides organization-level business intelligence — revenue trends, order volumes, top performers, and customer activity. All analytics endpoints require the **Admin** role. Your `OrganizationId` is automatically scoped from your JWT, so every response only ever contains data for your own organization.

## Common query parameters

All analytics endpoints accept the following query parameters:

| Parameter        | Type             | Required | Description                                                                             |
| ---------------- | ---------------- | -------- | --------------------------------------------------------------------------------------- |
| `startDate`      | `DateTimeOffset` | Yes      | Start of the reporting window (ISO 8601, e.g. `2024-01-01T00:00:00Z`)                   |
| `endDate`        | `DateTimeOffset` | Yes      | End of the reporting window (ISO 8601, e.g. `2024-01-31T23:59:59Z`)                     |
| `organizationId` | string           | —        | Automatically injected from your JWT `OrganizationId` claim. Do not pass this manually. |

<Note>
  All dates are interpreted in UTC. Pass a timezone offset (e.g. `-05:00`) if you need to align windows to a local business day.
</Note>

***

## GET /api/analytics/revenue

Returns total revenue for your organization within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

### Response

<ResponseField name="totalRevenue" type="decimal">
  Total revenue earned during the period.
</ResponseField>

<ResponseField name="currencyCode" type="string">
  ISO 4217 currency code (e.g. `USD`).
</ResponseField>

```json title="Example response" theme={null}
{
  "totalRevenue": 128450.75,
  "currencyCode": "USD"
}
```

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/analytics/revenue?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer <your_token>"
```

***

## GET /api/analytics/revenue/trend

Returns monthly revenue trend data grouped by period within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

### Response

Returns an array of monthly revenue data points.

<ResponseField name="date" type="string">
  Period start date (ISO 8601).
</ResponseField>

<ResponseField name="revenue" type="decimal">
  Total revenue for the period.
</ResponseField>

```json title="Example response" theme={null}
[
  { "date": "2024-01-01T00:00:00Z", "revenue": 42150.00 },
  { "date": "2024-02-01T00:00:00Z", "revenue": 38900.50 },
  { "date": "2024-03-01T00:00:00Z", "revenue": 47400.25 }
]
```

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/analytics/revenue/trend?startDate=2024-01-01T00:00:00Z&endDate=2024-03-31T23:59:59Z" \
  -H "Authorization: Bearer <your_token>"
```

***

## GET /api/analytics/orders/trend

Returns monthly order count trend data grouped by period within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

### Response

Returns an array of monthly order count data points.

<ResponseField name="date" type="string">
  Period start date (ISO 8601).
</ResponseField>

<ResponseField name="orderCount" type="integer">
  Number of orders placed during the period.
</ResponseField>

```json title="Example response" theme={null}
[
  { "date": "2024-01-01T00:00:00Z", "orderCount": 312 },
  { "date": "2024-02-01T00:00:00Z", "orderCount": 289 },
  { "date": "2024-03-01T00:00:00Z", "orderCount": 347 }
]
```

***

## GET /api/analytics/orders/mtd

Returns the number of orders placed month-to-date, along with a comparison to the previous month.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window (typically the first day of the current month).
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window (typically today).
</ParamField>

### Response

<ResponseField name="count" type="integer">
  Number of orders placed in the current month-to-date window.
</ResponseField>

<ResponseField name="previousMonthCount" type="integer">
  Number of orders placed in the equivalent window of the previous month.
</ResponseField>

<ResponseField name="percentChange" type="decimal">
  Percentage change compared to the previous month. Negative values indicate a decline.
</ResponseField>

```json title="Example response" theme={null}
{
  "count": 142,
  "previousMonthCount": 128,
  "percentChange": 10.94
}
```

***

## GET /api/analytics/aov

Returns the average order value for your organization within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

### Response

<ResponseField name="averageOrderValue" type="decimal">
  Average monetary value per order during the period.
</ResponseField>

<ResponseField name="currencyCode" type="string">
  ISO 4217 currency code (e.g. `USD`).
</ResponseField>

```json title="Example response" theme={null}
{
  "averageOrderValue": 412.50,
  "currencyCode": "USD"
}
```

***

## GET /api/analytics/active-customers

Returns the count of customers who placed at least one order during the specified period, plus a percentage change compared to the previous equivalent period.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

### Response

<ResponseField name="activeCustomers" type="integer">
  Number of unique customers who placed at least one order during the period.
</ResponseField>

<ResponseField name="percentChange" type="decimal">
  Percentage change in active customers compared to the previous equivalent period.
</ResponseField>

```json title="Example response" theme={null}
{
  "activeCustomers": 87,
  "percentChange": 5.48
}
```

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/analytics/active-customers?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer <your_token>"
```

***

## GET /api/analytics/products/top-by-revenue

Returns the top N products ranked by revenue within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

<ParamField query="limit" default="10" type="integer">
  Maximum number of products to return. Defaults to `10`.
</ParamField>

### Response

Returns an array of product revenue rankings.

<ResponseField name="productId" type="string">
  Unique identifier of the product.
</ResponseField>

<ResponseField name="sku" type="string">
  Product SKU.
</ResponseField>

<ResponseField name="name" type="string">
  Product display name.
</ResponseField>

<ResponseField name="revenue" type="decimal">
  Total revenue generated by this product during the period.
</ResponseField>

<ResponseField name="unitsOrdered" type="integer">
  Total units ordered during the period.
</ResponseField>

```json title="Example response" theme={null}
[
  {
    "productId": "prod_abc123",
    "sku": "WDG-001",
    "name": "Premium Widget",
    "revenue": 18450.00,
    "unitsOrdered": 246
  },
  {
    "productId": "prod_def456",
    "sku": "GDG-002",
    "name": "Standard Gadget",
    "revenue": 12300.50,
    "unitsOrdered": 410
  }
]
```

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/analytics/products/top-by-revenue?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&limit=5" \
  -H "Authorization: Bearer <your_token>"
```

***

## GET /api/analytics/customers/top-by-revenue

Returns the top N customers ranked by revenue within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

<ParamField query="limit" default="10" type="integer">
  Maximum number of customers to return. Defaults to `10`.
</ParamField>

### Response

Returns an array of customer revenue rankings.

<ResponseField name="customerNumber" type="string">
  The customer's account number.
</ResponseField>

<ResponseField name="companyName" type="string">
  The customer's company name.
</ResponseField>

<ResponseField name="revenue" type="decimal">
  Total revenue from this customer during the period.
</ResponseField>

<ResponseField name="orderCount" type="integer">
  Number of orders placed by this customer during the period.
</ResponseField>

```json title="Example response" theme={null}
[
  {
    "customerNumber": "CUST-0042",
    "companyName": "Acme Corp",
    "revenue": 24800.00,
    "orderCount": 18
  },
  {
    "customerNumber": "CUST-0017",
    "companyName": "Globex Industries",
    "revenue": 19100.75,
    "orderCount": 12
  }
]
```

***

## GET /api/analytics/categories/top-by-revenue

Returns the top N product categories ranked by revenue within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

<ParamField query="limit" default="10" type="integer">
  Maximum number of categories to return. Defaults to `10`.
</ParamField>

### Response

Returns an array of category revenue rankings.

<ResponseField name="categoryId" type="string">
  Unique identifier of the category.
</ResponseField>

<ResponseField name="name" type="string">
  Category display name.
</ResponseField>

<ResponseField name="revenue" type="decimal">
  Total revenue generated by products in this category during the period.
</ResponseField>

```json title="Example response" theme={null}
[
  { "categoryId": "cat_001", "name": "Widgets", "revenue": 52300.00 },
  { "categoryId": "cat_002", "name": "Gadgets", "revenue": 38700.50 }
]
```

***

## GET /api/analytics/sales-reps/top-by-revenue

Returns the top N sales representatives ranked by revenue within the specified date range.

**Security:** Admin policy

### Query parameters

<ParamField query="startDate" type="DateTimeOffset" required>
  Start of the reporting window.
</ParamField>

<ParamField query="endDate" type="DateTimeOffset" required>
  End of the reporting window.
</ParamField>

<ParamField query="limit" default="10" type="integer">
  Maximum number of sales reps to return. Defaults to `10`.
</ParamField>

### Response

Returns an array of sales rep revenue rankings.

<ResponseField name="salesRepNumber" type="string">
  The sales rep's representative number.
</ResponseField>

<ResponseField name="name" type="string">
  Full name of the sales representative.
</ResponseField>

<ResponseField name="revenue" type="decimal">
  Total revenue attributed to this sales rep during the period.
</ResponseField>

<ResponseField name="orderCount" type="integer">
  Number of orders attributed to this sales rep during the period.
</ResponseField>

```json title="Example response" theme={null}
[
  {
    "salesRepNumber": "REP-001",
    "name": "Jane Smith",
    "revenue": 31200.00,
    "orderCount": 54
  },
  {
    "salesRepNumber": "REP-002",
    "name": "Bob Johnson",
    "revenue": 27400.50,
    "orderCount": 41
  }
]
```

```bash title="curl example" theme={null}
curl -X GET \
  "https://api.achievemomentum.com/api/analytics/sales-reps/top-by-revenue?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&limit=5" \
  -H "Authorization: Bearer <your_token>"
```