Clients

Clients represent the customer's end clients: companies, merchants, or individuals the customer invoices. In the education model, students are also modeled as clients (see operating models).

Model

{
  "id": 1042,
  "businessName": "Kiosco Central",
  "taxId": "30998888887",
  "documentType": "CUIT",
  "email": "[email protected]",
  "branchExternalCode": null,
  "branchDescription": null,
  "branchReferenceAddress": null,
  "externalId": "ERP-CLI-12345"
}

Field	Type	Required	Description
id	int64	(response)	ID assigned by Max Pay
businessName	string	Yes	Legal name or full name
taxId	string	Yes	CUIT/CUIL, 11 digits without dashes
documentType	enum	Yes	CUIT or CUIL
email	string	No	Client contact email
branchExternalCode	string	Only if the client has a branch	Branch identifier code
branchDescription	string	Only if the client has a branch	Branch description
branchReferenceAddress	string	Only if the client has a branch	Branch address
externalId	string	No	Client ID in the integrator's ERP

Branches

A client with multiple branches is modeled as one row per branch, with the same taxId and a different branchExternalCode. Each branch is a separate client for the purposes of receivables and receivable accounts.

Example: BebidasPyme S.R.L. with 3 branches:

// All 3 rows share taxId and differ in branchExternalCode
[
  { id: 1101, businessName: "BebidasPyme S.R.L.", taxId: "30997777776", branchExternalCode: "01", branchDescription: "Centro"   },
  { id: 1102, businessName: "BebidasPyme S.R.L.", taxId: "30997777776", branchExternalCode: "02", branchDescription: "Norte"    },
  { id: 1103, businessName: "BebidasPyme S.R.L.", taxId: "30997777776", branchExternalCode: "03", branchDescription: "Belgrano" }
]

To list all branches for the same CUIT:

GET /v1/clients?taxId=30997777776

Endpoints

Method	Path	Description
GET	/v1/clients	List with filters
POST	/v1/clients	Create (upsert by taxId + branch)
GET	/v1/clients/{id}	Detail
PUT	/v1/clients/{id}	Update
GET	/v1/clients/{id}/receivable-accounts	Receivable accounts for the client
GET	/v1/clients/{id}/associates	Associates that share receivable accounts with this client (derived)

POST is upsert

POST /v1/clients has upsert behavior keyed by the uniqueness tuple (customer, documentType, documentNumber, branchExternalCode). If a client already exists with that combination, the response is 200 OK with the existing client (not 201 Created). This makes initial synchronization idempotent without having to handle duplicate errors.

POST /v1/clients
Idempotency-Key: erp-cli-12345
Content-Type: application/json

{
  "businessName": "Kiosco Central",
  "taxId": "30998888887",
  "documentType": "CUIT",
  "email": "[email protected]",
  "externalId": "ERP-CLI-12345"
}

Status	Meaning
201 Created	Client created for the first time
200 OK	Client already existed and is returned as-is from the system

Search filters

GET /v1/clients

Parameter	Type	Description
customerId	int64	(not applicable through the public API — customer is implicit)
taxId	string	Exact CUIT/CUIL, 11 digits without dashes
branchExternalCode	string	Branch code
ids	array of int64	List of specific IDs
externalId	string	Integrator's ID
page, count	int	Pagination

Update

PUT /v1/clients/1042
Content-Type: application/json

{
  "businessName": "Kiosco Central S.R.L.",
  "email": "[email protected]",
  "taxId": "30998888887",
  "documentType": "CUIT"
}

taxId, documentType, and branchExternalCode cannot be modified (they are part of the client's identity). To "rename" a client to a different CUIT, you must create a new one.

Common errors

Scenario	HTTP	code
taxId with invalid format	400	validation
Client with a branch but missing branchDescription or branchReferenceAddress	422	incomplete-branch
Client without a branch but branchExternalCode set	422	incomplete-branch
documentType not supported	400	validation

No bulk creation for now

Bulk client creation is not exposed for now; public exposure is being evaluated for future versions. If your integration requires bulk client creation (more than 50 per day), contact your account manager to evaluate options.

For bulk creation of receivable accounts linked to existing clients, see Bulk creation of receivable-accounts.