INVOQLY FLOW · API v1

Invoqly Flow.
Your workspace, connected.

Bring client details and draft invoices into Invoqly from your CRM, school system or internal software. Your API key is bound to one workspace and only the permissions you choose.

Start with Invoqly Flow

1. Sign in and open API access. Select the business workspace you want to connect.
2. Choose Create API key, give it a name and select only the permissions needed.
3. Copy the key once and store it in your server's secrets. There is one key type; new keys access your real workspace.
4. Check included credits or add a one-time top-up. Creating a key costs nothing.
5. Call the endpoints below. Review draft invoices in your dashboard before issuing or emailing them.

Invoqly Flow is our invoicing API, identified as invoqly-flow-v1. It is not a chat or text-generation model. API requests operate on real workspace records. Earlier sample keys remain isolated; they are never converted into production keys.

Authentication and permissions

Base URL: https://invoqly.top/api/v1. Send Authorization: Bearer YOUR_INVOQLY_API_KEY. Keys expire after 90 days; revoke and replace them to rotate. Keep keys in server-side secret settings. Do not put keys in public JavaScript, URLs, repositories or screenshots.

Choose clients:read, clients:write, invoices:read and/or invoices:write. Read access and write access are separate permissions. Additional opt-in scopes are invoices:share, payments:read, reports:read, business:read and usage:read. Existing keys do not gain these permissions automatically. Create a replacement key with only the access your integration needs. API keys are not your Google, Supabase, PayPal or OpenRouter credentials.

Available endpoints

New invoices are drafts. Review, issue, email and schedule reminders in the normal Invoqly dashboard. This API does not collect or hold your customers’ payments.

Create a client

Use a fresh Idempotency-Key for each intended new write. Reuse it, with the same body, when retrying a failed or timed-out request.

curl https://invoqly.top/api/v1/clients \
  -H "Authorization: Bearer $INVOQLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: client-sample-001" \
  -d '{"name":"Sample Studio","email":"sample@example.com"}'

Windows PowerShell: use curl.exe or the example below. Set the key only in your local session, never send it to support.

