App Integrations v2024-04-01 Use Case Guide

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

1. Sign in to Seller Central using the appropriate URL for your marketplace.

2. Navigate to the Developer Console.

3. Choose Action, then choose App Integration.

4. Choose Create a notification template.

5. 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:

• 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.

6. After you have completed the notification template form, choose Preview.

7. 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.

8. 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

1. On the App Integration page, choose the Draft tab.

2. Select the notification templates that are ready for submission. You can select up to 10 notification templates.

3. 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.

1. Sign in to Seller Central using the appropriate URL for your marketplace.

2. Navigate to Develop Apps.

3. In the Developer Console, choose Action, then choose App Integration.

4. On the App Integration page, choose In Review.

5. Check that your submitted notification template is marked as Submitted. You can preview a submitted template, but you can't edit it.

6. 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

1. 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.

2. 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

❗

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

1. Call the deleteNotifications operation and pass the following parameters:

Body parameters

❗

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

Call the recordActionFeedback operation and pass the following parameters:

Body parameters

❗

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

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

Status code: 200
{
  "notificationId": "174ec9ce-4c66-4208-ac92-46e22a925aa2"
}

Unsuccessful request example

Request example for 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

Status code: 400
{
  "errors": [
    {
        "code": "InvalidInput",
        "message": "Invalid input.",
        "details": "Bad request"
    }
  ]
}

Internal server error example

Request example for 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": ""
    }
  ]
}