Referencia de la API de Makatea

Introducción

The Makatea API lets your system create members and billing orders, register payments, and receive events. Every response carries Makatea-Version (the version applied to the request; the old name Makatea-API-Version carries the same value) and an X-Request-Id (send your own to correlate logs). Current version: 2026-09-27.

Versions

A version is a date. Which one applies to a request:

1. the Makatea-Version: YYYY-MM-DD header, if you send it (an unknown version is 400 invalid_api_version);
2. otherwise, the version pinned to your API key (the current one on the day the key was created — keys created before 2026-09-27 stay on 2026-09-23, so nothing changes for existing integrations);
3. otherwise (session JWT), the latest.

Webhook endpoints have their own frozen version (webhook_version, set when the endpoint is created): the shape of an event never changes under you.

• 2026-09-23: First public version: API keys, Idempotency-Key, cursor pagination, webhooks with signed bodies.
• 2026-09-27: Request bodies: a field the operation does not declare is 422 unknown_field (it used to be ignored silently, like unknown query parameters before). Webhook events (endpoints on this version): the body carries api_version and livemode (false for events of a test organization).

Sync like an ERP

PUT /v1/members/by-ref/{external_ref}, PUT /v1/billing-orders/by-ref/{external_ref} and PUT /v1/credits/by-ref/{external_ref} create or update by your identifier: 201 created, 200 updated, 200 unchanged when everything you sent is already so (nothing is written); the header Makatea-Upsert-Result says which. POST /v1/members/batch, /v1/billing-orders/batch and /v1/payments/batch take up to 500 rows, never fail as a whole (one result per row, with its index and error code), support dry_run, and emit no webhooks and send no messages.

Authentication

Create an API key in Makatea → Settings → API. Send it in either header:

Authorization: Bearer mk_live_…      (or mk_test_…)
X-API-Key: mk_live_…

Test keys (mk_test_…) work exactly the same against your organization's test copy («<org> · pruebas», created with the first test key): same rules and engine, separate data, and nothing leaves — messages are recorded as simulated, there is no payment provider. Every response says Makatea-Livemode: true|false and webhook events of the test copy carry "livemode": false (version 2026-09-27 or later).

Keys have scopes: read (GET) and write (everything else). A session JWT from the Makatea app is also accepted in Authorization (legacy). Missing or invalid credentials → 401; a key without the needed scope → 403 insufficient_scope.

Responses

Success always has the same shape, for single objects and for lists:

{"data": {…} }
{"data": [ … ], "pagination": {"limit": 100, "has_more": true, "next_cursor": "eyJm…"}}

Errors always look like this:

{"error": {"code": "validation_error", "message": "amount must be a positive number", "request_id": "…"}}

Pagination and sync

Lists accept limit (default 100, max 500) and cursor. Pass the next_cursor you received to get the next page, keeping the same filters; stop when has_more is false. offset still works for compatibility but can skip rows while data changes. Add count=true to get pagination.total (slower).

To mirror data into your system, call the list with updated_since=<last sync instant>: results come ordered by updated_at ascending, so you can page with the cursor and store the updated_at of the last row as your next checkpoint.

Idempotency

Send Idempotency-Key: <unique string> on any POST/PUT/PATCH/DELETE. Retrying with the same key and the same body returns the original response (with header Idempotent-Replayed: true) instead of acting twice. The same key with a different body is 422 idempotency_key_reused; while the first request is still running, 409 idempotency_in_progress. Keys are kept 24 hours.

Webhooks

Register an https endpoint (POST /v1/webhook-endpoints) with the event types you want (or *). The response includes the signing secret (whsec_…) only once. Each event is POSTed as:

{"id": "<event id>", "type": "payment.received", "created_at": "…", "data": {…}}

(endpoints on version 2026-09-27 or later also get "api_version" and "livemode"), with headers Makatea-Event-Id, Makatea-Event-Type, Makatea-Version (the endpoint's frozen version) and

Makatea-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

Verify by recomputing the HMAC over t + "." + raw body and comparing in constant time; reject timestamps older than 5 minutes. Answer 2xx within 10 seconds. Otherwise we retry after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h; after 8 failed attempts the delivery is failed (you can retry it with POST /v1/webhook-deliveries/{id}/retry). Deliveries can arrive more than once or out of order: use the event id to de-duplicate.

Event types: member.created, member.updated, member.paused, member.resumed, billing_order.created, billing_order.updated, billing_order.paid, billing_order.cancelled, payment.received, payment.voided, payment_link.opened, promise.created, promise.kept, promise.broken, message.sent, message.received, message.classified. *.updated events carry {"object": {…}, "previous_attributes": {…}}. Records created by CSV imports do not emit events.

Limits

600 requests per minute per API key (per organization for session JWTs), in fixed one-minute windows. Every response includes the IETF headers (draft-ietf-httpapi-ratelimit-headers)

RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=598;t=37

(q quota per w-second window, r remaining, t seconds until the window resets) and the older X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix seconds). Over the limit → 429 with Retry-After. A rejected request does not count: retrying while limited does not push the reset further. Request bodies up to 21 MB; documents up to 15 MB; batches up to 500 rows.

