BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

Update Subscription

put https://sandbox.bluesnap.com/services/2/recurring/subscriptions/

The Update Subscription request enables you to change any of the following settings for an existing subscription:

  • Plan associated to the subscription
  • Payment source
  • Override value for the recurring charge amount
  • Auto-renew setting (if you set it to false, the subscription expires at the end of the current period)
  • Next charge date
  • Quantity
  • Subscription status (ACTIVE/CANCELED)

Note: If you are using BlueSnap's tax feature, make sure to update the recurring-tax-reference parameter if you update the subscriptions' plan or recurring-charge-amount.

For more information about working with subscriptions, see the Subscriptions tutorial.

📘

Changing payment source

To change the payment source associated with a subscription:

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

📘

Switch contract separately from other changes

If you are switching the contract associated with the subscription, we recommend you do this in a separate API call from other changes, such as updating the payment source or overriding the recurring charge amount.

For example if you want to switch a subscription from plan 1 to plan 2 and also override the recurring charge amount for plan 2, we recommend that you first make an Update Subscription call to change the plan. Then make a separate call to override the recurring charge amount.

Try it in the API Explorer

Request Content

recurring-subscription container    required, contains the following properties (see recurring-subscription):
     plan-id     integer    optional (required with quantity)
     payment-source    container    optional
     override-recurring-charge-amount    decimal   optional
     auto-renew    boolean    optional
     next-charge-date    string    optional
     quantity    integer    optional
     status    string    optional
     recurring-tax-reference     string    optional

📘

Note

If you use the quantity parameter, you must include planid as well. If you want to change the quantity on the current plan, enter the current planId. If you want to 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 body contains the recurring-subscription resource.

Examples

Request Examples

curl -v -X PUT https://sandbox.bluesnap.com/services/2/recurring/subscriptions/8491543 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<recurring-subscription xmlns="http://ws.plimus.com">
  <plan-id>2283849</plan-id>
</recurring-subscription>'

curl -v -X PUT https://sandbox.bluesnap.com/services/2/recurring/subscriptions/8491543 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<recurring-subscription xmlns="http://ws.plimus.com">
  <status>CANCELED</status>
</recurring-subscription>'

curl -v -X PUT https://sandbox.bluesnap.com/services/2/recurring/subscriptions/8491543 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<recurring-subscription xmlns="http://ws.plimus.com">
  <next-charge-date>2021-10-01</next-charge-date>
</recurring-subscription>'

curl -v -X PUT https://sandbox.bluesnap.com/services/2/recurring/subscriptions/8491543 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<recurring-subscription xmlns="http://ws.plimus.com">
  <payment-source>
    <credit-card-info>
      <credit-card>
        <card-last-four-digits>1111</card-last-four-digits>
        <card-type>VISA</card-type>
      </credit-card>
    </credit-card-info>
  </payment-source>
</recurring-subscription>'

curl -v -X PUT https://sandbox.bluesnap.com/services/2/recurring/subscriptions/8491543 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<recurring-subscription xmlns="http://ws.plimus.com">
   <payment-source>
      <credit-card-info>
         <pf-token>4aa918221dfde1b0829bcf259aaeeda32dc35cef9ef13b2ffc1393ecef47e384_</pf-token>
      </credit-card-info>
   </payment-source>
</recurring-subscription>'

curl -v -X PUT https://sandbox.bluesnap.com/services/2/recurring/subscriptions/8491543 \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<recurring-subscription xmlns="http://ws.plimus.com">
  <plan-id>2283849</plan-id>
  <quantity>2</quantity>
</recurring-subscription>'

Response Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<recurring-subscription xmlns="http://ws.plimus.com">
  <subscription-id>8492717</subscription-id>
  <plan-id>2283849</plan-id>
  <vaulted-shopper-id>21188909</vaulted-shopper-id>
  <status>ACTIVE</status>
  <quantity>1</quantity>
  <soft-descriptor>BLS&#x2a;default_descriptor</soft-descriptor>
  <charge-frequency>MONTHLY</charge-frequency>
  <trial-period-days>14</trial-period-days>
  <recurring-charge-amount>29.99</recurring-charge-amount>
  <currency>USD</currency>
  <initial-charge-amount>100.00</initial-charge-amount>
  <auto-renew>true</auto-renew>
  <next-charge-date>2021-08-16</next-charge-date>
  <payer-info>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
  </payer-info>
  <payment-source>
    <credit-card-info>
      <billing-contact-info>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
      </billing-contact-info>
      <credit-card>
        <card-last-four-digits>1111</card-last-four-digits>
        <card-type>VISA</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <card-category>CLASSIC</card-category>
        <expiration-month>07</expiration-month>
        <expiration-year>2023</expiration-year>
      </credit-card>
    </credit-card-info>
  </payment-source>
  <charge>
    <charge-id>12117877</charge-id>
    <subscription-id>8492717</subscription-id>
    <plan-id>2283845</plan-id>
    <vaulted-shopper-id>21188909</vaulted-shopper-id>
    <transaction-id>1012463333</transaction-id>
    <transaction-date>2021-08-02</transaction-date>
    <amount>100.00</amount>
    <currency>USD</currency>
    <soft-descriptor>BLS&#x2a;default_descriptor</soft-descriptor>
    <payment-source>
      <credit-card-info>
        <credit-card>
          <card-last-four-digits>1111</card-last-four-digits>
          <card-type>VISA</card-type>
          <card-sub-type>CREDIT</card-sub-type>
          <expiration-month>07</expiration-month>
          <expiration-year>2023</expiration-year>
        </credit-card>
      </credit-card-info>
    </payment-source>
    <charge-info>
      <from-date>2021-08-02</from-date>
      <to-date>2021-08-16</to-date>
      <charge-type>INITIAL</charge-type>
    </charge-info>
  </charge>
  <fraud-result-info>
    <device-data-collector>N</device-data-collector>
  </fraud-result-info>
