Sign in
Schedule

Creates an Invoice Schedule

Required permission: Recurring Invoices - New

Accepts every settable field on a schedule, so a schedule can be fully configured in one call. Add its line items afterwards with POST /schedules/{id}/line_items, or seed them from an existing invoice by passing invoice_id.

id, account_id, created_at, updated_at and last_run are read-only. So are subscription_status and recurring_type_id, which are maintained for you: the first is recomputed from the linked contract and the unpaid invoice count on every run, and the second is what selects the billing engine for the whole schedule.

Every id in the request is checked against your account before anything is written, so a rejected request changes nothing. Errors come back as {"error": ["Location can't be found", ...]} with status 422.

post/schedules

Request body

customer_idinteger required

Customer the schedule bills. Required on create.

namestring required

Name of the schedule itself. Required.

frequency'Daily' | 'Monthly' | 'Weekly' | 'Biweekly' | 'Quarterly' | 'Semi-Annually' | 'Annually' | 'Biennially' | 'Triennially' required

How often the schedule runs. Required.

next_runstring date required

Date of the next run, YYYY-MM-DD. Required. Any other format is rejected with 422 {"error": "Sorry, unable to read the date, use this format: Y-m-d"}.

contract_idinteger

Contract this schedule is billed under. Must belong to the same customer as the schedule.

location_idinteger

Location the generated invoices belong to.

user_idinteger

Employee credited with the generated invoices, for commission.

invoice_term_idinteger

Billing terms applied to the generated invoices.

template_idinteger

Invoice template used to render the generated invoices. Must be an invoice template. Defaults to the account's.

source_idinteger

The schedule this one was copied from. Recorded for reference only — it does not copy anything. Use invoice_id on create to seed line items.

invoice_idinteger

Create only, and not stored on the schedule: the schedule's line items are seeded from this invoice's line items. Must be an invoice on your account.

period_mode_id0 | 1 | 2 | 3

Which billing period the generated invoice covers. 0 in arrears (period ends on the invoice date), 3 in arrears exclusive (ends the day before), 1 in advance (starts the day after), 2 in advance inclusive (starts on the invoice date).

last_day_of_monthboolean

Move each run to the last day of its month.

pausedboolean

A paused schedule generates nothing until it is resumed.

generated_invoice_namestring

Name given to each invoice this schedule generates.

memostring

Memo copied onto the generated invoices.

keep_pricing_currentboolean

Re-price every line from the current product price on each run, instead of holding the price captured when the line was added.

allow_blank_invoicesboolean

Generate an invoice even when the run produces no lines.

email_customerboolean

Email the generated invoice to the customer.

snail_mailboolean

Post the generated invoice to the customer.

email_receiptboolean

Email the customer a receipt after a successful charge.

charge_mopboolean

Auto-charge the stored payment method. Without a payment_id the schedule still generates invoices but charges nothing and records a failed payment on each run.

payment_idinteger

Stored payment method to auto-charge. Must be a payment profile belonging to this schedule's customer.

charge_on_due_dateboolean

Charge on the invoice due date rather than on the run date. Only meaningful together with invoice_term_id.

apply_creditboolean

Spend any available customer credit against the generated invoice.

reset_prepay_hoursboolean

Reset the customer's prepaid hours on each run.

invoice_unbilled_ticket_chargesboolean

Pull the customer's unbilled ticket charges onto the generated invoice.

invoice_unbilled_ticket_statusesstring

Restrict the unbilled ticket charges to tickets in these statuses. Send either a comma-separated string or a JSON array of strings; both are stored comma-separated. Every status must exist on your account. Blank means all statuses.

unbilled_ticket_charge_order'ticket_number' | 'ticket_resolved' | 'ticket_created' | 'timer_started' | 'timer_ended'

Order the unbilled ticket charges are added in.

create_ticket_on_failed_billingboolean

Open a ticket when a run fails to bill.

create_ticket_one_month_prior_to_endboolean

Open a ticket a month before the linked contract ends.

schedule_retry_card_on_failed_billingboolean

Retry the stored card later when a charge fails.

Response

Fully configured in a single call

Changes