Plans
View as MarkdownPlans define the price and dates for subscriptions in a sport.
On this page
- The plan object
- List plansGET
/api/v1/plans - Retrieve a planGET
/api/v1/plans/{id} - Update a planPATCH / PUT / POST
/api/v1/plans/{id} - Delete a planDELETE
/api/v1/plans/{id}POST/api/v1/plans/{id}/delete - Count linked subscriptionsGET
/api/v1/plans/{id}/subscription-impact - Preview expected payment eligibilityPOST
/api/v1/plans/{id}/subscription-impact
Plans define the price and dates for subscriptions in a sport.
Attributes
idinteger- Identifier assigned by the API.
sport_idinteger- ID of the sport.
namestring- Plan name, up to 100 characters. Must be unique for the dates and sport.
amountinteger- Plan amount in minor currency units.
currencystring- Three-letter currency code, stored in uppercase.
plan_startinteger- Unix timestamp in seconds.
plan_endinteger- Unix timestamp in seconds.
is_membership_feeinteger- Use 1 to mark the plan as a membership fee.
excludeinteger- Use 1 to exclude the plan from plan selection.
exclude_from_renewalsinteger- Use 1 to exclude this plan from renewals.
metadatamap or null- Plan metadata. The optional payments_expected schedule contains entries with date and a positive amount in minor currency units.
linked_membership_plansarray of objects- IDs and names of linked membership plans. Included on list responses with Membership plans → Write.
/api/v1/plansLists plan records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Plans → Read.
Headers
X-Sport-Idinteger- Use the sport ID to limit the response to one sport.
Query parameters
expiredinteger- Use 1 to list plans whose end date has passed. The default returns plans that have not ended.
qstring- Search by plan name.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, name, amount, plan_start, 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 plans 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/plans/{id}Returns one plan by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Plans → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the plan.
Returns
The plan 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/plans/{id}Updates a plan by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Plans → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the plan.
Body parameters
namestring- Plan name, up to 100 characters. Must be unique for the dates and sport.
amountinteger- Plan amount in minor currency units.
currencystring- Three-letter currency code, stored in uppercase.
plan_startinteger or date string- Start of the plan, as Unix seconds or an ISO date.
plan_endinteger or date string- End of the plan, as Unix seconds or an ISO date.
is_membership_feeinteger- Use 1 to mark the plan as a membership fee. Omission on update resets the value to 0.
excludeinteger- Use 1 to exclude the plan from plan selection. Omission on update resets the value to 0.
exclude_from_renewalsinteger- Use 1 to exclude this plan from renewals.
metadatamap or null- Plan metadata. The optional payments_expected schedule contains entries with date and a positive amount in minor currency units.
use_season_datesboolean- Use September 1 and August 31 of the current sports season for the plan dates.
update_linked_subscriptions_datesboolean- Apply changed plan dates to linked subscriptions. Defaults to false.
create_linked_subscriptions_expected_paymentsboolean- Create expected payments from the configured schedule for eligible linked subscriptions. Defaults to false.
Include the current is_membership_fee and exclude values if you want to preserve them. Use Preview expected payment eligibility before generating payments for linked subscriptions.
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.
400- The schedule contains invalid dates or amounts.
422- The fields failed validation or the name is already in use for the same dates.
500- The update could not be saved.
/api/v1/plans/{id}/api/v1/plans/{id}/deleteRemoves a plan that has no linked subscriptions.
Permissions
Send your API key in X-API-Key. Required permissions are Plans → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the plan.
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 plan has linked subscriptions or could not be removed.
/api/v1/plans/{id}/subscription-impactCounts subscriptions linked to a plan before a change.
Permissions
Send your API key in X-API-Key. Required permissions are Plans → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the plan.
Returns
Returns the plan ID and count of linked subscriptions.
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/plans/{id}/subscription-impactEstimates which linked subscriptions would receive expected payments. The preview can account for a proposed plan end date.
Permissions
Send your API key in X-API-Key. Required permissions are Plans → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the plan.
Body parameters
plan_endinteger or date string- End of the plan, as Unix seconds or an ISO date.
use_season_datesboolean- Use September 1 and August 31 of the current sports season for the plan dates.
update_linked_subscriptions_datesboolean- Apply changed plan dates to linked subscriptions. Defaults to false.
Returns
Returns the total subscriptions, the eligible active subscriptions, and the number skipped because they already have expected payments.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.