Error codes

Every operation lists the codes it can return, grouped by HTTP status (x-error-codes has the same as a map). The full catalog:

Status

GET /v1/status (no key) says whether the service and its database answer.

Índice de rutas

• Status
  • GET /v1/status
• Members
  • GET /v1/members
  • POST /v1/members
  • GET /v1/members/{id}
  • PUT /v1/members/{id}
  • PATCH /v1/members/{id}
  • DELETE /v1/members/{id}
• Sync
  • PUT /v1/members/by-ref/{external_ref}
  • POST /v1/members/batch
  • PUT /v1/billing-orders/by-ref/{external_ref}
  • POST /v1/billing-orders/batch
  • PUT /v1/credits/by-ref/{external_ref}
  • POST /v1/payments/batch
• Promises
  • GET /v1/members/{id}/promises
  • POST /v1/members/{id}/promises
  • DELETE /v1/members/{id}/promises/current
• Collection control
  • POST /v1/members/{id}/pause
  • POST /v1/members/{id}/resume
  • POST /v1/flows/{id}/members
  • DELETE /v1/flows/{id}/members/{member_id}
• Credit
  • GET /v1/members/{id}/credit
  • POST /v1/members/{id}/credit/apply
• Messages
  • GET /v1/members/{id}/conversation
  • POST /v1/messages
  • POST /v1/conversations/import
• Documents
  • GET /v1/members/{id}/documents
  • POST /v1/members/{id}/documents
  • DELETE /v1/members/{id}/documents/{document_id}
• Billing orders
  • GET /v1/billing-orders
  • POST /v1/billing-orders
  • GET /v1/billing-orders/{id}
  • PATCH /v1/billing-orders/{id}
  • DELETE /v1/billing-orders/{id}
  • POST /v1/billing-orders/{id}/transfer
  • POST /v1/billing-orders/{id}/split
  • POST /v1/billing-orders/{id}/forgive
  • POST /v1/billing-orders/{id}/late-fees
  • POST /v1/billing-orders/{id}/payment-link
• Payments
  • POST /v1/billing-orders/{id}/pay
  • POST /v1/billing-orders/{id}/payments
  • GET /v1/payments
  • GET /v1/payments/{id}
  • POST /v1/payments/{id}/void
• Credits (loans)
  • GET /v1/credits
  • POST /v1/credits
  • GET /v1/credits/{id}
  • PATCH /v1/credits/{id}
  • GET /v1/settings/payment-allocation
  • PUT /v1/settings/payment-allocation
• Settings
  • GET /v1/settings/branding
  • PUT /v1/settings/branding
• Webhooks
  • GET /v1/webhook-endpoints
  • POST /v1/webhook-endpoints
  • DELETE /v1/webhook-endpoints/{id}
  • GET /v1/webhook-events
  • GET /v1/webhook-deliveries
  • POST /v1/webhook-deliveries/{id}/retry
• Operations
  • GET /v1/sequence-runs
  • GET /v1/flows
  • GET /v1/templates
  • GET /v1/stats

Status

GET /v1/status

Service status (no authentication).

Checks that the database answers. Returns 503 when it does not.

Respuestas

• 200 OK · data: Status

Members

GET /v1/members

List members.

Parámetros

Respuestas

• 200 OK · data: array de Member
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/members

Create a member.

Two members may share a phone number. external_ref is unique per organization (409 if reused).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: Member
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 402 plan_limit_reached — Your plan's member limit is reached.
• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

reason_required — do_not_contact: true needs do_not_contact_reason.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/members/{id}

Get a member (with billing orders and recent interactions).

Parámetros

Respuestas

• 200 OK · data: Member
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PUT /v1/members/{id}

Update a member.

Only the fields you send are changed.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Member
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

reason_required — do_not_contact: true needs do_not_contact_reason.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PATCH /v1/members/{id}

Update a member (partial).

Only the fields you send are changed.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Member
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

reason_required — do_not_contact: true needs do_not_contact_reason.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

DELETE /v1/members/{id}

Soft-delete a member (state becomes churned).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: Member
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Sync

PUT /v1/members/by-ref/{external_ref}

Create or update a member by your external_ref (upsert).

