> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List merchants
> Retrieve a paginated list of all merchant records registered under your platform, with optional limit and offset controls for large result sets.
This endpoint returns a paginated collection of all merchant records associated with your platform. Use it to build internal dashboards, audit merchant onboarding progress, or sync merchant data to your own systems. Results are returned in descending order of creation date by default. For large platforms with many merchants, use the `limit` and `offset` query parameters to page through the full result set in manageable chunks.
To retrieve all merchants programmatically, iterate with `offset` incremented by `limit` on each request until `offset >=
total`.
## OpenAPI
````yaml GET /v1/merchants
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/merchants:
get:
tags:
- Merchants
summary: List merchants
description: Returns an array of merchants.
parameters:
- schema:
$ref: '#/components/schemas/limit'
required: false
description: The number of records to be taken.
name: limit
in: query
- schema:
allOf:
- $ref: '#/components/schemas/offset'
- nullable: true
required: false
description: The number of records to be skipped.
name: offset
in: query
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
minimum: 0
description: The number of taken records.
example: 100
offset:
type: integer
minimum: 0
description: The number of skipped records.
example: 0
total:
type: integer
minimum: 0
description: Total number of records
example: 140
items:
type: array
items:
type: object
properties:
external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a merchant.
status:
type: string
enum:
- ENROLLED
- INACTIVE
- EXPIRED
description: Merchant's enrollment status
created_at:
type: number
description: >-
Timestamp indicating when the merchant was created
(unix time in seconds).
example: 1582896122
updated_at:
type: number
description: >-
Timestamp indicating the last time the merchant was
updated (unix time in seconds).
example: 1582896122
legal_name:
type: string
description: >-
Merchant's full legal name incl. the legal form if
applicable.
example: ACME Distribution GmbH
legal_form:
type: string
enum:
- LIMITED_COMPANY
- SOLE_TRADER
- PARTNERSHIP
- PUBLIC_COMPANY
- COOPERATIVE
- GOVERNMENT
- OTHER
description: >-
Merchant's legal form, which depends on the
merchant's registered country. [Available legal
forms](https://docs.tilta.io/docs/legal-forms) cover
Tilta's operating countries.
trading_name:
type: string
nullable: true
description: Merchant's trading name.
example: ACME
business_identifiers:
type: array
nullable: true
items:
type: object
properties:
type:
type: string
enum:
- VAT_ID
- TAX_ID
- REGISTER_ID
- CREFO_ID
- ALLIANZ_TRADE_ID
- SCHUFA_ID
- CREDITSAFE_ID
- CRIF_ID
- ELLISPHERE_ID
description: The type of business identifier
value:
type: string
maxLength: 48
description: The value of the business identifier
country:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TM
- TC
- TV
- TR
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
description: Two-letter country code (ISO 3166-1 alpha-2).
required:
- type
- value
- country
additionalProperties: false
description: A list of business identifiers
business_address:
type: object
properties:
street:
type: string
description: Address line (e.g. street, road, place).
example: Example Street
house:
type: string
description: House number or denominator.
example: 42b
postcode:
type: string
description: ZIP or postal code.
example: '12345'
city:
type: string
description: City, district, town, or village.
example: Berlin
country:
type: string
enum:
- AF
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CD
- CG
- CK
- CR
- HR
- CU
- CW
- CY
- CZ
- CI
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MK
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RO
- RU
- RW
- RE
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TM
- TC
- TV
- TR
- UG
- UA
- AE
- GB
- UM
- US
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
- AX
description: Two-letter country code (ISO 3166-1 alpha-2).
additional:
type: string
nullable: true
description: >-
Additional address information (e.g. PO Box, c/o
name etc.).
example: c/o Testimonial
required:
- postcode
- city
- country
description: Merchant's address.
contact_emails:
type: array
items:
type: string
format: email
maxItems: 10
description: Merchant's contact emails
incorporated_at:
type: number
nullable: true
description: >-
Merchant's date of incorporation (unix time in
seconds), meaning the date when the business of
registered or started.
example: 1582896122
required:
- external_id
- status
- created_at
- updated_at
- legal_name
- legal_form
- business_address
- contact_emails
additionalProperties: false
description: A merchant has been successfully created or updated.
required:
- limit
- offset
- total
- items
additionalProperties: false
description: A list of merchants.
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
security:
- bearerAuth: []
components:
schemas:
limit:
type: integer
description: The number of records to be taken.
example: 100
default: 100
maximum: 100
offset:
type: integer
description: The number of records to be skipped.
example: 0
default: 0
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````