> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List buyer access
> Returns the store's buyer access records, newest first.
Returns a paginated list of buyer access records, newest first, under `data.access`. Filter by `product`, `status` (`active`, `expired` or `revoked`) and `email`. Requires the `READ_INVENTORY` scope.
The response includes buyers' **email addresses**, and it is gated by `READ_INVENTORY` alone: there is no separate customer scope on this endpoint. Treat the data accordingly and only request the scope when your app needs it.
`status` is the effective one: a pass past its end date reads as `expired` even before the nightly sweep has marked it. `data.failedGrants` lists paid orders whose access could not be granted yet; see [Retry failed grants](/apps-api/endpoint/digital-access/retry-digital-grants).
These endpoints only work on a store whose type is `digital`. On any other store they return `403` with `This is only available on digital stores.` See [Digital stores](/digital-stores).
```bash cURL theme={null}
curl -X GET https://api.salesive.com/api/v1/digital-access?status=active&limit=20 \
-H "Authorization: Bearer app_"
```
## OpenAPI
````yaml apps-api/specs/digital.json GET /digital-access
openapi: 3.1.0
info:
title: Salesive Apps API , Digital products
description: >-
Digital store endpoints (products, the all-access pass and buyer access)
callable by an installed third-party app using its app access token. They
only work on stores whose type is `digital`. The target store is bound to
the token server-side by the OAuth install flow.
version: 1.0.0
servers:
- url: https://api.salesive.com/api/v1
description: Production
security:
- AppToken: []
paths:
/digital-access:
get:
tags:
- digital-access
summary: List buyer access
description: >-
Returns a paginated list of the store's buyer access records, newest
first. The response includes buyer email addresses, and it is gated by
`READ_INVENTORY` alone: no customer scope is needed. `failedGrants`
lists paid orders whose access could not be granted yet. Requires the
`READ_INVENTORY` scope. The store must be a digital store, otherwise the
call returns 403.
operationId: listDigitalAccess
parameters:
- name: page
in: query
required: false
schema:
type: integer
default: 1
minimum: 1
description: Page number (1-based).
- name: limit
in: query
required: false
schema:
type: integer
default: 20
minimum: 1
maximum: 100
description: Items per page, 1 to 100.
- name: product
in: query
required: false
schema:
type: string
description: Only records for this digital product (ObjectId).
- name: status
in: query
required: false
schema:
type: string
enum:
- active
- expired
- revoked
description: Filter by effective status.
- name: email
in: query
required: false
schema:
type: string
description: >-
Partial, case-insensitive match on the buyer's email (max 120
characters).
responses:
'200':
description: 'List buyer access: success.'
content:
application/json:
schema:
type: object
required:
- status
- success
- message
- data
properties:
status:
type: integer
example: 200
success:
type: boolean
example: true
message:
type: string
example: Access records retrieved successfully
data:
type: object
properties:
access:
type: array
items:
$ref: '#/components/schemas/DigitalAccess'
pagination:
$ref: '#/components/schemas/Pagination'
failedGrants:
type: array
items:
$ref: '#/components/schemas/FailedGrant'
example:
access:
- _id: 6702d3f0e1b3a40012cd3001
email: ada@example.com
user: 66f0aa11e1b3a40012ef0001
scope: product
product:
_id: 6702c1a4e1b3a40012cd2001
name: The Lagos Cookbook
kind: pass
status: active
source: granted
startsAt: '2026-10-12T08:00:00.000Z'
accessUntil: '2026-11-11T08:00:00.000Z'
daysLeft: 30
autoRenew:
enabled: false
cardLast4: null
cardBrand: null
revokedAt: null
revokedReason: ''
createdAt: '2026-10-12T08:00:00.000Z'
updatedAt: '2026-10-12T08:00:00.000Z'
pagination:
total: 1
page: 1
limit: 20
pages: 1
hasNext: false
hasPrev: false
nextPage: null
prevPage: null
failedGrants: []
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
DigitalAccess:
type: object
description: >-
One buyer's access record. There is one record per buyer, product (or
the all-access pass) and kind, so buying a pass again extends the same
record.
properties:
_id:
type: string
email:
type: string
description: The buyer's email address. Personal data.
user:
type: string
description: The buyer's user id.
scope:
type: string
enum:
- product
- store
description: '`product` for one title, `store` for the all-access pass.'
product:
type: object
nullable: true
description: The title this record covers. `null` for the all-access pass.
properties:
_id:
type: string
name:
type: string
nullable: true
kind:
type: string
enum:
- lifetime
- pass
description: '`lifetime` never expires. `pass` runs until `accessUntil`.'
status:
type: string
enum:
- active
- expired
- revoked
description: >-
The effective status: a pass past its end date reads as `expired`
even before the nightly sweep runs.
source:
type: string
enum:
- purchase
- granted
description: >-
`granted` when a seller or app created the record, `purchase` when
an order did.
startsAt:
type: string
format: date-time
accessUntil:
type: string
format: date-time
nullable: true
description: End of the pass. `null` for lifetime access.
daysLeft:
type: integer
nullable: true
description: >-
Whole days left on an active pass. `null` for lifetime or inactive
records.
autoRenew:
type: object
properties:
enabled:
type: boolean
cardLast4:
type: string
nullable: true
cardBrand:
type: string
nullable: true
revokedAt:
type: string
format: date-time
nullable: true
revokedReason:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Pagination:
type: object
description: Pagination metadata.
properties:
total:
type: integer
description: Total number of matching items.
page:
type: integer
description: Current page (1-based).
pages:
type: integer
description: Total number of pages.
limit:
type: integer
description: Items per page.
hasNext:
type: boolean
hasPrev:
type: boolean
nextPage:
type: integer
nullable: true
prevPage:
type: integer
nullable: true
FailedGrant:
type: object
description: A paid digital order whose access could not be granted yet.
properties:
_id:
type: string
orderId:
type: integer
description: The order's number.
status:
type: string
attempts:
type: integer
lastError:
type: string
lastAttemptAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
responses:
BadRequest:
description: The body or query failed validation. `message` says which rule.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 400
success:
type: boolean
example: false
message:
type: string
example: A one-time price is required
data:
type: object
nullable: true
Unauthorized:
description: Missing or invalid app access token.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 401
success:
type: boolean
example: false
message:
type: string
example: App token expired or invalid.
data:
type: object
nullable: true
Forbidden:
description: >-
The app token lacks the required scope (`READ_INVENTORY` for reads,
`WRITE_INVENTORY` for writes), or the store is not a digital store
(`This is only available on digital stores.`).
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 403
success:
type: boolean
example: false
message:
type: string
example: >-
This app is missing the required permission(s):
WRITE_INVENTORY
data:
type: object
nullable: true
securitySchemes:
AppToken:
type: http
scheme: bearer
description: >-
Installed-app access token (prefix app_), issued by the OAuth install
flow. The store is bound to the token server-side , never send a shop
id.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.