The member identified by external_ref (your id) ends up as the body says. Does not exist → created, 201. Exists and something changed → only the fields you sent are updated, 200. Exists and every field you sent is equal → nothing is written (not even updated_at), 200. The header Makatea-Upsert-Result says which (created, updated, unchanged). Fields you omit are not touched; null clears a nullable field. Emits member.created / member.updated like the other routes (a batch does not).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Member
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 402 plan_limit_reached — Your plan's member limit is reached.
• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 external_ref_mismatch — external_ref in the body differs from the one in the path.

full_name_required — Creating a member needs full_name.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

reason_required — do_not_contact: true needs do_not_contact_reason.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/members/batch

Create or update up to 500 members by external_ref.

Never fails as a whole: each row gets its own result (created, updated, unchanged or failed with error.code, error.message, error.field), in the same order and with its index (0-based). Rows are matched by external_ref; sending the same batch twice leaves the data exactly as it was (the second time every row is unchanged). A repeated external_ref inside one batch: the first row wins, the others fail with duplicate_in_batch. dry_run: true runs everything (locks, constraints, triggers) and rolls it back: the results are the ones you would get for real. Batches emit no webhooks and send no messages (the records carry import_batch_id = batch_id); single-row calls (PUT …/by-ref/…) do emit. Each row has the same fields as PUT /v1/members/by-ref/{external_ref} plus external_ref.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Cada elemento de rows:

Respuestas

• 200 OK · data: BatchResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 402 plan_limit_reached — Your plan's member limit is reached.
• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 413 batch_too_large — More rows than the batch limit (500).
• 422 duplicate_in_batch — Another row of the same batch has this external_ref; only the first is processed.

full_name_required — Creating a member needs full_name.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

reason_required — do_not_contact: true needs do_not_contact_reason.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PUT /v1/billing-orders/by-ref/{external_ref}

Create or update a billing order by your external_ref (upsert).

Same contract as PUT /v1/members/by-ref/{external_ref}: 201 created, 200 updated or unchanged, header Makatea-Upsert-Result. To create, send member_id (or member_external_ref), amount and due_date. Updates go through the same path as PATCH /v1/billing-orders/{id} (moving due_date re-schedules its reminders, changing the breakdown re-applies its payments). An external_ref that belongs to another member's order is 409 member_mismatch (moving is explicit, with PATCH); cancelled orders are 409 order_cancelled.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

member_mismatch — The external_ref belongs to a record of another member. Moving is explicit (PATCH with member_id).

order_cancelled — The billing order is cancelled.

• 422 amount_below_paid — The new amount is lower than what was already paid and forgiven.

breakdown_exceeds_amount — capital_portion + interest_portion is larger than amount.

credit_member_mismatch — The credit belongs to another member.

credit_not_found — The credit referenced in the body (credit_id / credit_external_ref) does not exist.

external_ref_mismatch — external_ref in the body differs from the one in the path.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

immutable_field — The field can only be set when the record is created.

member_not_found — The member referenced in the body (member_id / member_external_ref) does not exist.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders/batch

Create or update up to 500 billing orders by external_ref.

Never fails as a whole: each row gets its own result (created, updated, unchanged or failed with error.code, error.message, error.field), in the same order and with its index (0-based). Rows are matched by external_ref; sending the same batch twice leaves the data exactly as it was (the second time every row is unchanged). A repeated external_ref inside one batch: the first row wins, the others fail with duplicate_in_batch. dry_run: true runs everything (locks, constraints, triggers) and rolls it back: the results are the ones you would get for real. Batches emit no webhooks and send no messages (the records carry import_batch_id = batch_id); single-row calls (PUT …/by-ref/…) do emit. Each row has the same fields as PUT /v1/billing-orders/by-ref/{external_ref} plus external_ref. New orders are scheduled for collection like any other (the reminders are the calendar, not a notification).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Cada elemento de rows:

Respuestas

• 200 OK · data: BatchResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

member_mismatch — The external_ref belongs to a record of another member. Moving is explicit (PATCH with member_id).

order_cancelled — The billing order is cancelled.

• 413 batch_too_large — More rows than the batch limit (500).
• 422 amount_below_paid — The new amount is lower than what was already paid and forgiven.

breakdown_exceeds_amount — capital_portion + interest_portion is larger than amount.

credit_member_mismatch — The credit belongs to another member.

credit_not_found — The credit referenced in the body (credit_id / credit_external_ref) does not exist.

duplicate_in_batch — Another row of the same batch has this external_ref; only the first is processed.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

immutable_field — The field can only be set when the record is created.

member_not_found — The member referenced in the body (member_id / member_external_ref) does not exist.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PUT /v1/credits/by-ref/{external_ref}

Create or update a credit (loan) by its folio (upsert).

