App Integrations v2024-04-01 Use Case Guide
How to use the App Integrations API v2024-04-01.
API Version: 2024-04-01
What is the App Integrations API v2024-04-01?
You can use the Selling Partner API for App Integrations to send targeted notifications to sellers. For example, you can send notifications to inform the seller about their business or to encourage the seller to take action on your website. The notification message is displayed on the notification banner in Seller Central. You can also track seller engagement with published notifications.
Important
The following notification content is not permitted:
- Notifications that name a non-Amazon sales channel. You can provide details or a summary of a non-Amazon channel, but not the channel name.
- Promotional notifications that invite the seller to adopt new products or features that:
- Incur additional costs or fees.
- Are not part of what the seller has already signed up for.
- Don't relate to the seller's business needs.
Key features
- Post notifications that are critical to your application and your selling partner's business in Seller Central.
- Delete notifications that are incorrect or outdated.
- Use notifications to track seller engagement activity.
Terminology
- Notification: The message that is displayed on the notifications banner in Seller Central. Each notification consists of a notification template and can optionally include dynamic notification parameters.
- Notification template: A template that contains static content and dynamic parameter placeholders.
- Notification parameter: Dynamic parameters that are required to fully construct a notification template.
- Template type: A unique identifier for your notification template.
Tutorial: Set up your notification template
Prerequisites:
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API Applications.
- The Notifications in Seller Central role assigned to your developer profile.
- The Notifications in Seller Central role selected in the App Registration page for your application.
Step 1. Create your notification template draft
-
Sign in to Seller Central using the appropriate URL for your marketplace.
-
Navigate to the Developer Console.
-
Choose Action, then choose App Integration.
-
Choose Create a notification template.
-
On the notification template form, add the following information:
- Source language for template: Select the language used to provide the listing information.
- Template type: Input the name of your notification template. Format the identifier using all capital letters, with an underscore to separate words. For example,
RESTOCK_LOW_INVENTORY
. - Template content: Specify the message that is displayed in the notification to the seller. This message must include between one and five parameters. Limit your message to 250 characters.
- Parameters: Specify the parameters and their supported types.
The following types of parameters are supported:
Parameter type | Description | Example of a valid value | |
---|---|---|---|
number | Integers or floating point numbers | 5, 100.50 | |
date | The date in YYYY-MM-DD format | 2022-07-30 | |
ASIN (enum) | The ASIN value | B09ZX1LRXX |
-
Template CTA URL: Specify the URL that relates to the seller's call-to-action. This section is required. If you do not have a URL that relates to the seller's call-to-action, populate this field with the URL to your website.
-
Expected action from sellers: Choose the action that the seller is expected to take based on the notification. Select the option that applies to your notification.
-
Template topic: Choose the template type category. Select the option that applies to your notification. If none of the options apply, select Other and provide a category name.
- Template topic - Other: Provide a category name.
-
Template granularity level: Choose whether you want your template available at the marketplace level or the regional level. If you don't specify, your template defaults to the regional level. For a list of supported regions and marketplaces, refer to Marketplace IDs.
Important
Do not use HTML reserved characters (
"
,'
,&
,<
, or>
) in any description. Including these characters delays the publishing of your notification.
-
After you have completed the notification template form, choose Preview.
-
On the Preview tab, review the notification for any errors. To make edits, close the Preview tab, and choose Edit on the notification template form.
-
After you edit your template, choose Save to save your edits.
Example notification templates
The following example shows a template for the fictitious RESTOCK_LOW_INVENTORY
notification type.
Template type: RESTOCK_LOW_INVENTORY
Template content: You have ${NumberofProducts} products running low on inventory. Restock your inventory by clicking here.
Parameters: numberOfProducts: number
Template CTA URL: -
Sample content: You have 5 products running low on inventory. Restock your inventory by clicking here.
Marketplace or region: -
Expected action from seller: -
Template topic: -
The following example shows a template for the fictitious SALES_SUMMARY
notification type.
Template type: SALES_SUMMARY
Template content: Your sales summary as of ${summaryAsOnDate} is ${salesSummaryInUSD} USD
Parameters: summaryAsOnDate: date
salesSummaryInUSD: number
Template CTA URL: -
Sample content: Your sales summary as of 2022-08-30 is 1000.50 USD
Marketplace or region: -
Expected action from seller: -
Template topic: -
Step 2. Submit your notification template for review
-
On the App Integration page, choose the Draft tab.
-
Select the notification templates that are ready for submission. You can select up to 10 notification templates.
-
Choose Submit for review.
Step 3. Check the status of your notification template
The notification template publishing process includes review and translation. You can track the status of your template on the Developer Console.
-
Sign in to Seller Central using the appropriate URL for your marketplace.
-
Navigate to Develop Apps.
-
In the Developer Console, choose Action, then choose App Integration.
-
On the App Integration page, choose In Review.
-
Check that your submitted notification template is marked as Submitted. You can preview a submitted template, but you can't edit it.
-
After Amazon approves and translates the template, navigate to the Developer Console and choose App Integrations. Then, choose Published.
Tip
If your template is not approved, feedback is provided with your template submission on the Drafts tab. Address the feedback and resubmit your template for review.
Step 6. Launch your new notification template
-
After your template is published, relist your application in the Selling Partner Appstore. After your application is relisted, Amazon grants you a Notifications in Seller Central badge.
-
Send notifications using the App Integrations API v2024-04-01.
Tutorial: Send a notification
Learn how to send a notification to sellers.
Prerequisites:
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API Applications.
- The Notifications in Seller Central role assigned to your developer profile.
- The Notifications in Seller Central role selected in the App Registration page for your application.
- A notification template for your app.
Step 1. Create a notification
Call the createNotification
operation and pass the following parameters:
Body parameters
Parameter | Description | Required |
---|---|---|
templateId | The notification template type identifier provided by developer during template onboarding. (for example, PRICE_CHANGE )Type: string | Yes |
notificationParameters | The request schema for the notificationsParameter operation.Type: CreateNotificationRequest | Yes |
marketplaceId | The encrypted marketplace identifier for the notification. Type: string | Yes |
Warning
The parameters in the API request body must be the same as the parameters in your notification template.
Request example
The following request example uses the example notification template, PRICE_CHANGE
.
POST https://sellingpartnerapi-na.amazon.com/appIntegrations/2024-04-01/notifications
{
"templateId": "PRICE_CHANGE",
"marketplaceId": "ATVPDKIKX0DER",
"notificationParameters": {}
}
Response
A successful response includes the unique notification ID.
Response example
Status code: 200
{
"notificationId": "47f05db0-03fe-11ed-b939-0242ac120002"
}
Tutorial: Delete your notifications from the Selling Partner Appstore notifications dashboard
Learn how to delete business-specific notifications that you previously sent to sellers.
Prerequisites:
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API Applications.
- The Notifications in Seller Central role assigned to your developer profile.
- The Notifications in Seller Central role selected in the App Registration page for your application.
- A notification template for your app.
Step 1. Delete a notification
- Call the
deleteNotifications
operation and pass the following parameters:
Body parameters
Parameter | Description | Required |
---|---|---|
templateId | The notification template type identifier provided by developer during template onboarding. (For example, PRICE_CHANGE_INVALID )Type: string | Yes |
DeletionReason | The request schema for the notificationsParameter operation.Type: enum ( INCORRECT_CONTENT ,INCORRECT_RECIPIENT ) | Yes |
Warning
The parameters in the API request body must be the same as the parameters in your notification template.
Request example
POST https://sellingpartnerapi-na.amazon.com/appIntegrations/2024-04-01/notifications/deletion
{
"templateId": "PRICE_CHANGE_INVALID",
"deletionReason": "INCORRECT_RECIPIENT"
}
Response
A successful response includes the unique notification ID.
Response example
Status code: 200
{
"notificationId": "47f05db0-03fe-11ed-b939-0242ac120002"
}
Tutorial: Record notification feedback from seller
Learn how to record the action that the seller takes after viewing the notification.
Prerequisites:
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API Applications.
- The Notifications in Seller Central role assigned to your developer profile.
- The Notifications in Seller Central role selected in the App Registration page for your application.
- A notification template for your app.
Step 1. Retrieve the FeedbackActionCode
FeedbackActionCode
Call the recordActionFeedback
operation and pass the following parameters:
Body parameters
Parameter | Description | Required |
---|---|---|
notificationId | The unique ID assigned to a notification. Type: string | Yes |
FeedbackActionCode | The unique ID for each notification status. Type: enum ( SELLER_ACTION_COMPLETED ) | Yes |
Warning
The parameters in the API request body must be the same as the parameters in your notification template.
Request example
POST https://sellingpartnerapi-na.amazon.com/appIntegrations/2024-04-01/notificaitons/:notificationId/feedback
{
"feedbackActionCode": "SELLER_ACTION_COMPLETED"
}
Response
A successful response includes the unique notification ID.
Response example
Status code: 200
{
"notificationId": "47f05db0-03fe-11ed-b939-0242ac120002"
}
Tutorial: Test notification template types in the sandbox
You can use the Selling Partner API sandbox to test template types and response payloads. The following examples demonstrate a successful request, an unsuccessful request, and a request that returns an internal server error.
Successful request example
Request example for SALES_SUMMARY
SALES_SUMMARY
The following request example uses the example notification template, SALES_SUMMARY
.
POST https://https://sellingpartnerapi-na.amazon.com/appIntegrations/2024-04-01/notifications/SALES_SUMMARY
{
"templateId":"SALES_SUMMARY",
"notificationParameters":{
"summaryAsOnDate":"2022-08-30",
"salesSummaryInUSD":1000.50
}
}
Response example for SALES_SUMMARY
SALES_SUMMARY
Status code: 200
{
"notificationId": "174ec9ce-4c66-4208-ac92-46e22a925aa2"
}
Unsuccessful request example
Request example for BAD_REQUEST_TYPE
BAD_REQUEST_TYPE
The following request example uses the example notification template, BAD_REQUEST_TYPE
.
POST https://https://sellingpartnerapi-na.amazon.com/appIntegrations/2024-04-01/notifications/BAD_REQUEST_TYPE
{
"notificationParameters": {
"summaryAsOnDate": "2022-08-30",
"salesSummaryInUSD": 1000.50
}
}
Unsuccessful response example for BAD_REQUEST_TYPE
BAD_REQUEST_TYPE
Status code: 400
{
"errors": [
{
"code": "InvalidInput",
"message": "Invalid input.",
"details": "Bad request"
}
]
}
Internal server error example
Request example for INTERNAL_SERVER_ERROR_TYPE
INTERNAL_SERVER_ERROR_TYPE
The following request example uses the example notification template, INTERNAL_SERVER_ERROR
.
POST https://https://sellingpartnerapi-na.amazon.com/appIntegrations/2024-04-01/notifications/INTERNAL_SERVER_ERROR_TYPE
{
"notificationParameters": {
"summaryAsOnDate": "2022-08-30",
"salesSummaryInUSD": 1000.50
}
}
Internal server error response example
Status code: 500
{
"errors": [
{ "code": "InternalFailure",
"message": "We encountered an internal error. Please try again.",
"details": ""
}
]
}
Updated about 1 month ago