ASDinCloudDocs

The plan object

View as Markdown

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.
GET/api/v1/plans

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

Retrieve a plan

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

Update a plan

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

Delete a plan

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

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

Count linked subscriptions

View as Markdown
GET/api/v1/plans/{id}/subscription-impact

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

Preview expected payment eligibility

View as Markdown
POST/api/v1/plans/{id}/subscription-impact

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