Same contract as the other by-ref routes: 201 created, 200 updated or unchanged, header Makatea-Upsert-Result. To create, send member_id (or member_external_ref), principal and start_date. A folio of another member is 409 member_mismatch. status accepts active or cancelled.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: LoanDetail
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

member_mismatch — The external_ref belongs to a record of another member. Moving is explicit (PATCH with member_id).

schedule_on_existing_credit — schedule only applies when the credit is created; it already has installments.

• 422 external_ref_mismatch — external_ref in the body differs from the one in the path.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

member_not_found — The member referenced in the body (member_id / member_external_ref) does not exist.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/payments/batch

Register up to 500 payments (reconciliation).

Each row is one payment to one billing order (billing_order_id or billing_order_external_ref). The row's external_ref is your payment folio and makes the batch idempotent: a folio already registered with the same order and amount is unchanged (with its id), with a different order or amount it fails with external_ref_reused (void it and send a new folio). excess works like in POST /v1/billing-orders/{id}/payments. The ledger is append-only: payments are never updated. Rows run in order, so two payments to the same order see each other's effect. By default members are not notified (no «we received your payment» message) and no webhooks are emitted; send notify_members: true to send the organization's payment confirmations as if each payment came one by one. Never fails as a whole; dry_run rolls everything back.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Cada elemento de rows:

Respuestas

• 200 OK · data: BatchResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 external_ref_reused — A payment with this external_ref exists with a different order or amount. Void it and send a new one.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_cancelled — The billing order is cancelled.

order_paid — The billing order is already paid.

• 413 batch_too_large — More rows than the batch limit (500).
• 422 amount_exceeds_balance — The payment is larger than the balance and excess is reject.

duplicate_in_batch — Another row of the same batch has this external_ref; only the first is processed.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

order_not_found — The billing order referenced in the body does not exist.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Promises

GET /v1/members/{id}/promises

Current promise and history.

Parámetros

Respuestas

• 200 OK · data: PromiseState
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/members/{id}/promises

Record a payment promise.

Pauses collection messages until the promised date (one reminder survives). Replaces any active promise. When the date passes the promise becomes kept or broken (webhooks promise.kept / promise.broken).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: PromiseState
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

DELETE /v1/members/{id}/promises/current

Cancel the active promise.

Marks it cancelled (kept in history) and re-schedules collection for the member's open orders. 409 if there is no active promise.

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: PromiseState
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

no_active_promise — The member has no active payment promise.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Collection control

POST /v1/members/{id}/pause

Pause collection for a member until a date.

Stops automatic collection and campaign messages to this member until until, through the same mechanism a payment promise uses: of the reminders due before until, only the one for the most serious delay survives (moved to until); the rest are withdrawn, and nothing new is scheduled before until. Event notices (payment confirmations) and explicit sends (POST /v1/messages) still go out. until as a date (2026-10-10) means 08:00 in the organization's timezone that day; a date-time without offset is local time. Pausing an already paused member replaces the date. When until passes, collection simply resumes (no call needed). Emits member.paused.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: PauseState
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/members/{id}/resume

Resume collection now (end a pause early).

Ends the pause. The reminder that was waiting for the end of the pause is moved to the member's next decent hour (08:00–22:00 local, otherwise the next morning), and the reminders the pause withdrew that are still in the future are scheduled again. 409 not_paused if there is no active pause. Emits member.resumed.

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: PauseState
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

not_paused — The member is not paused.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/flows/{id}/members

Enroll a member in a flow (flows whose audience is a member list).

Adds the member to the flow's explicit audience list and, if the flow is active, schedules its messages right away (idempotent: enrolling twice changes nothing). Only flows with audience_mode: members have a list; a flow whose audience is defined by tags, segments or states answers 409 flow_audience_not_editable (membership there follows that criterion: change the member's tags or state instead).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: FlowMembership
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 flow_audience_not_editable — The flow's audience is defined by tags, segments or states, not by a member list.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

DELETE /v1/flows/{id}/members/{member_id}

Remove a member from a flow (member-list flows).

Removes the member from the flow's list and withdraws its pending messages of that flow. Same 409 flow_audience_not_editable rule as enrolling.

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: FlowMembership
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 flow_audience_not_editable — The flow's audience is defined by tags, segments or states, not by a member list.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Credit

GET /v1/members/{id}/credit

Credit balance and its ledger.

Parámetros

Respuestas

• 200 OK · data: Credit
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/members/{id}/credit/apply

Apply the credit balance to open orders (oldest first).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: CreditApplied
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Messages

GET /v1/members/{id}/conversation

Messages exchanged with a member (newest first).

Parámetros

Respuestas

• 200 OK · data: array de Interaction
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/messages

Send a message to a member.

