Velocity Developer Resources

API Docs

API DOCS MENU

API Docs

Subscriptions

Method of creating subscriptions

Subscriptions details shall include(*required):

  • identifier
  • payment method identifier*
  • plan identifier*

Subscriptions on creation require merchant profile to be onboarded for recurring billing and are associated to merchant profile.

Subscriptions shall inherit all details of plan unless override parameter is specified on creation. See later requirements for coverage of all override scenarios.

Creating subscriptions with override on price

In addition to subscription basic creation elements, users shall pass the following elements in the request:

  • price

Creating subscription with trial period override from plan

In addition to subscription basic creation elements, users shall pass the following elements in the request:

  • trial duration

If trial duration is set to 0, the subscription will start immediately without any trial duration. If trial duration > 0, the subscription will be set with a trial period of “trial duration” value set of days regardless if inherited from plan or not.

Creating subscription with start date override on “service start date”

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • service start date

If the “service start date” > date.today, then status of subscription is set to pending.

Passing any “service start date” on subscription creation will override any trial period from the plan if one exists. No trial period will be associated to subscription.

Creating subscription with plan start date override with setting “billing day of month”

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • service start date

If the “service start date” > date.today, then status of subscription is set to pending.

Passing any “service start date” on subscription creation will override any trial period from the plan if one exists. No trial period will be associated to subscription.

Subscription “Identifier” setting rules on creation

If the “identifier” == empty, the system shall generate a subscription identifier unique to the merchant account. If the “identifier” != empty, the system shall validate on the uniqueness of subscription identifier for the merchant account.

Starting a Subscription Immediately

If a subscription does not have a trial period and will start immediately, the system will charge the customer right away.

If the transaction is declined, the subscription will not be created and you will get the transaction status in the response.

If the transaction is authorized, the subscription will be created and you will get both the subscription and transaction information in the response.

Creating subscription with plan addon override by adding new addons from plan.

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • addons
    • add
      • add on id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When adding new addons from plan, you can add multiple add ons at the same time.

When adding addons to subscription, all details will be inherited from add on id. You can override any of the following details of the add on by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Users can only add an addon to a subscription once. If they would like to apply an addon to a subscription several times, they can pass quantity when adding the addon.

Creating subscription with plan addon override by updating existing addons from plan.

In addition to subscription creation elements, users shall pass in the following elemnts on the request:

  • addons
    • add
      • add on id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When updating addons from plan, you can update multiple addons at the same time.

When updating addons on a subscription, all details will be inherited from add on id specified. You can override any of the following details of the add on by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Creating subscription with plan addon override by removing existing addons from plan.

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • addons
    • remove
      • add on id

Creating subscription with plan addon override by removing all existing addons from plan.

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • addons
  • do not inherit addons (Boolean)

Creating subscription with plan discount override by adding new discounts from plan.

In addition to subscription creation elements, users shall pass in the following elemnts on the request:

  • discounts
    • add
      • discount id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When adding new discounts from plan, you can add multiple discounts at the same time.

When adding discounts to subscription, all details will be inherited from disocunt id.

You can override any of the following details of the discount by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Creating subscription with plan discount override by updating existing discount from plan.

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • discounts
    • update
      • add on id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When updating discounts from plan, you can update multiple discounts at the same time.

When updating discounts on a subscription, all details will be inherited from discount id specified.

You can override any of the following details of the discount by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Creating subscription with plan discount override by removing existing discounts from plan.

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • discounts
    • remove
      • discount id

Creating subscription with plan discount override by removing all existing discounts from plan.

In addition to subscription creation elements, users shall pass in the following elements on the request:

  • discounts
    • do not inherit discounts (boolean)

Method of updating subscription

Users shall be able to update the following elements of the subscription:

  • identifier
  • price (see proration for additional requirements)
  • plan identifier
  • payment method identifier
  • add on and discount details (see further requirements)
  • number of billing cycles or never expires (boolean) (see further requirements)

When making the request for update, the user must reference subscription for update by its “identifier”.

Only subscriptions associated to merchant profile can be updated.

Updating subscription price with proration

To enable proration on a price increase update, users shall pass in addition to price increase:

  • prorate charges (boolean )

If “prorate charges” == true, the app will create a prorated transaction based on the change in price for the remainder of the billing cycle. The transaction is charged immediately, if the charge is declined, the update to the subscription is canceled by default.

If you would like to continue with the update to the subscription and add the prorated amount to the balance even though the transaction failed, users shall pass in addition:

  • revert subscription on proration failure

if “revert subscription on proration failure” == false, the subscription will update will stick regardless of the declined transaction.

Updating subscription by adding new addons

In addition to subscription update elements, users shall pass in the following elements on the request:

  • addons
    • add
      • add on id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When adding new addons, you can add multiple addons at the same time.

When adding addons to subscription, all details will be inherited from add on id. You can override any of the following details of the add on by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Users can only add an addon to a subscription once. If they would like to apply an addon to a subscription several times, they can pass quantity when adding the addon.

Updating subscription by updating existing addons

In addition to subscription update elements, users shall pass in the following elements on the request:

  • addons
    • update
      • add on id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When updating addons, you can update multiple add ons at the same time.

When updating add ons on a subscription, all details will be inherited from add on id specified.

