{"_id":"5c6c2407b8d4b2000e72da11","category":{"_id":"5c6c2407b8d4b2000e72d989","version":"5c6c2407b8d4b2000e72da25","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-27T10:22:06.636Z","from_sync":false,"order":8,"slug":"subscriptions","title":"Subscriptions"},"parentDoc":null,"user":"560d5913af97231900938124","project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"5c6c2407b8d4b2000e72da25","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5beec5a5f95d82011c6f3714","createdAt":"2018-04-24T15:24:22.608Z","releaseDate":"2018-04-24T15:24:22.608Z","categories":["5c6c2407b8d4b2000e72d981","5c6c2407b8d4b2000e72d982","5c6c2407b8d4b2000e72d983","5c6c2407b8d4b2000e72d984","5c6c2407b8d4b2000e72d985","5c6c2407b8d4b2000e72d986","5c6c2407b8d4b2000e72d987","5c6c2407b8d4b2000e72d988","5c6c2407b8d4b2000e72d989","5c6c2407b8d4b2000e72d98a","5c6c2407b8d4b2000e72d98b","5c6c2407b8d4b2000e72d98c","5c6c2407b8d4b2000e72d98d","5c6c2407b8d4b2000e72d98e","5c6c2407b8d4b2000e72d98f","5c6c2407b8d4b2000e72d990"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"Main","version_clean":"8976.0.0-XML","version":"8976-XML"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-29T19:23:55.868Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"text","code":""}]},"settings":"","auth":"optional","params":[],"url":""},"isReference":false,"order":13,"body":"##Definition\nhttps<span>://sandbox.bluesnap.com/services/2/recurring/subscriptions/:subscription-id/switch-charge-amount</span>\n\n<hr>\n\n##Documentation\nThe Retrieve Subscription Switch Charge Amount request enables you to retrieve the amount that would be charged to a shopper if you changed the subscription to a different plan or to a different quantity or both. If the switch would result in a negative balance, then the `value` parameter shows **0.00**.\n\nThis request does **not** make any changes to the subscription; it just retrieves the new price. To make the switch, use the [Update Subscription](doc:update-subscription) request.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Example:\",\n  \"body\": \"Your shopper's subscription (ID 98989) is currently associated with the Silver Plan, at a cost of $10 per month. It is halfway through the month, and you would like to find out how much the subscriber would be charged if you switched their subscription to the Gold Plan (ID 111111, cost of $20 per month) today. To do this, you would send a GET request in this format:\\n`services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111`\\n\\nBecause the month is half over, half of the amount that was charged for the Silver Plan is remaining (i.e. $5). That amount would be applied to the charge for the Gold Plan, so the value returned is **15.00**.\"\n}\n[/block]\n###Request Content\nEnter the parameters below into the request URL.  For example:\n`services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111`\n\nTo determine what the price would be if the quantity is changed, add the `newquantity` parameter.  For example:\n`services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=98989&newquantity=2`\n\n**Query Parameters**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Example\",\n    \"0-0\": \"`newplanid`\",\n    \"0-1\": \"The plan ID for which you want to retrieve the cost information.\\n**Required**\",\n    \"0-2\": \"`newplanid=111111`\",\n    \"1-1\": \"The number of subscriptions for  which you want to retrieve the combined cost.\\n*Optional*\",\n    \"1-0\": \"`newquantity`\",\n    \"1-2\": \"`newquantity=2`\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"You must include `newplanid` with the `newquantity` parameter.  If you want to see the cost of the new quantity on the current plan, enter the current `planId`. If you want to see the results if you change the plan and the quantity, enter the new values for both.\"\n}\n[/block]\n###Response Details\nIf successful, the response HTTP status code is 200 OK.\nThe response contains the retrieved **[price](doc:price)** object.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Note\",\n  \"body\": \"If you included the `newquantity` parameter in the Request, the response price is price of the subscription multiplied by the new quantity.\"\n}\n[/block]\n<hr>\n\n##Examples\n\n###Request Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X GET https://sandbox.bluesnap.com/services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='\",\n      \"language\": \"curl\",\n      \"name\": \"Retrieve Subscription Charge Request\"\n    },\n    {\n      \"code\": \"curl -v -X GET https://sandbox.bluesnap.com/services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111&newquantity=2 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='\",\n      \"language\": \"curl\",\n      \"name\": \"with new quantity\"\n    }\n  ]\n}\n[/block]\n###Response Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\" standalone=\\\"yes\\\"?>\\n<price xmlns=\\\"http://ws.plimus.com\\\">\\n  <currency>USD</currency>\\n  <value>15.00</value>\\n</price>\",\n      \"language\": \"xml\",\n      \"name\": \"Retrieve Subscription Charge Response\"\n    }\n  ]\n}\n[/block]\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"","slug":"retrieve-subscription-switch-charge-amount","type":"endpoint","title":"Retrieve Subscription Switch Charge Amount"}

Payment API (XML)

Card/Wallet Transactions

PayPal Transactions

ACH/ECP Transactions

SEPA Direct Debit Transactions

Batch Transactions

Refunds

Vaulted Shoppers

Subscriptions

Marketplace

Wallets

Errors

Resources

Test Data & Codes

Guides & Tools

Mobile SDK

getRetrieve Subscription Switch Charge Amount

Definition

https://sandbox.bluesnap.com/services/2/recurring/subscriptions/:subscription-id/switch-charge-amount

Documentation

The Retrieve Subscription Switch Charge Amount request enables you to retrieve the amount that would be charged to a shopper if you changed the subscription to a different plan or to a different quantity or both. If the switch would result in a negative balance, then the value parameter shows 0.00.

This request does not make any changes to the subscription; it just retrieves the new price. To make the switch, use the Update Subscription request.

Example:

Your shopper's subscription (ID 98989) is currently associated with the Silver Plan, at a cost of $10 per month. It is halfway through the month, and you would like to find out how much the subscriber would be charged if you switched their subscription to the Gold Plan (ID 111111, cost of $20 per month) today. To do this, you would send a GET request in this format:
services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111

Because the month is half over, half of the amount that was charged for the Silver Plan is remaining (i.e. $5). That amount would be applied to the charge for the Gold Plan, so the value returned is 15.00.

Request Content

Enter the parameters below into the request URL. For example:
services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111

To determine what the price would be if the quantity is changed, add the newquantity parameter. For example:
services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=98989&newquantity=2

Query Parameters

Parameter
Description
Example

newplanid

The plan ID for which you want to retrieve the cost information.
Required

newplanid=111111

newquantity

The number of subscriptions for which you want to retrieve the combined cost.
Optional

newquantity=2

Note

You must include newplanid with the newquantity parameter. If you want to see the cost of the new quantity on the current plan, enter the current planId. If you want to see the results if you change the plan and the quantity, enter the new values for both.

Response Details

If successful, the response HTTP status code is 200 OK.
The response contains the retrieved price object.

Note

If you included the newquantity parameter in the Request, the response price is price of the subscription multiplied by the new quantity.

Examples

Request Example

Retrieve Subscription Charge Request
with new quantity
curl -v -X GET https://sandbox.bluesnap.com/services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
curl -v -X GET https://sandbox.bluesnap.com/services/2/recurring/subscriptions/98989/switch-charge-amount?newplanid=111111&newquantity=2 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Response Example

Retrieve Subscription Charge Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<price xmlns="http://ws.plimus.com">
  <currency>USD</currency>
  <value>15.00</value>
</price>