Pre-Launch Announcement: Customer Returns (CRET) for India Marketplace

Starting July 2026, Amazon Shipping will introduce Customer Returns (C-Returns) support for the India marketplace via the Amazon Shipping V2 API. This feature enables merchants to create return shipments with doorstep quality checks through the existing GetRates API and OneClickShipment API.

What is changing?

Customer Returns for India is a new feature that enables Off-Amazon merchants in the India marketplace to create customer return shipments via the Amazon Shipping V2 API. This includes doorstep quality checks at the time of pickup, allowing merchants to verify item condition before accepting the return.

This launch introduces the following changes to the API:

• New service selection: SWA-CRET service ID for Customer Returns shipments in India
• New request item field: itemQualityChecks array at the item level for specifying quality check
• New tracking detail codes: PickupRejectedByCustomer and QualityChecksFailedin the tracking API response and push notifications.
• New Rate Item Id: QUALITY_CHECKS_FEEin the get rates API response
• New VAS option: qualityChecks under valueAddedServices (future scope)

Important — Schema Change Notice: If your integration strictly validates or de-serializes enum values against a fixed list, it may fail when encountering the new values.
We strongly recommend implementing flexible enum handling to accommodate new values gracefully — this is a best practice that will protect your integration against future enhancements as well.

With this launch, you'll be able to:

• Create return shipments: Use the SWA-CRET service ID to create customer return labels for the India marketplace
• Specify quality checks: Define item-level quality check parameters (e.g., product name match, seal tag check, stains check) that will be verified at the customer's doorstep during pickup
• Track return-specific details codes: Receive PickupRejectedByCustomer and QualityChecksFailed tracking details codes for granular return shipment visibility
• View quality check fees: Process the QUALITY_CHECKS_FEE as rate item id in rate responses when quality checks are opted in

Which marketplaces are affected?

This feature is available for the India (IN) marketplace only. The API schema changes (new enum values, new fields) are global and will be present in the worldwide API model. The feature will be available during July 2026.

Who is affected?

Developers who integrate with the Amazon Shipping V2 API (GetRatesV2, OneClickShipment, Tracking API) and Push Notifications are affected by this change. This is particularly relevant for:

• India marketplace merchants and platforms processing customer returns
• Integrators who strictly validate API response schemas

What action is required?

For India merchants/platforms implementing C-Returns:

• Update your integration to use the SWA-CRET service ID for customer return shipments
• Implement the itemQualityChecks array in request payloads to specify quality check parameters per item
• Update your tracking detail code handlers to process PickupRejectedByCustomer and QualityChecksFailed
• Update your rate processing logic to handle the QUALITY_CHECKS_FEE as rate item id

Technical Implementation Details

Service Selection

Customer Return shipments must use the SWA-CRET service ID:

"serviceSelection": {
    "serviceId": ["SWA-CRET"]
}

Item Quality Checks

Quality checks are specified at the item level using the itemQualityChecks array. Each item can have up to 5 quality check parameters.

Available Quality Check Codes:

Limitations: C-Return shipments are restricted to a maximum of 2 items per package and 5 quality checks per item.

Note: Complete list of questions will be available at the time of launch.

Sample API Requests

GetRatesV2 — Customer Returns with Item Quality Checks:

