Create and track vendor bills via the API

Bill Pay is Meow’s accounts-payable surface. You record what you owe a vendor as a bill, including its line items, due date, and how it should be paid, and the API saves it as a draft. Someone on your team approves the bill in the Meow dashboard, and only then does it get paid.

Every bill you touch through the API stays a draft pending approval. Creating a bill, editing it, or attaching documents never moves money on its own. Payment happens only after a human approves the bill in the dashboard.

You’ll need

An API key with billpay:read to list and retrieve bills, and billpay:write to create, update, delete, and attach documents to them.
A contact for each vendor, created with banking (ACH, wire, or check) counterparty details, or with a crypto_address to pay the vendor in stablecoin. A bill is payable to a contact that must already exist; create one first with POST /contacts. (The Contacts guide covers crypto contacts.)
If your key can access more than one entity, pass the x-entity-id header to choose which entity the bill belongs to.

1. Create a bill

A bill is payable to a contact_id and is made of one or more line items. Each line item is either an EXPENSE (a flat amount) or an ITEM (a unit amount times a quantity); the bill total is calculated from the lines. Send a unique Idempotency-Key header so a retried request never creates a duplicate.

curl -X POST https://api.meow.com/v1/bills \
  -H "x-api-key: $MEOW_API_KEY" \
  -H "Idempotency-Key: bill-2026-06-30-catnip-001" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "invoice_number": "CATNIP-4471",
    "bill_date": "2026-06-30",
    "bill_due_date": "2026-07-30",
    "description": "June cloud hosting",
    "memo": "Approved by ops",
    "payment_type": "ACH",
    "currency": "USD",
    "line_items": [
      { "type": "EXPENSE", "amount": 1200.00, "description": "Cloud hosting - June" },
      { "type": "ITEM", "amount": 15.00, "quantity": 20, "description": "Extra storage (GB)" }
    ]
  }'

Response

{
  "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "status": "DRAFT",
  "vendor_name": "Catnip Cloud",
  "invoice_number": "CATNIP-4471",
  "description": "June cloud hosting",
  "bill_date": "2026-06-30",
  "bill_due_date": "2026-07-30",
  "bill_total": "1500.00",
  "currency": "USD",
  "payment_type": "ACH",
  "contact_id": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "created_at": "2026-06-30T10:30:00.000Z",
  "line_items": [
    { "id": "1a2b3c4d-...", "type": "EXPENSE", "amount": "1200.00", "quantity": null, "description": "Cloud hosting - June", "amount_total": "1200.00" },
    { "id": "2b3c4d5e-...", "type": "ITEM", "amount": "15.00", "quantity": "20", "description": "Extra storage (GB)", "amount_total": "300.00" }
  ]
}

Save id. It is the {bill_id} for attaching documents, tracking, updating, or canceling the bill below.

Field	Description
`idempotency_key`	Deprecated. Send the `Idempotency-Key` header instead. Still accepted for now; when both are sent they must match.
`contact_id`	The vendor this bill is payable to. The vendor must already exist as a contact.
`payment_type`	How the bill is paid once approved: `ACH` (default), `WIRE`, `CHECK`, or `CRYPTO`.
`crypto_contact_destination_id`	Required when `payment_type` is `CRYPTO`: which of the vendor’s saved crypto addresses to pay, taken from the contact’s `payment_methods.crypto[].id`. Rejected for any other payment type.
`account_id`	The account to pay from, in the id format returned by `GET /accounts`. Defaults to your configured bill pay account.
`currency`	The bill’s currency (ISO 4217). Defaults to `USD`.
`bill_date` / `bill_due_date`	The date on the bill and the date it’s due (`YYYY-MM-DD`).
`line_items`	The lines that make up the bill. Use `type: "ITEM"` with a `quantity` for itemized lines, or `type: "EXPENSE"` for a flat amount.
`rrule`	An iCalendar RRULE to make this a recurring bill.

