Push Notifications - Claims Status

Push Notifications (WebHook) is a feature enabled by Amazon Shipping (IN marketplace only) which helps shippers/integrators to automatically receive Claim Status updates for eligible tracking IDs without the need to make any external API calls. Developers, including shippers and integrators, can subscribe to claims push notifications via their webhook URL endpoint.

Steps to Subscribe to Push Notification Feature:

1. The shipper/integrator needs to provide their -
   1. Webhook URL
   2. Authentication Mechanism
   3. Shipper Account ID or Shipping Party Account ID (for whom push notifications are being setup)
   4. Point of contact emails.
2. Once these details are shared with the Account Manager they will be able to request webhook subscription setup.
3. The Account Manager will internally coordinate configuring and activating the subscription for notifications.

Supported Authentication Mechanisms

One of the following must be enabled by the Shipper/Integrator:

Push Notifications payload follows this envelope structure with detail and few metadata fields: detail Object

Important: Ensure your webhook parser handles additional fields gracefully. We periodically enhance the payload with new attributes to make notifications more informative — these additions are backward-compatible, but if your parser is strict (e.g., fails on unrecognised fields), it may break when new fields are introduced. A flexible/lenient JSON parser that ignores unknown properties is recommended.

Sample event:

{
  "version": "0",
  "id": "48af9743-336e-00eb-7194-de9975baa012",
  "detail-type": "CLAIM",
  "source": "AmazonShipping",
  "account": "434519225125",
  "time": "2024-02-21T19:33:09Z",
  "region": "eu-west-1",
  "resources": [],
  "detail": {
    "shippingPartyAccountId": "A1QUX1G6QEPA2X",
    "claimId": "1967234896304",
    "eventTime": "2026-08-18T11:26:34Z",
    "trackingId": "371601855000",
    "status": "REFUND_FILED",
    "statusChangeReason": "OTHER",
    "refundAmount": {
      "value": 550.0,
      "unit": "INR"
    }
  }
}

FAQs

Onboarding & Subscription

1. What is the need for push notifications?
Using push notifications helps shippers to automatically receive claim status updates for eligible shipments as they become available, without calling any API.

2. Who can enable Claims Push Notification feature?
Third-party integrators and directly integrated shippers who use the Shipping V2 API to create shipments with Amazon Shipping can use this feature to receive notifications for claims.

3. What details does the Shipper/Integrator need to provide to enable Push Notifications?

4. Are HTTPS webhooks required?

Yes. HTTPS is a mandatory requirement for webhook URLs. Amazon will only accept and configure HTTPS-enabled webhook URLs to ensure secure communication and protect sensitive data during transmission.

5. How long does it take to enable push notifications?

Push Notifications are configured via our technical team. You will receive a response within 5 business days.

6. How can a Shipper/Integrator request a Claims Push Notification subscription?

Push Notifications can only be enabled for orders shipped with Amazon Shipping. As the subscription process is currently manual, please contact your Amazon Account Manager for assistance with enabling the Push Notification feature.

7. What are the possible values for status?

IN_REVIEW, APPROVED, REJECTED, REFUND_FILED, REFUND_COMPLETE, INVALID_CLAIM, PENDING_CUSTOMER_INFO

Troubleshooting

8. My webhook is returning 401 Unauthorized — what's wrong?

Common causes:

1. API Key mismatch — Verify the key-value pair matches what was configured during onboarding.
2. OAuth token expired — Ensure your OAuth endpoint issues tokens with sufficient TTL.
3. Username/Password incorrect — Verify the Basic Auth credentials match your endpoint's configuration.

9. I'm not receiving any events after subscription — what should I check?

1. Verify your endpoint is publicly accessible (not behind a VPN or firewall).
2. Ensure your endpoint returns HTTP 2xx for POST requests.
3. Check that your authentication credentials are valid and accessible.
4. Contact your Amazon Account Manager to verify your subscription is active and enabled.