{
    "shipFrom": {
        "name": "Customer Name",
        "addressLine1": "[Customer Address]",
        "city": "[City]",
        "stateOrRegion": "KARNATAKA",
        "postalCode": "[Postal Code]",
        "countryCode": "IN",
        "phoneNumber": "[Phone]",
        "email": "[email]"
    },
    "shipTo": {
        "name": "Warehouse Name",
        "addressLine1": "[Warehouse Address]",
        "city": "[City]",
        "stateOrRegion": "KARNATAKA",
        "postalCode": "[Postal Code]",
        "countryCode": "IN",
        "phoneNumber": "[Phone]",
        "email": "[email]"
    },
    "serviceSelection": {                  //New Object
        "serviceId": ["SWA-CRET"]
    },
    "taxDetails": [{
        "taxRegistrationNumber": "[GST Number]",
        "taxType": "GST"
    }],
    "packages": [{
        "dimensions": {
            "length": 7,
            "width": 7,
            "height": 7,
            "unit": "CENTIMETER"
        },
        "weight": {
            "unit": "GRAM",
            "value": 500
        },
        "insuredValue": {
            "unit": "INR",
            "value": 1349
        },
        "items": [{
            "description": "Product Description",
            "itemIdentifier": "SKU-12345",
            "quantity": 1,
            "weight": {
                "unit": "GRAM",
                "value": 500
            },
            "itemValue": {
                "unit": "INR",
                "value": 1349
            },
            "invoiceDetails": {
                "invoiceNumber": "INV-123456",
                "invoiceDate": "2026-01-09T00:01:40Z"
            },
            "itemQualityChecks": [                  //New Object
                {
                    "code": "ProductNameMatch",
                    "values": ["T-Shirt Blue XL"]
                },
                {
                    "code": "SealTagAttachedCheck",
                    "values": []
                },
                {
                    "code": "StainsCheck",
                    "values": []
                }
            ]
        }],
        "packageClientReferenceId": "RETURN-ORDER-001"
    }],
    "channelDetails": {
        "channelType": "EXTERNAL"
    }
}

{
    "rates": [{
        "carrierId": "ATS",
        "carrierName": "Amazon Shipping",
        "serviceId": "SWA-CRET",
        "serviceName": "Amazon Shipping Customer Returns",
        "rateItemList": [
            {
                "rateItemCharge": { "unit": "INR", "value": 21.0 },
                "rateItemID": "BASE_RATE",
                "rateItemNameLocalization": "Base Rate",
                "rateItemType": "MANDATORY"
            },
            {
                "rateItemCharge": { "unit": "INR", "value": 18.0 },
                "rateItemID": "QUALITY_CHECKS_FEE",                  //New Field
                "rateItemNameLocalization": "Quality Checks Fee",
                "rateItemType": "MANDATORY"
            }
        ],
        "totalCharge": { "unit": "INR", "value": 39.0 }
    }]
}

OneClickShipment — Customer Returns with Item Quality Checks:

{
    "shipTo": {
        "name": "Warehouse Name",
        "addressLine1": "[Warehouse Address]",
        "city": "[City]",
        "stateOrRegion": "KARNATAKA",
        "postalCode": "[Postal Code]",
        "countryCode": "IN",
        "phoneNumber": "[Phone]",
        "email": "[email]"
    },
    "shipFrom": {
        "name": "Customer Name",
        "addressLine1": "[Customer Address]",
        "city": "[City]",
        "stateOrRegion": "KARNATAKA",
        "postalCode": "[Postal Code]",
        "countryCode": "IN",
        "phoneNumber": "[Phone]",
        "email": "[email]"
    },
    "returnTo": {
        "name": "Warehouse Name",
        "addressLine1": "[Return Warehouse Address]",
        "city": "[City]",
        "stateOrRegion": "KARNATAKA",
        "postalCode": "[Postal Code]",
        "countryCode": "IN",
        "phoneNumber": "[Phone]",
        "email": "[email]"
    },
    "serviceSelection": {                 //New Object
        "serviceId": ["SWA-CRET"]
    },
    "taxDetails": [{
        "taxRegistrationNumber": "[GST Number]",
        "taxType": "GST"
    }],
    "labelSpecifications": {
        "size": { "unit": "INCH", "length": 6, "width": 4 },
        "pageLayout": "DEFAULT",
        "requestedDocumentTypes": ["LABEL"],
        "format": "PDF",
        "needFileJoining": false,
        "dpi": 203
    },
    "packages": [{
        "dimensions": {
            "length": 10,
            "width": 10,
            "height": 10,
            "unit": "CENTIMETER"
        },
        "weight": {
            "unit": "GRAM",
            "value": 500
        },
        "insuredValue": {
            "unit": "INR",
            "value": 1136.90
        },
        "isHazmat": false,
        "items": [
            {
                "description": "Product Item 1",
                "itemIdentifier": "SKU-ITEM-001",
                "quantity": 1,
                "weight": { "unit": "GRAM", "value": 166 },
                "itemValue": { "unit": "INR", "value": 568.45 },
                "isHazmat": false,
                "invoiceDetails": {
                    "invoiceNumber": "INV-9803295190",
                    "invoiceDate": "2025-08-10T15:54:10Z"
                },
                "itemQualityChecks": [{                   //New Object
                    "code": "ProductNameMatch",
                    "values": ["Product Item 1 Description"]
                }]
            },
            {
                "description": "Product Item 2",
                "itemIdentifier": "SKU-ITEM-002",
                "quantity": 1,
                "weight": { "unit": "GRAM", "value": 166 },
                "itemValue": { "unit": "INR", "value": 568.45 },
                "isHazmat": false,
                "invoiceDetails": {
                    "invoiceNumber": "INV-9803295190",
                    "invoiceDate": "2025-08-10T15:54:10Z"
                }
            }
        ],
        "packageClientReferenceId": "RETURN-ORDER-002"
    }],
    "channelDetails": {
        "channelType": "EXTERNAL"
    }
}

