codeyogi911/amazon-seller-india

Amazon Seller India — SP-API Agent Skill

When to Use This Skill

Use this skill when the user asks you to:

• Set up or troubleshoot Amazon SP-API authentication (LWA OAuth, refresh tokens, access tokens)
• Register as a private developer on Amazon Seller Central India
• Self-authorize a private SP-API application
• Make any Amazon Selling Partner API call for the India marketplace
• Manage orders, inventory, listings, pricing, or fulfillment via SP-API
• Pull reports (settlement, GST/tax, inventory, order, FBA, performance)
• Submit feeds (listings, pricing, order fulfillment, FBA inbound)
• Work with Amazon finances, payments, or settlement reconciliation
• Handle Restricted Data Tokens (RDT) for PII-sensitive operations
• Manage FBA inbound shipments, Easy Ship, or external fulfillment
• Retrieve catalog items, product types, or brand analytics
• Set up SP-API notifications or subscriptions
• Integrate Amazon Seller India data with Zoho Books/Inventory or other accounting systems

India Marketplace Constants

Parameter	Value
Marketplace ID	A21TJRUUN4KGV
Country Code	IN
SP-API Endpoint	https://sellingpartnerapi-eu.amazon.com
AWS Region	eu-west-1
Seller Central URL	https://sellercentral.amazon.in
LWA Token Endpoint	https://api.amazon.com/auth/o2/token

India is part of the Europe selling region in SP-API. All API calls go to sellingpartnerapi-eu.amazon.com.

Quick Reference

• For authentication setup (first-time registration, developer profile, self-authorization, credential collection): Load references/auth-setup-guide.md
• For complete API operations catalog (all APIs, endpoints, report types, feed types, roles): Load references/api-operations-catalog.md
• For ready-to-use scripts (token exchange, API calls): See scripts/ directory

Instructions

Step 1: Credential Collection

Before making any API call, collect these credentials from the user:

1. LWA Client ID — amzn1.application-oa2-client.xxxxx (from Seller Central → Apps & Services → Develop Apps → LWA Credentials)
2. LWA Client Secret — the secret paired with the Client ID
3. LWA Refresh Token — obtained during self-authorization (long-lived credential)

If the user has not yet set up their developer profile or application, walk them through the full auth setup. Load references/auth-setup-guide.md for the step-by-step guide.

Step 2: Exchange Refresh Token for Access Token

Every SP-API call requires a short-lived access token (expires in 3600 seconds / 1 hour).

curl -X POST "https://api.amazon.com/auth/o2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=${REFRESH_TOKEN}" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}"

Response:

{
  "access_token": "Atza|IQEBLjAs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Use scripts/get_access_token.py for a reusable Python implementation.

Step 3: Make SP-API Calls

All India marketplace calls use:

• Endpoint: https://sellingpartnerapi-eu.amazon.com
• Marketplace ID query param: marketplaceIds=A21TJRUUN4KGV
• Headers:
  • x-amz-access-token: {access_token}
  • user-agent: {AppName}/{Version} (Language=Python/3.x; Platform=Linux)

Example — Get Orders:

curl -X GET "https://sellingpartnerapi-eu.amazon.com/orders/v0/orders?MarketplaceIds=A21TJRUUN4KGV&CreatedAfter=2026-01-01T00:00:00Z" \
  -H "x-amz-access-token: ${ACCESS_TOKEN}" \
  -H "user-agent: MyApp/1.0 (Language=Python/3.10)"

Step 4: Handle Restricted Data (PII)

Some operations return PII (buyer name, address, phone). These require a Restricted Data Token (RDT) instead of the normal access token.

Get an RDT:

curl -X POST "https://sellingpartnerapi-eu.amazon.com/tokens/2021-03-01/restrictedDataToken" \
  -H "x-amz-access-token: ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "restrictedResources": [
      {
        "method": "GET",
        "path": "/orders/v0/orders/{orderId}",
        "dataElements": ["buyerInfo", "shippingAddress"]
      }
    ]
  }'

