Invoices

Create invoices, send them to customers, and accept payments against them. Invoices can be paid by card, ACH, or mail.

Invoice ↔ transaction linkage

When an invoice is paid, the resulting transaction's order_id and po_number fields are populated with the invoice ID, so you can look a transaction up from the invoice and vice versa. If you set invoice_number explicitly, that value is used as the order_id instead of the internal invoice ID.

Create invoice

POST /api/invoice

Top-level fields

Field	Type	Required	Description
`currency`	string	required	Currency code, e.g. `USD`.
`company_name`	string	optional	Issuing company.
`company_logo_url`	string	optional	Hosted URL of logo image to embed.
`customer_number`	string	optional	Your own customer identifier.
`customer_id`	string	optional	Vaulted customer ID, if this invoice is for a saved customer.
`invoice_number`	string	optional	Your own invoice identifier.
`date_due`	datetime	required	Due date, e.g. `2025-02-13T06:00:00.000Z`.
`payable_to`	object	required	Address of the company being paid. See below.
`bill_to`	object	required	Address of the customer being billed. See below.
`items`	array	required	Line items. See below.
`settings.allow_tipping`	boolean	optional	Show a tip input on the hosted invoice page.
`advanced_fields`	boolean	optional	Enables extra line-item fields (shipped quantity, freight, taxable, tax rates).
`enable_tax`	boolean	optional	When `true`, invoice-level tax overrides item-level tax.
`enable_shipping`	boolean	optional	Show a shipping amount on the invoice.
`require_shipping_details`	boolean	optional	Force collection of a shipping address.
`require_billing_details_on_payment_only`	boolean	optional	Delay billing-address collection until payment.
`tax_percent`	string	required	Invoice-level tax rate. Use `"0.000"` to treat `tax` as a flat amount.
`tax` / `shipping`	integer	optional	Amounts in cents. `tax` is overridden by `tax_percent` unless that is `"0"`.
`amount_paid`, `service_fees_paid`, `surcharge_paid`, `discount_credited`	integer	optional	Pre-existing paid amounts.
`adjustment`	integer	optional	Payment adjustment applied to the invoice total.
`allow_partial_payment`	boolean	optional	Let customers pay less than the full amount due.
`transaction_type`	string	optional	`sale` (default) or `authorize`.
`payment_methods`	string array	required	Allowed methods: some combination of `card`, `ach`, `mail`.
`card_processor_id` / `ach_processor_id`	string	required	Which processor to use for each type. Empty strings are accepted if you do not offer that type.
`message`	string	optional	Message shown to the customer on the invoice.
`save_customer_vault`	string	optional	`none`, `optional`, `required` — controls whether the customer gets vaulted at payment.
`send_via`	string	required	`email`, `text`, `both`, or `none`.
`email_to`	string	optional	Destination email address.

Address objects (payable_to, bill_to)

Either supply an id referring to a stored address, or inline all of: first_name, last_name, company, address_line_1 (required), address_line_2, city (required), state (two-letter, required), postal_code (required, must be valid for the country), country (two-letter, required), phone, fax, email.

Line items

Field	Type	Required	Description
`status`	string	required	`pending` or `paid`.
`type`	string	optional	Item type.
`name`	string	optional	Item name.
`description`	string	optional	Line description.
`unit_price`	integer	required	Cents.
`quantity`	integer	required	Units.
`quantity_shipped`	integer	optional	Units shipped so far.
`product_code`	string	optional	SKU or product identifier.
`commodity_code`	string	optional	Commodity code — used for Level 3 data.
`unit_of_measure`	string	optional	E.g. `lb`, `kg`.
`alternate_tax_identifier`	string	optional	Line-specific tax ID.
`taxable`	boolean	optional	Apply line-level tax instead of invoice-level.
`local_tax_rate` / `local_tax`	string / integer	optional	Local tax rate and amount in cents.
`national_tax_rate` / `national_tax`	string / integer	optional	National tax rate and amount in cents.
`tax_rate` / `tax_amount`	string / integer	optional	Combined rate (local + national) and total tax amount.
`discount_amount`	integer	optional	Line discount in cents.
`freight_amount`	integer	optional	Freight in cents.

Get invoice by ID

GET /api/invoice/{invoice_id}

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "bhi9vado3hogrne0u4tg",
    "currency": "USD",
    "company_name": "ACME Inc.",
    "customer_number": "123Customer",
    "payable_to": { ... },
    "bill_to": { ... },
    "items": [ ... ],
    "subtotal": 100,
    "tax_percent": "0.00",
    "tax": 0,
    "total": 100,
    "amount_paid": 0,
    "amount_due": 100,
    "payment_methods": ["card"],
    "status": "pending",
    "public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
    "hosted_url": "https://sandbox.fluidpay.com/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
  }
}

Search invoices

POST /api/invoices/search

Field	Type	Description
`id`	object	`{operator: "=" \| "!=", value: <id>}`
`amount_due`	object	`{operator: "=" \| "!=" \| "<" \| ">", value: <integer cents>}`
`date_due`	object	`{start_date, end_date}`, UTC `YYYY-MM-DDTHH:MM:SSZ`.
`limit` / `offset`	integer	0–100 / any.

Update invoice

POST /api/invoice/{invoice_id}

Same shape as create, with one additional field:

Field	Type	Description
`amount_due`	integer	Override the calculated amount due, in cents.

Delete invoice

DELETE /api/invoice/{invoice_id}

Resend invoice

POST /api/invoice/{invoice_id}/resend

Pay invoice

POST /api/invoice/{invoice_id}/pay

Charge an invoice directly from the API. Required unless paying_via_mail is set. The body looks like a transaction request:

Field	Description
`payment_method.card`	`number`, `expiration_date` (MM/YY), `cvc`.
`payment_method.ach`	`routing_number`, `account_number`, `sec_code` (`web`/`ccd`/`ppd`/`tel`), `account_type`.
`payment_method.customer`	`id` (required), optional `payment_method_id`.
`payment_method.token`	Tokenizer token.