Subscriptions
View as MarkdownSubscriptions connect athletes to plans. Use the resource to look up billing status, review expected payments, allocate credit, and send a payment summary.
On this page
- The subscription object
- List subscriptionsGET
/api/v1/subscriptions - Retrieve a subscriptionGET
/api/v1/subscriptions/{id} - Update a subscriptionPATCH / PUT / POST
/api/v1/subscriptions/{id} - Delete a subscriptionDELETE
/api/v1/subscriptions/{id}POST/api/v1/subscriptions/{id}/delete - Review expected paymentsGET
/api/v1/subscriptions/{id}/expected-payments - Preview a plan’s expected paymentsGET
/api/v1/subscriptions/expected-payments-preview - List subscription email recipientsGET
/api/v1/subscriptions/{id}/emails - Email a subscription payment summaryPOST
/api/v1/subscriptions/{id}/send - Allocate credit to a subscriptionPOST
/api/v1/subscriptions/{id}/allocate-credit
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.
/api/v1/subscriptionsLists 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.
/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.
/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.
/api/v1/subscriptions/{id}/api/v1/subscriptions/{id}/deleteRemoves 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.
/api/v1/subscriptions/{id}/expected-paymentsReviews 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.
/api/v1/subscriptions/expected-payments-previewPreviews 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.
/api/v1/subscriptions/{id}/emailsLists 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.
/api/v1/subscriptions/{id}/sendEmails 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.
/api/v1/subscriptions/{id}/allocate-creditApplies 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.