Create invoice

POST /api/v1/invoices

Create a new invoice for a customer. Optionally include 'recurring' config to also create a recurring template.

Operation ID: create_invoice_api_v1_invoices_post · 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: InvoiceCreateRequest

customer_id string required

UUID of the customer to invoice.

currency string

Currency for the invoice (USD, CAD, AUD, EUR, or GBP). Defaults to business default.

line_items array · LineItemRequest requiredLineItemRequest

Line items (at least one required). Can be variant-linked or custom.

5 fields

variant_id string: UUID of product variant. Omit or use 'custom' for manual line items.
quantity integer: Quantity ordered. Defaults to 1 for custom items.
description string: Line item description (required for custom items).
unit_price integer: Price per unit in cents. Required for custom items, auto-resolved for variants.
amount integer: Total amount in cents. Deprecated for custom items - use unit_price instead. For backward compatibility, if unit_price is not set, amount is treated as unit_price.

due_date string required

Payment due date in YYYY-MM-DD format.

description string

Optional invoice description or notes.

recurring InvoiceRecurringConfig

If provided, creates a recurring template for this invoice.

Responses

201 Successful Response

Schema: InvoiceResponse

id string required: Invoice UUID.
business_id string required: Business UUID.
created_at string · date-time required: Creation timestamp.
updated_at string · date-time required: Last update timestamp.
status string required: Status: draft, open, partially_paid, manual_paid, stripe_paid, void.
currency string: Currency for the invoice (USD, CAD, AUD, EUR, or GBP).
stripe_invoice_id string: Stripe invoice ID if synced.
total integer: Total amount in cents.
total_paid integer: Running total of payments received in cents.
balance_due integer: Remaining balance in cents (total - total_paid).
description string: Invoice description/notes.
customer_id string required: Customer UUID.
customer_name string: Customer name (resolved).
customer_email string: Customer email (resolved).
due_date string: Due date (YYYY-MM-DD).
line_items array · LineItemResponse: Invoice line items.
pdf_url string: URL to download invoice PDF.
number string: Invoice number (assigned on finalize).
delivered boolean: Whether invoice was delivered.
delivered_on string · date-time: Delivery timestamp.
hosted_invoice_url string: URL for customer payment portal.
paid_on string · date-time: Payment timestamp.
journal_entries array · object: Associated accounting journal entries.
payments array · InvoicePaymentResponse: Payment records linking bank transactions to this invoice.
recurring_template_id string: ID of recurring template if invoice was generated from one, or if one was created.

400 Bad Request - Invalid input

401 Unauthorized - Authentication required

403 Forbidden - Insufficient permissions

422 Validation Error

Schema: HTTPValidationError

detail array · ValidationError ValidationError

5 fields

loc array · string | integer required
msg string required
type string required
input object
ctx object

Code samples

POST /api/v1/invoices

bash

curl -X POST 'https://api.ondayzero.com/api/v1/invoices' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "customer_id": "string",
  "line_items": [],
  "due_date": "string"
}'

javascript

const response = await fetch('https://api.ondayzero.com/api/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "customer_id": "string",
  "line_items": [],
  "due_date": "string"
}),
});
const data = await response.json();

python

import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

payload = {
  "customer_id": "string",
  "line_items": [],
  "due_date": "string"
}

response = httpx.post("https://api.ondayzero.com/api/v1/invoices", headers=headers, json=payload)
data = response.json()