Get buyer
Returns the personal data of an order's buyer.
It is the only door to the buyer's personal data: name, taxId (CPF or CNPJ), state registration, e-mail, phone and the billing and shipping addresses. Neither the order nor the webhook carries these data.
Each field comes with a state:
| State | What it says |
|---|---|
available | the value is in value |
masked | the marketplace only shows the masked text, which is in value |
withheld | the marketplace does not show this field; there is no value |
purged | erased at the end of retention; there is no value |
Every call is logged: who read, when and for what. marketapi erases the fields at the end of retention and they become purged; the order stays. The deadline is in retainUntil (default: 90 days after the order closes, or less if the marketplace requires it). While the order is open, retainUntil is null. Keep only what you need.
Common errors
404 NOT_FOUNDwithBuyer contact not found.: the order exists but has no buyer stored. CheckhasBuyerContactin Get order.404 NOT_FOUNDwithOrder not found.: the order does not exist or belongs to another account.
api_keyAuthorizationBearer <token>API key (mk_...)
orderId*stringIdentifier of the order, as the API returns it.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidThe personal data of the buyer, each field with its state (available, masked, withheld or purged). Every read is logged with the caller.
application/json- response
Personal data of the buyer of one order. Every read is logged; the fields are purged at the end of the retention.
id*stringBuyer contact id.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidfields*Every personal field with its state: available (value shown), masked (the masked text the marketplace shows), withheld (the marketplace does not show it) or purged (deleted at the end of the retention).
retainUntil*|When the personal fields will be purged. null while the order is open: the clock starts when it closes (or is delivered, where the marketplace counts from delivery).
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timepurgedAt*|When the personal fields were purged. Every field is purged from then on; the order stays.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timecreatedAt*stringWhen the contact was first stored.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timeupdatedAt*stringWhen the contact last changed.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$date-timecurl -X GET "https://example.com/v1/orders/5f3b2c1a-9d8e-4a7b-8c6d-1e2f3a4b5c6d/buyer"{ "id": "6b0f4c2a-1d3e-4f5a-9b8c-7d6e5f4a3b2c", "fields": { "name": { "state": "available", "value": "Acme Buyer" }, "taxId": { "state": "masked", "value": "***.***.789-**" }, "stateRegistration": { "state": "withheld" }, "email": { "state": "available", "value": "buyer@example.com" }, "phone": { "state": "withheld" }, "billingAddress": { "state": "available", "value": { "street": "Rua Exemplo", "number": "100", "complement": "Apto 12", "neighborhood": "Centro", "city": "São Paulo", "state": "BR-SP", "postalCode": "01000-000", "country": "BR", "rawLines": [ "Rua Exemplo, 100, Apto 12", "Centro, São Paulo - SP, 01000-000" ] } }, "shippingAddress": { "state": "available", "value": { "street": "Rua Exemplo", "number": "100", "complement": "Apto 12", "neighborhood": "Centro", "city": "São Paulo", "state": "BR-SP", "postalCode": "01000-000", "country": "BR", "rawLines": [ "Rua Exemplo, 100, Apto 12", "Centro, São Paulo - SP, 01000-000" ] } } }, "retainUntil": "2027-01-10T15:00:00.000Z", "purgedAt": null, "createdAt": "2026-10-12T15:00:00.000Z", "updatedAt": "2026-10-12T15:00:00.000Z"}