Ensuring healthy seller account status

by Jiang G., Solutions Architect, Selling Partner Developer Services | October 11, 2022

Developers who manage seller accounts should be aware of the possibility that an unhealthy seller account status can cause API calls to fail. This blog post discusses the importance of having a healthy seller account status for SP-API calls and the relationship between account health status and SP-API errors. This blog post also covers the step-by-step the process for detecting whether an unhealthy account status is causing SP-API errors and the mechanism of using APIs to monitor the account status.

This topic is particularly important for third-party developers with a significant number of users. An unhealthy status indicates that developers may need to debug the API or reach out to sellers and ask for a check-up on their Seller Central account status.

Why account health status matters

Accounts are fundamental component of the Amazon Seller platform. Sellers are responsible for ensuring a healthy status for their accounts in each marketplace they participate in, and developers often help with this responsibility.

When SP-API authorization is utilized, an application can proceed with account operation on behalf of a seller. When utilizing feature compatibility between SP-API and Seller Central, developers should remember while assisting sellers, that a healthy account status is required for a successful API call. An unhealthy account status or an account issue, will leave sellers unable to use some features within Seller Central and SP-API.

Determining health status

The first step is to determine whether the account is healthy or not.
Indicators of an unhealthy account status include:

• Inactive or suspended account
• Verification required for credit cards.
• Low score for the Account Health Rating.

In addition to these indicators, you’ll also want to check for any API error messages.

Receiving an API error

Selling Partner APIs provide error messages that help you trace errors. Both account issues and incorrect API calls can cause an error, but how do you determine what caused your error?

In the following example, the 400 error response from the createFeed API was caused by an inactive account issue.

{
  "errors": [
    {
      "code": "InvalidInput",
      "message": "Invalid request parameters",
      "details": ""
    }
  ]
}

In this case, an incorrect API call is likely to blame, rather than an account issue. However, the issue is caused by the inactive account issue and the seller needs to check their account status in this marketplace. Keep in mind that createFeedDocument does not return an error until a request is made for the createFeed API call.

The next step is to figure out what’s causing the API error. The following section discusses the steps to determine the source of the error.

Troubleshooting

When you receive an API error message, you’ll want to determine if it was caused by an account issue.

Start by checking the following conditions:

1. Is there an issue with the request itself?
2. Are all sellers having the same issue?
3. Is the seller active in the designated marketplace?

The following flow chart can help you determine the most suitable course of action.

Determining the cause of an API error

When you receive an API error, and the error message does not contain enough information to help detect the issue immediately, the first thing to check is the HTTP status code. A status code of 200 means the API call was successful. If the status code is a 400 or 500 class, the API call has failed.

As an example, the getOrders API returns a 200 class but the response is an empty list. In this case, the API call was successful.

To fetch the correct API response, check the relevant request parameters. For example, check whether the date range specified in the query parameter is supposed to have no orders.

The 500 class reveals an internal server error indicating that the Amazon server failed to fulfill a request. However, for some specific APIs, such as in case of the getListingOffersBatch API, if the wrong URI parameter is presented in the request body, the response will be 500 instead of 400.

Other blog posts cover troubleshooting and optimization strategies related to 429 and 403 HTTP status codes. Here are a few:

• Strategies to optimize rate limits for your application workloads
• Troubleshooting Selling Partner API authorization errors

If you still don’t know the solution, you’ll want to check roles and tokens next.

Step 1: Check roles and tokens

After confirming the error, if the error code and messages don't provide solutions, the first step is to check with the engineering team to see if any recent code changes could have led to an API call failure. Especially when using a new API, don’t forget to check parameters for the role and tokens.

Roles

When checking role parameters, make sure an application has the correct role for the API call. For example, some analytical reports for brand owners require the Brand Analytics role and the Direct to Consumer Shipping role is required to fetch shipping address and buyer information.

Make sure the role is applied to both the developer profile and the application. A 403 error may be returned if the role is not set up correctly.

Access tokens

Next, you'll want to check the access tokens. There are three major types of access tokens that are based on the type of API request.

• The access token

The access token is the most commonly used access token for SP-API calls. If you include the refreshToken key in the query parameter of the LWA operation, then the access token will appear in the response.

• Access token for Grantless operations

The access token for Grantless operations is only used for grantless operations and Authorization API.

Be sure to include the scope parameter in the query parameter of the LWA operation, specifying either SCOPE_NOTIFICATIONS_API for the Notifications API or SCOPE_MIGRATION_API for the Authorization API.

• Restricted Data Token

A Restricted Data Token (RDT) is only used to fetch Personal Identifiable Information (PII) data, such as shipping address, buyer name, or tax-related information.

An RDT can only be fetched via the Tokens API. For example, if a developer needs to fetch shipping address information from the getOrders API response, the developer should first use the access token to request an RDT via theTokens API, and then use the RDT from the response as the access token to call the getOrders API.

When adopting a new API, the best practice is to use Postman and start with a simple API call with the minimal parameters. You’ll want to keep required parameters and remove optional parameters as much as possible. Make sure the API call is successful, and then add options one by one to avoid conflicting optional parameters.

After checking the roles and tokens, you’ll want to check the paths.

Step 2: Check paths

Checking paths is a critical step in distinguishing whether an error originates from seller account issues.

In order to know whether all sellers are receiving the same error, we recommend constantly logging the following information for each HTTP request.

• Resource path
• Status code
• Error message
• Seller ID (merchant ID)
• Marketplace ID

By logging this information, you will have records that can be reviewed at any time to help you determine issues with account health. This marketplace information will be used in step 3 as well.

When an error occurs, check the API resource path to identify the API operation, then filter out the log for this resource path to determine how many sellers have an error status.