Bill Pay accepts the ACH, WIRE, CHECK, and CRYPTO payment types. A CRYPTO bill must be in USD and names one of the vendor’s saved crypto addresses; the bill’s bill_payment_details.crypto_destination reports the address it will pay. International payments are arranged in the Meow dashboard, not through this API.

2. Attach supporting documents

Supporting documents can include receipts, purchase orders, and related files. The flow has three steps. Request upload URLs, upload each file, and attach the files. You can attach up to five documents in one request.

Request upload URLs

Describe each file, giving its filename, content_type, and size in bytes, and get a short-lived upload target for each.

curl -X POST https://api.meow.com/v1/bills/$BILL_ID/documents/presigned-urls \
  -H "x-api-key: $MEOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "files": [ { "filename": "catnip-cloud-4471.pdf", "content_type": "application/pdf", "size": 48213 } ] }'

Response

{
  "uploads": [
    {
      "url": "https://uploads.meow.com/billpay",
      "fields": { "key": "billpay/9a8b.../catnip-cloud-4471.pdf", "policy": "eyJ...", "x-amz-signature": "abc123" },
      "object_key": "billpay/9a8b.../catnip-cloud-4471.pdf",
      "filename": "catnip-cloud-4471.pdf",
      "max_bytes": 10485760
    }
  ]
}

Upload each file

POST the file to its url as a multipart form, including every entry from fields and putting the file last. Keep it under max_bytes and upload before the URL expires.

curl -X POST "https://uploads.meow.com/billpay" \
  -F "key=billpay/9a8b.../catnip-cloud-4471.pdf" \
  -F "policy=eyJ..." \
  -F "x-amz-signature=abc123" \
  -F "file=@catnip-cloud-4471.pdf"

Confirm the attachment

Confirm each upload with the object_key and filename you received. The response is the updated bill, now carrying the document under additional_documents with a short-lived download URL.

curl -X POST https://api.meow.com/v1/bills/$BILL_ID/documents \
  -H "x-api-key: $MEOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "documents": [ { "object_key": "billpay/9a8b.../catnip-cloud-4471.pdf", "filename": "catnip-cloud-4471.pdf" } ] }'

Response

{
  "id": "9a8b7c6d-...",
  "status": "DRAFT",
  "vendor_name": "Catnip Cloud",
  "additional_documents": [
    { "id": "d1e2f3a4-...", "name": "catnip-cloud-4471.pdf", "url": "https://download.meow.com/...", "created_at": "2026-06-30T10:32:00.000Z" }
  ]
}

Attach the primary invoice

Use the invoice endpoints when one file is the vendor’s primary invoice. The invoice can be replaced, and accounting integrations use it as the bill attachment.

Call POST /bills/{bill_id}/invoice/presigned-url with the file details.
Upload the file with the returned URL and fields.
Call POST /bills/{bill_id}/invoice with the returned object_key and filename.

Call DELETE /bills/{bill_id}/invoice to remove the invoice from the bill. Call DELETE /bills/{bill_id}/documents/{document_id} to remove a supporting document.

3. Track bills

GET /bills returns a paginated list and filters by status, vendor, amount, and date ranges, plus full-text search.

curl "https://api.meow.com/v1/bills?statuses=DRAFT&statuses=PENDING&due_date_to=2026-07-31&limit=25" \
  -H "x-api-key: $MEOW_API_KEY"

Parameter	Description
`statuses`	Filter by one or more bill statuses; repeat the parameter for several.
`contact_id`	Filter to bills payable to specific vendors.
`amount_min` / `amount_max`	Filter by bill total.
`bill_date_from` / `bill_date_to`	Filter by the date on the bill.
`due_date_from` / `due_date_to`	Filter by due date.
`search`	Full-text search across bill fields.
`sort_by` / `sort_descending`	Order the results.
`limit` / `offset`	Page through results using the `nextOffset` from the previous response.

