Introduction

Garage CRM billing API

Overview

Garage CRM invoices and payments API (Cloudflare Worker + D1).

Integration guide: Garage CRM billing service docs

OpenAPI v0.1.0 · source openapi/billing.json

OpenAPI 3.0.0 · v0.1.0 · 13 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/health"

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/health"

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Invoices

Invoice generation.

get/v1/invoices

List invoices

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/invoices"

Returns a compact summary per invoice for the organisation in the JWT (`orgId`). Use GET `/v1/invoices/{id}` for totals breakdown and catalog line `id`s.

Operation ID: listInvoices

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
customer_id	query	string (uuid)	Optional customer UUID filter within the authenticated organisation.

Responses

200
Invoice summaries
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/invoices

Create invoice

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  
}' \
  "https://api.mayawealth.co.uk/billing/v1/invoices"

Creates a draft invoice with line items for the JWT organisation. Server assigns invoice `id`. Response includes summary plus `items` (catalog `id` per line only); use GET `/v1/invoices/{id}/items` to list lines later.

Operation ID: createInvoice

Request body(required)

application/jsonobject

Responses

201
Invoice created
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/invoices/{id}

Get invoice

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/invoices/example-id"

Full invoice including line items (`id` = catalog item, pricing, VAT per line).

Operation ID: getInvoice

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).

Responses

200
Invoice detail
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/invoices/{id}/items

List invoice line items

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/invoices/example-id/items"

Line items persisted at create time (`id` = catalog item, quantity, unit_price, vat_rate, discount, line_total).

Operation ID: listInvoiceItems

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).
page	query	integer	—
page_size	query	integer	—

Responses

200
Invoice items
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/invoices/{id}/issue

Issue invoice

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/invoices/example-id/issue"

Operation ID: issueInvoice

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).

Responses

200
Invoice issued
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/invoices/{id}/cancel

Cancel invoice

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/invoices/example-id/cancel"

Operation ID: cancelInvoice

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).

Responses

200
Invoice cancelled
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

Payments

Payment recording.

get/v1/invoices/{id}/payments

List invoice payments

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/invoices/example-id/payments"

Operation ID: listInvoicePayments

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).
page	query	integer	—
page_size	query	integer	—

Responses

200
Payments
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/invoices/{id}/payments

Record payment

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/billing/v1/invoices/example-id/payments"

Records a completed payment against the invoice in the path (`invoice_id` is implicit). Body is `amount`, optional `currency`, and `payment_method` only — payment `status` is set to `paid` by the server; use POST `/v1/payments/{id}/refund` to reverse. Rejects amounts above `balance_due` (422 with remaining balance) and further payments when the invoice is already paid in full.

Operation ID: createPayment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).

Request body(required)

application/jsonPaymentCreate

Responses

201
Payment recorded
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/payments/{id}

Get payment

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/payments/example-id"

Operation ID: getPayment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).

Responses

200
Payment
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/payments/{id}/refund

Refund payment

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/payments/example-id/refund"

Operation ID: refundPayment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Resource id (UUID).

Responses

200
Payment refunded
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

Audit

Immutable change log for this service.

get/v1/audit

Audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/billing/v1/audit"

Operation ID: listAudit

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—

Responses

200
Audit events
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json