WePay

Beta

The Subscriptions API is in beta. Please provide feedback - api@wepay.com

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.

API Subscription Plan State Diagram

/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":"Donation to Smith Cancer Fund",
  "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 what the subscription plan.
amount Yes Decimal (64 bits) The amount that will be charged automatically every period.
currency No String (3 chars) The currency used ("USD" for now).
period Yes String (255 chars) The current period of time for each subscription. Must be a string: "weekly", "monthly", "yearly", or "quarterly".
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",
   "amount":50,
   "currency":"USD",
   "period":"monthly",
   "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.