REST API — v1

API Documentation

Access your invoices and clients programmatically. Available on the Business plan.

Authentication

All requests must include your API key in the Authorization header. Create and manage your keys in Account → API Keys.

curl https://paycivo.com/api/v1/invoices \
  -H "Authorization: Bearer pv_live_YOUR_KEY_HERE"

Base URL

https://paycivo.com/api/v1

All responses are JSON. All request bodies should be Content-Type: application/json.

Error Codes

Name	Description
200	OK — request succeeded
201	Created — resource was created
400	Bad Request — missing or invalid fields
401	Unauthorized — missing or invalid API key
403	Forbidden — feature not available on your plan
404	Not Found — resource does not exist
500	Server Error — something went wrong on our end

Endpoints

GET/api/v1/invoices— List Invoices

Returns a paginated list of invoices for the authenticated user.

Parameters

Name	Type	Required	Description
status	string	optional	Filter by status: draft \| sent \| paid \| overdue
limit	number	optional	Max results to return (default 50, max 100)
offset	number	optional	Pagination offset (default 0)

Example Response

{
  "data": [ { "id": "...", "invoice_number": "INV-2026-0001", "status": "paid", "total": 1500, ... } ],
  "total": 24,
  "limit": 50,
  "offset": 0
}

GET/api/v1/invoices/:id— Get Invoice

Returns a single invoice by ID.

Parameters

Name	Type	Required	Description
:id	string	required	The invoice UUID

Example Response

{ "data": { "id": "...", "invoice_number": "INV-2026-0001", "status": "paid", ... } }

PATCH/api/v1/invoices/:id— Update Invoice

Update an invoice's status, notes, or due date.

Parameters

Name	Type	Required	Description
:id	string	required	The invoice UUID
status	string	optional	New status: draft \| sent \| paid \| overdue
notes	string	optional	Updated notes
due_date	string	optional	Updated due date (YYYY-MM-DD)

Example Response

{ "data": { "id": "...", "status": "paid", ... } }

POST/api/v1/invoices— Create Invoice

Creates a new invoice.

Parameters

Name	Type	Required	Description
invoice_number	string	required	Unique invoice number (e.g. INV-2026-0001)
issue_date	string	required	Issue date (YYYY-MM-DD)
due_date	string	required	Due date (YYYY-MM-DD)
line_items	array	required	Array of { description, quantity, rate }
client_id	string	optional	Client UUID (from /api/v1/clients)
tax_rate	number	optional	Tax percentage (e.g. 8.5)
discount_percent	number	optional	Discount percentage (e.g. 10)
currency	string	optional	ISO currency code (default USD)
notes	string	optional	Optional notes

Example Response

{ "data": { "id": "...", "invoice_number": "INV-2026-0001", "status": "draft", "total": 1500, ... } }

GET/api/v1/clients— List Clients

Returns a paginated list of clients.

Parameters

Name	Type	Required	Description
limit	number	optional	Max results (default 50, max 100)
offset	number	optional	Pagination offset (default 0)

Example Response

{
  "data": [ { "id": "...", "name": "Acme Corp", "email": "billing@acme.com", ... } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

GET/api/v1/clients/:id— Get Client

Returns a single client by ID.

Parameters

Name	Type	Required	Description
:id	string	required	The client UUID

Example Response

{ "data": { "id": "...", "name": "Acme Corp", "email": "billing@acme.com", ... } }

Ready to build?

Get started free →

Questions? Email us at support@paycivo.com