No Marketplace Gives You a Real Buyer Phone Number (What to Do Instead)

You're generating an international label. The carrier API says something like:

Recipient phone number is required.

So you go back to the order payload to find the buyer's phone, and it isn't there. You check the API reference, assume you've missed a fieldGroups or an expansion parameter, and start hunting for the flag that unlocks it.

There is no flag. Most marketplaces do not give you the buyer's real phone number, by design. It's PII with very little upside for the marketplace in sharing it, and every one of them would rather intermediate contact themselves. What you get varies:

Amazon's relay number deserves a note of its own: it routes to the buyer through Amazon's system and it expires. It is fine to hand to a carrier for a delivery-exception call. It is not a contact record — don't store it in a CRM, don't build retention on it, and don't be surprised when it stops working.

The requirement isn't arbitrary. For international shipments the consignee phone is used for customs contact and delivery exceptions, and for some lanes it's a hard validation rule at the carrier's API rather than a nice-to-have. FedEx, DHL and most consolidators will reject the booking outright rather than accept a blank.

So you have a field the marketplace won't give you and the carrier won't accept without. Every marketplace-to-carrier integration hits this, and there are only three honest ways out.

Never fabricate. A placeholder either fails the carrier's format validation or, worse, passes it — and then a real delivery exception happens, the courier dials a dead number, and the parcel sits in a depot until it's returned. You've converted a data gap into a lost shipment.

A controlled fallback is the right default. Use a real, monitored phone number that belongs to your business, and put it in the consignee phone field when the marketplace gives you nothing. The courier reaches someone who can actually resolve the exception, which is the entire purpose of the field.

Here's the refinement that's easy to miss, and it caused us a real problem: the fallback should match the destination country, not your own.

The natural implementation is to default the phone from whichever contact record you already have on the shipment — the exporter or shipper contact. That's convenient and it validates fine. But on an export lane, that contact is in the origin country. So a US delivery ends up with an origin-country phone number on the label, and a US courier hitting a delivery exception has to dial internationally to resolve it. Technically valid, practically useless.

If you ship into a country regularly, get a number that's answerable there and key the fallback on destination:

def consignee_phone(order, shipment):
    # 1. whatever the marketplace gave us, if anything
    if order.buyer_phone:
        return order.buyer_phone, "marketplace"

    # 2. a monitored number in the DESTINATION country
    fallback = DESTINATION_CONTACTS.get(order.ship_country)
    if fallback:
        return fallback, "destination_fallback"

    # 3. last resort: our own contact, and flag it
    return shipment.exporter_phone, "origin_fallback"

Return the source alongside the value and persist it. When someone later asks why a label carried a particular number, you can answer in seconds — and you can report on how many shipments went out on a fallback, which is the number that tells you whether this matters at your volume.

The phone is one instance of a broader rule: marketplaces intermediate buyer contact deliberately. Emails are relay aliases. Phone numbers are relays or absent. There is no read API for the buyer message inbox on Amazon, Etsy or Walmart, which is why so many support-integration tools work by parsing the notification emails instead.

Design for that rather than against it. Treat the marketplace as the channel of record, keep your own contact defaults for operational fields the carrier demands, and don't build any process that assumes you can reach the buyer directly — because in most cases, contractually and technically, you can't.

Does the Etsy API return the buyer's phone number?

No. Etsy receipts do not include a buyer phone on the shipping address, so if your carrier requires a consignee phone you must supply one from your own configuration.

Is the Amazon buyer phone number real?

For merchant-fulfilled orders Amazon typically supplies a relay number, sometimes with an extension. It routes to the buyer through Amazon and expires — it is usable for a delivery exception call, but it is not the buyer's actual line and should not be stored as a contact record.

What should I put in the consignee phone field when the marketplace gives none?

A real, monitored number that your business controls, ideally one answerable in the destination country. Never a fabricated placeholder: it either fails carrier validation or leaves a courier unable to reach anyone during a delivery exception.

Does Walmart's Marketplace API return a buyer phone?

No, the order response does not include one. Plan for a fallback in the same way as Etsy.

Why does my carrier reject the shipment without a phone number?

For international shipments the consignee phone is used for customs contact and delivery exceptions, and carriers such as FedEx and DHL validate its presence at booking time rather than treating it as optional.