With text: sent right away through the organization's line (WhatsApp or SMS) — status: sent.

With template_id: queued for the sending engine, which renders the template variables — status: queued (any channel, including email).

Respects opt-outs (409 opted_out), the organization's kill switch (409 comms_disabled) and its send window (409 outside_send_window, text only; queued messages wait for the window).

Organizations in simulation mode record the message but nothing leaves (status: simulated).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 202 OK · data: MessageResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 comms_disabled — Messaging is turned off for this organization.

do_not_contact — The member is marked «do not contact»: nothing is sent to them.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

opted_out — The member opted out of messages.

outside_send_window — Outside the organization's send window.

template_inactive — The template is not active.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

no_recipient — The member has no phone (WhatsApp/SMS) or no email (email).

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.
• 502 send_failed — The channel provider rejected the message.
• 503 channel_unavailable — No connected line for that channel.

POST /v1/conversations/import

Import conversation history (messages that happened outside Makatea).

Up to 20,000 rows per call. Idempotent by external_id (or by member + time + direction + text). Imported messages trigger nothing: no auto-replies, no notices, no webhooks. dry_run validates without writing. Members are matched by member_external_ref, or by phone when exactly one member has it. Re-sending a row that was imported without its attachment completes it.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Cada elemento de rows:

Respuestas

• 200 OK · data: ConversationImportResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 413 payload_too_large — Body over 21 MB or document over 15 MB.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.
• 502 import_failed — The conversation import service failed.

Documents

GET /v1/members/{id}/documents

List a member's documents (with temporary download URLs, valid 1 hour).

Parámetros

Respuestas

• 200 OK · data: array de Document
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/members/{id}/documents

Attach a document to a member.

Send the file inline (content_base64) or a public https url the server downloads. Max 15 MB. With external_ref, repeating the call returns the existing document (200) instead of uploading twice.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: Document
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 413 payload_too_large — Body over 21 MB or document over 15 MB.
• 422 download_failed — The document URL could not be downloaded.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.
• 502 storage_error — The document could not be stored.

DELETE /v1/members/{id}/documents/{document_id}

Delete a document (file and record).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: Deleted
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Billing orders

GET /v1/billing-orders

List billing orders.

Default order: due_date ascending. With updated_since: updated_at ascending.

Parámetros

Respuestas

• 200 OK · data: array de BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders

Create a billing order.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 breakdown_exceeds_amount — capital_portion + interest_portion is larger than amount.

credit_member_mismatch — The credit belongs to another member.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/billing-orders/{id}

Get a billing order.

Parámetros

Respuestas

• 200 OK · data: BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PATCH /v1/billing-orders/{id}

Update a billing order (move the date, change the amount, …).

Moving due_date re-schedules its collection messages. Raising amount above what was paid re-opens a paid order; lowering it to what is covered marks it paid. late_fee sets the accumulated late fee (absolute). capital_portion/interest_portion set the breakdown (also on paid orders: it is history) and re-apply the order's payments. Cancelled orders cannot be edited (409).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_cancelled — The billing order is cancelled.

• 422 amount_below_paid — The new amount is lower than what was already paid and forgiven.

breakdown_exceeds_amount — capital_portion + interest_portion is larger than amount.

credit_member_mismatch — The credit belongs to another member.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

DELETE /v1/billing-orders/{id}

Cancel a billing order (409 if already paid).

Optional reason (query ?reason= or JSON body {"reason": …}, max 500 chars) is stored as cancel_reason — e.g. «consolidated into another account». Cancelling an already cancelled order with a reason updates the reason.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_paid — The billing order is already paid.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders/{id}/transfer

Transfer an installment's balance to another installment of the same member.

For a debt that is now collected elsewhere (restructure, consolidation into a new loan). The origin must be open and untouched (no payments, no forgiveness); it becomes cancelled with transferred_to_order_id and cancel_reason (reason or «Traspasada a <destination>»), and its collection stops. Its credit is liquidated by itself when nothing else of it is open. The destination's amount does not change unless add_to_destination is true (when your system did not already include it). Repeating the same transfer answers 200 with already_transferred. Do not send an amount of 0 to say this: amounts must be positive.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: TransferResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_has_payments — The billing order has payments or forgiveness; only an untouched balance can be transferred.

order_not_open — The operation needs a pending or overdue billing order.

transfer_not_allowed — The destination order is cancelled, paid (with add_to_destination), the same order, or belongs to another member.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

order_not_found — The billing order referenced in the body does not exist.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders/{id}/split

Split a billing order into several (explicit parts or generated installments).

