Update Subscriptions

As you gain subscribers, you might need to modify their subscriptions or update certain information. MoneyHash offers various options to better manage ongoing subscriptions, ensuring they are tailored to each specific scenario.

Ways to update a subscription

There are many details in a subscription that can be updated after it has already started. MoneyHash offers ways to manage ongoing subscriptions by updating their data, such as switching between plans, changing the amount to be charged in each cycle, applying discounts, and altering the cycle duration. Lastly, you can also update a subscription card token.

Update card token


Update the card token to automatically charge a subscription invoice.

Change Subscription Plan


Modify the subscription plan and reset the subscription value to the new plan.

Apply Discount to Subscription


Add new discounts or update existing discounts to a subscription that already exists.

Update Subscription cycle duration


Adjust the remaining cycles of a subscription to be longer or shorter than the original.

Update Subscription Amount


Change the amount of the subscription without making any changes to the other parameters.


All these updates can only be done when the subscription is in one of the following status:

  • NEW

In case the subscription is updated while its status is NEW, both the trial period and one-time fee of the new plan will be applied. However, if the subscription's status is INCOMPLETE, the trial period will be ignored while the one-time fee will still be applicable.

Change subscription plan

To switch to a different subscription plan, you can modify the current subscription plan and reset the subscription value to the new plan. When this change is initiated, all parameters of the current subscription, except the Trial period and One-time fee, will be changed to the parameters of the new plan and will be applied starting from the next billing cycle.

Apply discount to subscription

To add or update discounts to an existing subscription, you can apply new discounts to override any existing discounts within the subscription. This will update the discount parameters of the subscription with the new discount amount/percentage and discount cycle.

Update subscription cycle duration

Adjust existing subscription remaining cycles to be longer or shorter than the original remaining cycle. You need to inform the remaining_recurring_cycles parameter in the payload with its new value. The response will update the remaining_recurring_cycles of the subscription to the new specified value and reflect this change on the total reccuring_cyles of the subscription.

Update Subscription Amount

Modifying the subscription amount without altering any other parameter is a straightforward way to customize the cost of an existing subscription without altering any other subscription parameters.

Update subscription card token

If the subscription was initially created using card tokens, you can update the customer's card information by replacing the current primary_card_token. This is particularly useful when the current card has expired.

Moreover, you can utilize the update operation to convert a subscription that wasn't charged automatically into an automatically charged one. To achieve this, store a new primary_card_token and set charge_automatically to true in the process.

To update the card token for a subscription, utilize the Update subscription endpoint.

How to manage multiple updates in the same cycle

You may face the need to make multiple updates to a subscription to fit your customer needs, changing multiple parameters, or even making more than one update to the same one. Below are a few use cases presenting how these updates will work and the result in each scenario.

Use Case 1: Multiple changes for the same parameter

Only the last change should be considered when a parameter is changed multiple times in a single cycle. For example:

Having an initial subscription amount of $100. Executing the following two changes:

  • Change 1: The amount is set to $150.
  • Change 2: The amount is set to $130.

The result will be the last updated value. This means the next invoice will have an amount of $130.

Use Case 2: Multiple changes for multiple parameters without a plan change

When there are changes to multiple parameters, each change should be considered independently without requiring a plan change. For example:

Having an initial subscription amount of $100. Executing the following two changes:

  • Change 1: The amount is set to $150.
  • Change 2: Discount set to 15%.

As the changes are made to different parameters, the last update to each will apply, and both changes will be considered. Resulting in an amount of $150 with a 15% discount.

Use Case 3: Change the plan, then change any other parameter

If there is a change in the plan and another parameter is subsequently changed, the plan change should apply to all parameters except the one changed later. For example:

Initially, with a subscription to Plan A, with an amount of $100 and a discount of 10%.

  • Change 1: Switch to Plan B, with an amount of $120 and no discount.
  • Change 2: The amount is set to $130.

As the change to the amount was made after switching plans, the next invoice will apply every parameter from Plan B, except for the later changed amount. Resulting in an invoice amount of $130, and no discount applied.

Use Case 4: Change the parameter, then change the plan

When a parameter changes before a plan change in the same cycle, the plan change takes precedence over previous changes. For example:

Having an initial subscription amount of $100. Executing the following two changes:

  • Change 1: The amount is set to $150.
  • Change 2: Switches to Plan B, with an amount of $200.

The Plan change will overrule Change 1, and all parameters should be taken from the new plan (Plan B). resulting in an amount of $200, as per Plan B.