Pre-launch Announcement: Dynamic Return Address Support in Amazon Shipping API

Starting July 2026, Amazon Shipping API will actively validate and use the returnTo field on getRates and oneClickShipment for per-shipment return-to-origin (RTO) routing.

Key Updates

1. Per-shipment return address: Specify a different return address for each shipment directly in your API request
2. Automatic validation: Amazon Shipping validates the provided return address in real time. If valid, it is used for RTO routing. If validation fails, the system falls back to your pickup warehouse return address in Shipper Central
3. Fully backward compatible: Not sending returnTo today? Nothing changes for you

How It Works

When you include a returnTo address block in your getRates or oneClickShipment request, Amazon Shipping validates the address. If the address is specific and deliverable (a valid street-level address), it will be used as the return address for that shipment in the event of an RTO.

If the address cannot be validated, the system automatically falls back to the return address configured on your pickup warehouse in Shipper Central — your shipment is not rejected and no error is thrown.

Marketplace Rollout

Schema

The returnTo block is supported on getRates and oneClickShipment. This field already exists in the Amazon Shipping v2 schema — no integration rework is required.

{
  "returnTo": {
    "name": "string",
    "companyName": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "stateOrRegion": "string",
    "postalCode": "string",
    "countryCode": "string",
    "phoneNumber": "string"
  }
}

Please refer to Address schema under API reference doc.

Tip: Including the recommended fields (city, stateOrRegion) significantly reduces the chance of address validation falling back to your pickup warehouse default.

Sample API Request — getRates with returnTo

{
  "shipFrom": {
    "name": "Shipper Warehouse",
    "addressLine1": "500 Industrial Parkway",
    "city": "Columbus",
    "stateOrRegion": "OH",
    "postalCode": "43204",
    "countryCode": "US"
  },
  "shipTo": {
    "name": "Customer Name",
    "addressLine1": "123 Main Street",
    "city": "Austin",
    "stateOrRegion": "TX",
    "postalCode": "78701",
    "countryCode": "US"
  },
  "returnTo": {
    "name": "Returns Center",
    "companyName": "Shipper Returns Facility",
    "addressLine1": "200 Return Drive",
    "city": "Dallas",
    "stateOrRegion": "TX",
    "postalCode": "75201",
    "countryCode": "US"
  },
  "packages": [
    {
      "dimensions": {
        "length": 12,
        "width": 8,
        "height": 6,
        "unit": "INCH"
      },
      "weight": {
        "unit": "POUND",
        "value": 2.5
      },
      "items": [
        {
          "itemValue": {
            "unit": "USD",
            "value": 49.99
          },
          "description": "Apparel - Jacket",
          "quantity": 1
        }
      ],
      "packageClientReferenceId": "order-67890"
    }
  ],
  "channelDetails": {
    "channelType": "EXTERNAL"
  }
}

Sample API Request — oneClickShipment with returnTo

{
  "shipFrom": {
    "name": "Shipper Warehouse",
    "addressLine1": "500 Industrial Parkway",
    "city": "Columbus",
    "stateOrRegion": "OH",
    "postalCode": "43204",
    "countryCode": "US"
  },
  "shipTo": {
    "name": "Customer Name",
    "addressLine1": "123 Main Street",
    "city": "Austin",
    "stateOrRegion": "TX",
    "postalCode": "78701",
    "countryCode": "US"
  },
  "returnTo": {
    "name": "Returns Center",
    "companyName": "Shipper Returns Facility",
    "addressLine1": "200 Return Drive",
    "city": "Dallas",
    "stateOrRegion": "TX",
    "postalCode": "75201",
    "countryCode": "US"
  },
  "packages": [
    {
      "dimensions": {
        "length": 12,
        "width": 8,
        "height": 6,
        "unit": "INCH"
      },
      "weight": {
        "unit": "POUND",
        "value": 2.5
      },
      "items": [
        {
          "itemValue": {
            "unit": "USD",
            "value": 49.99
          },
          "description": "Apparel - Jacket",
          "quantity": 1
        }
      ],
      "packageClientReferenceId": "order-67890"
    }
  ],
  "channelDetails": {
    "channelType": "EXTERNAL"
  },
  "labelSpecifications": {
    "format": "PDF",
    "size": {
      "width": 4,
      "length": 6,
      "unit": "INCH"
    },
    "dpi": 300,
    "pageLayout": "DEFAULT",
    "needFileJoining": false,
    "requestedDocumentTypes": ["LABEL"]
  }
}