Splits what is still owed (amount − amount_paid − amount_forgiven) into new billing orders of the same member, credit and currency, each with parent_order_id = this one. Either send parts (2 to 60 {amount, due_date, period_label?, external_ref?} that must add up exactly to the balance, else 422 split_sum_mismatch with details.expected), or installments (2 to 60) + frequency (default monthly) + first_due_date (default: the order's due date, or today in the organization's timezone if that already passed): the balance is split to the cent and the last one absorbs the rounding. The original is kept as history: with nothing paid it becomes cancelled (cancel_reason = reason or «Dividida en N partes»); with partial payments its amount is lowered to what was covered and it becomes paid. A breakdown (capital/interest) is split proportionally; an order with a breakdown and payments cannot be split (409 split_breakdown_partially_paid). Only pending/overdue orders (409 order_not_open).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Cada elemento de parts:

Respuestas

• 201 OK · data: SplitResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_not_open — The operation needs a pending or overdue billing order.

split_breakdown_partially_paid — A billing order with a capital/interest breakdown and payments cannot be split; void the payments or remove the breakdown first.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

split_sum_mismatch — The parts of a split do not add up to the balance to the cent (details.expected, details.got).

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders/{id}/forgive

Forgive (condone) part or all of the balance.

Forgiven money is not a payment: it does not appear in /v1/payments. Without amount, forgives the whole balance and the order becomes paid. On orders with a breakdown the forgiveness takes, of what is still owed, late fee first, then interest, then other charges and principal last (forgiven_now_breakdown; forgiven principal is a loss).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

nothing_to_forgive — The billing order has no balance to forgive.

order_cancelled — The billing order is cancelled.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders/{id}/late-fees

Add a late fee to an order.

Adds to late_fee and fires the late_fee_applied notice if the organization configured one. With collectible: true the fee is also added to amount (it becomes owed; a paid order re-opens). When omitted, the organization's moratorio_cobrable setting decides (default: informational only).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: BillingOrder
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_cancelled — The billing order is cancelled.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders/{id}/payment-link

Create (or reuse) a payment link, optionally send it to the member.

Creates the link with the organization's payment provider, or returns the current one if it has not expired (url: Stripe Checkout, or Makatea's page for OXXO/SPEI references). page_url is always Makatea's payment page for this order (/pagar/<token>): it works with any provider and its opens are observable — each open emits payment_link.opened (deduplicated per link in a 10-minute window, no personal data) and is counted in opens.count / opens.last_opened_at.

expires_at asks for a validity; it is bounded to what the provider accepts (Stripe 30 min – 24 h, Conekta 1 h – 30 days) and the response carries the real one. Asking for a different validity than the current link's creates a new link.

The link charges the order's open balance (amount − paid − forgiven) in the order's currency. Providers by currency: Stripe, any currency; Conekta, MXN only; Pix, BRL orders of an organization with a Pix key (Pix comes first for BRL, even with Stripe connected; provider: "pix", no expiry). A new link is created when the balance or the currency changed since the current one.

send_via (whatsapp, sms or email) also sends page_url to the member right away, with the same rules as POST /v1/messages (opt-outs, «do not contact», kill switch, send window for WhatsApp/SMS, simulation mode). Nothing is sent without a payment provider for the order's currency (409 no_payment_provider) or for a paid/cancelled order (409 order_not_open). The link is created even if the send fails: the error says why it was not sent.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: PaymentLink
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 comms_disabled — Messaging is turned off for this organization.

do_not_contact — The member is marked «do not contact»: nothing is sent to them.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

no_payment_provider — The organization has no active payment provider.

opted_out — The member opted out of messages.

order_not_open — The operation needs a pending or overdue billing order.

outside_send_window — Outside the organization's send window.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

no_recipient — The member has no phone (WhatsApp/SMS) or no email (email).

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.
• 502 payment_link_unavailable — The payment provider could not create the link.

send_failed — The channel provider rejected the message.

• 503 channel_unavailable — No connected line for that channel.

Payments

POST /v1/billing-orders/{id}/pay

Settle the whole remaining balance.

Registers one payment for exactly the remaining balance. For partial or historical payments use POST /v1/billing-orders/{id}/payments.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: PaymentResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_cancelled — The billing order is cancelled.

order_paid — The billing order is already paid.

payment_voided — The Idempotency-Key belongs to a payment that was voided. A voided payment is not re-applied: send the new payment with a new key. details.payment_id is the voided one.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/billing-orders/{id}/payments

Register a payment (partial, historical date, overpayment policy).

excess decides what happens when amount is larger than the balance: reject (default) answers 422 amount_exceeds_balance; credit applies the excess to the member's next open orders (oldest first) and keeps the rest as credit balance.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: PaymentResult
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

order_cancelled — The billing order is cancelled.

