Getting Started with Amazon SP-API: A Developer's Introduction

Amazon’s Selling Partner API (SP-API) replaced the old MWS API and brought modern OAuth 2.0 authentication, RESTful endpoints, and a more consistent developer experience. It also brought significantly more setup complexity. This guide gets you from zero to a successful authenticated API call.

What Is the SP-API and Who Needs It?

The SP-API is Amazon’s programmatic interface for Selling Partners — sellers, vendors, and the agencies and tool developers who work with them. It gives you access to:

Orders API — Real-time order data, buyer contact info (within policy limits), fulfillment status
Inventory API — FBA inventory levels, reservations, unfulfillable quantities
Reports API — Scheduled and on-demand reports (settlement, FBA inventory reconciliation, etc.)
Feeds API — Bulk product listing, pricing, and inventory updates
Catalog API — Product data, ASIN lookups, categorization
Notifications API — Webhooks for real-time events (new order, FBA shipment update)

If you’re building any tool that reads from or writes to Amazon seller accounts programmatically, you need SP-API access.

SP-API vs MWS: Key Differences

Feature	MWS (Retired)	SP-API
Authentication	Access Key + Secret	OAuth 2.0 (LWA) + AWS SigV4
Protocol	SOAP/REST mixed	REST only
Rate Limiting	Per API section	Usage Plans per operation
Status	Retired June 2024	Active and expanding

The authentication model is the biggest shift. SP-API requires both Login with Amazon (LWA) OAuth tokens AND AWS request signing. If you’re coming from MWS, budget extra time for auth setup.

Prerequisites

Before you write a single line of code:

Amazon Seller Central account (or Vendor Central for vendors) — must be active and in good standing
AWS account — for IAM roles and credentials
Amazon Developer Central account — where you’ll register your application
Access to the Seller Central account you want to integrate with (or permission from the seller)

Step 1: Register Your Application

Go to Seller Central → Apps & Services → Develop Apps (or directly to sellercentral.amazon.com/developer/register).

Click Register New Application and fill in:

Application Name — Your tool’s name
IAM ARN — You’ll get this in Step 2; come back to fill it in
Application Type — “Private” for your own account, “Public” if you’re building for multiple sellers

For the OAuth redirect URI (for public/multi-seller apps), enter a URL you control that will handle the OAuth callback.

Step 2: Create an AWS IAM Role

This is where most developers get stuck. The SP-API requires an IAM role that Amazon can assume on your behalf to authorize requests.

Create the IAM Policy

In AWS Console → IAM → Policies → Create Policy. Use this JSON:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:*:*:*"
    }
  ]
}

Name it SellingPartnerAPIPolicy.

Create the IAM Role

In AWS Console → IAM → Roles → Create Role:

Trusted entity type: AWS account
Account ID: Use Amazon’s account ID — 437568002678
External ID: Your seller’s Merchant Token (found in Seller Central → Account Info)

Attach the SellingPartnerAPIPolicy you just created.

Your role ARN will look like: arn:aws:iam::YOUR_ACCOUNT_ID:role/SellingPartnerAPIRole

Go back to your Developer Central application and paste this ARN in the IAM ARN field.

In Developer Central, under your application’s LWA credentials section:

Client ID — amzn1.application-oa2-client.XXXXXXX
Client Secret — A long random string

These are your OAuth 2.0 credentials. Store them securely — treat the client secret like a password.

Step 4: Authorize Your Seller Account

For your own seller account (private app):

In Seller Central → Apps & Services → Your Apps, find your app and click Authorize. This generates a Refresh Token specific to your seller account.

Store this refresh token securely. You’ll exchange it for short-lived access tokens.

Step 5: The Token Exchange Flow

Every API request requires a fresh access token. Access tokens expire in 1 hour. Here’s the exchange:

import axios from 'axios';

async function getLWAToken(clientId, clientSecret, refreshToken) {
  const response = await axios.post('https://api.amazon.com/auth/o2/token', {
    grant_type: 'refresh_token',
    refresh_token: refreshToken,
    client_id: clientId,
    client_secret: clientSecret
  }, {
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
  });

  return response.data.access_token; // Valid for 3600 seconds
}

Cache this token and reuse it across requests until it expires. Don’t fetch a new token on every API call — you’ll hit rate limits on the auth endpoint itself.

Step 6: Sign Requests with AWS SigV4

Every SP-API request must be signed with your AWS credentials using the SigV4 algorithm. The easiest approach is using the aws4 npm package:

import aws4 from 'aws4';
import axios from 'axios';

async function callSPAPI(accessToken, endpoint, method = 'GET', body = null) {
  const url = new URL(endpoint);

  const requestOptions = {
    host: url.host,
    path: url.pathname + url.search,
    method: method,
    service: 'execute-api',
    region: 'us-east-1', // or your marketplace region
    headers: {
      'x-amz-access-token': accessToken,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined
  };

  // Sign the request with AWS credentials
  const signedRequest = aws4.sign(requestOptions, {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
  });

  const response = await axios({
    method: signedRequest.method,
    url: `https://${signedRequest.host}${signedRequest.path}`,
    headers: signedRequest.headers,
    data: signedRequest.body
  });

  return response.data;
}

Step 7: Make Your First API Call

Fetch recent orders:

const accessToken = await getLWAToken(
  process.env.LWA_CLIENT_ID,
  process.env.LWA_CLIENT_SECRET,
  process.env.REFRESH_TOKEN
);

const orders = await callSPAPI(
  accessToken,
  'https://sellingpartnerapi-na.amazon.com/orders/v0/orders?MarketplaceIds=ATVPDKIKX0DER&CreatedAfter=2025-01-01T00:00:00Z'
);

console.log(orders.payload.Orders);

Marketplace IDs by region:

US: ATVPDKIKX0DER
UK: A1F83G8C2ARO7P
Germany: A1PA6795UKMFR9
Canada: A2EUQ1WTGCTBG2

Understanding Usage Plans (Rate Limits)

SP-API rate limits per operation group. Check the x-amzn-RateLimit-Limit response header to see your rate for that operation.

Implement exponential backoff when you receive a 429:

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Recommended SDK

Rather than building all of this manually, use the amazon-sp-api npm package:

npm install amazon-sp-api

import SellingPartner from 'amazon-sp-api';

const sp = new SellingPartner({
  region: 'na',
  refresh_token: process.env.REFRESH_TOKEN,
  credentials: {
    SELLING_PARTNER_APP_CLIENT_ID: process.env.LWA_CLIENT_ID,
    SELLING_PARTNER_APP_CLIENT_SECRET: process.env.LWA_CLIENT_SECRET,
  }
});

const orders = await sp.callAPI({
  operation: 'getOrders',
  endpoint: 'orders',
  query: {
    MarketplaceIds: ['ATVPDKIKX0DER'],
    CreatedAfter: '2025-01-01T00:00:00Z'
  }
});

The SDK handles token refresh and SigV4 signing automatically.

SP-API integration is one of the more complex API setups in e-commerce, but the data access it unlocks is worth it. Our team has built production SP-API applications for FBA sellers, agencies, and SaaS tools. Reach out if you need help getting started or building something more complex.