> ## 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.
# Grant buyer access
> Gives a buyer lifetime or pass access to a product, or the all-access pass, without a payment.
Gives a buyer access without a payment. Requires the `WRITE_INVENTORY` scope.
* The buyer must already have a shopper account in the store (they have signed in once). Otherwise the call returns `404`.
* Send either `productId` or `allAccess: true`. The all-access pass can only be granted as a `pass`. `lifetime` takes no `days`.
* A pass defaults to 30 days (1 to 3650).
* If that buyer already has a record for the same product and kind, it is extended or reactivated instead of duplicated.
* Send the same `grantId` (an ObjectId you generate) on a retry and the repeat changes nothing. Without a `grantId`, every call applies again.
The response is `201` when a record was created, `200` otherwise. The buyer does not get an email from this call.
Granting access changes what a buyer can download. It uses the same `WRITE_INVENTORY` scope as editing products, so only request it for apps that are meant to manage buyers.
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 POST https://api.salesive.com/api/v1/digital-access/grant \
-H "Authorization: Bearer app_" \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.com","productId":"6702c1a4e1b3a40012cd2001","kind":"pass","days":30,"grantId":"6702f0b2e1b3a40012cd5001"}'
```
## OpenAPI
````yaml apps-api/specs/digital.json POST /digital-access/grant
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/grant:
post:
tags:
- digital-access
summary: Grant buyer access
description: >-
Gives a buyer access without a payment. The buyer must already have a
shopper account in the store (they signed in once), otherwise the call
returns 404. Choose either `productId` or `allAccess: true`. If a record
for that buyer, product and kind already exists it is extended or
reactivated instead of duplicated. Send the same `grantId` on a retry
and the second call changes nothing and returns 200; without a
`grantId`, every call applies again (a pass is extended each time).
Returns 201 when a record was created. Requires the `WRITE_INVENTORY`
scope. The store must be a digital store, otherwise the call returns
403.
operationId: grantDigitalAccess
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- kind
properties:
email:
type: string
format: email
description: >-
The buyer's email address. Must belong to an existing
shopper account.
productId:
type: string
description: >-
The digital product to grant. Omit when `allAccess` is
`true`.
allAccess:
type: boolean
description: >-
Grant the store-wide all-access pass instead of one product.
Only valid with `kind: "pass"`.
kind:
type: string
enum:
- lifetime
- pass
description: '`lifetime` never expires. `pass` runs for `days`.'
days:
type: integer
minimum: 1
maximum: 3650
description: >-
Length of a pass in days. Default 30. Not allowed with
`lifetime`.
grantId:
type: string
description: >-
Optional ObjectId you generate. Makes a retried request a
no-op.
example:
email: ada@example.com
productId: 6702c1a4e1b3a40012cd2001
kind: pass
days: 30
grantId: 6702f0b2e1b3a40012cd5001
responses:
'200':
description: >-
Grant buyer access: an existing record was extended, or this
`grantId` was already applied (`Access was already granted`).
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 granted
data:
allOf:
- $ref: '#/components/schemas/DigitalAccess'
example:
_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'
'201':
description: 'Grant buyer access: record created.'
content:
application/json:
schema:
type: object
required:
- status
- success
- message
- data
properties:
status:
type: integer
example: 201
success:
type: boolean
example: true
message:
type: string
example: Access granted
data:
allOf:
- $ref: '#/components/schemas/DigitalAccess'
example:
_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'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
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
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
NotFound:
description: The record does not exist in this store.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 404
success:
type: boolean
example: false
message:
type: string
example: Product not found
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.