payment_voided — The Idempotency-Key belongs to a payment that was voided. A voided payment is not re-applied: send the new payment with a new key. details.payment_id is the voided one.

• 422 amount_exceeds_balance — The payment is larger than the balance and excess is reject.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/payments

List payments (the ledger).

Every money movement: payments (kind: payment) and reversals of voided payments (kind: reversal, negative amount). allocation says how each entry was applied to its installment (principal, interest, late fee, other charges, unassigned; null when the installment has no breakdown); a reversal carries exactly the same figures, negative. paid_at is when the money was received (it can be in the past); recorded_at is when the entry reached Makatea — created_since/updated_since and the ordering use recorded_at, so a back-dated payment registered today still shows up in your next sync. The ledger is append-only, so updated_since is an alias of created_since. Default order: newest first; with a *_since filter: oldest first.

Parámetros

Respuestas

• 200 OK · data: array de Payment
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/payments/{id}

Get a payment.

Parámetros

Respuestas

• 200 OK · data: Payment
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/payments/{id}/void

Void a payment.

Writes a reversal (negative) entry, lowers the order's amount_paid and re-opens it if needed. 409 already_voided the second time.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Payment
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 already_voided — The payment was already voided.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

not_voidable — Reversal entries cannot be voided.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Credits (loans)

GET /v1/credits

List credits (loans) with their principal, what came back and what is owed.

Each credit groups the installments of one loan (external_ref = your folio) and carries its principal. totals are to date: capital_recovered/interest_collected/late_fee_collected = what the payment ledger applied to its installments (voided payments net out); capital_outstanding/interest_outstanding = of its open installments with breakdown; balance = amount − paid − forgiven of its open installments; paid_without_ledger = paid amounts imported as history, with no ledger entry. Default order: start_date descending; with updated_since: updated_at ascending.

Parámetros

Respuestas

• 200 OK · data: array de Loan
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/credits

Create a credit (loan): generate its installments or attach existing ones.

external_ref (your folio) is unique per organization: reusing it is 409. start_date is when the money was lent: it decides in which period the principal counts as «placed».

Generate the installments with schedule: installments payments, frequency weekly (+7 days), biweekly (+14 days), semimonthly (the 15th and the last day of each month; a first_due_date on another day moves to the next of the two) or monthly (same day each month, or day_of_month; a day the month lacks becomes its last day: Jan 31 → Feb 28 → Mar 31), starting at first_due_date (default: one period after start_date). Amounts: installment_amount each (total = n × amount), otherwise total_amount split in n, otherwise principal split in n. Split exactly to the cent: the first ones get the floor and the last one absorbs the rounding (1,000 / 3 = 333.33 + 333.33 + 333.34). When both principal and total are known each installment carries its capital/interest breakdown (the interest is total − principal, split the same way). Installments are labeled «Pago i de n» and, if the credit has a folio, get external_ref = <folio>-<i>. All or nothing: if they cannot be created the credit is not created either.

Attach existing installments instead by id or external_ref; they must belong to the same member (422 credit_member_mismatch).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: LoanDetail
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 billing_orders_not_found — Some billing orders in the list do not exist (details.missing).

credit_member_mismatch — The credit belongs to another member.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/credits/{id}

Get a credit with its installments and their breakdown.

Parámetros

Respuestas

• 200 OK · data: LoanDetail
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PATCH /v1/credits/{id}

Update a credit, attach or detach installments.

Only the fields you send change. status can be set to cancelled (the principal stops counting as placed) or back to active; liquidated is computed from its installments.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: LoanDetail
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 billing_orders_not_found — Some billing orders in the list do not exist (details.missing).

credit_member_mismatch — The credit belongs to another member.

idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/settings/payment-allocation

How payments are split between late fee, interest and principal.

Parámetros

Respuestas

• 200 OK · data: AllocationRule
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PUT /v1/settings/payment-allocation

Change the payment allocation rule.

moratorio_interes_capital (default: late fee, then interest, then other charges, then principal), proporcional (each payment split in proportion to what is owed of each part) or al_liquidar (a partial payment stays «unassigned» until the installment is settled; the settling payment recognizes all of its principal and interest on its date). The rule is fixed on each installment when its breakdown is loaded; with apply_existing: true every installment with breakdown is re-applied with the new rule (past figures change).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: AllocationRule
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Settings

GET /v1/settings/branding

Whether messages and pages carry «Cobrado con Makatea».

Parámetros

Respuestas

• 200 OK · data: Branding
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

PUT /v1/settings/branding

Show or hide «Cobrado con Makatea» (on by default).

Controls the footer of collection emails («Cobrado con Makatea · makatea.ai»; other emails say «Enviado con Makatea») and the Makatea mark on the payment page (/pagar/<token>). On by default.

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 200 OK · data: Branding
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Webhooks