What Stays the Same

• No API contract changes — returnTo already exists in the v2 schema. No new fields, no version bump.
• Fully backward compatible — Shippers not sending returnTo continue to use the warehouse default.
• Works with all carrier configurations — AMZL, USPS DDU, USPS GA, or any combination on your account.
• Return address is not printed on the label — No label format changes.
• No changes to billing, pricing, or claims — The return address used for RTO routing does not affect how shipments are billed or invoiced.

Error Handling

No new error codes are introduced with this feature. The returnTo field uses a silent fallback model:

• If the address is valid → used for RTO routing
• If the address is invalid or incomplete → system falls back to your warehouse default
• If the field is omitted → no change from current behaviour

Your API call will not be rejected due to an invalid returnTo address.

Important Notes

• This feature applies to outbound shipments. The returnTo address is used only in the event of a Return-to-Origin (RTO) scenario.
• The returnTo field is optional. If omitted, behaviour remains exactly as today.
• Address validation happens in real time during the API call. No pre-registration or onboarding step is required for your return address.
• If you are already sending returnTo values in your API requests today, be aware that these values are currently not yet utilised for routing. Once this feature is live for your account, those addresses will be actively validated and used. Review your existing values for accuracy.
• Integrators: Ensure that the returnTo field is passed through to the Amazon Shipping API if your shipper provides it.

FAQs

1. Do I need to make any API changes to use this feature?
   No. The returnTo field already exists in the Amazon Shipping v2 schema on getRates and oneClickShipment. Simply include it in your request payload. No new endpoints, no version changes, no integration rework.

2. What happens if I don't send a returnTo address?
   Nothing changes. Your shipments will continue to use the return address configured on your pickup warehouse in Shipper Central, exactly as they do today.

3. What happens if the return address I provide fails validation?
   The system automatically falls back to the return address on your pickup warehouse in Shipper Central. Your shipment is not rejected and no error is thrown.

4. Are there any additional charges when the return address differs from my warehouse address?
   No. There are no changes to billing, pricing, or claims with this feature. The return address used for RTO routing does not affect how shipments are billed. No additional line items will appear on your invoice.

5. I'm already sending returnTo in my API requests today. What happens when this feature goes live?
   Today, returnTo values are not yet utilised for routing — the system always uses your warehouse default. Once this feature is enabled on your account, those addresses will be actively validated and used for RTO routing. If your existing values are accurate street-level addresses, no action is needed. If they contain test data or placeholder values, update them before the feature is enabled.

6. I'm using a 3P integrator. Will this work?
   Yes, provided your integrator passes the returnTo field through to the Amazon Shipping API. If your integrator strips optional fields, the feature will not function. Contact your integrator to confirm returnTo passthrough support.

7. Can I send a different return address for every shipment?
   Yes. Each API call can include a unique returnTo address, allowing you to route returns to different facilities based on product type, geography, or business logic.

8. Is the return address printed on the shipping label?
   No. The return address is not printed on the label. The returnTo address is used internally by Amazon Shipping for RTO routing only.

9. Does this work for all carrier types on my account?
   Yes. Dynamic return address works with all carrier configurations — AMZL, USPS DDU, USPS GA, or any combination enabled on your account.

10. Will this feature be available in all marketplaces?
    The feature launches in the US first (July 2026), followed by UK, FR, IT, and ES in late Q3 2026.

11. Does this affect Push Notifications or Tracking API responses?
    No. Push Notifications and Tracking API responses are not affected by this feature.

12. What address formats are accepted?
    The return address must be a valid, specific, street-level address in the same country as the shipment origin. PO Boxes, vague locations, or incomplete addresses may fail validation and trigger the fallback to your warehouse default.

13. Is there an option to opt out of this feature?
    If you do not send a returnTo field, the feature does not activate. No separate opt-out mechanism is needed.

14. Will I be notified before this feature is enabled on my account?
    Pilot shippers will be contacted directly. For General Availability, the feature will be available to all eligible shippers. If you are currently sending returnTo values, review them for accuracy ahead of the GA date.