ASDinCloudDocs
API ReferenceSubscriptions

Subscriptions

View as Markdown

The subscription object

View as Markdown

Subscriptions connect athletes to plans. Use the resource to look up billing status, review expected payments, allocate credit, and send a payment summary.

Attributes

idinteger
Identifier assigned by the API.
sport_idinteger
ID of the sport.
plan_idinteger
ID of the plan.
athlete_idinteger
ID of the athlete.
subscription_startinteger or null
Start date as Unix seconds.
subscription_endinteger or null
End date as Unix seconds.
suspended_atinteger or null
Suspension time as Unix seconds.
canceled_atinteger or null
Cancellation time as Unix seconds.
custom_amountinteger or null
Override of the plan amount, in minor units.
notesstring or null
Notes for the subscription.
tscinteger or null
Creation time as Unix seconds.
tsuinteger or null
Last update time as Unix seconds.
athlete_fullnamestring
Athlete name included when listing subscriptions.
plan_namestring
Plan name included when listing subscriptions.
amountnumber
Total amount in minor units, included when listing subscriptions.
amount_paidnumber
Paid amount in minor units, included when listing subscriptions.
amount_leftnumber
Outstanding amount in minor units, included when listing subscriptions.
statusstring
List status: active, expired, suspended, or unknown.

List subscriptions

View as Markdown
GET/api/v1/subscriptions

Lists subscription records in the workspace.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Read.

Headers

X-Sport-Idinteger
Use the sport ID to limit the response to one sport.

Query parameters

athlete_idinteger
ID of the athlete.
plan_idinteger
ID of the plan.
expand_athleteinteger
Use 1 to include the athlete record.
expand_planinteger
Use 1 to include the plan record.
statusstring
Use active, expired, suspended, custom_amount, or all. Defaults to active.
unpaidboolean
Use true to include only subscriptions with an outstanding balance. This removes the end-date restriction from the active and expired filters.
view_totalsinteger
Use 1 to request calculated totals.
qstring
Search athlete names or subscription notes.
lengthinteger
Number of records to return.
startinteger
Zero-based offset.
drawstring
Optional request marker echoed in the response.
sortstring
Sort by id, subscription_start, subscription_end, plan_name, athlete_fullname, amount, amount_paid, amount_left, tsc, or tsu. Prefix the field name with a minus sign for descending order.
orderstring
Direction for unprefixed sort fields. Use asc or desc.

Returns

Returns matching subscriptions, names, and calculated totals in data.

Errors

401
The API key is missing or invalid.
403
The API key lacks the required permission.

Retrieve a subscription

View as Markdown
GET/api/v1/subscriptions/{id}

Returns one subscription by ID.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Read.

Headers

X-Sport-IdintegerRequired
The sport ID from List sports. Use the sport the record belongs to.

Path parameters

idintegerRequired
ID of the subscription.

Query parameters

expand_athleteinteger
Use 1 to include the athlete record.
expand_planinteger
Use 1 to include the plan record.

Returns

The subscription is returned in data.

Errors

401
The API key is missing or invalid.
403
The API key lacks the required permission.
404
The requested record was not found.

Update a subscription

View as Markdown
PATCH / PUT / POST/api/v1/subscriptions/{id}

Updates a subscription by ID.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Write.

Headers

X-Sport-IdintegerRequired
The sport ID from List sports. Use the sport the record belongs to.

Path parameters

idintegerRequired
ID of the subscription.

Body parameters

plan_idinteger
ID of the plan.
athlete_idinteger
ID of the athlete.
subscription_startdate string
Start date in YYYY-MM-DD format.
subscription_enddate string
End date in YYYY-MM-DD format.
custom_amountinteger or null
Override the plan amount in minor units. Use null to clear it. Omission also clears the override on this update.
notesstring or null
Notes for the subscription.
suspendedboolean
Set true to suspend or false to clear the suspension.
canceledboolean
Set true to cancel or false to clear cancellation.

Include the current custom_amount to preserve an override.

Returns

Returns a successful update response.

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
One or more fields failed validation.

Delete a subscription

View as Markdown
DELETE/api/v1/subscriptions/{id}
POST/api/v1/subscriptions/{id}/delete

Removes the subscription and any linked expected payments. Paid or refunded payments block removal.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Write.

Headers

X-Sport-IdintegerRequired
The sport ID from List sports. Use the sport the record belongs to.

Path parameters

idintegerRequired
ID of the subscription.

Returns

Returns a successful removal response.

Errors

401
The API key is missing or invalid.
403
The API key lacks the required permission.
404
The requested record was not found.
400
The subscription has settled payments or could not be removed.

Review expected payments

View as Markdown
GET/api/v1/subscriptions/{id}/expected-payments

Reviews the expected payment schedule and totals for an existing subscription.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Write and Payments → Write.

Headers

X-Sport-IdintegerRequired
The sport ID from List sports. Use the sport the record belongs to.

Path parameters

idintegerRequired
ID of the subscription.

Returns

Returns plan and subscription amounts in minor units, the currency, and the current expected payment rows in due-date order.

Errors

401
The API key is missing or invalid.
403
The API key lacks the required permission.
404
The requested record was not found.

Preview a plan’s expected payments

View as Markdown
GET/api/v1/subscriptions/expected-payments-preview

Previews the expected payment schedule configured on a plan.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Write and Payments → Write.

Query parameters

plan_idintegerRequired
ID of the plan.

Returns

Returns the plan amount, currency, and proposed payments with no assigned IDs.

Errors

401
The API key is missing or invalid.
403
The API key lacks the required permission.
400
A plan ID is required.
404
The requested record was not found.

List subscription email recipients

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

Lists suggested recipients for a subscription payment summary.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Read and Messages → Write.

Headers

X-Sport-IdintegerRequired
The sport ID from List sports. Use the sport the record belongs to.

Path parameters

idintegerRequired
ID of the subscription.

Returns

Returns unique recipient addresses, names, roles, and the default recipient flag.

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 a subscription payment summary

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

Emails a rendered payment summary to one or more recipients.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Write and Messages → Write.

Headers

X-Sport-IdintegerRequired
The sport ID from List sports. Use the sport the record belongs to.

Path parameters

idintegerRequired
ID of the subscription.

Body parameters

template_idintegerRequired
ID of an email template.
subjectstringRequired
Subject, up to 255 characters.
body_htmlstringRequired
HTML email content. Alias body.
emailsarray of stringsRequired
Between 1 and 20 unique valid email addresses.

Returns

Returns delivery counts and a per-address failure list. An HTTP 200 response can report outcome partial.

Errors

401
The API key is missing or invalid.
403
The API key lacks the required permission.
400
The payload or template is invalid.
404
The requested record was not found.
422
The summary could not be prepared.
500
The request failed during delivery.
502
All deliveries failed.

Allocate credit to a subscription

View as Markdown
POST/api/v1/subscriptions/{id}/allocate-credit

Applies available credit from a paid payment for the same athlete to the subscription balance.

Permissions

Send your API key in X-API-Key. Required permissions are Subscriptions → Write.

Headers

X-Sport-IdintegerRequired
The sport ID from List sports. Use the sport the record belongs to.

Path parameters

idintegerRequired
ID of the subscription.

Body parameters

payment_idintegerRequired
ID of the incoming athlete credit payment.
amountintegerRequired
Positive allocation in minor units. It cannot exceed the available credit or subscription balance.
notesstring
Optional notes about the allocation.

Returns

Returns the new credit allocation in data.

Errors

401
The API key is missing or invalid.
403
The API key lacks the required permission.
400
The payment, amount, or available balance is invalid.
404
The requested record was not found.