{"_id":"5a96ec9589442e002041118e","category":{"_id":"5a96ec9189442e0020411158","version":"5a96ec9189442e002041114d","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-06T17:26:31.422Z","from_sync":false,"order":10,"slug":"tutorials","title":"Guides & Tools"},"user":"560d5913af97231900938124","project":"57336fd5a6a9c40e00e13a0b","parentDoc":null,"version":{"_id":"5a96ec9189442e002041114d","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2018-02-28T17:53:21.809Z","releaseDate":"2018-02-28T17:53:21.809Z","categories":["5a96ec9189442e002041114e","5a96ec9189442e002041114f","5a96ec9189442e0020411150","5a96ec9189442e0020411151","5a96ec9189442e0020411152","5a96ec9189442e0020411153","5a96ec9189442e0020411154","5a96ec9189442e0020411155","5a96ec9189442e0020411156","5a96ec9189442e0020411157","5a96ec9189442e0020411158"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.24.2 Release","version_clean":"8976.0.0-Extended","version":"8976-Extended"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-14T12:07:43.185Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":185,"body":"BlueSnap's **Extended Payment API** provides two ways to work with subscriptions:\n\n  * [BlueSnap Subscription Billing Engine](#section-bluesnap-subscription-billing-engine): Take advantage of our award-winning Subscription Billing Engine to automate and optimize your subscriptions.\n  * [Merchant-Managed Subscriptions](#section-merchant-managed-subscriptions): Manage your own subscriptions and process the payments through BlueSnap.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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](/v8976-XML/docs/subscription-management).\"\n}\n[/block]\n#BlueSnap Subscription Billing Engine\nThe Extended Payment API provides end-to-end subscription management capabilities, enabling you to:\n  * Create custom subscription billing plans, with or without a trial period or an initial charge, and with the billing frequency you want\n  * Create a subscription, which associates a shopper with a billing plan\n  * Change subscription pricing for specific shoppers, for example for discounts or promotions\n  * Easily move subscriptions from one plan to another\n\nBlueSnap automatically processes your recurring subscription payments, keeps shoppers' cards updated, and runs automatic retries for subscription payments several times during a grace period.\nFor more details about our Subscription Billing Engine, see [Subscription Capabilities](http://support.bluesnap.com/docs/subscription-options).\n\n##Tutorial: Subscriptions\nThis 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.\n  * [Step 1: Creating subscription contracts (i.e. plans)](#section-step-1-creating-subscription-contracts-i-e-plans-)\n  * [Step 2: Adding new subscriptions](#section-step-2-adding-new-subscriptions)\n  * [Step 3: Upgrading a subscription](#section-step-3-upgrading-a-subscription)\n  * [Step 4: Creating a subscription with a discounted price](#section-step-4-creating-a-subscription-with-a-discounted-price)\n  * [Step 5: Retrieving subscription charge history for a shopper](#section-step-5-retrieving-subscription-charge-history-for-a-shopper)\n\n###Step 1: Creating subscription contracts (i.e. plans)\nBegin by creating one or more subscription contracts for the relevant product.\n\nIn 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:\n  * Gold: $100\n  * Silver: $50\n  * Bronze: $25\n\nSo we need to create a product for the gym membership and three subscription contracts under that product - one for each tier.\n\nThere are two ways to create products and contracts: either directly in the BlueSnap Merchant Console, or via the Extended Payment API.\n\nFor instructions on setting up products and subscription contracts in the BlueSnap Merchant Console, see:\n  * [Creating a product](http://support.bluesnap.com/docs/creating-a-product)\n  * [Setting up a standard subscription plan](http://support.bluesnap.com/docs/setting-up-a-standard-subscription-plan): This includes subscription plans with or without a trial, or optionally with an initial fee.\n  * [Setting up a custom subscription plan](http://support.bluesnap.com/docs/setting-up-a-custom-subscription-plan): Use a custom subscription plan if you need flexible options like an various trial periods, reduced pricing, or bonus reward periods.\n \nIf you prefer to set up your products and contracts (SKUs) via the API, use these web services:\n  * [Create Product](doc:create-product) \n  * [Create SKU](doc:create-sku) \n\nBlueSnap 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.\n\nFor 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.\n\n###Step 2: Adding new subscriptions\nNow 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:\n  * For credit cards, wallets, ACH/ECP, and SEPA Direct Debit:\n    * For a new shopper, use the [Create Order and New Shopper](doc:create-shopper-and-order) service\n    * For an existing shopper, use the [Create Order with Existing Shopper](doc:create-order) service\n  * For PayPal and other alternative payment methods (or if you want to separate the Auth and Capture phases), use the [Create Shopping Context](doc:create-shopping-context) service to start the order creation and then use the [Update Shopping Context](doc:update-shopping-context) service to place the order.\n\nThese are examples of the request content to create subscriptions on the Gold, Silver and Bronze plans, with different payment methods:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/**Use the Create Order and New Shopper service**/\\n\\n<batch-order xmlns=\\\"http://ws.plimus.com\\\">\\n  <shopper>\\n    <web-info>\\n      <ip>62.219.121.253</ip>\\n    </web-info>\\n    <shopper-info>\\n      <shopper-currency>USD</shopper-currency>\\n      <store-id>4677</store-id>\\n      <locale>en</locale>\\n      <shopper-contact-info>\\n        <title>Mr.</title>\\n        <first-name>Allen</first-name>\\n        <last-name>A</last-name>\\n        <email>allena:::at:::example.com</email>\\n        <company-name>AllenACompany</company-name>\\n        <address1>1 Main St</address1>\\n        <city>Town</city>\\n        <zip>12345</zip>\\n        <state>CA</state>\\n        <country>US</country>\\n        <phone>210-999-0000</phone>\\n        <fax>210-999-0001</fax>\\n      </shopper-contact-info>\\n      <payment-info>\\n        <credit-cards-info>\\n          <credit-card-info>\\n            <billing-contact-info>\\n              <first-name>Allen</first-name>\\n              <last-name>A</last-name>\\n              <address1>1 Main St</address1>\\n              <city>Town</city>\\n              <zip>12345</zip>\\n              <state>CA</state>\\n              <country>US</country>\\n            </billing-contact-info>\\n            <credit-card>\\n         \\t\\t  <card-number>4263982640269299</card-number>\\n              <security-code>837</security-code>\\n              <card-type>VISA</card-type>\\n              <expiration-month>02</expiration-month>\\n              <expiration-year>2018</expiration-year>         \\n            </credit-card>\\n          </credit-card-info>\\n        </credit-cards-info>\\n      </payment-info>\\n    </shopper-info>\\n  </shopper>\\n  <order>\\n    <ordering-shopper>\\n      <web-info>\\n        <ip>62.219.121.253</ip>\\n        <remote-host>www.merchant.com</remote-host>\\n        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n      </web-info>\\n    </ordering-shopper>\\n    <cart>\\n      <cart-item>\\n        <sku>\\n          <sku-id>111</sku-id>\\n        </sku>\\n        <quantity>1</quantity>\\n      </cart-item>\\n    </cart>\\n    <expected-total-price>\\n      <amount>100.00</amount>\\n      <currency>USD</currency>\\n    </expected-total-price>\\n  </order>\\n</batch-order>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Subscription on Gold Plan: new shopper using credit card\"\n    },\n    {\n      \"code\": \"/**Use the Create Order with Existing Shopper service**/\\n\\n<order xmlns=\\\"http://ws.plimus.com\\\">\\n  <ordering-shopper>\\n    <shopper-id>343434</shopper-id>\\n    <web-info>\\n      <ip>62.219.121.253</ip>\\n      <remote-host>www.merchant.com</remote-host>\\n      <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n    </web-info>\\n  </ordering-shopper>\\n  <cart>\\n    <cart-item>\\n      <sku>\\n        <sku-id>222</sku-id>\\n      </sku>\\n      <quantity>1</quantity>\\n    </cart-item>\\n  </cart>\\n  <expected-total-price>\\n    <amount>50.00</amount>\\n    <currency>USD</currency>\\n  </expected-total-price>\\n</order>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Subscription on Silver Plan: existing shopper using credit card\"\n    },\n    {\n      \"code\": \"/**Use the Create Shopping Context service**/\\n\\n<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>www.merchant.com</remote-host>\\n    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <shopper-details>\\n    <shopper>\\n      <fraud-info>\\n        <fraud-session-id>1234567890</fraud-session-id>\\n      </fraud-info>\\n      <shopper-info>\\n        <shopper-contact-info>\\n          <title>Ms</title>\\n          <first-name>Carla</first-name>\\n          <last-name>C</last-name>\\n          <email>CarlaC@example.com</email>\\n          <company-name>CarlaCCompany</company-name>\\n          <address1>2 West St</address1>\\n          <address2 />\\n          <city>City</city>\\n          <zip>12345</zip>\\n          <country>US</country>\\n          <phone>654-333-2222</phone>\\n          <fax>654-333-2223</fax>\\n        </shopper-contact-info>\\n        <store-id>10980</store-id>\\n        <vat-code />\\n        <shopper-currency>USD</shopper-currency>\\n        <locale>en</locale>\\n      </shopper-info>\\n    </shopper>\\n  </shopper-details>\\n  <order-details>\\n    <order>\\n      <ordering-shopper>\\n        <paypal>\\n          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>\\n          <pp-return-url>http://www.success-site.com</pp-return-url>\\n          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>\\n          <pp-no-shipping>0</pp-no-shipping>\\n          <pp-in-context>false<pp-in-context>\\n        </paypal>\\n      </ordering-shopper>\\n      <cart>\\n        <cart-item>\\n          <sku>\\n            <sku-id>333</sku-id>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n      </cart>\\n      <expected-total-price>\\n        <amount>25.00</amount>\\n        <currency>USD</currency>\\n      </expected-total-price>\\n    </order>\\n  </order-details>\\n</shopping-context>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Subscription on Bronze Plan: new shopper using PayPal\"\n    }\n  ]\n}\n[/block]\nThe response will provide the ID for each new subscription in the `url` field under `cart-item`. For example:\n`https://sandbox.bluesnap.com/services/2/subscriptions/100000`\n\nIn 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.\n\n###Step 3: Upgrading a subscription\nBetty, who currently has a subscription on the Silver Plan, is very happy with her gym membership and wants to upgrade to the Gold Plan.\n\nTo 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <subscription-id>200000</subscription-id>\\n  <status>A</status>\\n  <underlying-sku-id>111</underlying-sku-id>\\n  <shopper-id>343434</shopper-id>\\n</subscription>\",\n      \"language\": \"xml\",\n      \"name\": \"Upgrade Subscription to Gold Plan\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Notes on switching plans\",\n  \"body\": \"**Prorated charges**\\nBecause 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.\\n\\nFor 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.\\n\\n**Trial period skipped**\\nThe trial period in the Gold Plan will be automatically ignored, since this is an existing subscription that already started running.\"\n}\n[/block]\n###Step 4: Creating a subscription with a discounted price\nYou 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. \n\nTo 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.\n\nThis is an example of the request content:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/**Use the Create Order and New Shopper service**/\\n\\n<batch-order xmlns=\\\"http://ws.plimus.com\\\">\\n  <shopper>\\n    <web-info>\\n      <ip>62.219.121.253</ip>\\n    </web-info>\\n    <shopper-info>\\n      <shopper-currency>USD</shopper-currency>\\n      <store-id>4677</store-id>\\n      <locale>en</locale>\\n      <shopper-contact-info>\\n        <title>Mr.</title>\\n        <first-name>Daniel</first-name>\\n        <last-name>D</last-name>\\n        <email>danield@example.com</email>\\n        <company-name>DanielDCompany</company-name>\\n        <address1>4 East St</address1>\\n        <city>City</city>\\n        <zip>54321</zip>\\n        <state>CA</state>\\n        <country>US</country>\\n        <phone>555-777-9999</phone>\\n        <fax>555-777-9991</fax>\\n      </shopper-contact-info>\\n      <payment-info>\\n        <credit-cards-info>\\n          <credit-card-info>\\n            <billing-contact-info>\\n              <first-name>Daniel</first-name>\\n              <last-name>D</last-name>\\n              <address1>4 East St</address1>\\n              <city>City</city>\\n              <zip>54321</zip>\\n              <state>CA</state>\\n              <country>US</country>\\n            </billing-contact-info>\\n            <credit-card>\\n         \\t\\t  <card-number>4263982640269299</card-number>\\n              <security-code>837</security-code>\\n              <card-type>VISA</card-type>\\n              <expiration-month>02</expiration-month>\\n              <expiration-year>2018</expiration-year>         \\n            </credit-card>\\n          </credit-card-info>\\n        </credit-cards-info>\\n      </payment-info>\\n    </shopper-info>\\n  </shopper>\\n  <order>\\n    <ordering-shopper>\\n      <web-info>\\n        <ip>62.219.121.253</ip>\\n        <remote-host>www.merchant.com</remote-host>\\n        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n      </web-info>\\n    </ordering-shopper>\\n    <cart>\\n      <cart-item>\\n        <sku>\\n          <sku-id>222</sku-id>\\n        </sku>\\n        <sku-charge-price>\\n          <charge-type>recurring</charge-type>\\n          <amount>40.00</amount>\\n          <currency>USD</currency>\\n        </sku-charge-price>\\n        <quantity>1</quantity>\\n      </cart-item>\\n    </cart>\\n    <expected-total-price>\\n      <amount>40.00</amount>\\n      <currency>USD</currency>\\n    </expected-total-price>\\n  </order>\\n</batch-order>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Subscription with discounted price for Silver Plan\"\n    }\n  ]\n}\n[/block]\n###Step 5: Retrieving subscription charge history for a shopper\nFinally, we can get details about all subscription charges that have been processed for a specific shopper.\n\nTo 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`\nSince we included the `fulldescription` parameter, the response shows all charge details, as shown in this example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<plans xmlns=\\\"http://ws.plimus.com\\\">\\n  <total-results>3</total-results> (only appears if getTotal=true)\\n  <last-page>true</last-page>\\n  <plan>\\n   <plan-id>111</plan-id>\\n   <name>Gold Plan</name>\\n   <recurring-charge-amount>100</recurring-charge-amount>\\n   <currency>USD</currency>\\n   <charge-frequency>MONTHLY</charge-frequency>\\n   <trial-period-days>7</trial-period-days>\\n   <initial-charge-amount>0</initial-charge-amount>\\n   <charge-on-plan-switch>true</charge-on-plan-switch>\\n   <max-number-of-charges>12</max-number-of-charges>\\n   <grace-period-days>14</grace-period-days>\\n   <status>ACTIVE</status>\\n  </plan>\\n  <plan>\\n   <plan-id>222</plan-id>\\n   <name>Silver Plan</name>\\n   <recurring-charge-amount>50</recurring-charge-amount>\\n   <currency>USD</currency>\\n   <charge-frequency>MONTHLY</charge-frequency>\\n   <trial-period-days>7</trial-period-days>\\n   <initial-charge-amount>0</initial-charge-amount>\\n   <charge-on-plan-switch>true</charge-on-plan-switch>\\n   <max-number-of-charges>12</max-number-of-charges>\\n   <grace-period-days>14</grace-period-days>\\n   <status>ACTIVE</status>\\n  </plan>\\n  <plan>\\n   <name>Bronze Plan</name>\\n   <recurring-charge-amount>25</recurring-charge-amount>\\n   <currency>USD</currency>\\n   <charge-frequency>MONTHLY</charge-frequency>\\n   <trial-period-days>7</trial-period-days>\\n   <initial-charge-amount>0</initial-charge-amount>\\n   <charge-on-plan-switch>true</charge-on-plan-switch>\\n   <max-number-of-charges>12</max-number-of-charges>\\n   <grace-period-days>14</grace-period-days>\\n   <status>ACTIVE</status>\\n  </plan>\\n</plans>\",\n      \"language\": \"xml\",\n      \"name\": \"Retrieve Plans Response\"\n    }\n  ]\n}\n[/block]\n#Testing your subscriptions\nBecause 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.\n\nEnter the `subscription-id` in the following GET request, to simulate a subscription event. The execution of this request will trigger the IPN's, emails, and invoices associated with the transaction.\n\n**Note**: This request does not impact subscription dates, meaning time-sensitive properties, such as grace period, are not simulated.  \n\n`/services/2/subscriptions/subscription-id/run-specific`\n\nThe successful response is 204 No Content\n\n<hr>\n#Merchant-Managed Subscriptions\nIf you prefer to manage subscriptions on your side (or through a third party) but process the payments through BlueSnap, follow these steps:\n  * [Step 1: Creating On Demand subscription contracts (i.e. plans)](#section-step-1-creating-on-demand-subscription-contracts-i-e-plans-)\n  * [Step 2: Adding new subscriptions to your On Demand subscription plans](#section-step-2-adding-new-subscriptions-to-your-on-demand-subscription-plans)\n  * [Step 3: Processing recurring payments for On Demand subscriptions](#section-step-3-processing-recurring-payments-for-on-demand-subscriptions)\n  * [Upgrading a subscription, overriding the subscription price, and retrieving subscription charge history](#section-upgrading-a-subscription-overriding-the-subscription-price-and-retrieving-subscription-charge-history)\n  * [Account Updater for merchant-managed cards](#section-account-updater-for-merchant-managed-cards)\n\n###Step 1: Creating On Demand subscription contracts (i.e. plans)\nCreate an \"On Demand\" type of subscription contract via the BlueSnap Merchant Console.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"BlueSnap approval required to enable On Demand subscriptions\",\n  \"body\": \"In order to create an On Demand subscription contract, you must first speak to the BlueSnap Support team ([merchants@bluesnap.com](mailto:merchants@bluesnap.com)) and request that this feature be enabled in your account.\"\n}\n[/block]\nFor instructions on setting up products and contracts in the Merchant Console, see:\n  * [Creating a product](http://support.bluesnap.com/docs/creating-a-product)\n  * [Creating a contract](http://support.bluesnap.com/docs/creating-a-contract) (select one of the On Demand contract types in the **Plan Type** menu when setting up the contract)\n\n###Step 2: Adding new subscriptions to your On Demand subscription plans\nThe 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](doc:create-shopper-and-order), [Create Order with Existing Shopper](doc:create-order), or  [Create Shopping Context](doc:create-shopping-context) services and insert the ID of your On Demand SKU into the `sku-id field`. For details, [go here](#section-step-2-adding-new-subscriptions).\n\n###Step 3: Processing recurring payments for On Demand subscriptions\nSince you are managing your own subscriptions and using the On Demand contract type, you will need to send a [Create Subscription Charge](doc:create-subscription-charge) request each time you want to process a recurring payment for a subscription.\n\nTo 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):\n`services/2/subscriptions/10000/subscription-charges`\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<subscription-charge xmlns=\\\"http://ws.plimus.com\\\">\\n  <charge-info>\\n    <charge-description>September Subscription Fee</charge-description>\\n    <from-date>01-Sep-18</from-date>\\n    <to-date>30-Sep-18</to-date>\\n  </charge-info>\\n  <sku-charge-price>\\n    <amount>100</amount>\\n    <currency>USD</currency>\\n  </sku-charge-price>\\n  <expected-total-price>\\n    <amount>100</amount>\\n    <currency>USD</currency>\\n  </expected-total-price>\\n</subscription-charge>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Subscription Charge\"\n    }\n  ]\n}\n[/block]\n###Upgrading a subscription, overriding the subscription price, and retrieving subscription charge history\nThe 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.\n\nPlease 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](doc:update-subscription) action. However, ongoing recurring charges will need to be sent via the [Create Subscription Charge](doc:create-subscription-charge) request, [as described in step 3](#section-step-3-processing-recurring-payments-for-on-demand-subscriptions).\n\n###Account Updater for merchant-managed cards\nIf 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](/v8976-Tools/docs/account-updater).","excerpt":"Learn how to work with subscriptions in BlueSnap's Extended Payment API","slug":"subscriptions-guide","type":"basic","title":"Subscriptions Guide"}

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>allena@example.com</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>CarlaC@example.com</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>danield@example.com</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>

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 IPN's, 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 these steps:

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 (merchants@bluesnap.com) 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.