BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Subscriptions Guide

Learn how to work with subscriptions in BlueSnap's Extended Payment API

BlueSnap's Extended Payment API provides two ways to work with subscriptions:

📘

This guide is for the Extended Payment API, which is based on a product catalog. If you are working with the Payment API, see the Subscriptions Guide for the Payment API.

BlueSnap Subscription Billing Engine

The Extended Payment API provides end-to-end subscription management capabilities, enabling you to:

  • Create custom subscription billing plans, with or without a trial period or an initial charge, and with the billing frequency you want
  • Create a subscription, which associates a shopper with a billing plan
  • Change subscription pricing for specific shoppers, for example for discounts or promotions
  • Easily move subscriptions from one plan to another

BlueSnap automatically processes your recurring subscription payments, keeps shoppers' cards updated, and runs automatic retries for subscription payments several times during a grace period.
For more details about our Subscription Billing Engine, see Subscription Capabilities.

Tutorial: Subscriptions

This tutorial will show you how to work with subscriptions when using BlueSnap's full Subscription Billing Engine capabilities. We'll cover setting up subscription plans, adding shoppers to a plan (i.e. creating subscriptions), and performing common tasks like switching a subscription to a different plan or changing the subscription price.

Step 1: Creating subscription contracts (i.e. plans)

Begin by creating one or more subscription contracts for the relevant product.

In this example, we are selling a gym membership and will set up subscription billing plans for it. The plans will have a monthly billing frequency and a trial period of one week. We will set up three tiers:

  • Gold: $100
  • Silver: $50
  • Bronze: $25

So we need to create a product for the gym membership and three subscription contracts under that product - one for each tier.

There are two ways to create products and contracts: either directly in the BlueSnap Merchant Console, or via the Extended Payment API.

For instructions on setting up products and subscription contracts in the BlueSnap Merchant Console, see:

If you prefer to set up your products and contracts (SKUs) via the API, use these web services:

BlueSnap will assign an ID to each product and contract (SKU). In the BlueSnap Merchant Console, go to Products in the left menu in order to see the IDs. If you created the products and contracs/SKUs via the API, the IDs are also sent in the Location header in the response.

For this example, we'll assume that the Gym Membership product ID will be 9, the Gold Plan's ID will be 111, the Silver Plan's ID will be 222, and the Bronze Plan's ID will be 333. We'll need those IDs for the next step.

Step 2: Adding new subscriptions

Now that we have our plans (contracts) ready, let's add a shopper to each one. To add a shopper to a plan, you will create a subscription for that shopper. There are three ways to do this, depending on the payment method:

These are examples of the request content to create subscriptions on the Gold, Silver and Bronze plans, with different payment methods:

/**Use the Create Order and New Shopper service**/

<batch-order xmlns="http://ws.plimus.com">
  <shopper>
    <web-info>
      <ip>62.219.121.253</ip>
    </web-info>
    <shopper-info>
      <shopper-currency>USD</shopper-currency>
      <store-id>4677</store-id>
      <locale>en</locale>
      <shopper-contact-info>
        <title>Mr.</title>
        <first-name>Allen</first-name>
        <last-name>A</last-name>
        <email>[email protected]</email>
        <company-name>AllenACompany</company-name>
        <address1>1 Main St</address1>
        <city>Town</city>
        <zip>12345</zip>
        <state>CA</state>
        <country>US</country>
        <phone>210-999-0000</phone>
        <fax>210-999-0001</fax>
      </shopper-contact-info>
      <payment-info>
        <credit-cards-info>
          <credit-card-info>
            <billing-contact-info>
              <first-name>Allen</first-name>
              <last-name>A</last-name>
              <address1>1 Main St</address1>
              <city>Town</city>
              <zip>12345</zip>
              <state>CA</state>
              <country>US</country>
            </billing-contact-info>
            <credit-card>
         		  <card-number>4263982640269299</card-number>
              <security-code>837</security-code>
              <card-type>VISA</card-type>
              <expiration-month>02</expiration-month>
              <expiration-year>2018</expiration-year>         
            </credit-card>
          </credit-card-info>
        </credit-cards-info>
      </payment-info>
    </shopper-info>
  </shopper>
  <order>
    <ordering-shopper>
      <web-info>
        <ip>62.219.121.253</ip>
        <remote-host>www.merchant.com</remote-host>
        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
      </web-info>
    </ordering-shopper>
    <cart>
      <cart-item>
        <sku>
          <sku-id>111</sku-id>
        </sku>
        <quantity>1</quantity>
      </cart-item>
    </cart>
    <expected-total-price>
      <amount>100.00</amount>
      <currency>USD</currency>
    </expected-total-price>
  </order>