Retrieve one bill with GET /bills/{bill_id}:

curl https://api.meow.com/v1/bills/$BILL_ID -H "x-api-key: $MEOW_API_KEY"

A bill moves through these statuses as it’s approved and paid:

`status`	Meaning
`DRAFT`	Created and waiting for approval in the dashboard.
`PENDING`	Submitted and moving through approval.
`APPROVED`	Approved and ready to be scheduled.
`SCHEDULED`	Approved with a payment scheduled; see `scheduled_at`.
`PAYMENT_INITIATED`	Payment is on its way.
`PAYMENT_DELIVERED`	Payment delivered; see `paid_at`.
`PAYMENT_FAILED`	The payment attempt failed.
`REJECTED`	An approver declined the bill.
`CANCELED`	The bill was canceled before payment.

4. Update or cancel a draft

While a bill is still a DRAFT, you can edit it. PATCH uses partial semantics: only the fields you send change, and sending line_items replaces the existing lines (send an empty list to clear them).

curl -X PATCH https://api.meow.com/v1/bills/$BILL_ID \
  -H "x-api-key: $MEOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "memo": "Revised per updated invoice", "payment_type": "WIRE" }'

Cancel a bill that hasn’t been approved yet by deleting it:

curl -X DELETE https://api.meow.com/v1/bills/$BILL_ID -H "x-api-key: $MEOW_API_KEY"

Once a bill is approved (or paid), it can no longer be edited or deleted through the API.

Update line items without replacing the list

The main PATCH /bills/{bill_id} endpoint can replace the complete line_items list. Use the line-item endpoints when you want to change one line and keep the identifiers and accounting mappings of the other lines.

POST /bills/{bill_id}/line-items adds one line.
PATCH /bills/{bill_id}/line-items/{line_item_id} updates one line.
DELETE /bills/{bill_id}/line-items/{line_item_id} removes one line.

Connect a bill to your accounting system

Read the accounting catalogs before you set mappings:

GET /billpay/accounting/vendors
GET /billpay/accounting/expense-accounts
GET /billpay/accounting/classes

Then call PATCH /bills/{bill_id}/accounting-mappings to map the vendor and default expense account. Use PATCH /bills/{bill_id}/line-items/{line_item_id}/expense-account for a different expense account on one line. Call POST /bills/{bill_id}/sync to retry or refresh an eligible bill in the connected accounting system. The response shows the latest accounting status.

Call GET /billpay/settings before you draft bills. It reports the default funding account, approval count, accounting provider, and required mappings.

5. Schedule recurring bills

To generate a bill on a repeating schedule, include an iCalendar rrule (with a DTSTART) when you create it. Each occurrence is generated as its own draft for approval. Recurring bills are never paid automatically.

curl -X POST https://api.meow.com/v1/bills \
  -H "x-api-key: $MEOW_API_KEY" \
  -H "Idempotency-Key: bill-rent-recurring-001" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f",
    "description": "Monthly office rent",
    "payment_type": "ACH",
    "rrule": "DTSTART:20260701T000000Z\nRRULE:FREQ=MONTHLY;BYMONTHDAY=1",
    "line_items": [ { "type": "EXPENSE", "amount": 4500.00, "description": "Office rent, Whisker Works" } ]
  }'

Building the schedule string by hand is fiddly. A tool like the RRULE generator will assemble the DTSTART/RRULE for you.

Use GET /bill-schedules to list recurring schedules. Use GET /bill-schedules/{schedule_id} to read one schedule and its generated bills. A schedule starts as DRAFT. It becomes PENDING after submission in the dashboard and ACTIVE after approval. Only an active schedule creates bill drafts. Call POST /bill-schedules/{schedule_id}/cancel to stop future drafts. Existing bills remain unchanged, and a canceled schedule cannot become active again.

Estimate delivery dates

Call GET /billpay/expected-payment-date before you create a bill when the delivery date determines the payment rail. The endpoint uses banking days and account cutoff times. It returns an estimate and does not reserve or send funds.