Then use the returned restrictedDataToken value in x-amz-access-token header for the restricted call.

Restricted operations include:

• Orders API: getOrders, getOrder, getOrderItems, getOrderAddress, getOrderBuyerInfo, confirmShipment
• Merchant Fulfillment API: getShipment, createShipment
• Easy Ship API: createScheduledPackageBulk
• Reports with PII (shipping reports, tax reports)

Step 5: Common Workflows

Pull Settlement Report (for Zoho Books reconciliation)

POST /reports/2021-06-30/reports
{
  "reportType": "GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE_V2",
  "marketplaceIds": ["A21TJRUUN4KGV"]
}

Then poll GET /reports/2021-06-30/reports/{reportId} until status is DONE, then download via reportDocumentId.

Pull GST Reports (India-specific)

Report	reportType Value	Role Required
GST MTR B2B	GST_MTR_B2B	Tax Remittance (Restricted)
GST MTR B2C	GST_MTR_B2C	Tax Remittance (Restricted)
GST Stock Transfer	GST_MTR_STOCK_TRANSFER_REPORT	Tax Remittance (Restricted)
On Demand GST B2B	GET_GST_MTR_B2B_CUSTOM	Tax Invoicing (Restricted)
On Demand GST B2C	GET_GST_MTR_B2C_CUSTOM	Tax Invoicing (Restricted)
On Demand Stock Transfer	GET_GST_STR_ADHOC	Amazon Fulfillment

Update Inventory

Use Listings Items API or submit a feed:

POST /feeds/2021-06-30/feeds
{
  "feedType": "JSON_LISTINGS_FEED",
  "marketplaceIds": ["A21TJRUUN4KGV"],
  "inputFeedDocumentId": "{feedDocumentId}"
}

Update Pricing

POST /feeds/2021-06-30/feeds
{
  "feedType": "JSON_LISTINGS_FEED",
  "marketplaceIds": ["A21TJRUUN4KGV"],
  "inputFeedDocumentId": "{feedDocumentId}"
}

Use the Listings Items API patchListingsItem for individual price updates.

Error Handling

HTTP Code	Meaning	Action
400	Bad request / invalid params	Check query params, marketplace ID, date formats
401	Invalid or expired access token	Re-exchange refresh token for a new access token
403	Missing role or unauthorized	Check developer profile roles; may need to request additional roles
404	Resource not found	Verify order ID, ASIN, SKU exists
429	Rate limit exceeded	Back off and retry with exponential backoff
500/503	Amazon server error	Retry with exponential backoff (max 3 retries)

Rate Limits

SP-API enforces per-operation rate limits. Key limits for high-volume operations:

• getOrders: 0.0167 requests/sec (1 per minute burst of 20)
• getOrder: 0.5 requests/sec (burst of 30)
• getOrderItems: 0.5 requests/sec (burst of 30)
• createReport: 0.0167 requests/sec (1 per minute burst of 15)
• getReport: 2 requests/sec (burst of 15)
• Catalog Items searchCatalogItems: 2 requests/sec (burst of 2)
• Listings patchListingsItem: 5 requests/sec (burst of 10)
• Feeds createFeed: 0.0083 requests/sec (1 per 2 minutes burst of 15)

Always implement exponential backoff for 429 responses.

Important Notes

• No AWS IAM/STS required: Since 2023, SP-API no longer requires AWS Signature V4 signing or IAM role assumption. Only LWA OAuth tokens are needed.
• Grantless operations: Some operations (e.g., Notifications API subscriptions) use client_credentials grant instead of refresh_token. Use scope=sellingpartnerapi::notifications with grant_type=client_credentials.
• Sandbox testing: SP-API offers static and dynamic sandbox environments for testing. Use x-amzn-sandbox: true header (static sandbox) or sandbox endpoint patterns.
• India timezone: Amazon India operates in IST (UTC+5:30). Order dates and report dates are in UTC; convert as needed.
• Settlement cycle: Amazon India typically settles every 7 days. Settlement reports contain all transaction-level details including fees, refunds, and net payout.