# UpdateSubscriptionRequest **amount**integer\ Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD). **Example: **`110` **interval**Subscription-Interval Subscription interval. The `minute` and `hour` intervals are only available in test mode. | Enum Value | Description | | ---------- | ------------------ | | minute | Minutely | | hour | Hourly | | day | Daily | | week | Weekly | | month | Monthly | | quarter | Every three months | | year | Yearly | **Possible values:** \[`minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`] **Example: **`month` **intervalCount**integer\ Number of intervals between subscription payments. **Example: **`1` **allowedPaymentMethods**string\[] List of payment methods allowed for subscriptions. | Enum Value | Description | | ---------- | ----------- | | card | Card | | bizum | Bizum | **Example: **`["card","bizum"]` **description**Subscription-Description An arbitrary string attached to the subscription. Often useful for displaying to users. **Example: **`MoonMail Monthly Lite` **customerId**string\ The [customer](https://docs.monei.com/apis/rest/customers-create/) this subscription belongs to. Linking a subscription to a customer turns on **renewal failover**: when a renewal is declined by the issuing bank, MONEI retries it against up to two of the customer's other saved payment methods within the same attempt, before the subscription goes `PAST_DUE`. One declined renewal can therefore produce up to three charge attempts on different cards. If one succeeds the subscription continues and moves to that payment method. **Example: **`a4e1d1dd-e0c2-4f7a-a2b1-2b0f1f9b6b1e` **customer** object **email**string The customer's email address. **Example: **`john.doe@example.com` **name**string The customer's full name or business name. **Example: **`John Doe` **phone**string The customer's phone number in E.164 format. **Example: **`null` **billingDetails** object Billing information associated with the payment method at the time of the transaction. **name**string The customer's billing full name. **Example: **`John Doe` **email**string The customer's billing email address. **Example: **`john.doe@example.com` **phone**string The customer's billing phone number in E.164 format. **Example: **`null` **company**string Billing company name. **Example: **`null` **taxId**string Company tax ID. **Example: **`null` **address** object **country**Country Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). **Example: **`ES` **city**string City, district, suburb, town, or village. **Example: **`Málaga` **line1**string Address line 1 (e.g., street, PO Box, or company name). **Example: **`Fake Street 123` **line2**string Address line 2 (e.g., apartment, suite, unit, or building). **Example: **`null` **zip**string ZIP or postal code. **Example: **`1234` **state**string State, county, province, or region. **Example: **`Málaga` **shippingDetails** object Shipping information associated with the payment. **name**string The shipping customer's full name. **Example: **`John Doe` **email**string The shipping customer's email address. **Example: **`john.doe@example.com` **phone**string The shipping customer's phone number in E.164 format. **Example: **`null` **company**string Name of the company where the shipment is going. **Example: **`null` **taxId**string Company tax ID. **Example: **`null` **address** object **country**Country Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). **Example: **`ES` **city**string City, district, suburb, town, or village. **Example: **`Málaga` **line1**string Address line 1 (e.g., street, PO Box, or company name). **Example: **`Fake Street 123` **line2**string Address line 2 (e.g., apartment, suite, unit, or building). **Example: **`null` **zip**string ZIP or postal code. **Example: **`1234` **state**string State, county, province, or region. **Example: **`Málaga` **trialPeriodEnd**number\ The end date of the trial period. Measured in seconds since the Unix epoch. **Example: **`1636366897` **callbackUrl**Subscription-CallbackUrl The URL will be called each time subscription status changes. You will receive a subscription object in the body of the request. **Example: **`https://example.com/subscriptions/callback` **paymentCallbackUrl**Subscription-PaymentCallbackUrl The URL will be called each time subscription creates a new payments. You will receive the payment object in the body of the request. **Example: **`https://example.com/payments/callback` **pauseAtPeriodEnd**Subscription-PauseAtPeriodEnd If true, the subscription will be paused at the end of the current period. **Example: **`false` **cancelAtPeriodEnd**Subscription-CancelAtPeriodEnd If true, the subscription will be canceled at the end of the current period. **Example: **`false` **pauseIntervalCount**integer\ Number of intervals when subscription will be paused before it activates again. **Example: **`1` **skipIntervalCount**integer\ The number of intervals during which the subscription billing cycle will be skipped without altering the subscription status. This is useful when payment for a specific period is received through different methods. **Example: **`1` **retrySchedule** object\[] Defines a custom schedule for retrying failed subscription payments. Each entry in the array specifies how long to wait before attempting the next payment retry. If not specified, the system's default retry schedule will be used. * Array \[ **interval**stringrequired The unit of time to wait before the retry attempt. | Enum Value | Description | | ---------- | ----------- | | day | Daily | | week | Weekly | | month | Monthly | | year | Yearly | **Possible values:** \[`day`, `week`, `month`, `year`] **Example: **`day` **intervalCount**integer\required The number of intervals to wait before the retry attempt. **Possible values:** `>= 1` and `<= 31` **Example: **`3` * ] **prorate**Subscription-Prorate Settle the price difference immediately when you change `amount`, `interval`, `intervalCount` or `nextPaymentAt` mid-period. Unused time is credited at the current price. An `amount` change charges the remaining time at the new price and keeps the billing period. An `interval` or `intervalCount` change charges the full new price and restarts the period from now. A `nextPaymentAt` change charges the time from now until the new date and moves the period end to it, so a later date charges and an earlier one refunds. A positive difference is charged to the saved payment method. A negative difference is refunded against the payments that funded the current period, newest money first: the charge taken by the most recent prorated change in this period, then the payment that renewed it. A refund those together cannot cover is rejected before any of it moves, so a change is either settled in full or not at all. The same rule applies to the preview, which returns the same rejection rather than quoting a settlement the update would refuse. A billing period can be prorated more than once. Two limits apply: * While a settlement is in flight the next one is rejected, and the guard has one-second granularity, so a repeat inside the same second as the previous change is rejected too. Retry after at least a second. * A period whose length no longer matches the plan's interval cannot be prorated at all until the next renewal restores it. A `nextPaymentAt` change resizes the period by definition, and an `interval` or `intervalCount` change without `prorate` leaves the old period in place under the new interval. Either one closes the period to further prorated changes, because the credit and the charge are both fractions of the stored period and would divide by a length the price was never set against. Accepted on active and trialing subscriptions only. On a trialing subscription the fields change and no money moves, because there is no paid time to credit. Any other status is rejected. You cannot combine `prorate` with `trialPeriodEnd`, `cancelAtPeriodEnd`, `pauseAtPeriodEnd`, `pauseIntervalCount` or `skipIntervalCount`. On an active subscription, these are rejected too: * A subscription that pays with Bizum, or whose `allowedPaymentMethods` include it. * `prorate` without a change to `amount`, `interval`, `intervalCount` or `nextPaymentAt`, because there is nothing to settle. * An `interval` or `intervalCount` change while `cancelAtPeriodEnd`, `pauseAtPeriodEnd` or `skipIntervalCount` is pending. An `amount` change is accepted. * A change that would refund, when refunds are disabled for the account. A `nextPaymentAt` change has its own rules: * Only on an active subscription. A prorated `nextPaymentAt` change is rejected on a trialing one, where nothing would settle, and on a past due one, which a plain change accepts. * Not together with `interval` or `intervalCount`. Those already restart the period from now, so the new period end would have two answers. * The charge is capped at 24 billing periods. A date far enough ahead to exceed that is rejected rather than charged. * The clearing value described on `nextPaymentAt` is accepted on an anchor move and on nothing else. Any other prorated change still rejects those fields outright. **Example: **`false` **nextPaymentAt**integer\ The date when the next payment will be made. Measured in seconds since the Unix epoch. Send it on an update to move the next charge without changing the price. The date must be in the future and no more than five years ahead, and the subscription must be active or past due with a live schedule. A trialing subscription moves with `trialPeriodEnd` instead, and a paused one has to be resumed first. A pending `skipIntervalCount`, `pauseIntervalCount`, `pauseAtPeriodEnd` or `cancelAtPeriodEnd` blocks the change, because it would turn the charge at the new date into a skipped, paused or cancelled cycle instead of a payment. Clear it in the same request by sending `0`, `null` or `false` for that field. Moving the date on its own settles no money. Combine it with `prorate` to charge or refund the time that moves. **Example: **`1636366897` **metadata**object A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format. **Example: **`{"systemId":"12345"}` UpdateSubscriptionRequest ``` { "amount": 110, "interval": "month", "intervalCount": 1, "allowedPaymentMethods": [ "card", "bizum" ], "description": "MoonMail Monthly Lite", "customerId": "a4e1d1dd-e0c2-4f7a-a2b1-2b0f1f9b6b1e", "customer": { "email": "john.doe@example.com", "name": "John Doe", "phone": null }, "billingDetails": { "name": "John Doe", "email": "john.doe@example.com", "phone": null, "company": null, "taxId": null, "address": { "country": "ES", "city": "Málaga", "line1": "Fake Street 123", "line2": null, "zip": "1234", "state": "Málaga" } }, "shippingDetails": { "name": "John Doe", "email": "john.doe@example.com", "phone": null, "company": null, "taxId": null, "address": { "country": "ES", "city": "Málaga", "line1": "Fake Street 123", "line2": null, "zip": "1234", "state": "Málaga" } }, "trialPeriodEnd": 1636366897, "callbackUrl": "https://example.com/subscriptions/callback", "paymentCallbackUrl": "https://example.com/payments/callback", "pauseAtPeriodEnd": false, "cancelAtPeriodEnd": false, "pauseIntervalCount": 1, "skipIntervalCount": 1, "retrySchedule": [ { "interval": "day", "intervalCount": 1 }, { "interval": "day", "intervalCount": 3 }, { "interval": "week", "intervalCount": 1 } ], "prorate": false, "nextPaymentAt": 1636366897, "metadata": { "systemId": "12345" } } ```