GET /v1/webhook-endpoints

List webhook endpoints.

Parámetros

Respuestas

• 200 OK · data: array de WebhookEndpoint
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/webhook-endpoints

Register a webhook endpoint (the signing secret is returned only here).

Parámetros

Acepta Idempotency-Key.

Cuerpo (JSON)

Respuestas

• 201 OK · data: WebhookEndpointCreated
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 409 conflict — A record with the same unique value (usually external_ref) already exists.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

unknown_field — A body field the operation does not accept (API version 2026-09-27 or later). details.field names it.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

DELETE /v1/webhook-endpoints/{id}

Delete a webhook endpoint (its pending deliveries are dropped).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: Deleted
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.
• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/webhook-events

List emitted events (newest first).

Events are recorded only while the organization has at least one active endpoint subscribed to that type.

Parámetros

Respuestas

• 200 OK · data: array de WebhookEvent
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/webhook-deliveries

List delivery attempts (newest first).

Parámetros

Respuestas

• 200 OK · data: array de WebhookDelivery
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

POST /v1/webhook-deliveries/{id}/retry

Retry a delivery now (pending or failed).

Parámetros

Acepta Idempotency-Key.

Respuestas

• 200 OK · data: WebhookDelivery
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_idempotency_key — Idempotency-Key must be 1 to 255 characters.

invalid_json — The body is not valid JSON, is not an object, or is missing when required.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 404 not_found — The resource does not exist in your organization.
• 409 already_delivered — The webhook delivery was already delivered.

idempotency_in_progress — A request with the same Idempotency-Key is still running. Retry shortly.

• 422 idempotency_key_reused — The Idempotency-Key was already used with a different request body.

validation_error — A field is missing or has an invalid value. details.field names it.

• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Operations

GET /v1/sequence-runs

List scheduled/sent collection messages (newest scheduled first).

Parámetros

Respuestas

• 200 OK · data: array de SequenceRun
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_cursor — The cursor is malformed or belongs to another ordering. Keep the same filters between pages.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/flows

List the organization's flows.

Parámetros

Respuestas

• 200 OK · data: array de Flow
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/templates

List the organization's active templates.

Parámetros

Respuestas

• 200 OK · data: array de Template
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

GET /v1/stats

Dashboard numbers — the same figures the app's Panel shows.

Every money figure comes from the same database function the app uses (org_metricas_cobranza), so the API and the Panel never disagree. metrics has the full set for the period (from/to, default: 1st of the current month to today, in the org's timezone): collected = money that came in by payment date (voided payments, credit-balance applications and future-dated rows excluded), overdue/upcoming = real balance (amount − paid − forgiven) of open installments due before / on-or-after today, aging by days late (1-9, 10-30, 31-60, 60+), collection_rate = of what came due in the period up to today, the share already paid. metrics.capital_profit splits the same period into principal and profit: placed (principal lent, by credit start_date), collected.capital|interest|late_fee|other|unassigned|no_breakdown|to_credit_balance (they add up exactly to collected.total, the same «collected» as above), profit = interest + late fee collected with its margin over what was collected with a breakdown, outstanding principal and interest (current / overdue) of open installments, and forgiven split into principal (a loss), interest, late fee and other. coverage.status is none when no installment has a breakdown: then every figure is 0 and no_breakdown carries the money. portfolio and members keep their old shape.

Parámetros

Respuestas

• 200 OK · data: Stats
• 400 invalid_api_version — The Makatea-Version header names a version that does not exist. details.versions lists the valid ones.

invalid_parameter — A query parameter has an invalid value (not a UUID, not a date, out of range).

unknown_parameter — A query parameter the route does not declare. details.allowed lists the valid ones.

• 401 invalid_api_key — The API key (mk_live_… or mk_test_…) does not exist, was revoked or expired.

unauthorized — Missing or invalid credentials.

• 403 insufficient_scope — The API key lacks the scope this operation needs (read for GET, write for the rest).
• 429 rate_limited — Over the per-minute limit. Wait Retry-After seconds. Rejected requests do not count against the limit.
• 500 internal_error — Our fault. Safe to retry with the same Idempotency-Key.

Objetos

ErrorBody

Error

Pagination

Status

Member

BillingOrder

Payment

TransferResult

PaymentResult

PromiseState

Credit

CreditApplied

Interaction

MessageResult

ConversationImportResult

Document

Deleted

PaymentLink

Branding

WebhookEndpoint

WebhookEndpointCreated

object

WebhookEvent

WebhookDelivery

SequenceRun

Flow

FlowMembership

PauseState

Template

Stats

object

Loan

SplitResult

LoanDetail

object

BatchResult

AllocationRule