Invoices
View as MarkdownInvoices represent annual payment certifications for athletes and staff. Generate them for a fiscal year, then use the resulting IDs to print or deliver individual certifications.
On this page
- The invoice object
- List invoicesGET
/api/v1/invoices - Generate annual certificationsPOST / GET
/api/v1/invoices/generate/{year} - Get invoice print optionsGET
/api/v1/invoices/{id}/print-options - Generate an invoice PDFPOST
/api/v1/invoices/{id}/print - List invoice email recipientsGET
/api/v1/invoices/{id}/emails - Email an invoice certificationPOST
/api/v1/invoices/{id}/send - Schedule annual certification emailsPOST
/api/v1/invoices/send/{year} - Delete certifications for a yearDELETE
/api/v1/invoices/year/{year}
An invoice summarizes qualifying payments for one subject and fiscal year.
Attributes
idinteger- Identifier assigned by the API.
fiscal_yearinteger- Fiscal year covered by the certification.
payment_typestring- Use incoming or outgoing. Generation defaults to incoming.
subject_typestring- Use athlete or staff.
subject_idinteger- ID of the athlete or staff member.
currencystring- Three-letter currency code.
amountinteger- Total amount in minor currency units.
invoice_numberinteger- Sequential certification number for the year and payment direction.
invoice_codestring- Formatted certification code.
payer_parent1_idinteger or null- ID of the first paying parent, when included.
amount_parent1integer or null- Amount attributed to the first parent, in minor units.
payer_parent2_idinteger or null- ID of the second paying parent, when included.
amount_parent2integer or null- Amount attributed to the second parent, in minor units.
certification_parent_modestring or null- Certification format: athlete, single, joint, or separated.
payment_countinteger- Number of payments included in the certification.
first_receipt_at_tsinteger or null- First receipt time as Unix seconds.
last_receipt_at_tsinteger or null- Last receipt time as Unix seconds.
template_idinteger or null- ID of the selected print template.
notesstring or null- Additional certification notes.
tscinteger or null- Creation time as Unix seconds.
tsuinteger or null- Last update time as Unix seconds.
/api/v1/invoicesLists annual certifications by payment direction, year, or subject.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Read.
Query parameters
payment_typestring- Filter by incoming or outgoing payments.
fiscal_yearinteger- Filter by fiscal year.
subject_typestring- Filter by athlete or staff.
subject_idinteger- Filter by subject ID.
athlete_idinteger- Filter by athlete ID. Takes precedence over subject_type and subject_id.
contextstring- Use athlete_detail or athlete_details to return only the ID, fiscal year, invoice number, payment type, and amount.
include_readableinteger- Use 1 to include formatted dates and payer names in readable. Alias expand_readable. Amounts remain in minor units.
expand_subjectinteger- Use 1 to include the subject object.
qstring- Search invoice code or notes.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, fiscal_year, payment_type, invoice_number, invoice_code, amount, tsc, tsu, subject_name, payer_parent1_name, or payer_parent2_name. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
Returns
Returns matching certifications in data, with counts before and after text search.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
/api/v1/invoices/generate/{year}Generates or refreshes certifications for one fiscal year and payment direction.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Write.
Path parameters
yearintegerRequired- Four-digit fiscal year, from 1970 through 9999.
Query parameters
payment_typestring- Use incoming or outgoing. Generation defaults to incoming.
Body parameters
payment_typestring- Use incoming or outgoing. Generation defaults to incoming.
Both methods generate records. You can send payment_type in the query string or the POST JSON body. When both are present, the body takes precedence.
Returns
Returns created and updated counts in stats. Inspect the error and warning arrays even on HTTP 200.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The fiscal year or payment type is invalid.
/api/v1/invoices/{id}/print-optionsReturns the configured template and print format for one certification.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Read.
Path parameters
idintegerRequired- ID of the invoice.
Returns
Returns a template ID or null, and the print mode: athlete, single, joint, or separated.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/invoices/{id}/printGenerates a PDF for one certification.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Write.
Path parameters
idintegerRequired- ID of the invoice.
Body parameters
template_idinteger- Override the configured print template for this request.
Returns
Returns the PDF URL in url.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
422- The PDF could not be generated.
/api/v1/invoices/{id}/emailsLists email addresses associated with an invoice.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Read.
Path parameters
idintegerRequired- ID of the invoice.
Returns
Returns email addresses, display names, and their roles, such as athlete, staff, parent1, or parent2.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/invoices/{id}/sendEmails a certification link to one recipient.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Write.
Path parameters
idintegerRequired- ID of the invoice.
Body parameters
emailstringRequired- Recipient address. Alias email_to.
body_htmlstringRequired- HTML content of the email. Alias body.
subjectstring- Email subject. Defaults to the annual certification subject.
Returns
Returns a confirmation and the certification link when available.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The email or body is missing, or the email could not be sent.
404- The requested record was not found.
503- The certification link could not be prepared.
/api/v1/invoices/send/{year}Creates and schedules an email campaign for incoming-payment certifications from one fiscal year.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Write.
Path parameters
yearintegerRequired- Four-digit fiscal year, from 1970 through 9999.
Query parameters
payment_typestring- Use incoming. This is also the default.
Returns
Returns the new campaign, the recipient count, and its queue status.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The fiscal year or payment type is invalid.
422- No eligible recipients were found or the workspace email template is incomplete.
500- The campaign could not be created.
503- The certification links could not be prepared.
/api/v1/invoices/year/{year}Removes certifications for one fiscal year across both payment directions.
Permissions
Send your API key in X-API-Key. Required permissions are Invoices → Write.
Path parameters
yearintegerRequired- Four-digit fiscal year, from 1970 through 9999.
Returns
Returns a confirmation. The numeric deleted field indicates whether the delete operation succeeded.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The fiscal year or payment type is invalid.