Tutorial: Use the Claims API To Create Claim For Single Eligible Shipment

API Version: v2

This tutorial explains the create claim API, which allows shippers to create claims for a single eligible shipment. This API supports claims buckets such as LOST_IN_TRANSIT, DAMAGED_IN_TRANSIT, DELIVERED_NOT_RECEIVED, ITEM_MISSING_SWITCHEROO and COD_ABUSE.

Note: This API is currently available only for the India (IN) marketplace.

The createClaim API provides shippers with an additional channel alongside Shipper Central to create claims for eligible shipments.

Prerequisites

To successfully complete this tutorial, you must have the following prerequisites:

Enrollment in an eligible program.
A Shipper Central account to create and manage shipments.
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.

Process to create a claim

The shipper has the capability to submit a claim for eligible tracking IDs. When filing a claim, the shipper is required to specify a reason and a type:

Reason for a claim is referred to as claimReason
Type of claim is referred to as settlementType

The shipper can choose one of these claimReason values:

SL#	claimReason	Claims bucket
1	`LOST_IN_TRANSIT`	If the shipment was lost in transit
2	`DAMAGED_IN_TRANSIT`	If the shipment was received in damaged condition
3	`DELIVERED_NOT_RECEIVED`	If the shipment was delivered but not received
4	`ITEM_MISSING_SWITCHEROO`	If the shipment was delivered but the content is missing or different
5	`COD_ABUSE`	If cash was collected from the customer but the delivery agent marked it rejected

And one of these settlementType values:

SL#	settlementType	Purpose
1	`REFUND`	If the shipper wants a refund for the item value
2	`CERTIFICATE_OF_FACT`	If the shipper wants to request a COF (Certificate of Fact)

Step 1. Create a claim for an eligible shipment

Call the createClaim operation, passing the following parameters:

Request payload

Name	Description	Required
`trackingId`	Tracking ID for the shipment for which the claim is to be filed. Type: string	Yes
`claimReason`	The reason for which the shipper is filing the claim for an eligible shipment. Type: enum [`LOST_IN_TRANSIT`, `DAMAGED_IN_TRANSIT`, `DELIVERED_NOT_RECEIVED`, `ITEM_MISSING_SWITCHEROO`, `COD_ABUSE`]	Yes
`settlementType`	Type of settlement the shipper wants to receive for a particular shipment. Type: enum [`REFUND`, `CERTIFICATE_OF_FACT`]	Yes
`claimProof`	A list of proof URLs for a claim. Basic URL validation is performed for each URL present in the list. Type: list	No
`declaredValue`	To determine the value of the shipment. Type: Currency	No
`isReplacementPackageSent`	To identify if a replacement was sent. Type: boolean	No

Request header parameters

Name	Description	Required
`x-amzn-shipping-business-id`	Amazon shipping business to assume for this request. The default is `AmazonShipping_IN`	Yes
`x-amz-access-token`	Amazon shipping request token	Yes

Sample API Request

POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/claims
x-amzn-shipping-business-id: AmazonShipping_IN
x-amz-access-token: Atza|IwEBIGorlXXX.....

Request body examples

LOST_IN_TRANSIT

{
    "trackingId": "371798609820",
    "settlementType": "REFUND",
    "claimReason": "LOST_IN_TRANSIT",
    "claimProof": [
        "https://test22.in",
        "https://test22.com"
    ],
    "declaredValue": {
        "unit": "INR",
        "value": 22
    },
    "isReplacementPackageSent": false
}

DAMAGED_IN_TRANSIT

{
    "trackingId": "371798609820",
    "settlementType": "REFUND",
    "claimReason": "DAMAGED_IN_TRANSIT",
    "claimProof": [
        "https://test22.in",
        "https://test22.com"
    ],
    "declaredValue": {
        "unit": "INR",
        "value": 22
    },
    "isReplacementPackageSent": false
}

DELIVERED_NOT_RECEIVED

{
    "trackingId": "371798609820",
    "settlementType": "REFUND",
    "claimReason": "DELIVERED_NOT_RECEIVED",
    "claimProof": [
        "https://test22.in",
        "https://test22.com"
    ],
    "declaredValue": {
        "unit": "INR",
        "value": 22
    },
    "isReplacementPackageSent": false
}

ITEM_MISSING_SWITCHEROO

{
    "trackingId": "371798609820",
    "settlementType": "REFUND",
    "claimReason": "ITEM_MISSING_SWITCHEROO",
    "claimProof": [
        "https://test22.in",
        "https://test22.com"
    ],
    "declaredValue": {
        "unit": "INR",
        "value": 22
    },
    "isReplacementPackageSent": false
}

COD_ABUSE

{
    "trackingId": "371798609820",
    "settlementType": "REFUND",
    "claimReason": "COD_ABUSE",
    "claimProof": [
        "https://test22.in",
        "https://test22.com"
    ],
    "declaredValue": {
        "unit": "INR",
        "value": 22
    },
    "isReplacementPackageSent": false
}

Response

A successful call returns claimId in the payload with status code 201 after the claim is created.

FAQ

Which fields are required in the payload?

trackingId, claimReason and settlementType are mandatory fields and must always be provided when submitting a claim.

What is claimProof?

claimProof is a list of proof URLs that the shipper can attach to support the claim.

Can I continue to submit claims through Shipper Central?

Yes. You can continue to use the functionality in Shipper Central to submit claims.