📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

December 24, 2024

ReturnPackageDetailsInput now has the field reason which you can use to indicate why a delivery failed.

December 18, 2024

The packageTracker query is now available for you to get the status of a PackageTracker.

November 22, 2024

This changelog lists the updates associated with Buy with Prime API v2024-11-01.

• Backwards-incompatible changes
• Backwards-compatible changes
• Sandbox

Backwards-incompatible changes

v2024-11-01 of the Buy with Prime API has the following backwards-incompatible updates from the v2024-04-01 version. These updates require code changes on your end if you decide to migrate to this version.

Delivery Preview interface

• To enable delivery previews for all types of deliveries and to provide a common input term for delivery preview and ordering, DeliveryTermsInput replaces DeliveryPreviewTermsInput.

• DeliveryOfferDetails now has a deliveryTerms entity, which has isPrimeEligible and deliverySpeed fields.

• location and shopperIdentity are now top-level fields in DeliveryPreviewInput and are no longer nested under DeliveryPreviewTermsInput.

Order interface

• In createOrder, updateOrder, and order query response, the deliveryInformation field is renamed to packageInformation.

• In the input to createOrder, the DeliveryProvider BUY_WITH_PRIME is replaced with AMAZON. For products that offer Buy with Prime, isPrimeEligible is true, otherwise it is false.

• For products fulfilled by MERCHANT, product attributes in LineItemInput are now optional.

• cancelOrder now allows a maximum of five aliases.

• cancelOrder and updateOrder inputs are updated to include orderIdentifier for consistency.

• The following changes are made to UpdateOrderInput:

  • The type for the lineItems field changed from LineItemInput to a new type called UpdateLineItemInput.
  • The type for orderId changed from ID to OrderIdentifierInput so that you can use the order alias instead of the order ID.
  • The deliveryInformation field is renamed to packageInformation. The type for packageInformation is a new type UpdatePackageInformationInput.

• You can now find complete tracking details in PackageTracker in the order query response.

• There are new error codes for createOrder, updateOrder and cancelOrder.

• StoreFingerprintInput field is removed from ClientDetailsInput.

Backwards-compatible changes

v2024-11-01 of the Buy with Prime API has the following backwards-compatible updates from the v2024-04-01 version.

• Error outputs across the Buy with Prime API are standardized to include type, code, and details.

• The Buy with Prime API now uses the same transitive authentication token header in service headers as the Selling Partner API (SP-API).

Analytics interface

• There is a new ORDER_FEES report type in ReportRequest.

Catalog interface

• A Product can now have variations, such as a t-shirt with available sizes of small, medium, and large. The new fields arevariationGroupMembership and representativeOfVariationGroup. CreateProductInput and UpdateProductInput also have the new field variationGroupMembership.

• A set of related Products can now be grouped together as a purchase group, also called a bundle.

• Product, CreateProductInput, and UpdateProductInput have new fields title, externalVersion and advertisedPrice.

• There is new filter functionality in the products query.

• The metadata field is added to the Product type and is visible to the product and products queries.

Delivery Preview interface

• The deliveryPreview response now has a deliveryTerms entity, which has isPrimeEligible and deliverySpeed fields.

Order interface

• A set of related Products can now be grouped together as a purchase group, also called a bundle. The new field is purchaseGroupMembership.

• Changes to CreateOrderInput:

  • shopperIdentityInput and CustomerInput are now optional for products that don't offer Buy with Prime.
  • DeliveryOfferDetails now has DeliveryTermsInput which has isPrimeEligible and deliverySpeed fields.

• In the order query response, the carrier code returned under PackageTracker is now consistent across the Buy with Prime API.

• Querying the PackageTracker entity in Order requires AppPackageTrackingMilestoneRead scope.

• You can now reject a refund with the new state REJECTED for RefundStateInput used in RefundDetailsInput state field. RefundDetailsInput also has new fields refundRequestReason and refundStatusReason.

Refund interface

• The refund request reason can no longer be changed for refunds generated by cancellations, returns, or customer service agents.

Return interface

• When a customer initiates an external return, which is a return outside of Buy with Prime, you can now use ReturnsInput in updateOrder to add the information to the associated Buy with Prime order.

• The reversalOffers query returns a ReversalItemOfferSummary with a window for return eligibility.

• To update an external return, you can now provide a returnIdentifier that is either a Buy with Prime return ID or an alias.

• ReturnLineItem now has refundDetails and returnReason fields.

Sandbox

• The Buy with Prime API now provides a sandbox environment that you can use to test your integration without affecting production data or triggering real-world events. Along with all other APIs, the sandbox environment provides updateOrderPackageInformation and updateOrderReturns that you can use to move order states and test ordering and post ordering scenarios.