Create bill

POST/api/v1/bills

Create a new bill in draft status. Optionally include 'recurring' config to also create a recurring template.

Operation ID: create_bill·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: BillCreateRequest

descriptionstring: Description of what the bill is for.
currencystring: Currency for the bill (USD, CAD, AUD, EUR, or GBP). Defaults to business default.
vendor_idstring: UUID of the vendor this bill is from.
bill_numberstring: Bill/invoice number from the vendor. Auto-generated if not provided.
payment_term_idstring: Optional UUID of the payment term the vendor billed under (Net 30, Due on Receipt ...). Recorded for reference; the due date is its own field, so a date you set yourself always wins over the term.
typestring: Bill type: 'recurring' (monthly rent, subscriptions) or 'one_time'.
expected_amountinteger: Expected bill amount in cents.
expected_paid_on_datestring · date-time | string: Expected payment date (ISO 8601 format).
s3_keystring: S3 key of uploaded bill document (PDF/image).
recurringRecurringConfig: If provided, creates a recurring template for this bill.
submitted_for_reviewboolean: When true, marks this draft as a client-submitted expense and notifies the assigned advisor to confirm or deny it.

Responses

201Successful Response

Schema: SuccessEnvelope_BillResponse_

successboolean
messagestring
codestring
dataBillResponse

400Bad Request - Invalid input

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

401Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

403Forbidden - Insufficient permissions

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

422Validation Error

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

Code samples

POST/api/v1/bills

bash

curl -X POST 'https://api.ondayzero.com/api/v1/bills' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Monthly office rent - January 2024",
  "expected_amount": 250000,
  "expected_paid_on_date": "2024-01-31T00:00:00Z",
  "type": "recurring",
  "vendor_id": "019ab37c-ae0d-7000-8000-000000000001"
}'