Sign in
Subscriptions

Update Subscription

Update subscription items, coupons, billing interval, description, auto-cancel cycles, or payment methods.

Updatable fields:

  • Items (products and quantities) — deferred to the next cycle.
  • Subscription-level coupons — same deferral as items.
  • Recurring interval / interval count (e.g. monthly ↔ yearly) — deferred to the next cycle.
  • Description — applied immediately.
  • Until cycle number (auto-cancel) — applied immediately.
  • Payment method overrides — applied immediately.

Any change to items, coupons, or interval is recorded as a pending change that takes effect at current_period_end. The response carries a pending_change block describing the deferred change, including a next_invoice_preview and the per-line diff. If the next-cycle invoice has already been generated and is unpaid, it is automatically cancelled and re-issued with the new amount.

To change anything else (e.g. the consumer / payer), cancel the subscription and create a new one. Use DELETE /pending-change to revert a previously scheduled change before it takes effect.

put/api/v2/subscriptions/{subscription_id}

Path parameters

subscription_idstring uuid required

Unique identifier (UUID) of the subscription to update

Unique identifier (UUID) of the subscription to update

Request body

descriptionstring nullable

Description of the subscription.

couponsstring[] required

coupons to apply to the subscription for discounts.If you want to keep existing coupons, include them in the list.

until_cycle_numberinteger nullable

Number of billing cycles the subscription should run before it auto-cancels. If set to the current cycle, cancellation is scheduled at period end. If set to null, subscription will continue indefinitely until manually canceled.

recurring_interval'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR'
recurring_interval_countinteger nullable

Optional new interval multiplier. Defaults to the current value if omitted. Same deferral behavior as recurring_interval.

exclude_coupons_if_installmentsboolean nullable

Optional override for the same field on the subscription.

Response

Successful Response

created_atstring date-time

Creation timestamp of the object.

updated_atstring date-time nullable

Last modification timestamp of the object.

idstring uuid4

Unique identifier (UUID) of the subscription

descriptionstring nullable

Description of the subscription

amountstring

Total subscription amount after discounts

original_amountstring

Original subscription amount before discounts

item_level_discounted_amountstring

Total amount discounted at the item level

remaining_daysinteger

Number of days remaining in the current billing period

currency'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR'

ISO 4217 currency codes supported by Moyasar.

Includes all currencies supported by Moyasar payment gateway.

home_currency_amountstring nullable

Amount in home currency (SAR) at creation

exchange_rate_at_creationstring nullable

Exchange rate used at subscription creation

recurring_interval'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR'
recurring_interval_countinteger

Number of intervals per billing cycle (e.g., 2 for bi-monthly)

status'INACTIVE' | 'ACTIVE' | 'EXPIRED' | 'CANCELED' | 'FROZEN' | 'TRIALING' | 'TRIAL_PENDING'
current_period_startstring date-time

Start date and time of the current billing period

current_period_endstring date-time

End date and time of the current billing period

current_cycle_numberinteger

Current cycle number of the subscription

cancel_at_period_endboolean

Whether the subscription will be canceled at the end of the current period

cancel_at_cycle_numberinteger nullable

Cycle number at which the subscription will be automatically canceled

started_atstring date-time nullable

Date and time when the subscription started

ended_atstring date-time nullable

Date and time when the subscription ended

user_idstring uuid4

Unique identifier (UUID) of the user who created the subscription

organization_consumer_idstring uuid4

Unique identifier (UUID) of the organization consumer

latest_invoice_idstring uuid4 nullable

Unique identifier (UUID) of the most recent invoice for this subscription

trial_period_daysinteger nullable

Number of days for the free trial period

trial_endstring date-time nullable

Date and time when the trial period ends

amount_in_smallest_unitinteger

Subscription amount in smallest currency unit (e.g. halala for SAR).

original_amount_in_smallest_unitinteger

Original subscription amount (before discounts) in smallest currency unit.

Changes