</batch-order>

/**Use the Create Order with Existing Shopper service**/

<order xmlns="http://ws.plimus.com">
  <ordering-shopper>
    <shopper-id>343434</shopper-id>
    <web-info>
      <ip>62.219.121.253</ip>
      <remote-host>www.merchant.com</remote-host>
      <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    </web-info>
  </ordering-shopper>
  <cart>
    <cart-item>
      <sku>
        <sku-id>222</sku-id>
      </sku>
      <quantity>1</quantity>
    </cart-item>
  </cart>
  <expected-total-price>
    <amount>50.00</amount>
    <currency>USD</currency>
  </expected-total-price>
</order>

/**Use the Create Shopping Context service**/

<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>www.merchant.com</remote-host>
    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <shopper-details>
    <shopper>
      <fraud-info>
        <fraud-session-id>1234567890</fraud-session-id>
      </fraud-info>
      <shopper-info>
        <shopper-contact-info>
          <title>Ms</title>
          <first-name>Carla</first-name>
          <last-name>C</last-name>
          <email>[email protected]</email>
          <company-name>CarlaCCompany</company-name>
          <address1>2 West St</address1>
          <address2 />
          <city>City</city>
          <zip>12345</zip>
          <country>US</country>
          <phone>654-333-2222</phone>
          <fax>654-333-2223</fax>
        </shopper-contact-info>
        <store-id>10980</store-id>
        <vat-code />
        <shopper-currency>USD</shopper-currency>
        <locale>en</locale>
      </shopper-info>
    </shopper>
  </shopper-details>
  <order-details>
    <order>
      <ordering-shopper>
        <paypal>
          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>
          <pp-return-url>http://www.success-site.com</pp-return-url>
          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>
          <pp-no-shipping>0</pp-no-shipping>
          <pp-in-context>false<pp-in-context>
        </paypal>
      </ordering-shopper>
      <cart>
        <cart-item>
          <sku>
            <sku-id>333</sku-id>
          </sku>
          <quantity>1</quantity>
        </cart-item>
      </cart>
      <expected-total-price>
        <amount>25.00</amount>
        <currency>USD</currency>
      </expected-total-price>
    </order>
  </order-details>
</shopping-context>

The response will provide the ID for each new subscription in the url field under cart-item. For example:
https://sandbox.bluesnap.com/services/2/subscriptions/100000

In this example, we'll assume that Allen's Gold Plan subscription ID will be 100000, Betty's Silver Plan subscription ID will be 200000, and Carla's Bronze Plan subscription ID will be 300000. We'll need those IDs for the next step.

Step 3: Upgrading a subscription

Betty, who currently has a subscription on the Silver Plan, is very happy with her gym membership and wants to upgrade to the Gold Plan.

To switch a subscription to a different plan, you will send an Update Subscription request, and change the underlying-sku-id for the subscription to the Gold Plan (ID 111), as shown in this example:

<subscription xmlns="http://ws.plimus.com">
  <subscription-id>200000</subscription-id>
  <status>A</status>
  <underlying-sku-id>111</underlying-sku-id>
  <shopper-id>343434</shopper-id>
</subscription>

📘

Notes on switching plans

Prorated charges
Because the charge-on-plan-switch setting for the Gold Plan is set to true, the Gold Plan price will be charged immediately upon switching the plan, rather than waiting until the next billing period. The amount that was already applied to the previous plan will be deducted from the new plan's charge.

