Amazon — API Version Setup
Amazon API Version Setup
EcartAPI supports two versions of the Amazon SP-API integration: v1 (legacy) and v2 (recommended). The version determines how EcartAPI communicates with Amazon for products, fulfillments, webhooks, and more.
We strongly recommend using v2. It is synchronous, returns real-time data, provides complete buyer information via Restricted Data Tokens, and includes endpoints not available in v1 (allowed carriers, inventory updates, fulfillment status updates).
How to configure the version
The API version is set at the app level in the EcartAPI dashboard. It applies to all Amazon integrations connected to that app — it cannot be changed per request.
Steps
- Log in to your EcartAPI dashboard.
- Go to E-commerce Setup in the left sidebar.
- Select Amazon from the list of platforms.
- Open the Additional Settings section.
- Set the
version_apifield to eitherv1orv2. - Click Save Settings.
Once saved, every API request made with that app's credentials will use the selected version.
Choosing between v1 and v2
| v1 | v2 | |
|---|---|---|
| Products | Reports API (async — generates and downloads a report) | Listings API (real-time, paginated with nextToken) |
| Fulfillments | Feeds API with XML (async) | Shipment Confirmation API (synchronous) |
| Fulfillment updates | Not supported | Supported via PUT /orders/{orderId}/fulfillments/{id} |
| Buyer data | May be incomplete | Complete via Restricted Data Tokens (RDT) |
| Webhooks | Notifications API via SDK | Notifications API via Amazon SQS (native, more reliable) |
| Allowed carriers | Not available | GET /services/allowed — required for fulfillment companyId |
| Inventory update | Not available | PUT /locations/{locationID}/inventories/{itemId} |
| Cancel fulfillment | Supported | Not supported (use v1 if required) |
When to use v1
Use v1 only if you specifically need to cancel fulfillments (POST /orders/{orderId}/fulfillments/{id}/cancel), which is not available in v2.
When to use v2 (recommended)
Use v2 for all other scenarios. Key advantages:
- Real-time product data — no waiting for Amazon to generate a report.
- Synchronous fulfillments — immediate confirmation instead of async feed processing.
- Complete customer info — shipping address and buyer details are accessible via RDT.
package.idsupport — required for future fulfillment updates. Save this value immediately after creating a fulfillment, as Amazon does not expose an endpoint to retrieve it later.- Allowed carriers endpoint — use
GET /services/allowedto get validcompanyIdvalues before creating fulfillments.
Important: package.id in v2 fulfillments
package.id in v2 fulfillmentsWhen creating a fulfillment in v2, you can include a package.id in the request body. This ID is required if you need to update the fulfillment later.
Amazon does not provide an endpoint to retrieve
package.idafter the fulfillment is created. Save this value immediately in your system.
If you lose the package.id, you will not be able to update the fulfillment tracking information for that shipment.
Related resources
Updated 11 days ago