End to end

# 1. Create the bill and capture its id.
BILL_ID=$(curl -s -X POST https://api.meow.com/v1/bills \
  -H "x-api-key: $MEOW_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: bill-$(date +%Y%m%d)-catnip-001" \
  -d '{"contact_id":"b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d","invoice_number":"CATNIP-4471","payment_type":"ACH","line_items":[{"type":"EXPENSE","amount":1200.00,"description":"Cloud hosting - June"}]}' \
  | jq -r .id)

# 2. Request an upload URL for the vendor's primary invoice PDF.
UPLOAD=$(curl -s -X POST https://api.meow.com/v1/bills/$BILL_ID/invoice/presigned-url \
  -H "x-api-key: $MEOW_API_KEY" -H "Content-Type: application/json" \
  -d '{"filename":"catnip-cloud-4471.pdf","content_type":"application/pdf","size":48213}')
OBJECT_KEY=$(echo "$UPLOAD" | jq -r '.uploads[0].object_key')

# 3. Upload the file to .uploads[0].url with .uploads[0].fields, then attach it.
curl -s -X POST https://api.meow.com/v1/bills/$BILL_ID/invoice \
  -H "x-api-key: $MEOW_API_KEY" -H "Content-Type: application/json" \
  -d "{\"object_key\":\"$OBJECT_KEY\",\"filename\":\"catnip-cloud-4471.pdf\"}" | jq '.status'

The bill now sits as a DRAFT with its invoice attached, waiting for an approver in the dashboard.

Bulk loads

There is no batch endpoint. To load a run of bills — a month of contractor payments, for example — call POST /bills once per bill. Two things make a large run safe to retry:

Give every bill its own Idempotency-Key, derived from your own record (a payroll row id, an invoice number). Replaying the whole run then re-sends the same key per bill, so nothing is duplicated.
Create the vendor contacts first. A bill needs a contact that already carries the banking details for its payment type, so resolve or create contacts before the run rather than inside it.

Drafting is capped at 500 bills per rolling 24 hours per creator — your entity key, or the user a user-scoped key acts as. Creates past the cap return 429 Too Many Requests; retry after the oldest drafts in the window age out, or split the run across keys. Every bill still lands as a DRAFT awaiting approval in the dashboard, so a bulk load never moves money on its own.

Create a contact

Create a bill

Full request contract for POST /bills.

List bills

Every filter, sort, and pagination option.

Update a bill

Edit a draft with PATCH partial semantics.

Confirm bill documents

Attach uploaded receipts and supporting files.

Bill Pay settings

Read the default funding account and accounting requirements.

List bill schedules

Track recurring schedules and the bills they create.

Get Started

MCP Server

Tutorials

Create and track vendor bills via the API

You’ll need

1. Create a bill

2. Attach supporting documents

Attach the primary invoice

3. Track bills

4. Update or cancel a draft

Update line items without replacing the list

Connect a bill to your accounting system

5. Schedule recurring bills

Estimate delivery dates

End to end

Bulk loads

See also

Create a contact

Create a bill

List bills

Update a bill

Confirm bill documents

Bill Pay settings

List bill schedules

​You’ll need

​1. Create a bill

​2. Attach supporting documents

​Attach the primary invoice

​3. Track bills

​4. Update or cancel a draft

​Update line items without replacing the list

​Connect a bill to your accounting system

​5. Schedule recurring bills

​Estimate delivery dates

​End to end

​Bulk loads

​See also

Create a contact

Create a bill

List bills

Update a bill

Confirm bill documents

Bill Pay settings

List bill schedules

You’ll need

1. Create a bill

2. Attach supporting documents

Attach the primary invoice

3. Track bills

4. Update or cancel a draft

Update line items without replacing the list

Connect a bill to your accounting system

5. Schedule recurring bills

Estimate delivery dates

End to end

Bulk loads

See also