Discontinued
Subscription payments are available to current subscription API users only.
The /subscription API calls
The "subscription" object represents a single subscription to a subscription_plan. Subscriptions take on the rules of the subscription plan they are associated with. The following calls let you create, view, and modify "subscription" objects on WePay:
Subscription States
The "subscription" object has the following states and the following possible state transitions (you can receive callback notifications when the subscription changes state, please read our IPN Tutorial for more details):
- new
- The subscription was just created by the application.
- trial
- The subscription is currently in trial.
- active
- The subscription is active after trial period is over.
- transition
- The subscription is currently in transition and seeking reauthorization from the subscriber.
- ended
- The subscription has completed.
- cancelled
- The subscription was cancelled by the application or by the subscriber.
- failed
- When payment to renew the subscription fails, WePay retries once. If it fails again, the subscription enters state failed.
- expired
- Subscriptions get expired if they are still in state new after 30 minutes (i.e. they have been abandoned).
/subscription
This call allows you to lookup the details of a specific subscription on WePay using the subscription_id.
Arguments:
| Parameter | Required | Type | Description |
| subscription_id | Yes | Integer (64 bits) | The unique ID of the subscription you want to look up. |
Example:
{
"subscription_id":12345
}
Response:
| Response | Type | Description |
| subscription_plan_id | Integer (64 bits) | The unique ID of the subscription plan that the subscription is associated with. |
| subscription_id | Integer (64 bits) | The unique ID of the subscription you want to look up. |
| subscription_uri | String (2083 chars) | The uri a user visits to confirm and pay for their subscription. Do not store the returned URI on your side as it can change. |
| payer_name | String (255 chars) | The name of the subscriber. |
| payer_email | String (255 chars) | The email of the subscriber. |
| currency | String (255 chars) | The currency used (always "USD" for now). |
| amount | Decimal (64 bits) | The amount that the subscription pays every period. This amount determined by the subscription plan. |
| period | String (255 chars) | The period for each subscription. Either "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 is in. See the subscription states section for a listing of all states. |
| create_time | Integer (64 bits) | The unixtime when the subscription was created. |
| redirect_uri | String (2083 chars) | The uri that the subscriber will be redirected to after confirming the subscription. |
| callback_uri | String (2083 chars) | The uri which instant payment notifications will be sent to. |
| payment_method_id | Integer (64 bits) | The ID of the credit card if subscriber used tokenization. |
| payment_method_type | String (255 chars) | This is set to 'credit_card' if tokenization was used. |
| quantity | Integer (64 bits) | Quantity for this subscription. |
| mode | String (255 chars) | What mode the subscription will be displayed in. The options are 'iframe' or 'regular'. |
| trial_days_remaining | Integer (64 bits) | The days left in the trial of the given subscription. This is only outputted if the subscription is in trial state. |
| transition_expire_time | Integer (64 bits) | The unixtime that the given subscription will expire at if it is not reauthorized. This is only outputted if the subscription is in a transition state. |
| transition_prorate | Boolean | Is the subscription going to be prorated after the transition. This is only outputted if the subscription is in a transition state. |
| transition_quantity | Integer (64 bits) | The new quantity the this subscription is requesting to be transitioned into. This is only outputted if the subscription is in a transition state. |
| transition_subscription_plan_id | Integer (64 bits) | The subscription_plan_id of the plan this subscription is requesting to be transitioned into. This is only outputted if the subscription is in a transition state. |
| reference_id | String (255 chars) | The unique reference_id passed by the application (if available). |
Example:
{
"subscription_plan_id":54321,
"subscription_id":12345,
"subscription_uri":"http://stage.wepay.com/subscriptions/123456/1a2s3d",
"payer_name":"John Doe",
"payer_email":"johndoe@wepay.com",
"currency":"USD",
"amount":"100",
"period":"monthly",
"app_fee":"5"
"fee_payer":"payee",
"redirect_uri":"http://example.com/my-plan-page",
"callback_uri":"http://example.com/callback/status/1531",
"state":"active",
"quantity":"1",
"reference_id":"abc123"
}
/subscription/find
This call allows you to search for subscriptions that match the search parameters.
Arguments:
| Parameter | Required | Type | Description |
| subscription_plan_id | Yes | Integer (64 bits) | The subscription plan that you want to look for subscriptions under. |
| 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). |
| start_time | No | Integer (64 bits) or String (255 chars) | The subscriptions that were activated after this start time. Can be a unix_timestamp or a valid, parse-able date time. |
| end_time | No | Integer (64 bits) or String (255 chars) | The subscriptions that were activated before this end time. Can be a unix_timestamp or a valid, parse-able date-time. |
| state | No | String (255 chars) | What state the subscription is in (see the subscription states section for details). |
| reference_id | No | String (255 chars) | The unique reference id of the subscription (set by the application in /subscription/create). |
Example:
{
"subscription_plan_id":54321,
"start":10,
"limit":20,
"state":"new"
}
Response:
An array of subscriptions matching the search parameters. Each element of the array will include the same data as returned from the /subscription call.
Example:
[
{
"subscription_plan_id":54321,
"subscription_id":12345,
"subscription_uri":"http://stage.wepay.com/subscriptions/123456/1a2s3d",
"payer_name":"John Doe",
"payer_email":"johndoe@wepay.com",
"currency":"USD",
"amount":"100",
"period":"monthly",
"app_fee":"5"
"fee_payer":"payee",
"redirect_uri":"http://example.com/my-plan-page",
"callback_uri":"http://example.com/callback/status/1531",
"state":"active",
"quantity":"1",
"reference_id":"abc123",
},
{
"subscription_plan_id":54321,
"subscription_id":22345,
"subscription_uri":"http://stage.wepay.com/subscriptions/22345/1a2s3d",
"payer_name":"Jane Smith",
"payer_email":"janesmith@wepay.com",
"currency":"USD",
"amount":"100",
"period":"monthly",
"app_fee":"5"
"fee_payer":"payee",
"redirect_uri":"http://example.com/my-plan-page",
"callback_uri":"http://example.com/callback/status/1532",
"state":"active",
"quantity":"1",
"reference_id":"def456"
}
]
/subscription/create
Creates a subscription for a subscription plan.
Arguments:
| Parameter | Required | Format | Description |
| subscription_plan_id | Yes | Integer (64 bits) | The unique ID of the subscription plan you want to create the subscription for. |
| redirect_uri | No | String (2083 chars) | The uri that the subscriber will be redirect to after confirming and paying for the subscription. |
| 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. |
| payment_method_id | No | Integer (64 bits) | If you are using credit card tokenization use the credit_card_id you received from the /credit_card/create call. |
| payment_method_type | No | String (255 chars) | Set to 'credit_card' for tokenization. |
| mode | No | String (255 chars) | What mode the subscription will be displayed in. The options are 'iframe' or 'regular'. Mode defaults to 'regular'. |
| quantity | No | Integer (64 bits) | Quantity for the subscription. Defaults to "1". |
| reference_id | No | String (255 chars) | The unique reference id of the subscription. |
| prefill_info | No | Prefill_Info Structure | Information to pre fill certain fields in the subscription flow (a JSON object, not a JSON serialized string). |
Example:
{
"subscription_plan_id": 54321,
"redirect_uri":"http://example.com/my-plan-page",
"callback_uri":"http://example.com/callback/status/1531",
"mode":"iframe",
"quantity":"1",
"reference_id":"cba123"
}
Response:
| Response | Format | Description |
| subscription_id | Integer (64 bits) | The unique ID of the subscription. |
| subscription_uri | String (2083 chars) | The uri a user visits to confirm and pay for their subscription. Do not store the returned URI on your side as it can change. |
Example:
{
"subscription_id":6789,
"subscription_uri":"http://stage.wepay.com/subscriptions/6789/1a2s3d"
}
/subscription/cancel
Cancels a subscription.
Arguments:
| Parameter | Required | Format | Description |
| subscription_id | Yes | Integer (64 bits) | The unique ID of the subscription to be cancelled. |
| reason | No | String (255 chars) | The reason the subscription is being canceled. |
Example:
{
"subscription_id":12345,
"reason":"Moving to a new city."
}
Response:
| Response | Format | Description |
| subscription_plan_id | Integer (64 bits) | The unique ID of the subscription plan that the cancelled subscription was subscribed to. |
| subscription_id | Integer (64 bits) | The unique ID of the subscription that was cancelled. |
| state | String (255 chars) | The state the subscription is in. It will be cancelled. |
Example:
{
"subscription_plan_id":54321,
"subscription_id":12345,
"state":"cancelled"
}
/subscription/modify
This call allows you to modify the details of a subscription, change to a different plan or quantity, or extend a trial period. Please note that certain subscription changes will require the subscriber to accept the change. Changes that require subscriber approval include: quantity increase and/or changes to subscription_plan_id.
Arguments:
| Parameter | Required | Type | Description |
| subscription_id | Yes | Integer (64 bits) | The unique ID of the subscription you want to modify. |
| subscription_plan_id | No | Integer (64 bits) | If this matches the current subscription_plan_id, we will change the subscriber's price to the latest plan price (prorating not available). If this doesn't match the current subscription_plan_id, we will ask the subscriber to agree to the new plan (prorating is optional). |
| quantity | No | Integer (64 bits) | Quantity for the subscription (prorating is optional). Defaults to "1". |
| prorate | No | Boolean | Default is false. If set to true then this subscription change will be prorated for plan and quantity changes. |
| transition_expire_days | No | Integer (64 bits) | The number of days the subscriber has to agree to price or plan changes before the subscription is auto-cancelled. Defaults to 30 days. Minimum is 2 days. |
| redirect_uri | No | String (2083 chars) | The uri that the subscriber will be redirect to after confirming and paying for the subscription. |
| 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. |
| payment_method_id | No | Integer (64 bits) | If you are using credit card tokenization use the credit_card_id you received from the /credit_card/create call. |
| payment_method_type | No | String (255 chars) | Set to 'credit_card' for tokenization. |
| reference_id | No | String (255 chars) | The unique reference id of the subscription. |
| extend_trial_days | No | Integer (64 bits) | The amount of time (in days) you want to extend the trial for the given subscription by. This must be an integer. |
Example:
{
"subscription_id":12345,
"redirect_uri":"http://example.com/my-plan-page",
"quantity":2
}
Response:
This call will return the same response as the /subscription call.