> ## Documentation Index
> Fetch the complete documentation index at: https://developers.entri.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Purchased Domains
> Retrieve the list of domains purchased through Sell for your application, including the userId provided at purchase time.
**Use this if…** you need to reconcile the domains your users purchased through Sell against your own user records — for example, matching each domain to the right account in your system, running audits, or backfilling data missed by [webhook notifications](https://developers.entri.com/webhooks). This endpoint only returns domains purchased **through Sell**; domains transferred directly to another registrar outside of Sell are not included.
## **Overview**
The **List Purchased Domains** API returns every domain your application has sold through Entri Sell, along with the `userId` you passed in at purchase time, so you can match each domain to the correct user in your own system. Results are scoped to your application — you will only ever see domains purchased through your own `applicationId`.
**What this list includes:** every domain purchased through the Sell flow for your application, regardless of which registrar (IONOS, GoDaddy, etc.) ultimately fulfilled the purchase.
**What this list does not include:** legacy domains that were transferred directly to another registrar outside of Sell. Those transfers are handled by a separate process and never appear here.
***
## **Request Structure**
**Base URL:**
```txt theme={"system"}
https://api.goentri.com/backend/utils/sell/domains
```
**General format:**
```txt theme={"system"}
GET https://api.goentri.com/backend/utils/sell/domains?{query-params}
```
**Request headers:**
* Authorization: Bearer `{access_token}` — required for authentication
* applicationId: `{your-application-id}` — identifies your integration
* Accept: `application/json` — required, JSON is the only supported format
***
## **Authentication**
The List Purchased Domains API uses the same **short-lived JWT** authentication as every other Entri product API. You mint the token **server-side** using your `applicationId` and `secret`. Do **not** expose your secret in client code. The JWT expires after **60 minutes**.
### **1) Create a JWT**
**Endpoint**
POST `https://api.goentri.com/token`
**Headers**
`Content-Type: application/json`
**Body**
```json theme={"system"}
{
"applicationId": "",
"secret": ""
}
```
**Response (200)**
```json theme={"system"}
{ "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi..." }
```
### **2) Call the API with the JWT**
Include the JWT as a **Bearer** token, and pass your `applicationId` header on every request:
```
Authorization: Bearer
applicationId:
```
### **Notes**
* Mint tokens **server-side** only; never ship your secret to the browser.
* Tokens expire after **60 minutes** — mint a fresh token as needed.
* If your credentials are missing or invalid, the request is rejected before any data is returned — see [Errors](#errors) below.
***
## **List Purchased Domains**
GET `/sell/domains` — Retrieves the list of domains purchased through Sell for your application.
**Authentication**
Required (JWT)
**Query Parameters (Filters)**
| Parameter | Required | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId` | No | Return only the domain(s) purchased for this specific end-user. Matches the `userId` you passed in your integration config at purchase time. |
| `domain` | No | Return only domains whose name contains this text (partial match, not case-sensitive). |
| `fromDate` | No | Only include purchases made on or after this date. Format: `YYYY-MM-DD`. |
| `toDate` | No | Only include purchases made on or before this date. Format: `YYYY-MM-DD`. |
| `page` | No | Page number, starting at `0`. Defaults to `0`. |
| `limit` | No | Number of results per page. Defaults to `100`, maximum `500`. |
If no filters are supplied, the endpoint returns every domain purchased through Sell for your application, most recent first.
**Example request**
```bash theme={"system"}
curl -X GET \
"https://api.goentri.com/backend/utils/sell/domains?fromDate=2026-01-01&toDate=2026-01-31&page=0&limit=10" \
-H "Authorization: Bearer " \
-H "applicationId: " \
-H "Accept: application/json"
```
**Example response**
```json theme={"system"}
{
"items": [
{
"purchaseId": "fb044917-e35d-42fb-a195-c43c4e031d6b",
"domain": "example.com",
"userId": "square-user-123",
"purchaseDate": "2026-01-14 19:43:46",
"status": "purchased",
"provider": "GODADDY",
"connectionId": "gYSe9Q8cKEw4KEhyLA==",
"companyId": "79fa2550-1e21-4fd8-9ec7-61351e4fd8f9",
"couponCode": "",
"freeDomain": false,
"mailUpsell": false,
"customerId": "",
"sourceApplicationUuid": ""
}
],
"total": 56,
"page": 0,
"limit": 10,
"count": 10,
"pages": 6,
"nextPage": 1,
"prevPage": null
}
```
### **Field Definitions**
Each entry in `items` represents one purchased domain:
| Field | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `purchaseId` | Unique identifier for this purchase record. Useful for referencing a specific purchase in support requests. |
| `domain` | The domain name that was purchased. |
| `userId` | The end-user ID you passed in your integration config at the time of purchase. **Empty string** if no `userId` was provided at purchase time. |
| `purchaseDate` | Date and time the domain was purchased, in `YYYY-MM-DD HH:MM:SS` format. |
| `status` | Currently always `purchased` for every entry in this list. |
| `provider` | The registrar that fulfilled the purchase, e.g. `IONOS`, `GODADDY`. |
| `connectionId` | Internal identifier linking this purchase to a DNS connection flow, if applicable. Empty string if not applicable. |
| `companyId` | Identifier for the Entri company account associated with this purchase. |
| `couponCode` | Coupon code applied at purchase, if any. Empty string if none was used. |
| `freeDomain` | `true` if this domain was provided free as part of a bundle or promotion. |
| `mailUpsell` | `true` if the customer also purchased an email add-on at the same time. |
| `customerId` | Internal customer identifier, if available in your environment. Empty string if not applicable. |
| `sourceApplicationUuid` | Identifies the originating application when a purchase was made through a sub-account or reseller flow that differs from your own application. Empty string when the purchase originated directly from your application. |
**Response envelope**
| Field | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items` | Array of purchased-domain objects, described above. |
| `total` | Total number of domains matching your filters, across all pages. |
| `page` | The page number returned (matches your `page` query parameter, or `0` by default). |
| `limit` | The page size used (matches your `limit` query parameter, or `100` by default). |
| `count` | Number of items in this specific response. |
| `pages` | Total number of pages needed to return every matching result at this page size (rounded up — e.g. 56 results at `limit: 10` is `6` pages, not `5`). |
| `nextPage` | The next page number to request, or `null` if this is the last page. |
| `prevPage` | The previous page number, or `null` if this is the first page. |
***
## **Errors**
All errors are returned in a standard JSON structure, with the corresponding HTTP status code in the response headers.
**Format:**
```json theme={"system"}
{
"message": "Error description"
}
```
| HTTP Status | When it happens | Example body |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `401 Unauthorized` | Your credentials are missing or invalid — no `applicationId`, an expired or invalid JWT, or a JWT that doesn't match your `applicationId`. No data is returned. | `{"message": "Unauthorized. Missing application_id in authorizer context"}` |
| `400 Bad Request` | A query parameter is invalid — e.g. `fromDate`/`toDate` isn't in `YYYY-MM-DD` format, or `limit`/`page` isn't a number. | `{"message": "Invalid value for 'fromDate': expected YYYY-MM-DD"}` |
| `500 Internal Server Error` | An unexpected error occurred on our end. | `{"message": "Internal Server Error"}` |
**Empty results are not an error.** If your application simply has no domains matching your filters (or no Sell purchases at all yet), the request still returns `200 OK` with an empty list:
```json theme={"system"}
{
"items": [],
"total": 0,
"page": 0,
"limit": 100,
"count": 0,
"pages": 0,
"nextPage": null,
"prevPage": null
}
```
***
## **Scope: What's Included**
This endpoint only returns domains **purchased through Sell**. If a user's domain was:
* Purchased through the Sell flow, via any supported registrar → **included**
* Transferred directly to another registrar **outside of Sell** (for example, as part of a bulk migration) → **not included**
If you're reconciling your full domain inventory and some domains you expect aren't showing up here, they were likely handled outside the Sell purchase flow and won't appear in this list.