Update Subscriptions

Subscriptions outlive the terms they were created with. A customer negotiates a discount, upgrades a tier, extends a commitment, or replaces an expired card. MoneyHash lets you change all of that on a running subscription without cancelling and recreating it.

There are five updates, each with its own endpoint, and they all leave the underlying plan untouched.

Update	What it changes
Update amount	The amount charged each cycle, with nothing else touched.
Update discount	Adds or replaces the discount and how many cycles it runs for.
Update cycle duration	Makes the remaining cycles longer or shorter.
Change plan	Moves the subscription onto a different plan and resets its terms to that plan's.
Update card token	Replaces the saved card, or switches a manual subscription onto automatic billing.

Updates only work in four statuses

Every update on this page requires the subscription to be in one of:

NEW
TRIAL
INCOMPLETE
ACTIVE

There is one asymmetry worth knowing. If you change the plan while the subscription is NEW, both the new plan's trial period and its one-time fee apply. If it is INCOMPLETE, the trial period is ignored and only the one-time fee applies.

Update the amount

The narrowest change available: a different price per cycle, with every other term left exactly as it was.

  POST
  /api/v1.4/subscriptions/{subscription_id}/update_amount/

curl -X POST https://web.moneyhash.io/api/v1.4/subscriptions/<YOUR_SUBSCRIPTION_ID>/update_amount/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "59.00" }'

amount is required and overrides the plan's base amount for this subscription only.

Apply or change a discount

New discount terms replace whatever discount the subscription had, rather than stacking on top of it.

  POST
  /api/v1.4/subscriptions/{subscription_id}/update_discount/

Field	Required	What it does
`discount_cycles`	Yes	How many cycles the discount applies to.
`discount_amount`	No	A fixed discount off each invoice.
`discount_percentage`	No	A percentage off each invoice.

curl -X POST https://web.moneyhash.io/api/v1.4/subscriptions/<YOUR_SUBSCRIPTION_ID>/update_discount/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "discount_percentage": "20.00", "discount_cycles": 6 }'

As on a plan, discount_amount and discount_percentage are alternatives. Send one. The subscription then counts down remaining_discount_cycles from the value you set.

Change the cycle duration

Extend or shorten what is left of a subscription without touching its price.

  POST
  /api/v1.4/subscriptions/{subscription_id}/update_remaining_recurring_cycles/

curl -X POST https://web.moneyhash.io/api/v1.4/subscriptions/<YOUR_SUBSCRIPTION_ID>/update_remaining_recurring_cycles/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "remaining_recurring_cycles": 18 }'

remaining_recurring_cycles is required, and it is nullable: send null to make the subscription run indefinitely. The response updates both remaining_recurring_cycles and the subscription's total recurring_cycles to reflect the change.

Change the plan

The broadest change. For a subscription that is already billing, every parameter is reset to the new plan's values except the trial period and the one-time fee, which are carried over. A subscription that has not started billing yet behaves differently - see the status note above.

  POST
  /api/v1.4/subscriptions/{subscription_id}/update_plan/

Field	Required	What it does
`plan`	Yes	The new plan id.
`change_date_strategy`	No	`END_OF_THE_CURRENT_CYCLE` (the default) or `IMMEDIATE`. Decides when the new terms bite.
`next_recurring_cycle_start_date`	Conditional	The date the new invoice reflecting the updated plan is due. Required when `change_date_strategy` is `IMMEDIATE`.
`prorated_billing`	No	Enables proration calculation for immediate plan changes. Defaults to `false`.

curl -X POST https://web.moneyhash.io/api/v1.4/subscriptions/<YOUR_SUBSCRIPTION_ID>/update_plan/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "<YOUR_NEW_PLAN_ID>",
    "change_date_strategy": "IMMEDIATE",
    "next_recurring_cycle_start_date": "2026-10-15",
    "prorated_billing": true
  }'

When the change takes effect

END_OF_THE_CURRENT_CYCLE is the default - the customer finishes the cycle they have already paid for on the old terms, and the new plan applies from the next cycle onward. Nobody is repriced mid-month, which is what you usually want for a downgrade.

IMMEDIATE - the new plan applies straight away. You must also send next_recurring_cycle_start_date so MoneyHash knows when the first invoice on the new terms is due. Add prorated_billing: true and the part-cycle between the change and that date is prorated rather than charged in full. This is the shape you want for an upgrade the customer expects to feel at once.

A queued change shows up in the subscription's scheduled_updates array until it applies, so you can always read back what is pending.

Update the card token

Two jobs, one endpoint: replacing an expired card, and turning automatic billing on for a subscription that was previously paid by hand.

  POST
  /api/v1.4/subscriptions/{subscription_id}/card_token/

Field	Required	What it does
`charge_automatically`	Yes	Whether invoices are charged automatically using the card token.
`primary_card_token`	Conditional	The card token to charge. Required when `charge_automatically` is `true`.

curl -X POST https://web.moneyhash.io/api/v1.4/subscriptions/<YOUR_SUBSCRIPTION_ID>/card_token/ \
  -H "x-api-key: <YOUR_ACCOUNT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_automatically": true,
    "primary_card_token": "<YOUR_NEW_CARD_TOKEN_ID>"
  }'

Sending charge_automatically: true with a fresh token on a subscription that was created without one converts it to automatic billing from the next due date. From then on it cycles inside ACTIVE instead of dropping to PAST_DUE while it waits for the customer. See Tokenize Cards for how to obtain the token.

Several updates in the same cycle

You will sometimes make more than one change before the next invoice is generated. The resolution rules are consistent, and they come down to one idea: a field change resets that field, a plan change resets everything.

In every example below the subscription starts at SAR 100 per cycle.

1. The same field changed twice

Change 1: amount set to 150
Change 2: amount set to 130

Only the last change counts. The next invoice is 130.

2. Two different fields, no plan change

Change 1: amount set to 150
Change 2: discount set to 15 percent

Different fields do not compete, so the last update to each one applies. The next invoice is 150 with 15 percent off.

3. A plan change, then a field change

Starting on Plan A at 100 with a 10 percent discount.

Change 1: switch to Plan B, which is 120 with no discount
Change 2: amount set to 130

The plan applies to every parameter except the one changed after it. The next invoice is 130, with no discount, because Plan B carries none.

4. A field change, then a plan change

Change 1: amount set to 150
Change 2: switch to Plan B, which is 200

The plan change overrules whatever came before it, so every parameter is taken from Plan B. The next invoice is 200.

Where to next

Manage Subscriptions - the lifecycle these updates operate on.
Manage Plans - create the plan you are moving a subscription onto.
Tokenize Cards - obtain a primary_card_token for automatic billing.