Invoice automation API

Start with a new delivery

Use an API key from Settings and the Pro webhook allowance. The free invoice editor and anonymous PDF downloads remain available without an account.

In an HTTP action, send a JSON POST to https://freeinvoicemaker.app/api/webhooks/inbound/v1. Prepare one unique Idempotency-Key for each delivery before its first attempt. Save that key with the request body.

After a timeout or an unconfirmed response, retry this same endpoint with the same key and JSON fields. Don’t generate another key for the same delivery.

curl -X POST https://freeinvoicemaker.app/api/webhooks/inbound/v1 \
  -H "Authorization: Bearer iv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_NEW_DELIVERY_ID" \
  -d '{
    "from": "Acme Studio",
    "to": "Globex Inc",
    "items": [
      { "description": "Web design", "quantity": 1, "rate": 420000 }
    ],
    "currency": "USD",
    "notes": "Payment details agreed with the client."
  }'

Invoice fields

Amounts use whole currency minor units: 420000 means $4,200.00 in USD. Names and line items are validated; text is never silently shortened and fractional minor-unit amounts are rejected.

from, to

Required business and client names; up to 500 characters each.

items

One to 200 items with an optional description, quantity and whole minor-unit rate. Quantity defaults to 1 and rate to 0.

amount

A whole minor-unit amount for one service item, when items are absent. Provide items or amount.

currency

Three-letter currency code. Defaults to USD.

due_date

Optional real calendar date in YYYY-MM-DD format.

notes

Optional payment or project notes, up to 5,000 characters.

The issue date is the date of the first accepted delivery. A later retry keeps that original invoice. Item order matters; JSON object-key order does not.

Read the result

• 201: a new unpaid draft was accepted.
• 200: this delivery was already accepted. The response shows the current invoice and its original write_ack; later edits are preserved.
• 409, OPERATION_REUSED: that key already accepted different JSON fields. Keep the original request and review the intended change.
• 409, ACCEPTED_UNAVAILABLE: acceptance is confirmed, but the invoice is no longer available. Don’t create a replacement automatically.
• 409, LEGACY_DELIVERY_REVIEW_REQUIRED: review the earlier invoice and automation run before starting a new delivery.
• 500, UNKNOWN_RESULT: keep the key and body and retry them together. This response does not prove that creation failed.

Invalid inputs return 400 or 422. A missing entitlement returns 403; new-creation rate limits return 429. An exact accepted retry can still be acknowledged after an entitlement change or rate limit.

Earlier automation setups

The unversioned /api/webhooks/inbound endpoint is retired. Pause old jobs and review their runs and existing invoices before configuring this version with fresh delivery keys. Don’t redirect a queue of uncertain old requests to the new endpoint.

Earlier delivery records did not preserve request hashes, and some may have expired. Their absence cannot establish that an invoice was never created.

Delivery boundaries

This endpoint creates invoice drafts. It does not send email, collect payment or forward outbound webhooks. Provider-specific workflows need their own end-to-end qualification; this guide does not claim an installed Zapier or Make.com app.

For other workflows, use the Developer Portal, API reference or free invoice editor.