# Analytics API overview

**Current version: 1.0**  
*For versioning details, read the [Versioning](/commerce-apis/versioning) guide.*

Use the Analytics API to retrieve aggregated commerce data for contacts on a Squarespace merchant site. The API currently returns transaction summaries — order and donation metrics — grouped by contact, making it useful for segmentation, reporting, and CRM enrichment workflows.

> *Note: In the old Profiles API, transaction summary data is embedded inline on each `Profile` resource. The Analytics API provides the same information as a standalone, dedicated endpoint that accepts contact IDs from the [Contacts API](/commerce-apis/contacts-overview) and returns summaries in bulk — up to 1,000 contacts per request.*

## API resources

### Transaction summaries

`TransactionsSummary` provides an aggregated view of a contact's commerce activity on the site. Each summary includes:

- `firstOrderSubmittedOn` — when the contact's first order was placed
- `lastOrderSubmittedOn` — when the contact's most recent order was placed
- `orderCount` — total number of orders
- `totalOrderAmount` — grand total across all orders
- `totalRefundAmount` — total value of all refunds
- `firstDonationSubmittedOn` — when the contact's first donation was submitted
- `lastDonationSubmittedOn` — when the contact's most recent donation was submitted
- `donationCount` — total number of donations
- `totalDonationAmount` — grand total across all donations

Monetary amounts are returned as `MonetaryAmount` objects (value and currency).

### Asynchronous computation

Transaction summary data is computed **asynchronously**. There may be a delay between when an order or donation is submitted and when it is reflected in the summary. Integrations with the endpoint should be built in a way that tolerates this eventual consistency.

## How it works

The Analytics API exposes a single endpoint that accepts a list of contact IDs and returns a transaction summary for each:

1. Retrieve contact IDs — either by listing contacts via the [Contacts API](/commerce-apis/contacts-overview), or by extracting `customerId` from orders.
2. Post up to **1,000 contact IDs** to the transaction summaries endpoint, specifying `groupBy: "contactId"`.
3. Receive a `TransactionsSummaryWrapper` for each contact, containing the `contactId` and its `TransactionsSummary`.

Contacts with no commerce activity will return a summary with zero counts and `null` date fields.

## Cross-API relationships


| API          | Field        | Relationship                                                                                                                                                               |
| ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contacts** | `id`         | Pass contact `id` values as `contactIds` in the request.                                                                                                                   |
| **Profiles** | `id`         | A profile's `id` is the same identifier. The Profiles API includes a `TransactionsSummary` inline; the Analytics API provides the same data via a dedicated bulk endpoint. |
| **Orders**   | `customerId` | The `customerId` on an Order corresponds to a contact `id`. Use it to look up transaction summaries after processing orders.                                               |


## Common workflows

**CRM segmentation by spend**  
Query contacts using the [Contacts API](/commerce-apis/contacts-overview) to identify a cohort (e.g. contacts who accept marketing), then pass their IDs to the Analytics API to retrieve order totals and donation counts for segmentation.

**Lifetime value reporting**  
Periodically fetch transaction summaries for all active contacts to build lifetime value (LTV) reports, using `totalOrderAmount` and `orderCount` as the core metrics.

**Post-order enrichment**  
After receiving an order webhook, use the `customerId` to fetch an updated transaction summary, then sync the contact's commerce metrics back to an external CRM or analytics platform.

## Further reading

- Learn about the [Contacts API](/commerce-apis/contacts-overview), which provides the contact records referenced by this API
- Become familiar with [common commerce terms](/commerce-apis/glossary) and how they're related to the API
- [Obtain an API key or use OAuth](/commerce-apis/authentication-and-permissions)
- Read the [FAQ](/commerce-apis/faq) guide for answers to common questions