$headers = @{
  Authorization = "Bearer $env:INVOQLY_API_KEY"
  "Idempotency-Key" = "client-sample-001"
}
Invoke-RestMethod -Method Post `
  -Uri "https://invoqly.top/api/v1/clients" `
  -Headers $headers -ContentType "application/json" `
  -Body '{"name":"Sample Studio","email":"sample@example.com"}'

Create a draft invoice

Use the returned client ID from the same workspace. Dates are YYYY-MM-DD; the due date must be on or after the issue date. All of Invoqly’s supported billing currencies remain available.

{
  "client_id": "REPLACE_WITH_RETURNED_CLIENT_ID",
  "issue_date": "2026-10-25",
  "due_date": "2026-11-08",
  "currency": "USD",
  "items": [
    {"description": "Design services", "quantity": 1, "unit_price": 125}
  ],
  "notes": "Thank you for your business."
}

POST this body to /invoices with a new Idempotency-Key. Each item supports description (1–500 characters), quantity, unit_price and optional tax_rate (0–100) and discount_amount. Include 1–100 items. Unknown fields are rejected, including workspace, owner, payment and status fields.

Open the invoice from the API response

Creating an invoice returns data.invoice_url: a normal browser link to the same Invoqly invoice preview used on the website. Show it as an “Open invoice” link in your integration. data.edit_url opens the draft editor; data.api_url is the server API endpoint, not a public preview.

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "draft",
    "invoice_url": "https://invoqly.top/dashboard#invoice/11111111-1111-4111-8111-111111111111",
    "edit_url": "https://invoqly.top/dashboard#editor/11111111-1111-4111-8111-111111111111",
    "api_url": "https://invoqly.top/api/v1/invoices/11111111-1111-4111-8111-111111111111"
  },
  "mode": "live",
  "credits_used": 1,
  "credits_remaining": 499
}

This example uses a fictional ID. The real response contains your created invoice’s ID. Opening invoice_url in the current browser uses its existing Invoqly session. If signed out, sign in with the account that owns the invoice; the route is remembered in that tab for ten minutes. Another account cannot open your private invoice. Browser viewing does not spend API credits. Invoice reads, lists and updates also include the workspace link; draft responses include the editor link. Legacy sample records do not receive workspace links.

For a customer who should not sign in, first issue the invoice in your workspace, then call POST /invoices/{id}/share with {"enabled":true} and the invoices:share permission. Its data.url is the existing client-facing https://invoqly.top/i/… link, using your Invoqly invoice design. The response’s invoice_url still opens your private workspace. Share links grant viewing access to anyone holding them; disabling or regenerating invalidates the old link. Creating a draft never publishes it or sends an email.

Connect a complete workflow

Download the Node.js integration example (Node.js 22+). It keeps the API origin fixed, does not follow redirects, retries temporary failures and preserves the same Idempotency-Key. Store your key in a server environment variable; the downloaded file contains no secret and creates nothing until you call it.

1. Create a client, then create a draft invoice using that client ID. This uses two credits. Return invoice.data.invoice_url to your frontend and render an ordinary browser link. Keep the key on your server.
2. Read GET /invoices/{id} to obtain updated_at. To edit a draft, send PATCH /invoices/{id} with expected_updated_at plus notes, due_date and/or payment_instructions. A changed invoice returns 409; read it again before retrying a new edit. Issued invoices cannot be edited this way.
3. Client PATCH supports name, email, phone, address, tax_number and notes. It does not rewrite snapshots on earlier invoices.
4. Issue and email the invoice from your normal workspace. The API does not issue invoices or send invoice/reminder emails.
5. With invoices:share, POST to /invoices/{id}/share using {"enabled":true}. Add "regenerate":true to replace the old link, or use {"enabled":false} to turn sharing off. Only issued, non-void invoices can be shared. Anyone with an enabled link can open it.
6. Read recorded payment history, currency-separated reports, business details and plan/credit usage through their separate permissions. These endpoints do not collect money or verify a bank payment.

Every successful operation still uses one credit. PATCH and share requests require an Idempotency-Key, just like creation. Identical write retries cost zero. credits_remaining in the response is the balance after that request; a usage snapshot is taken before its own credit is consumed.

Activity, alerts and reliability

API access shows seven days of database-handled request totals and errors. Gateway rejections before database access appear only in service logs. Totals record operation, response status, date and database processing duration, without keys, invoice content or client details. Cloudflare service logs use request IDs, status, operation and timing for troubleshooting.

You can enable or disable low-credit, seven-day key-expiry and unconfirmed-checkout notices in API access. They go through Resend from hello@invoqly.top to your verified account email. Low-credit notices are limited to one per seven days during recent API use; key and checkout notices are deduplicated. An unconfirmed checkout can be abandoned and is not proof that money was charged.

Operational checks run every five minutes. Two consecutive failures notify the service owner once, followed by a recovery notice when checks pass again. Alerts do not automatically buy credits.

Pagination, limits and retry safety

List endpoints accept ?limit=20&offset=0, with limit 1–50 and offset 0–10,000. Responses include next_offset when another page may exist. Keys allow 30 requests/minute; a workspace allows 60/minute and 2,000/day across all its keys. Days reset at midnight UTC. These are usage safeguards, not credit expiry.

Write retries return the original response, even across two keys for the same workspace. Reusing an Idempotency-Key for different data returns 409. Retry identifiers are retained; delayed retries do not silently create duplicates. This pilot allows 10,000 distinct writes per workspace; contact hello@invoqly.top before reaching that ceiling.

Prices and how long they last

The API has no separate monthly fee or automatic refill. Successful reads also cost one credit. Fractional top-up credits are rounded down. The full quantity is shown before payment.

API credits and pricing

One successful API request uses one credit. Validation errors, denied requests, provider failures and successful idempotent write replays use zero credits. Repeat GET requests each use one credit. Included plan credits are used before purchased credits.

Included credits are shared across the account, do not roll over and are available only for its confirmed paid subscription period. Yearly plans receive their yearly allocation for that paid year. The Scale plan has a finite API allowance; invoice and client allowances are separate.

Any verified account can purchase extra API credits. $0.95 buys 500 credits ($0.0019 per successful request). Minimum top-up: $4.99 for 2,626 credits. Maximum per top-up: $99.99 for 52,626 credits. Fractional credits are rounded down. Existing purchase quotes keep their original credit quantity. Purchases are in USD, belong to the selected workspace, do not expire and are not transferable or cash-withdrawable. There is no automatic refill or automatic API card charge.

Open API access → choose an amount → Continue to PayPal. Enter PayPal or card details only on PayPal’s secure page. Guest/card availability depends on PayPal, region and account eligibility. Invoqly does not collect or store card details. Credits appear only after our server verifies the completed payment with PayPal; approval or a return link alone is insufficient. Use Check payment if confirmation is delayed. Refunds and reversals remove the corresponding credits; if those credits have already been used, further API requests can be paused until the balance is resolved. Read the refund policy.

Credit purchases do not upgrade your subscription or increase invoice/client capacity. For example, a Free account still has its Free invoice/client limits. Drafts count toward normal invoice allowance. This API does not charge your clients or process their invoice payments.

Errors

Errors use {"error":{"code":"…","message":"…"},"request_id":"…"}. Keep the request ID when contacting support; never include your key or private invoice data.

Version policy

These routes are versioned as v1. Additive fields may appear; integrations should ignore fields they do not recognize. Breaking changes will use a new API version and be announced in this guide at least 90 days before v1 retirement.

Privacy · Terms · Refunds · hello@invoqly.top