You can override any of the following details of the add on by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Users can only add an addon to a subscription once. If they would like to apply an addon to a subscription several times, they can pass quantity when updating the addon.

Updating subscription by removing existing addons

In addition to subscription update elements, users shall pass in the following elements on the request:

  • addons
    • remove
      • add on id

When removing addons from plan, you can remove multiple add ons at the same time.

Updating subscription by adding new discounts

In addition to subscription update elements, users shall pass in the following elements on the request:

  • discounts
    • add
      • discount id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When adding new discounts, you can add multiple discounts at the same time.

When adding discounts to subscription, all details will be inherited from discount id.

You can override any of the following details of the discount by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Users can only add an discount to a subscription once. If they would like to apply an discount to a subscription several times, they can pass quantity when adding the discount.

Updating subscription by updating existing discount

In addition to subscription update elements, users shall pass in the following elements on the request:

  • discounts
    • update
      • add on id
      • amount
      • number of billing cycles or never expires boolean
      • quantity

When updating discounts, you can update multiple discounts at the same time.

When updating discounts on a subscription, all details will be inherited from discount id specified.

You can override any of the following details of the discount by specifying:

  • amount
  • number of billing cycles or never expires boolean
  • quantity

Users can only add an discount to a subscription once. If they would like to apply an discount to a subscription several times, they can pass quantity when updating the discount.

Updating subscription by removing existing discounts

In addition to subscription update elements, users shall pass in the following elements on the request:

  • discounts
    • remove
    • discount id

When removing discounts, you can remove multiple discounts at the same time.

Updating subscriptions that are Cancelled or Expired status

Subscriptions with a status of cancelled or expired cannot be updated.

Updating subscription in Past Due status

When updating a subscription that is past due, you can only update fields that do not change the price:

  • subscription identifier
  • payment mehtod token identifier

Method of getting subscription details

The following elements shall be returned on plan detail requests:

  • identifier
  • plan identifier
  • payment method token identifier
  • balance
  • price
  • status
  • failure count
  • trial duration
  • trial start date
  • service start date
  • billing day of month
  • billing cycle start date
  • billing cycle end date
  • never expires (boolean)
  • next billing date (date of subscription will be billed again, this date includes retries if they are enabled)
  • next billing period amount (does not include balance, just what regular billing cycle will be accumulating)
  • paid thru date (last successful billed transaction)
  • add on
    • add on id, amount, number of billing cycles or never expires, quantity
  • discounts
    • discount id, amount, number of billing cycles or never expires, quantity
  • transactions
    • trxn.id, trxn.status, trxn.amount, trxn.created date, trxn.subscription. payment method type, trxn.subscription.payment method id, trxn.subscription.plan id, trxn.subscription.balance, trxn.subscription.price, trxn.subscription.add on, trxn.subscription. discount, trxn.subscription.billing cycle start date, trxn.subscription.billing cycle end date, trxn.subscription.paid thru date, trxn.subscription.failure count, trxn.subscription.retry, trxn.subscription.manual, trxn.subscription.prorated, subscription status

Method for listing all subscriptions by merchant

The following elements for each subscription shall be returned:

  • subscription identifier
  • plan identifier
  • payment method token identifier
  • balance
  • price
  • status
  • failure count
  • trial duration
  • trial start date
  • service start date
  • billing day of month
  • billing cycle start date
  • billing cycle end date
  • never expires (boolean)
  • next billing date (date of subscription will be billed again, this date includes retries if they are enabled)
  • next billing period amount (does not include balance, just what regular billing cycle will be accumulating)
  • paid thru date (last successful billed transaction)

Listing subscriptions by price by merchant

On a index request for subscriptions by merchant, users shall be able to filter subscriptions list by price range.

Listing subscriptions by plan id by merchant

On a index request for subscriptions by merchant, users shall be able to filter subscriptions list by plan id.

Listing subscriptions by status by merchant

On a index request for subscriptions by merchant, users shall be able to filter subscriptions list by status.

Listing subscriptions by “days past due” by merchant

On a index request for subscriptions by merchant, users shall be able to filter subscriptions list by “days past due”.

Listing subscription by “billing cycles remaining” by merchant

On a index request for subscriptions by merchant, users shall be able to filter subscriptions list by “billing cycles remaining”.

Listing subscription by “next billing date” by merchant

On a index request for subscriptions by merchant, users shall be able to filter subscriptions list by “next billing date”.

Method for canceling a subscription

Users shall via programming interface have a method to cancel subscriptions. Once a subscription is canceled, it cannot be reactivated.

Validation: Cannot edit a cancelled subscription

After a subscription has been canceled, it cannot be updated

Validation: Subscription ID has already been taken

Subscription ID needs to be unique

Validation: Price cannot be blank

If you provide a price, it can’t be an empty string. If you omit the price, the subscription will inherit the price of from the plan

Validation: Price is an invalid format

Price must be formatted like “10” or “10.00”

Validation: Subscription has already been cancelled

You can’t cancel subscriptions that have already been cancelled.

Updated: June 2, 2017

Need Help?

SUBMIT A DEVELOPER SUPPORT REQUEST

Agent or a merchant? Contact NAB support at 866.485.8999 EXT 2341