[TBD] Sample Response. 

Note: QUALITY_CHECKS_FEE is only charged when quality checks are opted in (either via itemQualityChecks at item level or qualityChecks VAS) and the checks are actually performed at the doorstep.

Schema Details — New Request Fields:

itemQualityChecks — Array at item level:

valueAddedServices.qualityChecks — VAS level (future scope):

Schema Details — New Response Enum Values:

Tracking Details Code — 2 new values:

StatusCode Mapping for New EventCodes:

rateItemID — 1 new value:

Error Handling [To be shared soon]

When implementing this feature, be prepared to handle these potential error responses:

Item limit exceeded (max 2 items per package):

//Item limit exceeded (max 2 items per package)
{
    "errors": [{
        "code": "[TBD]",
        "message": "[TBD]",
        "details": "[TBD]"
    }]
}

//Quality check limit exceeded (max 5 per item)
{
    "errors": [{
        "code": "[TBD]",
        "message": "[TBD]",
        "details": "[TBD]"
    }]
}

Note: The exact error codes and messages for item/quality check limit violations are being finalised and will be updated in the final launch announcement.

Future Enhancements

The launch of Customer Returns for India is the first step in our C-Returns roadmap. Future enhancements will include:

• Value Added Service — Quality Checks (VAS): A simplified opt-in for basic quality checks without specifying individual checks at item level, using "valueAddedServices": { "qualityChecks": {} } in the request
• Enhanced quality check types: Additional quality check codes beyond the initial set

FAQs

1. Will my integration break if I don't update before launch?
   If your client strictly validates enum values and rejects unknown entries, yes — the response will contain values your code does not recognise (PickupRejectedByCustomer, QualityChecksFailed, QUALITY_CHECKS_FEE). We strongly recommend treating unknown enum values gracefully.

2. Do the new TrackingDetailsCode apply to both Amazon-originated and non-Amazon-originated shipments?
   The Customer Returns feature in India is for Off-Amazon (non-Amazon-originated) shipments only. The new tracking event codes will only appear for C-Return shipments.

3. Can PickupRejectedByCustomer and QualityChecksFailed occur on the same shipment?
   No. These are mutually exclusive events — a shipment will receive one or the other, not both.

4. Is QUALITY_CHECKS_FEE charged automatically, or only when the quality checks service is opted in?
   The fee is charged only when quality checks are opted in (via itemQualityChecks at item level or qualityChecks VAS) and the checks are actually performed at the customer's doorstep.

5. What is the difference between item-level quality checks and the Quality Checks VAS?
   Item-level quality checks (itemQualityChecks) allow you to specify individual check parameters per item (e.g., product name match, seal tag check). The Quality Checks VAS (valueAddedServices.qualityChecks) is a simplified opt-in for basic quality checks without specifying individual parameters — this is reserved for future use and not available in the initial launch.

6. What are the limitations on items and quality checks?
   C-Return shipments are restricted to a maximum of 2 items per package and 5 quality checks per item.

7. How do I create a C-Return shipment?
   Use the SWA-CRET service ID in your serviceSelection, include the shipTo address (warehouse), and optionally specify itemQualityChecks at the item level. The flow is the same as standard shipment creation — GetRatesV2 → PurchaseShipment, or OneClickShipment.