Invoice Recurring

Reference for the invoice_recurring resource. Requests follow the conventions in Requests and Responses; fields you receive and may write are filtered by your user's permissions, so responses can contain a subset of the fields below.

Operations

Required on create: link customer under data.relationships — a create that omits it is rejected with 422 naming the relationship.

How it works

invoice_recurring is a recurring invoice — a schedule that generates a customer invoice every interval. It's a composite of two records: the recurring schedule and a template Invoice that holds the line items and header (dates, notes, PO). The two are created, updated, and deleted together through this one resource. Requires the Enhanced Invoicing add-on (a write without it returns 422).

A row belongs to a customer through entity_id, and its permission location is that customer's: everything is gated by the Customer Invoices permission at the customer's location (leads use the lead-invoices permission).

Some fields live on the template invoice (sale_date, po_number, internal_note, external_note, mailing_address, mailing_name); the rest are the recurrence schedule. You send them all together — the API routes each to the right record.

Creating

POST /invoice_recurring requires the customer parent (in data.relationships) and:

Optional: billing_id (the customer billing method to charge — must belong to the same customer), sold_by_user_id, send_on_generation, send_on_attempted_processing, tax_override, recurring_email, default_message, and the template-invoice fields (po_number, internal_note, external_note, mailing_address, mailing_name).

Line items are created inline: send them as an embedded invoice_line_items relationship. Each is created against the template invoice (its amounts computed from quantity × unit_price as on the invoice_line_items resource).

curl -X POST "https://portal.securitytrax.com/acme/user/v4/invoice_recurring" \
  -H "Authorization: Bearer stx_acme_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"attributes":{"sale_date":"2026-09-01","recurring_interval_number":1,"recurring_interval_period":"months","num_times_to_recur":-1},"relationships":{"customer":{"data":{"type":"customers","id":100}},"invoice_line_items":{"data":[{"attributes":{"quantity":"1","unit_price":"49.99"},"relationships":{"invoice_billable_item":{"data":{"type":"invoice_billable_items","id":5}}}}]}}}}'

Managed (read-only) fields

entity_type (fixed customer), invoice_id (the template invoice link), next_date and last_date (derived from the schedule), status, and bill_with_parent are returned on read but not writable — a PATCH that sets them returns 422. next_date is set to sale_date; last_date is computed from the interval and num_times_to_recur (null when recurring forever).

Updating

PATCH /invoice_recurring/{id} accepts the schedule fields and the template-invoice fields. Changing sale_date, the interval, or num_times_to_recur recomputes last_date. sale_date cannot be changed once child invoices have been generated (422). To edit the line items of an existing recurring invoice, use the invoice_line_items endpoint against the template invoice_id.

Deleting

DELETE /invoice_recurring/{id} soft-deletes the whole thing — the recurring schedule, its template invoice, and the template's line items — together. Afterward every read returns 404.

Listing

GET /invoice_recurring returns active customer recurring invoices at locations where you can view customer invoices. Filters (all optional, combinable):

Sortable: id, entity_id, next_date, last_date, created_at, updated_at. Add ?count_only=true for just the total.

Fields

Fields are grouped by the permission that gates them. A group you may not view is absent from responses; a group you may not write is rejected with 422 when sent in a write.

Invoice

View: customers — Customer Invoices at the record's location; leads — Lead Invoices. Create: customers — Customer Invoices at the record's location; leads — Lead Invoices. Update: customers — Customer Invoices at the record's location; leads — Lead Invoices.

Recurring Invoice

View: customers — Customer Invoices at the record's location; leads — Lead Invoices. Create: customers — Customer Invoices at the record's location; leads — Lead Invoices. Update: customers — Customer Invoices at the record's location; leads — Lead Invoices.

Managed

View: customers — Customer Invoices at the record's location; leads — Lead Invoices.

Pagination

The list endpoint uses client-controlled offset pagination: ?page= (1-based) and ?per_page= (default 25, max 100). The response mirrors meta.pagination (page, per_page, total, last_page) and sends an RFC5988 Link header; follow rel="next" to walk pages. See Pagination.

Filters

The list endpoint accepts these query-param filters: entity_id, sold_by_user_id, billing_id, next_date_from, next_date_to, last_date_from, last_date_to, created_at_from, created_at_to, updated_at_from, updated_at_to. An unsupported filter parameter returns 422. See Filtering collections for matching semantics.

Sorting

GET .../invoice_recurring?sort= orders the list by: id, entity_id, next_date, last_date, created_at, updated_at. Prefix a field with - for descending; comma-separate for tie-breakers. An unsupported field returns 422. See Sorting collections.

Related

• Requests and Responses — envelope, errors, pagination, and rate limits.
• Authentication — tokens and the Authorization header.