WePay

Beta

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

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

API Subscription State Diagram

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