For example, the price for the Silver Plan is $50 per month and Betty upgraded to the Gold Plan after two weeks. This means that half of the monthly price paid was already used. So the remaining unspent amount ($25) will be applied to the charge for the Gold Plan. The Gold Plan price is $100 and the prorated amount deducted is $25, so Betty will be charged $75 at the time of the upgrade.

Trial period skipped
The trial period in the Gold Plan will be automatically ignored, since this is an existing subscription that already started running.

Step 4: Creating a subscription with a discounted price

You now have a new shopper, Daniel, who would like to sign up for the Silver Plan at the discounted price of $40, which you offered as a promotion.

To do this, you will send a Create Subscription request with Daniel's payment information. In the request, you will include the sku-charge-price resource, with the new recurring charge amount of 40.00. This will change the recurring price to $40 permanently. It applies only to Daniel's subscription and does not affect the price of the Silver Plan itself.

This is an example of the request content:

/**Use the Create Order and New Shopper service**/

<batch-order xmlns="http://ws.plimus.com">
  <shopper>
    <web-info>
      <ip>62.219.121.253</ip>
    </web-info>
    <shopper-info>
      <shopper-currency>USD</shopper-currency>
      <store-id>4677</store-id>
      <locale>en</locale>
      <shopper-contact-info>
        <title>Mr.</title>
        <first-name>Daniel</first-name>
        <last-name>D</last-name>
        <email>[email protected]</email>
        <company-name>DanielDCompany</company-name>
        <address1>4 East St</address1>
        <city>City</city>
        <zip>54321</zip>
        <state>CA</state>
        <country>US</country>
        <phone>555-777-9999</phone>
        <fax>555-777-9991</fax>
      </shopper-contact-info>
      <payment-info>
        <credit-cards-info>
          <credit-card-info>
            <billing-contact-info>
              <first-name>Daniel</first-name>
              <last-name>D</last-name>
              <address1>4 East St</address1>
              <city>City</city>
              <zip>54321</zip>
              <state>CA</state>
              <country>US</country>
            </billing-contact-info>
            <credit-card>
         		  <card-number>4263982640269299</card-number>
              <security-code>837</security-code>
              <card-type>VISA</card-type>
              <expiration-month>02</expiration-month>
              <expiration-year>2018</expiration-year>         
            </credit-card>
          </credit-card-info>
        </credit-cards-info>
      </payment-info>
    </shopper-info>
  </shopper>
  <order>
    <ordering-shopper>
      <web-info>
        <ip>62.219.121.253</ip>
        <remote-host>www.merchant.com</remote-host>
        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
      </web-info>
    </ordering-shopper>
    <cart>
      <cart-item>
        <sku>
          <sku-id>222</sku-id>
        </sku>
        <sku-charge-price>
          <charge-type>recurring</charge-type>
          <amount>40.00</amount>
          <currency>USD</currency>
        </sku-charge-price>
        <quantity>1</quantity>
      </cart-item>
    </cart>
    <expected-total-price>
      <amount>40.00</amount>
      <currency>USD</currency>
    </expected-total-price>
  </order>
</batch-order>

Step 5: Retrieving subscription charge history for a shopper

Finally, we can get details about all subscription charges that have been processed for a specific shopper.

To retrieve a list of the subscription charges for Allen, whose shopper ID in BlueSnap is 111, we send a GET request to services/2/tools/shopper-subscriptions-retriever?shopperid=111&fulldescription=true
Since we included the fulldescription parameter, the response shows all charge details, as shown in this example:

<plans xmlns="http://ws.plimus.com">
  <total-results>3</total-results> (only appears if getTotal=true)
  <last-page>true</last-page>
  <plan>
   <plan-id>111</plan-id>
   <name>Gold Plan</name>
   <recurring-charge-amount>100</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
   <status>ACTIVE</status>
  </plan>
  <plan>
   <plan-id>222</plan-id>
   <name>Silver Plan</name>
   <recurring-charge-amount>50</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
   <status>ACTIVE</status>
  </plan>
  <plan>
   <name>Bronze Plan</name>
   <recurring-charge-amount>25</recurring-charge-amount>
   <currency>USD</currency>
   <charge-frequency>MONTHLY</charge-frequency>
   <trial-period-days>7</trial-period-days>
   <initial-charge-amount>0</initial-charge-amount>
   <charge-on-plan-switch>true</charge-on-plan-switch>
   <max-number-of-charges>12</max-number-of-charges>
   <grace-period-days>14</grace-period-days>
   <status>ACTIVE</status>
  </plan>
