List merchants
LiveServed by the v1 API in development with the same checks as production; production opens on the same contract. The capabilities from before v1 keep running in production at the path your account team gives you.
Merchants of your company, most recent first. Needs the merchants:read scope.
oauth2 merchants:readAuthorizationBearer <token>OAuth 2.0 client credentials. Exchange your client_id and client_secret at /oauth/token of the environment for a bearer token valid for one hour. The playground of every operation asks for your own client and keeps it in your browser tab only.
Scope: merchants:read
external_id?stringFilter by your id.
rfc?stringFilter by RFC.
status?stringFilter by status. csd_expiring is within 30 days of the CSD's end.
"active""pending_csd""csd_expiring""csd_expired"created_from?stringCreated on or after this day (YYYY-MM-DD, Mexico City time), inclusive.
datecreated_to?stringCreated on or before this day (YYYY-MM-DD, Mexico City time), inclusive. There is no cap on the range.
datecursor?stringFrom next_cursor of the previous page.
limit?integer1 to 500.
1 <= value <= 500100OK
application/json- response
data*array<>next_cursor*|nullcurl -X GET 'https://api.dev.b2b.heru.app/v1/merchants?created_from=2026-10-01&created_to=2026-10-31'{ "data": [ { "id": "mer_01m4ra8wsyfh3s0tr4nrq3y96j", "external_id": "AFIL-000123", "status": "active", "rfc": "HEGL900101K44", "legal_name": "JOSE LUIS HERNANDEZ GARCIA", "trade_name": "Cafetería La Esquina", "slug": "cafeteria-la-esquina", "tax_regime": "612", "postal_code": "06700", "email": "facturacion@cafeteria-la-esquina.example", "locations": [ { "external_id": "SUC-01", "name": "Sucursal Roma", "postal_code": "06700" }, { "external_id": "SUC-02", "name": "Sucursal Condesa", "postal_code": "06140" } ], "default_item": { "product_code": "90101500", "unit_code": "E48", "description": "Consumo de alimentos y bebidas", "vat_rate": "0.16" }, "csd": { "active": true, "valid_from": "2025-03-18", "valid_to": "2029-03-18" }, "onboarding": { "status": "completed", "url": null, "expires_at": null, "completed_at": "2026-10-12T15:41:27.904Z" }, "created_at": "2026-10-12T15:04:06.206Z", "updated_at": "2026-10-12T18:10:58.543Z" } ], "next_cursor": null}Upload the CSDPUT
Uploads or replaces the merchant's CSD from your back end, for integrations that already hold it. Prefer the onboarding page when you can: with it you never handle the merchant's certificate or password. heru checks the files and calculates the merchant status from the certificate dates. When a check fails it answers `422` and keeps the current CSD; every code is explained in [CSD errors](/errors/csd). Needs the `merchants:csd` scope.
Get a merchantGET
Returns the merchant with its CSD and onboarding status. Needs the `merchants:read` scope.