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 interface APIs, the sandbox provides updateOrderPackageInformation and updateOrderReturns that you can use to move order states and test ordering and post ordering scenarios.