API BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesBlueSnap.com
Top of Section

Update Subscription

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.

Updating Payment Source

Supported Use Cases

You can only change the payment source if you are updating:

  • to a credit card
  • to a new payment source within the same Apple Pay or Google Pay payment method

Unsupported Use Cases

  • Any update to a new ACH account is not supported

How to Update 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.

Request Content

recurring-subscription container    required, contains the following properties (see recurring-subscription):

PropertyTypeRequired
auto-renewbooleanoptional
next-charge-datestringoptional
override-recurring-charge-amountdecimaloptional
payment-sourcecontaineroptional
plan-idintegeroptional (required with quantity)
quantityintegeroptional
recurring-tax-referencestringoptional
statusstringoptional

📘

Notes

  • 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.
  • Non-reusable cards, like gift cards, cannot be used as a new payment-source.

Response Details

If successful, the response HTTP status code is 200 OK.
The response body contains the recurring-subscription resource.

Back to Top

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>02453</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>

📘

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