ASDinCloudDocs

The invoice object

View as Markdown

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.

List invoices

View as Markdown
GET/api/v1/invoices

Lists 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.

Generate annual certifications

View as Markdown
POST / GET/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.

Get invoice print options

View as Markdown
GET/api/v1/invoices/{id}/print-options

Returns 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.

Generate an invoice PDF

View as Markdown
POST/api/v1/invoices/{id}/print

Generates 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.

List invoice email recipients

View as Markdown
GET/api/v1/invoices/{id}/emails

Lists 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.

Email an invoice certification

View as Markdown
POST/api/v1/invoices/{id}/send

Emails 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.

Schedule annual certification emails

View as Markdown
POST/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.

Delete certifications for a year

View as Markdown
DELETE/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.