Custom n8n node for the Amazon Selling Partner API
npm install n8n-nodes-amazon-selling-partnerA production-grade n8n custom node for Amazon Selling Partner API with comprehensive error handling, rate limiting, monitoring, and security features.
/dataKiosk/2023-11-15, poll status, and download resultsbash
npm install n8n-nodes-amazon-selling-partner
`$3
1. Go to Settings > Community Nodes in your n8n instance
2. Search for n8n-nodes-amazon-selling-partner
3. Click InstallSetup
$3
1. Register as a developer in the Amazon Developer Console
2. Create a new SP-API application
3. Obtain your LWA credentials (Client ID, Client Secret)
4. Generate a refresh token through the authorization workflow$3
#### Basic Setup (Recommended)
For most use cases, you only need LWA credentials:
1. In n8n, create a new Amazon Selling Partner API credential
2. Fill in the required fields:
- Environment: Choose Sandbox for testing, Production for live data
- AWS Region: Select your application's region
- LWA Client ID: From your SP-API application
- LWA Client Secret: From your SP-API application
- LWA Refresh Token: Generated during authorization
#### Authentication
This node authenticates with SP-API via Login with Amazon (LWA) only. AWS IAM SigV4 signing has been intentionally disabled to reduce setup friction in n8n. For endpoints requiring Restricted Data Tokens (PII), the node automatically exchanges the LWA token for an RDT.
$3
- Reports API – needed for the Sales & Traffic report fallback (
GET_SALES_AND_TRAFFIC_REPORT).
- Selling Partner Insights / Data Kiosk – needed for the Data Kiosk analytics endpoints.Ensure these roles are assigned to your app in Developer Central and authorized by the seller account. After adding roles, restart the authorization flow to obtain a refresh token that carries the new scopes.
$3
Create a workflow with the Amazon Selling Partner node:
1. Resource
sellers, operation getMarketplaceParticipations.
2. Execute the node.
- 200 OK → credentials are correct.
- 401 Unauthorized → LWA credentials invalid/refresh token expired.
- 403 Forbidden → seller hasn’t authorized the required role or the app lacks it.$3
Use the
Data Kiosk resource to run GraphQL queries:1. Operation
Run Query and Download
2. Provide your GraphQL query using the correct versioned schema (see guide below)
3. The node will create the query, poll until DONE, then download the document (handles pagination when present)Important: DataKiosk requires versioned domain fields. Example:
`graphql
query {
analytics_salesAndTraffic_2024_04_24 {
salesAndTrafficTrends(
asinAggregation: CHILD
dateAggregation: DAY
startDate: "2024-01-01"
endDate: "2024-01-07"
filters: { asins: [], marketplaceId: "ATVPDKIKX0DER" }
) {
traffic { pageViews sessions }
sales { unitsOrdered orderedProductSales { amount currencyCode } }
}
}
}
`📖 See DATA_KIOSK_GUIDE.md for complete documentation, examples, and query structure.
Grant the "Selling Partner Insights / Data Kiosk" role in Developer Central. If you lack this role, use the
Reports resource instead.$3
Still getting LWA errors after signing? Rotate the LWA client secret, re-authorize the seller, and paste the new refresh token into n8n.
Usage
$3
`json
{
"resource": "orders",
"operation": "getOrders",
"marketplaceIds": ["ATVPDKIKX0DER"],
"createdAfter": "2024-01-01T00:00:00Z",
"createdBefore": "2024-01-31T23:59:59Z"
}
`$3
`json
{
"resource": "orders",
"operation": "getOrder",
"orderId": "123-1234567-1234567"
}
`$3
`json
{
"resource": "orders",
"operation": "getOrderItems",
"orderId": "123-1234567-1234567",
"returnAll": true
}
`$3
`json
{
"resource": "orders",
"operation": "getOrders",
"marketplaceIds": ["ATVPDKIKX0DER", "A2EUQ1WTGCTBG2"],
"createdAfter": "2024-01-01T00:00:00Z",
"createdBefore": "2024-01-07T23:59:59Z",
"additionalOptions": {
"orderStatuses": ["Unshipped", "PartiallyShipped"],
"fulfillmentChannels": ["AFN"],
"maxResultsPerPage": 50,
"returnAll": true
}
}
`$3
#### List Financial Event Groups
`json
{
"resource": "finance",
"operation": "listFinancialEventGroups",
"financialEventGroupStartedAfter": "2024-01-01T00:00:00Z",
"financialEventGroupStartedBefore": "2024-01-31T23:59:59Z",
"additionalOptions": {
"maxResultsPerPage": 100,
"returnAll": true
}
}
`#### List Financial Events
`json
{
"resource": "finance",
"operation": "listFinancialEvents",
"postedAfter": "2024-01-01T00:00:00Z",
"postedBefore": "2024-01-31T23:59:59Z",
"additionalOptions": {
"maxResultsPerPage": 100,
"returnAll": false
}
}
`#### List Financial Events by Group ID
`json
{
"resource": "finance",
"operation": "listFinancialEventsByGroupId",
"eventGroupId": "12345678901234567890123456789012",
"postedAfter": "2024-01-01T00:00:00Z",
"additionalOptions": {
"maxResultsPerPage": 50,
"returnAll": true
}
}
`#### List Financial Events by Order ID
`json
{
"resource": "finance",
"operation": "listFinancialEventsByOrderId",
"orderId": "123-1234567-1234567",
"additionalOptions": {
"returnAll": false
}
}
`#### List Transactions (Finances v2024-06-19)
`json
{
"resource": "finance",
"operation": "listTransactions",
"postedAfter": "2024-01-01T00:00:00Z",
"postedBefore": "2024-01-31T23:59:59Z",
"marketplaceId": "ATVPDKIKX0DER",
"additionalOptions": {
"maxResultsPerPage": 100,
"returnAll": true
}
}
`$3
`json
{
"resource": "reports",
"operation": "salesTrafficByAsin",
"marketplaceIds": ["ATVPDKIKX0DER"],
"dateFrom": "2024-08-01T00:00:00Z",
"dateTo": "2024-08-07T23:59:59Z",
"granularity": "DAILY",
"aggregationLevel": "CHILD",
"includeSessions": true
}
`$3
`json
{
"resource": "reports",
"operation": "returnsByAsinFba",
"marketplaceIds": ["ATVPDKIKX0DER"],
"dateFrom": "2024-08-01T00:00:00Z",
"dateTo": "2024-08-07T23:59:59Z",
"granularity": "DAILY"
}
`$3
`json
{
"resource": "reports",
"operation": "consolidatedSalesAndReturnsByAsin",
"marketplaceIds": ["ATVPDKIKX0DER"],
"dateFrom": "2024-08-01T00:00:00Z",
"dateTo": "2024-08-07T23:59:59Z",
"granularity": "DAILY",
"includeRefunds": false,
"emitRawSubdatasets": false
}
`$3
`json
{
"resource": "reports",
"operation": "refundsByAsin",
"marketplaceIds": ["ATVPDKIKX0DER"],
"dateFrom": "2024-08-01T00:00:00Z",
"dateTo": "2024-08-07T23:59:59Z"
}
`Supported Marketplaces
$3
- 🇺🇸 Amazon.com (US) - ATVPDKIKX0DER
- 🇨🇦 Amazon.ca (Canada) - A2EUQ1WTGCTBG2
- 🇲🇽 Amazon.com.mx (Mexico) - A1AM78C64UM0Y8
- 🇧🇷 Amazon.com.br (Brazil) - A2Q3Y263D00KWC$3
- 🇬🇧 Amazon.co.uk (UK) - A1F83G8C2ARO7P
- 🇩🇪 Amazon.de (Germany) - A1PA6795UKMFR9
- 🇫🇷 Amazon.fr (France) - A13V1IB3VIYZZH
- 🇮🇹 Amazon.it (Italy) - APJ6JRA9NG5V4
- 🇪🇸 Amazon.es (Spain) - A1RKKUPIHCS9HS
- 🇳🇱 Amazon.nl (Netherlands) - A1805IZSGTT6HS
- 🇸🇪 Amazon.se (Sweden) - A2NODRKZP88ZB9
- 🇵🇱 Amazon.pl (Poland) - A1C3SOZRARQ6R3$3
- 🇯🇵 Amazon.co.jp (Japan) - A1VC38T7YXB528
- 🇦🇺 Amazon.com.au (Australia) - A39IBJ37TRP1C6
- 🇸🇬 Amazon.sg (Singapore) - A19VAU5U5O7RUS
- 🇦🇪 Amazon.ae (UAE) - A2VIGQ35RCS4UG
- 🇸🇦 Amazon.sa (Saudi Arabia) - A17E79C6D8DWNP
- 🇮🇳 Amazon.in (India) - A21TJRUUN4KGVRate Limiting
This node implements Amazon's token bucket algorithm for rate limiting:
- Automatic Rate Detection: Reads rate limits from API response headers
- Intelligent Queuing: Queues requests when rate limits are exceeded
- Exponential Backoff: Implements backoff strategies for optimal throughput
- Per-Endpoint Limits: Different rate limits for different API operations
Error Handling
$3
- Network Errors: Automatic retry with exponential backoff
- Rate Limiting (429): Intelligent waiting and retry
- Temporary Server Errors (5xx): Configurable retry attempts$3
- Authentication Errors (401/403): Clear guidance on credential issues
- Not Found Errors (404): Helpful context for missing resources
- Validation Errors (400): Detailed parameter validation feedback
- Rate Limit Errors (429): Actionable rate limiting guidanceDevelopment
$3
`bash
git clone https://github.com/your-org/n8n-nodes-amazon-selling-partner.git
cd n8n-nodes-amazon-selling-partner
npm install
npm run build
`$3
`bash
Run all tests
npm testRun tests in Docker (as per project convention)
npm run test:dockerRun with coverage
npm test -- --coverage
`$3
`bash
Lint code
npm run lintFix linting issues
npm run lintfixFormat code
npm run format
`Troubleshooting
$3
#### "LWA authentication failed"
- Verify your LWA Client ID and Client Secret
- Ensure your refresh token is valid and not expired
- Check that your application has the correct roles assigned
#### "Request throttled by Amazon SP-API"
- Reduce request frequency
- Implement delays between requests
- Check your rate limits in the Amazon Developer Console
#### "Authentication failed (403)"
- Verify AWS credentials are correct
- Ensure IAM user has SP-API permissions
- Check that your application is approved for production (if using production)
#### "Date range cannot exceed 30 days"
- Amazon SP-API limits order queries to 30 days maximum
- Split larger date ranges into smaller chunks
$3
Enable debug logging by setting the environment variable:
`bash
export DEBUG=n8n-amazon-sp-api:*
`Security Considerations
$3
- Never commit credentials to version control
- Use environment variables for sensitive data
- Regularly rotate AWS access keys
- Monitor credential usage in AWS CloudTrail$3
- Use HTTPS endpoints only
- Implement proper firewall rules
- Monitor for suspicious API activity
- Use AWS IAM roles when possiblePerformance Optimization
$3
- Use appropriate date ranges (avoid very large ranges)
- Implement pagination for large result sets
- Cache frequently accessed data
- Monitor rate limit usage$3
- Track API response times
- Monitor error rates
- Set up alerts for rate limit breaches
- Monitor credential expirationContributing
1. Fork the repository
2. Create a feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)This project is licensed under the MIT License - see the LICENSE file for details.
- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions
- 📧 Email Support
- Amazon Selling Partner API team for comprehensive documentation
- n8n community for the excellent node development framework
- All contributors who help improve this project
---
Note: This is an unofficial community-maintained node. It is not affiliated with or endorsed by Amazon or n8n.