Monetization REST API Reference
Use the Monetization REST API to view paid skills and in-skill products that the customer purchased already and to get in-skill products available to the customer to purchase. You can use this API in your paid skill and in custom skills that include in-skill purchasing (ISP).
If you want to manage your in-skill products, use the In-Skill Product Management API to view and update your product definitions. For more details, see In-Skill Product Management REST API Reference.
API endpoint
Use one of the following API hosts, based on the region where the customer is located:
- North America:
https://api.amazonalexa.com - Europe:
https://api.eu.amazonalexa.com - Far East:
https://api.fe.amazon.com
You can find the API endpoint in the context.System.apiEndpoint retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.
Authentication
Each API request must have an authorization header whose value is
set to the token stored with the customer information or to the apiAccessToken property of the System object from the LaunchRequest or IntentRequest.
Operations
The Monetization API includes the following operations.
| Operation | HTTP method and URI |
|---|---|
|
| |
|
| |
|
| |
|
|
Get customer entitlement
Get the entitlement status of the specified paid skill or in-skill product for the specified customer. Use the status to determine whether to invoke the purchase flow or to continue with paid content.
Request
To get the entitlement status, you make a GET request to the inSkillProducts resource.
Request header example
GET /v1/users/~current/skills/~current/inSkillProducts/{id}
Host: api.amazonalexa.com
Accept-Language: {locale}
Authorization: Bearer {apiAccessToken}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the paid skill or in-skill product. |
String |
Yes |
|
|
Header |
Set to the locale of the customer. |
String |
Yes |
|
|
Header |
Identifies the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with the entitlement status of the specified paid skill or in-skill product. Use the response to determine whether to make a purchase suggestion or to continue with paid content.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
This interface returns ENTITLED if the customer purchased the skill, or if a free trial is in progress. If the free trial expired, the customer canceled the subscription, or the customer hasn't purchased the skill, the interface returns NOT_ENTITLED and an indication of whether the customer can purchase the skill.
Response body examples
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Identifies the product. Guaranteed to be unique. |
String |
|
|
The canonical name of the product. Use this name when referring to the product in code. |
String |
|
|
Name of the product in the language provided in the |
String |
|
|
Payment model. A consumable is purchased, consumed, and purchased again. With a subscription, the customer owns the content for the period of the subscription. The customer owns the content of an entitlement forever. |
String |
|
|
Description of the product in the language provided in the |
String |
|
|
Indicates if the customer can purchase the product. |
String |
|
|
Indicates if this customer can use the product. |
String |
|
|
Indicates the reason for the entitled status. When the customer is in a free trial or already purchased the product, the |
String |
|
|
Number of purchased products. For a |
Integer |
|
|
Indicates whether the customer purchased the product during the live skill stage or during development stage. In development, the customer isn't charged. |
String |
|
|
(Valid for subscriptions only.) Uniquely identifies the subscription purchase. |
String |
|
|
(Valid for subscriptions only.) Indicates when the current subscription period started. |
String |
|
|
(Valid for subscriptions only.) Indicates when the current subscription period ends. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the product and entitlement status. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get voice purchasing status
Determine whether parents enabled voice purchasing for kid skills.
Request
To get the status of voice purchasing, you make a GET request to the setting resource.
Request path and header example
GET /v1/users/~current/skills/~current/settings/voicePurchasing.enabled
Host: api.amazonalexa.com
Authorization: Bearer {apiAccessToken}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Header |
Identifies the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with the voice purchasing enablement status.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"enabled": true
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
Indicates whether parental controls enabled voice purchasing. |
Boolean |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains voice purchasing status. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get voice purchasing transactions
Get voice purchasing transactions by date or transaction status. Valid for kid skills where parents enabled voice purchasing with parental approval.
Request
To get the voice purchasing transactions, you make a GET request to the inSkillProductsTransactions resource.
Request path and header example
GET /v1/users/~current/skills/~current/inSkillProductsTransactions?productId={productId}&status={status}&fromLastModifiedTime={fromLastModifiedTime}&toLastModifiedTime={toLastModifiedTime}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Accept-Language: {locale}
Authorization: Bearer {apiAccessToken}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Query |
Filter results by product. |
String |
No |
|
|
Query |
Filter results by purchasing status for in-skill products. |
String |
No |
|
|
Query |
Include results greater than or equal to the specified time. |
String |
No |
|
|
Query |
Include results less than or equal to the specified time. |
String |
No |
|
|
Query |
Maximum number of results to return in the response. |
Number |
No |
|
|
Query |
Token from the previous response. |
String |
No |
|
|
Header |
Set to the locale of the customer. |
String |
Yes |
|
|
Header |
Identifies the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with a list of transactions that match the filter criteria from the last 30 days.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
The following example shows the transactions for three products from most recent to oldest.
{
"results": [{
"status": "PENDING_APPROVAL_BY_PARENT",
"productId": "amzn1.ask.skill.3",
"createdTime": "2018-11-23T11:21:10.52Z",
"lastModifiedTime": "2018-11-23T11:21:10.52Z"
},
{
"status": "EXPIRED_NO_ACTION_BY_PARENT",
"productId": "amzn1.ask.skill.3",
"createdTime": "2018-11-20T12:23:10.52Z",
"lastModifiedTime": "2018-11-21T12:23:10.52Z"
},
{
"status": "DENIED_BY_PARENT",
"productId": "amzn1.ask.skill.2",
"createdTime": "2018-11-15T11:03:07.52Z",
"lastModifiedTime": "2018-11-15T11:03:08.52Z"
},
{
"status": "APPROVED_BY_PARENT",
"productId": "amzn1.ask.skill.1",
"createdTime": "2018-11-14T22:21:00.52Z",
"lastModifiedTime": "2018-11-14T22:22:00.52Z"
}
],
"metadata": {
"resultSet": {
"nextToken": "someToken.1"
}
}
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
List of transactions that match the filter criteria. |
Array of objects |
|
|
Purchasing status for the in-skill product. |
String |
|
|
Identifies the in-skill product. |
String |
|
|
Time the purchase was initiated. |
String |
|
|
Time at which the transaction status was last updated. |
String |
|
|
(Optional) Included when there are more results to return. Use this value in a subsequent request. |
Object |
|
|
Indicates the results are paginated. |
Object |
|
|
Include in the next request. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of transactions that match the filter criteria from the last 30 days. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List in-skill products
Gets a list of in-skill products available for purchase in this skill.
For each product, the interface returns ENTITLED if the customer purchased the product, or if a free trial is in progress. If the customer cancels the subscription, depletes the consumable, or hasn't purchased the product, the interface returns NOT_ENTITLED and an indication of whether the customer can purchase the product.
Request
To retrieve a list of available products, you make a GET request to the inSkillProducts resource.
Request header example
GET /v1/users/~current/skills/~current/inSkillProducts
Host: api.amazonalexa.com
Accept-Language: {locale}
Authorization: Bearer {apiAccessToken}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Header |
Set to the locale of the customer. |
String |
Yes |
|
|
Header |
Identifies the customer. |
String |
Yes |
Request body example
{
"purchasable": "PURCHASABLE",
"entitled": "ENTITLED"
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Include to filter the list of products based on whether a product is available for purchase by the customer. |
String |
No |
|
|
Include to filter the list of products based on whether the customer purchased a product already. |
String |
No |
|
|
Include to filter the list of products based on the type of product. |
String |
No |
|
|
Include the |
String |
No |
|
|
Set the maximum number of results to return in the response. If there are additional results, the response contains |
Number |
No |
Response
A successful response returns HTTP 200 OK, along with the list of in-skill products. Use the response to determine whether to make a purchase suggestion or to continue with paid content. Only offer products to the customer with purchasable = PURCHASABLE.
On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.
Response body example
{
"inSkillProducts": [
{
"productId": "amzn1.adg.product.1",
"referenceName": "your_product_name_1",
"type": "ENTITLEMENT",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "NOT_ENTITLED",
"entitledReason": "NOT_PURCHASED",
"purchasable": "PURCHASABLE",
"activeEntitlementCount": 0,
"purchaseMode": "LIVE"
},
{
"productId": "amzn1.adg.product.2",
"referenceName": "your_product_name_2",
"type": "SUBSCRIPTION",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "ENTITLED",
"entitledReason": "PURCHASED",
"purchasable": "NOT_PURCHASABLE",
"activeEntitlementCount": 1,
"purchaseMode": "LIVE",
"subscriptionId": "2273c794797f4367a45c3b6c2b56416f797f4367a45c3b6c2b56",
"startTime": "2022-05-01T00:00:00Z",
"endTime": "2022-05-31T00:00:00Z"
},
{
"productId": "amzn1.adg.product.3",
"referenceName": "your_product_name_3",
"type": "CONSUMABLE",
"name": "Friendly Name",
"summary": "Description of the product.",
"entitled": "ENTITLED",
"entitledReason": "PURCHASED",
"purchasable": "PURCHASABLE",
"activeEntitlementCount": 2,
"purchaseMode": "LIVE"
}
],
"isTruncated": false
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
List of available products for this skill, if any. |
Array of objects |
|
|
Identifies the paid skill or in-skill product. Guaranteed to be unique. |
String |
|
|
The canonical name of the product. Use this name when referring to the product in code. Valid for in-skill products only. |
String |
|
|
Name of the product in the language provided in the |
String |
|
|
Payment model. |
String |
|
|
Description of the skill or product in the language provided in the |
String |
|
|
Indicates if the customer can purchase the skill or product. If the customer already owns the skill or product, set to |
String |
|
|
Indicates if this customer can use the skill or product. |
String |
|
|
Indicates the reason for the entitled status. When the customer is in a free trial or already purchased the skill or product, the |
String |
|
|
Number of purchased products. For a |
Integer |
|
|
Indicates whether the customer purchased the skill or product during the live skill stage or during development stage. In development, the customer isn't charged. |
String |
|
|
(Valid for subscriptions only.) Uniquely identifies the subscription purchase. |
String |
|
|
(Valid for subscriptions only.) Indicates when the current subscription period started. |
String |
|
|
(Valid for subscriptions only.) Indicates when the current subscription period ends. |
String |
|
|
Indicates whether there are more items to return. If set to |
Boolean |
|
|
(Optional) Included when there are more results to return. Use this value in a subsequent request. The token expires in 24 hours. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the list of in-skill products available for purchase. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
Last updated: Aug 01, 2024