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

The endpoint of the Monetization API is the Alexa endpoint stored with your customer information or the apiEndpoint property of the System object from 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}

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: {apiEndpoint}
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

apiEndpoint

Header

Set to the apiEndpoint property of the System object from the request.

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 (enum)

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. If the customer already owns the product, set to NOT_PURCHASABLE.
Valid values: PURCHASABLE or NOT_PURCHASABLE.

String (enum)

entitled

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

String (enum)

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 skill as part of a promotion or other reason. Valid values: PURCHASED, NOT_PURCHASED, AUTO_ENTITLED.

String (enum)

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 (enum)

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 Success

Returns the product and entitlement status.

400 Invalid Request

Indicates the request is invalid. The response body might include a specific error message that indicates why the request is invalid.

401 Unauthorized

The request didn't include the access token, the token is invalid or expired, or the skill doesn't have permission to make the request.

404 Not Found

A product with the specified ID not found. This error might happen if you published an updated version of the product and the product isn't available in production.

500 Server Error

An error occurred on the server. The skill can retry by using exponential back-off.

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: {apiEndpoint}
Accept-Language: {locale}
Authorization: Bearer {apiAccessToken}

Request path and header parameters

Parameter Located in Description Type Required

apiEndpoint

Header

Set to the apiEndpoint property of the System object from the request.

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

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",
      "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",
      "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": "NOT_ENTITLED",
      "purchasable": "PURCHASABLE",
      "activeEntitlementCount": 0,
      "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 or NOT_PURCHASABLE.

String

inSkillProducts[].entitled

Indicates if this customer can use the skill or product.
Valid values: ENTITLED or 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 Success

Returns the product list.

400 Invalid Request

Indicates the request is invalid. The response body might include a specific error message that indicates why the request is invalid.

401 Unauthorized

The request didn't include the access token, the token is invalid or expired, or the skill doesn't have permission to make the request.

500 Server Error

An error occurred on the server. The skill can retry by using exponential back-off.


Last updated: May 25, 2023