Ensuring healthy seller account status
Seller account maintenance for maintaining a healthy status for SP-API calls
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:
- Is there an issue with the request itself?
- Are all sellers having the same issue?
- 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 betweenNORMAL
,AT_RISK
, orDEACTIVATED
. Go to Seller Account Information from Seller Central if notified that thecurrentAccountStatus
is notNORMAL
. -
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.
Updated 3 months ago