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 /v1/users/~current/skills/~current/inSkillProducts/{id}

Get voice purchasing status

GET /v1/users/~current/skills/~current/settings/voicePurchasing.enabled

Get voice purchasing transactions

GET /v1/users/~current/skills/~current/inSkillProductsTransactions?productId={productId}&status={status}&fromLastModifiedTime={fromLastModifiedTime}&toLastModifiedTime={toLastModifiedTime}&maxResults={maxResults}&nextToken={nextToken}

List in-skill products

GET /v1/users/~current/skills/~current/inSkillProducts

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

Copied to clipboard.

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

id

Path

Identifies the paid skill or in-skill product.
To get the entitlement status of a paid skill, set id to the skill ID.
To get the entitlement status of an in-skill product, set id to the product ID.

String

Yes

locale

Header

Set to the locale of the customer.
Format as: 2-letter language code, dash, 2-letter country/region code, for example, en-US. For valid string values, see Where can I offer paid skills and Locales that support in-skill products.

String

Yes

apiAccessToken

Header

Identifies the customer.
Use the token from stored customer information or theLaunchRequest or IntentRequest.

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

productId

Identifies the product. Guaranteed to be unique.

String

referenceName

The canonical name of the product. Use this name when referring to the product in code.
Valid length: 3 — 50 characters

String

name

Name of the product in the language provided in the locale request parameter.

String

type

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.
Valid values: CONSUMABLE, SUBSCRIPTION, ENTITLEMENT (one-time purchase).

String

summary

Description of the product in the language provided in the locale request parameter. You provided this summary during product creation.

String

purchasable

Indicates if the customer can purchase the product. NOT_PURCHASABLEmeans that the customer already owns the product.
Valid values: PURCHASABLE, NOT_PURCHASABLE.

String

entitled

Indicates if this customer can use the product.
Valid values: ENTITLED, NOT_ENTITLED.

String

entitledReason

Indicates the reason for the entitled status. When the customer is in a free trial or already purchased the product, the entitledReason is PURCHASED.
AUTO_ENTITLED means that the customer obtained the product as part of a promotion or other reason.
Valid values: PURCHASED, NOT_PURCHASED, AUTO_ENTITLED.

String

activeEntitlementCount

Number of purchased products. For a CONSUMABLE, activeEntitlementCount is the total number of times the customer purchased the product. This value doesn't reflect the customer's consumption of the purchased units. You must manage the customer's inventory separately. For a SUBSCRIPTION or ENTITLEMENT, this value is 0 or 1.

Integer

purchaseMode

Indicates whether the customer purchased the product during the live skill stage or during development stage. In development, the customer isn't charged.
Valid values: LIVE or TEST.

String

subscriptionId

(Valid for subscriptions only.) Uniquely identifies the subscription purchase.

String

startTime

(Valid for subscriptions only.) Indicates when the current subscription period started.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

endTime

(Valid for subscriptions only.) Indicates when the current subscription period ends.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

HTTP status codes

Status Description

200 OK

Response body contains the product and entitlement status.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

apiAccessToken

Header

Identifies the customer.
Use the token from stored customer information or theLaunchRequest or IntentRequest.

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

enabled

Indicates whether parental controls enabled voice purchasing.

Boolean

HTTP status codes

Status Description

200 OK

Response body contains voice purchasing status.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

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

Copied to clipboard.

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

productId

Query

Filter results by product.

String

No

status

Query

Filter results by purchasing status for in-skill products.
Valid values: PENDING_APPROVAL_BY_PARENT, APPROVED_BY_PARENT, DENIED_BY_PARENT, EXPIRED_NO_ACTION_BY_PARENT, ERROR.

String

No

fromLastModifiedTime

Query

Include results greater than or equal to the specified time.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

toLastModifiedTime

Query

Include results less than or equal to the specified time.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

No

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–100.

Number

No

nextToken

Query

Token from the previous response.
Include if iterating over a paginated response.

String

No

locale

Header

Set to the locale of the customer.
Format as: 2-letter language code, dash, 2-letter country/region code, for example, en-US. For valid string values, see Where can I offer paid skills and Locales that support in-skill products.

String

Yes

apiAccessToken

Header

Identifies the customer.
Use the token from stored customer information or theLaunchRequest or IntentRequest.

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

results

List of transactions that match the filter criteria.

Array of objects

results[].status

