Discontinued
Subscription payments are available to current subscription API users only.
The /subscription_plan API calls
The "subscription plan" object defines a plan for executing automatic payments according to the defined schedule. The following calls let you create, view, and modify "subscription plan" objects on WePay:
Subscription Plan States
The "subscription plan" object has the following states and the following possible state transitions (you can receive callback notifications when the subscription plan changes state, please read our IPN Tutorial for more details):
- available
- The subscription plan is available and subscribers can be added to it.
- deleted
- The subscription plan has been deleted.
/subscription_plan
This call allows you to lookup the details of a specific subscription plan on WePay using the subscription_plan_id.
Arguments:
| Parameter | Required | Type | Description |
| subscription_plan_id | Yes | Integer (64 bits) | The unique ID of the subscription plan you want to look up. |
Example:
{
"subscription_plan_id":12345
}
Response:
| Response | Type | Description |
| subscription_plan_id | Integer (64 bits) | The unique ID of the subscription plan you want to look up. |
| account_id | Integer (64 bits) | The unique ID of the account that created the plan and where the money will go into. |
| name | String (255 chars) | The name of the subscription plan. |
| short_description | String (2047 chars) | The short description of the subscription plan. |
| currency | String (3 chars) | The currency used ("USD" for now). |
| amount | Decimal (64 bits) | The amount that the subscriptions to this plan will charge the payer automatically every period. |
| period | String (255 chars) | The current period of time for each subscription. Must be a string: "weekly", "monthly", "yearly", or "quarterly". |
| app_fee | Decimal (64 bits) | The dollar amount that the application received in fees. App fees go into the API application's WePay account. |
| fee_payer | String (255 chars) | Who is paying the WePay fees. Set to "payee". |
| state | String (255 chars) | The state the subscription plan is in. See the subscription plan states section for a listing of all states. |
| create_time | Integer (64 bits) | The unixtime when the subscription plan was created. |
| number_of_subscriptions | Integer (64 bits) | Total number of subscriptions to the plan. |
| callback_uri | String (2083 chars) | The uri which instant payment notifications will be sent to. |
| trial_length | Integer (64 bits) | The trial length for new subscriptions. This will be an integer (in days). Subscriptions with trial_length set will only be charged subscription amount after trial_length has expired. |
| setup_fee | Decimal (64 bits) | A one-time fee that the subscription plan can charge for creating the subscription. It will be charged right when users confirm their subscription. |
| reference_id | String (255 chars) | The unique reference_id passed by the application (if available). |
Example:
{
"subscription_plan_id":12345,
"account_id":54321,
"name":"WeGym Gold Plan Membership",
"short_description":"Gold membership privileges",
"currency":"USD",
"amount":100,
"period":"monthly",
"app_fee":5,
"fee_payer":"payee",
"number_of_subscriptions":108,
"callback_uri":"http://example.com/callback/status/1531",
"state":"captured",
"trial_length":"2",
"setup_fee":5,
"reference_id":"abc123"
}
/subscription_plan/find
This call allows you to search for subscription plans associated with an account. If no account_id is passed, then it will look for subscription plans on an app level basis. Returns an array of matching subscription plans.
Arguments:
| Parameter | Required | Type | Description |
| account_id | No | Integer (64 bits) | The unique ID of the account whose subscription plans you are searching. |
| start | No | Integer (64 bits) | The start position for your search (default 0). |
| limit | No | Integer (64 bits) | The maximum number of returned entries (default 50). |
| state | No | String (255 chars) | What state the subscription plan is in (see the subscription plan states section for details). |
| reference_id | No | String (255 chars) | The unique reference id of the subscription plan (set by the application in /subscription_plan/create). |
Example:
{
"account_id":54321,
"start":10,
"limit":20,
"state":"available"
}
Response:
An array of subscription plans matching the search parameters. Each element of the array will include the same data as returned from the /subscription_plan call.
Example:
[
{
"subscription_plan_id":12345,
"account_id":54321,
"name":"WeGym Gold Plan Membership",
"short_description":"Gold membership privileges",
"amount": 100,
"currency":"USD",
"period":"monthly",
"app_fee":5,
"fee_payer":"payee",
"number_of_subscriptions":"108",
"callback_uri":"http://example.com/callback/status/1531",
"state":"captured",
"trial_length":"2",
"setup_fee":5,
"reference_id":"abc123",
},
{
"subscription_plan_id":12345,
"account_id":54321,
"name":"WeGym Bronze Plan Membership",
"short_description":"Bronze membership privileges",
"amount":50,
"currency":"USD",
"period":"monthly",
"app_fee":5,
"fee_payer":"payee",
"number_of_subscriptions":"108",
"callback_uri":"http://example.com/callback/status/1531",
"state":"captured",
"trial_length":"2",
"setup_fee":5,
"reference_id":"def456"
}
]
/subscription_plan/create
Creates a subscription_plan for an account.
Arguments:
| Parameter | Required | Format | Description |
| account_id | Yes | Integer (64 bits) | The unique ID of the account that will own the subscription plan and receive the funds. |
| name | Yes | String (255 chars) | The name of the subscription plan. |
| short_description | Yes | String (2047 chars) | A short description of the subscription plan. |
| amount | Yes | Decimal (64 bits) | The amount that will be charged automatically every period. |
| period | Yes | String (255 chars) | The current period of time for each subscription. Must be a string: "weekly", "monthly", "yearly", or "quarterly". |
| currency | No | String (3 chars) | The currency used ("USD" for now). |
| app_fee | No | Decimal (64 bits) | The dollar amount that the application will receive in fees. App fees go into the API applications WePay account. |
| callback_uri | No | String (2083 chars) | The uri that will receive any instant payment notifications sent. Needs to be a full uri (ex https://www.wepay.com ) and must NOT be localhost or 127.0.0.1 or include wepay.com. |
| trial_length | No | Integer (64 bits) | An integer that represents the number of days that a trial will last before charges occur. |
| setup_fee | No | Decimal (64 bits) | A one-time fee that the subscription plan can charge for creating the subscription. It will be charged right when users confirm their subscription. |
| reference_id | No | String (255 chars) | The unique reference id of the subscription plan. |
Example:
{
"account_id":54321,
"name":"WeGym Bronze Plan Membership",
"short_description":"Bronze membership privileges",
"amount":50,
"period":"monthly",
"currency":"USD",
"app_fee":5,
"callback_uri":"http://example.com/callback/status/1531",
"trial_length":"2",
"setup_fee":5,
"reference_id":"cba123"
}
Response:
This call will return the same response as the /subscription_plan call.
/subscription_plan/delete
Deletes the subscription plan. Existing subscriptions to the plan will still be active, but there will be no new subscriptions to the plan.
Arguments:
| Parameter | Required | Format | Description |
| subscription_plan_id | Yes | Integer (64 bits) | The unique ID of the subscription plan to be deleted. |
| reason | No | String (255 chars) | The reason the subscription plan is being deleted. |
Example:
{
"subscription_plan_id":12345,
"reason":"A new plan will take this plan's place."
}
Response:
| Response | Format | Description |
| subscription_plan_id | Integer (64 bits) | The unique ID of the subscription plan that was successfully deleted. |
| state | String (255 chars) | The state the subscription plan is in. It will be deleted. |
Example:
{
"subscription_plan_id":12345,
"state":"deleted"
}
/subscription_plan/modify
This call allows you to modify the details of a subscription plan. Whenever you modify a subscription plan detail that affects
the price that a new subscription will have to pay, you can pass in a parameter update_subscriptions
that will update existing subscriptions to the new details.
We require reauthorization when a subscription is updated so that they must pay a higher price than when they initially agreed to do so. We do not
require reauthorization when a subscription is updated to pay a lower price than they originally agreed to pay.
Arguments:
| Parameter | Required | Type | Description |
| subscription_plan_id | Yes | Integer (64 bits) | The unique ID of the subscription plan you want to modify. |
| name | No | String (255 chars) | The name of the subscription plan. |
| short_description | No | String (2047 chars) | A short description of what the subscription plans is for. |
| amount | No | Decimal (64 bits) | The amount that the payer will be charged automatically every period. |
| app_fee | No | Decimal (64 bits) | The dollar amount that the application will receive in fees. App fees go into the API applications WePay account. |
| callback_uri | No | String (2083 chars) | The uri that will receive any instant payment notifications sent. Needs to be a full uri (ex https://www.wepay.com ) and must NOT be localhost or 127.0.0.1 or include wepay.com. |
| trial_length | No | Integer (64 bits) | An integer that represents the number of days that a trial will last before charges occur. |
| setup_fee | No | Decimal (64 bits) | A one-time fee that the subscription plan can charge for creating the subscription. It will be charged right when users confirm their subscription. |
| update_subscriptions | No | String (255 chars) | The possible values for this call are 'all', 'none', 'paying_higher', and 'paying_lower'. Whenever you modify a subscription plan, you can pass in a value to update_subscriptions (default is 'none'). Depending on the value, we will update the existing subscriptions to match the new subscription plan details. |
| transition_expire_days | No | Integer (64 bits) | The number of days that you give a subscription to reauthorize and transition to the new subscription plan details. If the subscription did not reauthorize and its transition_expire_time has passed, then the subscription will automatically be cancelled. This defaults to 30 days if not set. |
| reference_id | No | String (255 chars) | Unique ID to reference the subscription plan. |
Example:
{
"subscription_plan_id":12345,
"name":"WeGym Platinum Membership",
"short_description":"Platinum membership privileges",
"amount":150,
"update_subscriptions":"paying_lower",
"transition_expire_days":"14"
}
Response:
This call will return the same response as the /subscription_plan call.