If a service is having backend issues, the error will return for all sellers. It can be deduced that the error is caused by an account issue if only one seller, or a limited group of sellers, is receiving the error message. If only some sellers are getting an error message, you'll likely need to do more debugging to find the issue. By comparing the number of occurrences of the same error, you can roughly determine whether the next troubleshooting step is to continue to step 3 or to reach out to sellers.

Step 3: Determining the affected marketplace

In steps 1 and 2, you confirmed whether the API was correctly requested and whether other sellers are facing the same error. The final step is to check which marketplace the seller participates in, for the account throwing the error. This step is particularly essential for global selling partners.

Developers should note that sellers may have independent accounts per marketplace, which means that the account issue is limited and will only affect one marketplace. For example, suppose a seller calls Authorization API but has an inactive account status in only one marketplace. In this case, the API will return an Invalid partyIds: {MERCHANT_ID} error message for this marketplace, with an inactive account status. For all other marketplaces, the API will return a 200 class.

It can be challenging to manage multiple accounts and therefore API call failures can also come from sellers providing incorrect account information unintentionally. To determine which marketplaces sellers are participating in, call the getMarketplaceParticipations API.

If you see any of the following responses, please double-check with the seller regarding their account in this marketplace, or ask them to re-authorize:

• A 403 Unauthorized error.
• The expected marketplace is not included in the response.
• The value of the isParticipating field in this marketplace is false.

The following is a sample response for the FE region:

{
     "payload": [
        {
             "marketplace": {
                "id": "A1VC38T7YXB528",
                 "countryCode": "JP",
                 "name": "Amazon.co.jp",
                 "defaultCurrencyCode": "JPY",
                 "defaultLanguageCode": "ja_JP",
                 "domainName": "www.amazon.jp (http://www.amazon.jp/)“
             },
             "participation": {
                 "isParticipating": true,
                 "hasSuspendedListings": false
             }
        },
         {
             "marketplace": {
                 "id": "A1VN0HAN483KP2",
                 "countryCode": "JP",
                 "name": "Non-Amazon",
                 "defaultCurrencyCode": "JPY",
                 "defaultLanguageCode": "ja_JP",
                 "domainName": "jp-shipment-injection.stores.amazon.co.jp"
             },
             "participation": {
                 "isParticipating": true,
                 "hasSuspendedListings": false
             }
         }
     ]
}

You should also check whether the API is available for the marketplace, especially for Reports API, Feeds API and Notifications API operations, because not all resource paths are available for every marketplace.

To determine which marketplace an API supports, refer to the Feeds Type, Reports Type and the Notification Type documentation.

If you’re receiving errors, you’re likely wondering how you can prevent them from occurring. One way to help prevent account issues is to set up APIs to help you monitor account health.

Using APIs to prevent account issues

As a developer, knowing whether a seller has an account issue before the API call is made is helpful for preventing unnecessary API errors. There are two APIs you can request to periodically monitor an account’s status.

• ACCOUNT_STATUS_CHANGED Notification Type API
  A notification is sent whenever the account status changes for seller/marketplace pairs. By implementing this notification type, developers will receive a notification whenever the merchant's account status changes between NORMAL, AT_RISK, or DEACTIVATED. Go to Seller Account Information from Seller Central if notified that the currentAccountStatus is not NORMAL.

• GET_V2_SELLER_PERFORMANCE_REPORT Report Type API
  This report type contains individual performance metrics data from the Seller Central Account Health dashboard. The response will be similar to the following example, but you shouldn’t rely on this format.

{
   "accountStatuses":[
      {
         "marketplaceId":"A1VC38T7YXB528",
         "status":"NORMAL"
      }
   ],
   "performanceMetrics":[
      {
         "lateShipmentRate":{},
         "invoiceDefectRate":{},
         "orderDefectRate":{
            "afn":{},
            "mfn":{}
         },
         "onTimeDeliveryRate":{},
         "validTrackingRate":{},
         "preFulfillmentCancellationRate":{},
         "warningStates":[],
         "accountHealthRating":{},
         "listingPolicyViolations":{},
         "productAuthenticityCustomerComplaints":{},
         "productConditionCustomerComplaints":{},
         "productSafetyCustomerComplaints":{},
         "receivedIntellectualPropertyComplaints":{},
         "restrictedProductPolicyViolations":{},
         "suspectedIntellectualPropertyViolations":{},
         "foodAndProductSafetyIssues":{},
         "customerProductReviewsPolicyViolations":{},
         "otherPolicyViolations":{},
         "documentRequests":{},
         "marketplaceId":"A1VC38T7YXB528"
      }
   ]
}

Periodically call the GET_V2_SELLER_PERFORMANCE_REPORT and check the first level of the performanceMetrics object. It includes account metrics and each metric contains status information.

If any metrics are not in GOOD status, check the seller’s account status in Seller Central for further information. Check out the Reports API User Guide for more information on adopting this API.

By combining use of the ACCOUNT_STATUS_CHANGED and GET_V2_SELLER_PERFORMANCE_REPORT APIs with the Sellers API, you can determine which marketplaces the seller participated in, whether the account is active in this marketplace, and whether there are any indications of poor account performance.

The following flow chart outlines the best practice for system design in regards to preventing account issues.

Conclusion

As you now know, seller account statuses will affect the API call and may lead to an API error. This blog post explained why account health is important for SP-API calls and how you can detect whether the account issue caused an error by checking data points. Following the steps covered in this blog post and utilizing the Notifications API and Reports API will help you diagnose the account status relatively early and help you keep the account healthy.

👍

Have feedback on this post?

If you have questions or feedback on this post, we'd like to hear from you! Please vote and leave a comment using the tools at the bottom of this page.

Subscribe to updates via RSS feed.