Purchasing status for the in-skill product.
Valid values: PENDING_APPROVAL_BY_PARENT, APPROVED_BY_PARENT, DENIED_BY_PARENT, EXPIRED_NO_ACTION_BY_PARENT, ERROR.

String

results[].productId

Identifies the in-skill product.

String

results[].createdTime

Time the purchase was initiated.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

results[].lastModifiedTime

Time at which the transaction status was last updated.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

metadata

(Optional) Included when there are more results to return. Use this value in a subsequent request.

Object

metadata.resultSet

Indicates the results are paginated.

Object

metadata.resultSet.nextToken

Include in the next request.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of transactions that match the filter criteria from the last 30 days.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

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

locale

Header

Set to the locale of the customer.
Format as: 2-letter language code, dash, 2-letter country/region code, for example, en-US. For valid string values, see Where can I offer paid skills and Locales that support in-skill products.

String

Yes

apiAccessToken

Header

Identifies the customer.
Use the token from stored customer information or theLaunchRequest or IntentRequest.

String

Yes

Request body example

Copied to clipboard.

{
  "purchasable": "PURCHASABLE",
  "entitled": "ENTITLED"
}

Request body properties

Property Description Type Required

purchasable

Include to filter the list of products based on whether a product is available for purchase by the customer.
Valid values: PURCHASABLE, NOT_PURCHASABLE.

String

No

entitled

Include to filter the list of products based on whether the customer purchased a product already.
Valid values: ENTITLED , NOT_ENTITLED.

String

No

productType

Include to filter the list of products based on the type of product.
Valid values: CONSUMABLE, SUBSCRIPTION, ENTITLEMENT.

String

No

nextToken

Include the nextToken value from the previous response to get the next page of products. If not included, the Alexa service returns the first page of results.
Include if iterating over a paginated response.

String

No

maxResults

Set the maximum number of results to return in the response. If there are additional results, the response contains isTruncated = true.
Valid values: 1–100.

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

inSkillProducts

List of available products for this skill, if any.

Array of objects

inSkillProducts[].productId

Identifies the paid skill or in-skill product. Guaranteed to be unique.

String

inSkillProducts[].referenceName

The canonical name of the product. Use this name when referring to the product in code. Valid for in-skill products only.
Valid length: 3 — 50 characters

String

inSkillProducts[].name

Name of the product in the language provided in the locale request parameter.

String

inSkillProducts[].type

Payment model.
A consumable is purchased, consumed, and purchased again. With a subscription, the customer owns the content for the period of the subscription. For a one-time purchase (entitlement), customer owns the content forever.
Valid values: CONSUMABLE, SUBSCRIPTION, ENTITLEMENT (one-time purchase).

String

inSkillProducts[].summary

Description of the skill or product in the language provided in the locale request parameter. You provided this summary during product creation.

String

inSkillProducts[].purchasable

Indicates if the customer can purchase the skill or product. If the customer already owns the skill or product, set to NOT_PURCHASABLE.
Valid values: PURCHASABLE, NOT_PURCHASABLE.

String

inSkillProducts[].entitled

Indicates if this customer can use the skill or product.
Valid values: ENTITLED, NOT_ENTITLED.

String

inSkillProducts[].entitledReason

Indicates the reason for the entitled status. When the customer is in a free trial or already purchased the skill or product, the entitledReason is PURCHASED.
AUTO_ENTITLED means that the customer obtained the skill or product as part of a promotion or other reason.
Valid values: PURCHASED, NOT_PURCHASED, AUTO_ENTITLED.

String

inSkillProducts[].activeEntitlementCount

Number of purchased products. For a CONSUMABLE, activeEntitlementCount is the total number of times the customer purchased the product. This value doesn't reflect the customer's consumption of the purchased units. You must manage the customer's inventory separately.
For a SUBSCRIPTION or ENTITLEMENT, this value is 0 or 1.

Integer

inSkillProducts[].purchaseMode

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.
Valid values: LIVE or TEST.

String

inSkillProducts[].subscriptionId

(Valid for subscriptions only.) Uniquely identifies the subscription purchase.

String

inSkillProducts[].startTime

(Valid for subscriptions only.) Indicates when the current subscription period started.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

inSkillProducts[].endTime

(Valid for subscriptions only.) Indicates when the current subscription period ends.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

isTruncated

Indicates whether there are more items to return. If set to true, include nextToken a subsequent request.

Boolean

nextToken

(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

200 OK

Response body contains the list of in-skill products available for purchase.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

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.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.


Was this page helpful?

Last updated: Aug 01, 2024