{"_id":"5b19742cb3baf90003cab5a5","category":{"_id":"5b19742cb3baf90003cab4ed","version":"5b19742cb3baf90003cab5ae","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-01-13T18:38:47.347Z","from_sync":false,"order":5,"slug":"ecp-transaction-service","title":"Subscriptions"},"project":"57336fd5a6a9c40e00e13a0b","user":"560d5913af97231900938124","parentDoc":null,"version":{"_id":"5b19742cb3baf90003cab5ae","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5adf4e59ac13b80003d23152","createdAt":"2018-04-24T15:33:45.744Z","releaseDate":"2018-04-24T15:33:45.744Z","categories":["5b19742cb3baf90003cab4e8","5b19742cb3baf90003cab4e9","5b19742cb3baf90003cab4ea","5b19742cb3baf90003cab4eb","5b19742cb3baf90003cab4ec","5b19742cb3baf90003cab4ed","5b19742cb3baf90003cab4ee","5b19742cb3baf90003cab4ef","5b19742cb3baf90003cab4f0","5b19742cb3baf90003cab4f1","5b19742cb3baf90003cab4f2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.26 Release","version_clean":"8976.0.0-Extended","version":"8976-Extended"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-12T15:01:00.537Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","examples":{"codes":[]},"method":"put","auth":"optional","params":[],"url":""},"isReference":true,"order":0,"body":"##Definition\nhttps<span>://sandbox.bluesnap.com/services/2/subscriptions/:subscription-id</span>\n\n<hr>\n\n##Documentation\nThe Update Subscription request enables you to update the settings of an existing subscription in your account.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Changing payment source\",\n  \"body\": \"If you wish to change the payment source associated with the subscription:  \\n\\n1. Make sure the payment details are saved to the shopper. If not, [update the shopper](doc:update-shopper) with the new details. \\n2.  Update the subscription to specify the new payment source.\"\n}\n[/block]\n###Request Content\n`subscription` &nbsp;&nbsp;&nbsp;<span style=\"color:#F37500\">**required**</span>, contains the following properties (see [subscription](doc:subscription)):\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`status` *string* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`cancellation-reason` *string* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`underlying-sku-id` *long* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`shopper-id` *long* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`credit-card` *container* &nbsp;&nbsp;&nbsp;optional (see [credit-card](doc:credit-card)) \n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`paypal` *string* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`paypal-subscription` *container* &nbsp;&nbsp;&nbsp;optional (see [paypal-subscription](doc:paypal-subscription)) \n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`override-recurring-charge` *container* &nbsp;&nbsp;&nbsp;optional (see [override-recurring-charge](doc:override-recurring-charge)) \n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`coupon` *string* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`next-charge-date` *date* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`auto-renew` *boolean* &nbsp;&nbsp;&nbsp;optional\n\n###Response Details\nIf successful, the response HTTP status code is 204 No Content.\nFor details about possible errors, see: [General Errors](doc:general-errors), [Payment & Processor Errors](doc:payment-errors), and [Fraud Errors](doc:fraud-errors).\n\n<hr>\n\n##Examples\n\n###Request Examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <subscription-id>39469016</subscription-id>\\n  <status>C</status>\\n  <underlying-sku-id>2178834</underlying-sku-id>\\n  <shopper-id>19505364</shopper-id>\\n</subscription>'\",\n      \"language\": \"curl\",\n      \"name\": \"Update Subscription Request: status\"\n    },\n    {\n      \"code\": \"curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/5741000 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <override-recurring-charge>\\n    <currency>USD</currency>\\n    <amount>111.99</amount>\\n  </override-recurring-charge>\\n</subscription>'\",\n      \"language\": \"curl\",\n      \"name\": \"override recurring price\"\n    },\n    {\n      \"code\": \"curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <next-charge-date>15-Sep-18</next-charge-date>\\n</subscription>'\",\n      \"language\": \"curl\",\n      \"name\": \"change next charge date\"\n    },\n    {\n      \"code\": \"curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <credit-card>\\n    <card-last-four-digits>0126</card-last-four-digits>\\n    <card-type>VISA</card-type>\\n  </credit-card>\\n</subscription>'\",\n      \"language\": \"curl\",\n      \"name\": \"change credit card\"\n    },\n    {\n      \"code\": \"curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <subscription-id>39469016</subscription-id>\\n  <status>A</status>\\n  <underlying-sku-id>2178834</underlying-sku-id>\\n  <coupon>100off</coupon>\\n  <shopper-id>19505364</shopper-id>\\n</subscription>'\",\n      \"language\": \"curl\",\n      \"name\": \"add coupon\"\n    },\n    {\n      \"code\": \"curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <subscription-id>39469016</subscription-id>\\n  <status>A</status>\\n  <underlying-sku-id>2178834</underlying-sku-id>\\n  <shopper-id>19505364</shopper-id>\\n  <auto-renew>true</auto-renew>\\n</subscription>'\",\n      \"language\": \"curl\",\n      \"name\": \"auto-renew\"\n    },\n    {\n      \"code\": \"curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<subscription xmlns=\\\"http://ws.plimus.com\\\">\\n  <subscription-id>39469016</subscription-id>\\n  <status>A</status>\\n  <underlying-sku-id>2181034</underlying-sku-id>\\n  <shopper-id>19505364</shopper-id>\\n</subscription>'\",\n      \"language\": \"curl\",\n      \"name\": \"switch SKU (contract)\"\n    }\n  ]\n}\n[/block]\n###Response Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/ 1.1 204 No Content\",\n      \"language\": \"http\",\n      \"name\": \"Update Subscription Response\"\n    }\n  ]\n}\n[/block]\n<hr>\n\n##Example Descriptions\n\n###Update Subscription: status\nThe example above shows how to cancel or activate a subscription by setting the relevant value in the status field. Values are:\n  * **A**: Active\n  * **C**: Cancelled\n\n###Update Subscription: override recurring price\nThe example shows how to change the recurring price for a subscription, using the [override-recurring-charge](doc:override-recurring-charge) parameter. This will change the price that is charged each time for this specific subscription, but will not affect the price of the associated SKU (contract).\n\n###Update Subscription: change next charge date\nThis example shows how to change the date of the next recurring charge by entering a date in the `next-charge-date` parameter. All future charge dates will also be recalculated based on the next charge date. For example, if your subscription was charged on the 1st of each month, but you change the next charge date to be on the 15th of September, then it will be charged on the 15th of the month going forward.\n\n###Update Subscription: change credit card\nThe example above shows how to change the credit card used for the recurring subscription charges by sending the card type and the last four digits of the card to be charged going forward. To do this, the new credit card first has to be added to the shopper using the [Update Shopper](doc:update-shopper) request.\n\n###Update Subscription: add coupon\nThe example above shows how to apply a coupon to a subscription by sending the coupon code in the request. The coupon discount will applied based on the terms of the coupon.\n\n###Update Subscription: auto-renew\nThe example above shows how to turn auto-renew on for a subscription by setting the `auto-renew` parameter value to **true**.\n\n###Update Subscription: switch SKU (contract)\nThe example above shows how to change the SKU (contract) that is associated with a subscription by setting the value in the `underlying-sku-id`. You might use this, for example, if you would like to move a subscription from a silver plan to a gold plan. The pricing will be charged according to the new SKU.\n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"","slug":"update-subscription","type":"endpoint","title":"Update Subscription"}

putUpdate Subscription


Definition

https://sandbox.bluesnap.com/services/2/subscriptions/:subscription-id


Documentation

The Update Subscription request enables you to update the settings of an existing subscription in your account.

Changing payment source

If you wish to change the payment source associated with the subscription:

  1. Make sure the payment details are saved to the shopper. If not, update the shopper with the new details.
  2. Update the subscription to specify the new payment source.

Request Content

subscription    required, contains the following properties (see subscription):
      status string    optional
      cancellation-reason string    optional
      underlying-sku-id long    optional
      shopper-id long    optional
      credit-card container    optional (see credit-card)
      paypal string    optional
      paypal-subscription container    optional (see paypal-subscription)
      override-recurring-charge container    optional (see override-recurring-charge)
      coupon string    optional
      next-charge-date date    optional
      auto-renew boolean    optional

Response Details

If successful, the response HTTP status code is 204 No Content.
For details about possible errors, see: General Errors, Payment & Processor Errors, and Fraud Errors.


Examples

Request Examples

curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<subscription xmlns="http://ws.plimus.com">
  <subscription-id>39469016</subscription-id>
  <status>C</status>
  <underlying-sku-id>2178834</underlying-sku-id>
  <shopper-id>19505364</shopper-id>
</subscription>'
curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/5741000 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<subscription xmlns="http://ws.plimus.com">
  <override-recurring-charge>
    <currency>USD</currency>
    <amount>111.99</amount>
  </override-recurring-charge>
</subscription>'
curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<subscription xmlns="http://ws.plimus.com">
  <next-charge-date>15-Sep-18</next-charge-date>
</subscription>'
curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<subscription xmlns="http://ws.plimus.com">
  <credit-card>
    <card-last-four-digits>0126</card-last-four-digits>
    <card-type>VISA</card-type>
  </credit-card>
</subscription>'
curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<subscription xmlns="http://ws.plimus.com">
  <subscription-id>39469016</subscription-id>
  <status>A</status>
  <underlying-sku-id>2178834</underlying-sku-id>
  <coupon>100off</coupon>
  <shopper-id>19505364</shopper-id>
</subscription>'
curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<subscription xmlns="http://ws.plimus.com">
  <subscription-id>39469016</subscription-id>
  <status>A</status>
  <underlying-sku-id>2178834</underlying-sku-id>
  <shopper-id>19505364</shopper-id>
  <auto-renew>true</auto-renew>
</subscription>'
curl -v -X PUT https://sandbox.bluesnap.com/services/2/subscriptions/39469016 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<subscription xmlns="http://ws.plimus.com">
  <subscription-id>39469016</subscription-id>
  <status>A</status>
  <underlying-sku-id>2181034</underlying-sku-id>
  <shopper-id>19505364</shopper-id>
</subscription>'

Response Example

HTTP/ 1.1 204 No Content


Example Descriptions

Update Subscription: status

The example above shows how to cancel or activate a subscription by setting the relevant value in the status field. Values are:

  • A: Active
  • C: Cancelled

Update Subscription: override recurring price

The example shows how to change the recurring price for a subscription, using the override-recurring-charge parameter. This will change the price that is charged each time for this specific subscription, but will not affect the price of the associated SKU (contract).

Update Subscription: change next charge date

This example shows how to change the date of the next recurring charge by entering a date in the next-charge-date parameter. All future charge dates will also be recalculated based on the next charge date. For example, if your subscription was charged on the 1st of each month, but you change the next charge date to be on the 15th of September, then it will be charged on the 15th of the month going forward.

Update Subscription: change credit card

The example above shows how to change the credit card used for the recurring subscription charges by sending the card type and the last four digits of the card to be charged going forward. To do this, the new credit card first has to be added to the shopper using the Update Shopper request.

Update Subscription: add coupon

The example above shows how to apply a coupon to a subscription by sending the coupon code in the request. The coupon discount will applied based on the terms of the coupon.

Update Subscription: auto-renew

The example above shows how to turn auto-renew on for a subscription by setting the auto-renew parameter value to true.

Update Subscription: switch SKU (contract)

The example above shows how to change the SKU (contract) that is associated with a subscription by setting the value in the underlying-sku-id. You might use this, for example, if you would like to move a subscription from a silver plan to a gold plan. The pricing will be charged according to the new SKU.



Back to Top