</plans>

Card Brand Subscription Compliance

Merchants must clearly disclose the basic terms of the subscription at the point of payment and capture the cardholder’s affirmative acceptance of such terms. The disclosure must include the price that will be billed and the frequency of the billing. For example, "You will be billed USD 9.95 per month until you cancel the subscription.

Merchants who utilize a negative option billing model must also disclose the terms of the trial, including any initial charges, the length of the trial period, and the price and frequency of the subsequent subscription. For example, "You will be billed USD 2.99 today for a 30-day trial. Once the trial ends, you will be billed USD 19.99 each month thereafter until you cancel."

Testing your subscriptions

Because the subscription model requires a time lapse in order to understand the total flow, we have provided a simulator to test your subscriptions in sandbox.

Enter the subscription-id in the following GET request, to simulate a subscription event. The execution of this request will trigger the IPNs, emails, and invoices associated with the transaction.

Note: This request does not impact subscription dates, meaning time-sensitive properties, such as grace period, are not simulated.

/services/2/subscriptions/subscription-id/run-specific

The successful response is 204 No Content

#Merchant-Managed Subscriptions If you prefer to manage subscriptions on your side (or through a third party) but process the payments through BlueSnap, follow the steps below.

👍

Account Updater

BlueSnap's built-in support for Account Updater ensures your shopper's card information is kept up-to-date. It works by automatically updating cards set to expire within a month so you don't lose sales and the shopper continues to enjoy their subscription service.

Step 1: Creating On Demand subscription contracts (i.e. plans)

Create an "On Demand" type of subscription contract via the BlueSnap Merchant Console.

📘

BlueSnap approval required to enable On Demand subscriptions

In order to create an On Demand subscription contract, you must first speak to the BlueSnap Support team ([email protected]) and request that this feature be enabled in your account.

For instructions on setting up products and contracts in the Merchant Console, see:

Step 2: Adding new subscriptions to your On Demand subscription plans

The process of adding new subscriptions is the same as described above for subscriptions on BlueSnap's Subscription Billing Engine. You will use the Create Order and New Shopper, Create Order with Existing Shopper, or Create Shopping Context services and insert the ID of your On Demand SKU into the sku-id field. For details, go here.

Step 3: Processing recurring payments for On Demand subscriptions

Since you are managing your own subscriptions and using the On Demand contract type, you will need to send a Create Subscription Charge request each time you want to process a recurring payment for a subscription.

To do this, send a POST request to this URL and include the ID of the relevant subscription contract (in this example, the subscription contract ID is 10000):
services/2/subscriptions/10000/subscription-charges

<subscription-charge xmlns="http://ws.plimus.com">
  <charge-info>
    <charge-description>September Subscription Fee</charge-description>
    <from-date>01-Sep-18</from-date>
    <to-date>30-Sep-18</to-date>
  </charge-info>
  <sku-charge-price>
    <amount>100</amount>
    <currency>USD</currency>
  </sku-charge-price>
  <expected-total-price>
    <amount>100</amount>
    <currency>USD</currency>
  </expected-total-price>
</subscription-charge>

Upgrading a subscription, overriding the subscription price, and retrieving subscription charge history

The process of upgrading subscriptions, overriding the subscription price, and retrieving subscription charge history is the same as described above for subscriptions on BlueSnap's Subscription Billing Engine.

Please note that when you switch a subscription to an On Demand subscription contract, then the relevant charge for the new contract will be processed as part of that Update Subscription action. However, ongoing recurring charges will need to be sent via the Create Subscription Charge request, as described in step 3.

Account Updater for merchant-managed cards

If you are storing your shoppers' credit cards, you can use BlueSnap's Account Updater service to stay up-to-date with the last card and account information. For more information, see Account Updater.