</recurring-subscription>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<recurring-subscription xmlns="http://ws.plimus.com">
    <subscription-id>39600224</subscription-id>
    <plan-id>2205010</plan-id>
    <vaulted-shopper-id>19641146</vaulted-shopper-id>
    <status>ACTIVE</status>
    <quantity>1</quantity>
    <soft-descriptor>BLS&#x2a;try</soft-descriptor>
    <charge-frequency>MONTHLY</charge-frequency>
    <recurring-charge-amount>1.99</recurring-charge-amount>
    <currency>USD</currency>
    <auto-renew>true</auto-renew>
    <next-charge-date>2021-04-05</next-charge-date>
    <payer-info>
        <first-name>Shevie</first-name>
        <last-name>Chen</last-name>
        <email>sdk_test1&#x40;gmail.com</email>
        <country>il</country>
        <phone>1800123456789</phone>
    </payer-info>
    <payment-source>
        <credit-card-info>
            <billing-contact-info>
                <first-name>bFname1</first-name>
                <last-name>bLname1</last-name>
                <address1>bAddress1</address1>
                <city>bCity1</city>
                <state>ON</state>
                <zip>bZip1</zip>
                <country>ca</country>
            </billing-contact-info>
            <credit-card>
                <card-last-four-digits>4444</card-last-four-digits>
                <card-type>MASTERCARD</card-type>
                <bin-category>CONSUMER</bin-category>
                <card-regulated>N</card-regulated>
                <expiration-month>11</expiration-month>
                <expiration-year>2023</expiration-year>
                <issuing-country-code>BR</issuing-country-code>
            </credit-card>
        </credit-card-info>
    </payment-source>
</recurring-subscription>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<recurring-subscription xmlns="http://ws.plimus.com">
  <subscription-id>8492717</subscription-id>
  <plan-id>2283849</plan-id>
  <vaulted-shopper-id>21188909</vaulted-shopper-id>
  <status>ACTIVE</status>
  <quantity>2</quantity>
  <soft-descriptor>BLS&#x2a;default_descriptor</soft-descriptor>
  <charge-frequency>MONTHLY</charge-frequency>
  <trial-period-days>14</trial-period-days>
  <recurring-charge-amount>59.98</recurring-charge-amount>
  <currency>USD</currency>
  <initial-charge-amount>100.00</initial-charge-amount>
  <auto-renew>true</auto-renew>
  <next-charge-date>2021-08-16</next-charge-date>
  <payer-info>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
  </payer-info>
  <payment-source>
    <credit-card-info>
      <billing-contact-info>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
      </billing-contact-info>
      <credit-card>
        <card-last-four-digits>1111</card-last-four-digits>
        <card-type>VISA</card-type>
        <card-sub-type>CREDIT</card-sub-type>
        <card-category>CLASSIC</card-category>
        <expiration-month>07</expiration-month>
        <expiration-year>2023</expiration-year>
      </credit-card>
    </credit-card-info>
  </payment-source>
  <charge>
    <charge-id>12117877</charge-id>
    <subscription-id>8492717</subscription-id>
    <plan-id>2283845</plan-id>
    <vaulted-shopper-id>21188909</vaulted-shopper-id>
    <transaction-id>1012463333</transaction-id>
    <transaction-date>2019-08-02</transaction-date>
    <amount>100.00</amount>
    <currency>USD</currency>
    <soft-descriptor>BLS&#x2a;default_descriptor</soft-descriptor>
    <payment-source>
      <credit-card-info>
        <credit-card>
          <card-last-four-digits>1111</card-last-four-digits>
          <card-type>VISA</card-type>
          <card-sub-type>CREDIT</card-sub-type>
          <expiration-month>07</expiration-month>
          <expiration-year>2023</expiration-year>
        </credit-card>
      </credit-card-info>
    </payment-source>
    <charge-info>
      <from-date>2021-08-02</from-date>
      <to-date>2021-08-16</to-date>
      <charge-type>INITIAL</charge-type>
    </charge-info>
  </charge>
  <fraud-result-info>
    <device-data-collector>N</device-data-collector>
  </fraud-result-info>
</recurring-subscription>

Back to Top

Example Descriptions

To update any subscription setting, simply send the relevant field within the request. No other fields are required.

📘

Reactivation

If you reactivate a subscription (by sending <status>ACTIVE</status> on a cancelled subscription), the next charge date is set based on the last period usage.

For example:

  • The subscription was charged on Jun-08-2018, for a period of one year.
  • The subscription was cancelled on Jun-11-2018 (meaning the subscription was used for 3 days, with 362 days not used).
  • The subscription was reactivated on Jun-04-2019.
  • The subscription next charge date is Jun-1-2020, based on the following calculation:
        Jun-04-2019 [reactivation date] + 362 Days [unused] = Jun-01-2020

Back to Top

API Explorer

To test out a call, in the subscription-id field, enter the ID of an existing subscription (e.g. 8491543). In the Body Content field, paste in the XML portion of the request and then click Try it!

Tip: Copy the XML portion from one of the example requests above, or use the XML code below as a starting point. You can enter different parameter values to see how your test scenario would work. The request headers, including authorization, are already built in for you in this test area, so you should not include them here.

<recurring-subscription xmlns="http://ws.plimus.com">
  <next-charge-date>2021-07-01</next-charge-date>
</recurring-subscription>
Language
Credentials
:
Click Try It! to start a request and see the response here!