# Updates a subscription by Id

Use to update a Subscription. Cannot be used if the Subscription is Cancelled or Ended.

Endpoint: PATCH /subscriptions/{subscriptionId}
Version: 1.1.0
Security: secretApiKeyAuth

## Path parameters:

  - `subscriptionId` (string, required)
    Subscription to retrieve
    Example: "sub_01FCTS1XMKH9FF43CAFA4CXT3P"

## Request fields (application/json):

  - `price` (object,null)
    Defines how much and how often to charge the customer for the Subscription. At least one field should be specified. You can change just the amount OR the interval OR both. Note that merchants operating in the European Union must notify the customer 4 weeks in advance of any changes in pricing. You cannot update this field if the Subscription is Paused, PastDue, Cancelled or Ended. Any updates to the price will be reflected instantly but will only take effect in the next billing cycle

  - `price.amount` (integer,null)
    The amount (in minor units) that is charged on each recurring payment throughout the subscription. Omit this from the request if you are only changing the interval and want to keep charging the customer the same amount.
    Example: 5000

  - `price.interval` (object,null)

  - `price.interval.unit` (string, required)
    The type of interval to wait for between charges
    Enum: "Days", "Months"

  - `price.interval.count` (number, required)
    The number of intervals between charges. e.g. type = Days & count = 60 would charge the customer every 60 days.
    Example: 1

  - `price.interval.times` (number,null)
    (optional) The total number of charges throughout the lifecycle of the recurring series. Leave null for products that continue indefinitely.
    Example: 12

  - `paymentMethod` (object,null)
    Update the payment method that will be charged throughout the subscription. This is useful if your customer wishes to change their card or if a previous card has expired. Note that changing this field will trigger the next payment to apply 3DS - check the requiredAction on the latest payment session. Changing this field whilst in PastDue will trigger a automatic retry at the next available opportunity - check the NextBillingTimestamp

  - `paymentMethod.id` (string)
    The Id of an already stored PaymentMethod belonging to the customer that you want to use to pay for the subscription instead.
    Example: "pmt_01FCTS1XMKH9FF43CAFA4CXT3P"

  - `description` (string,null)
    (optional) description that helps you personalise/identify the specific subscription
    Example: "Bob's monthly gym membership"

  - `billingCycleTimestamp` (number,null)
    The (epoch) timestamp representing the date on which the customer will regularly be billed. e.g. 15th of each month. You can only update this field if the Subscription is Pending. If you update this field to today then a payment will be triggered immediately. Note: If you want to update this for an Active subscription then we recommend cancelling and re-creating the subscription.
    Example: 1631703901

  - `metadata` (object)
    use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata.
    Example: {"orderId":"1","customerId":"123"}

  - `shippingDetails` (object,null)
    Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}

  - `shippingDetails.address` (object)
    Example: {"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}

  - `shippingDetails.phoneNumber` (string,null)
    The phone number of the recipient receiving the goods, in E.164 format
    Example: "+447900000000"

  - `paymentSettings` (object)
    Settings for controlling fields/options on the underlying Payment Session's created by this subscription.

  - `paymentSettings.statementDescriptor` (object,null)
    Used to supply a dynamic statement descriptor for the payments created throughout the lifecycle of this subscription. Note that dynamic statement descriptors are not enabled by default and will be ignored if passed.

  - `paymentSettings.statementDescriptor.descriptor` (string)
    The statement descriptor that will be shown on the customer's bank statement for this payment. If you don't specify this then the descriptor set on your account will be used instead.
It must satisfy the following regex pattern: ^[A-Za-z0-9 ][A-Za-z][A-Za-z0-9 ]$
    Example: "Ryft Ltd"

  - `paymentSettings.statementDescriptor.city` (string)
    This is the city that will be shown on the statements of the account's customers. If you don't specify this then the descriptor set on your account will be used instead.
It must satisfy the following regex pattern: ^[A-Za-z0-9 ][A-Za-z][A-Za-z0-9 ]$
    Example: "London"

## Response 200 fields (application/json):

  - `id` (string)
    The ID of the subscription
    Example: "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ"

  - `status` (string)
    Enum: "Pending", "Active", "Cancelled", "PastDue", "Ended", "Paused"

  - `description` (string,null)
    (optional) description helps you personalise/identify the specific subscription
    Example: "Bob's monthly gym membership"

  - `customer` (object)

  - `customer.id` (string)
    The Id of the customer this subscription belongs to
    Example: "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"

  - `paymentMethod` (object,null)

  - `paymentMethod.id` (string)
    The Id of the PaymentMethod belonging to the customer that will be used to pay for the subscription
    Example: "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"

  - `paymentSessions` (object)

  - `paymentSessions.initial` (object)

  - `paymentSessions.initial.id` (string)
    The Id of the PaymentSession
    Example: "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ"

  - `paymentSessions.initial.clientSecret` (string,null)
    The client secret of the payment session, only supplied when action is required by the customer Supply this to the frontend (web/iOS/Android) to collect the payment details / handle any required actions (3ds)
    Example: "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004"

  - `paymentSessions.initial.requiredAction` (object,null)
    The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS)
    Example: {"type":"Redirect","url":"https://ryftpay.com/3ds-auth"}

  - `paymentSessions.initial.requiredAction.type` (string)
    The type of action
    Enum: "Redirect", "Identify", "Challenge"

  - `paymentSessions.initial.requiredAction.url` (string,null)
    The url to redirect to (if the requiredAction has type Redirect)
    Example: "https://ryftpay.com/3ds-auth"

  - `paymentSessions.initial.requiredAction.identify` (object,null)

  - `paymentSessions.initial.requiredAction.challenge` (object,null)

  - `paymentSessions.latest` (object)

  - `price` (object)

  - `price.amount` (integer)
    The amount (in minor units) that is charged on each recurring payment
    Example: 5000

  - `price.currency` (string)
    The ISO currency code
    Example: "GBP"

  - `price.interval` (object)

  - `price.interval.unit` (string)
    The type of interval to wait for between charges
    Enum: "Days", "Months"

  - `price.interval.count` (number)
    The number of intervals between charges. e.g. type = Days & count = 60 would charge the customer every 60 days.
    Example: 1

  - `price.interval.times` (number,null)
    (optional) The total number of charges throughout the lifecycle of the recurring series. Leave null for products that continue indefinitely.
    Example: 12

  - `balance` (object)
    The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price)
    Example: {"amount":5000}

  - `balance.amount` (integer)
    The amount owed (in minor units of the currency in price)
    Example: 5000

  - `pausePaymentDetail` (object,null)
    Non-null if you have paused payments for the subscription.

  - `pausePaymentDetail.reason` (string,null)
    Field describing why the subscription is paused.
    Example: "Offering service for free to customer"

  - `pausePaymentDetail.resumeAtTimestamp` (number,null)
    The epoch timestamp (seconds) when the subscription should resume collecting payments
    Example: 1470989538

  - `pausePaymentDetail.pausedAtTimestamp` (number)
    The epoch timestamp (seconds) when the subscription was paused
    Example: 1470989538

  - `cancelDetail` (object,null)
    Non-null if the subscription is cancelled

  - `cancelDetail.reason` (string,null)
    Field describing why the subscription is cancelled.
    Example: "Customer no longer wants to use the service"

  - `cancelDetail.cancelledAtTimestamp` (integer)
    The epoch timestamp (seconds) when the subscription was cancelled
    Example: 1480989538

  - `billingDetail` (object)

  - `billingDetail.totalCycles` (number)
    The total number of billing cycles throughout the lifespan of the subscription.
    Example: 12

  - `billingDetail.currentCycle` (number)
    The subscription's current billing cycle. e.g. given a monthly subscription for a 12 month recurring product, where the current date is 4 months removed from the initial charge will have currentCycle = 4
    Example: 4

  - `billingDetail.currentCycleStartTimestamp` (number)
    The (epoch) timestamp representing the start date for the current billing period.
    Example: 1480989538

  - `billingDetail.currentCycleEndTimestamp` (number)
    The (epoch) timestamp representing the end date for the current billing period.
    Example: 1480989538

  - `billingDetail.billingCycleTimestamp` (number)
    The (epoch) timestamp representing the date on which the customer will regularly be billed. e.g. 15th of each month.
    Example: 1480989538

  - `billingDetail.nextBillingTimestamp` (number,null)
    The (epoch) timestamp representing the date on which we will next try to bill your customer. This will be equal to the billingCycleTimestamp at the start of each new billing cycle, but is updated should we fail to successfully charge the customer. The updated timestamp reflects when our recurring engine will retry payment. When 'null' it means that we are not currently planning to bill the customer again (it is Cancelled, Ended or Paused indefinitely)
    Example: 1480989538

  - `billingDetail.failureDetail` (object,null)
    Non-null if the Subscription has become PastDue and one or more payment attempts have been unsuccessful.

  - `billingDetail.failureDetail.paymentAttempts` (number)
    The number of consecutive payment attempts that have failed.
    Example: 2

  - `billingDetail.failureDetail.lastPaymentError` (string,null)
    The most recent error when attempting to Pay.

Note that we may add further values without notice.
    Enum: "insufficient_funds", "declined_do_not_honour", "invalid_card_number", "cvv2_failure", "restricted_card", "blacklisted_card", "blacklisted_bin", "blacklisted_country", "blacklisted_ip", "risk_declined", "security_violation", "expired_card", "gateway_reject", "suspected_fraud", "contact_issuer", "not_permitted", "invalid_account", "pickup_card", "stolen_card", "issuer_decline", "closed_account", "account_not_activated", "limit_exceeded", "withdrawal_limit_exceeded", "blocked_by_cardholder", "3ds_authentication_failure", "3ds_cardholder_not_participating", "3ds_authentication_required", "payment_method_option_amex_disabled", "cvc_required", "payment_method_not_available", "payment_method_option_amex_not_available", "credit_card_not_permitted", "issuer_error", "system_error", "unknown_error"

  - `shippingDetails` (object,null)
    Example: {"address":{"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}}

  - `shippingDetails.address` (object)
    Example: {"firstName":"Fox","lastName":"Mulder","lineOne":"Stonehenge","postalCode":"SP4 7DE","city":"Salisbury","country":"GB"}

  - `shippingDetails.phoneNumber` (string,null)
    The phone number of the recipient receiving the goods, in E.164 format
    Example: "+447900000000"

  - `metadata` (object,null)
    use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata.
    Example: {"myCustomerId":"1"}

  - `paymentSettings` (object)
    Settings for controlling fields/options on the underlying Payment Session's created by this subscription.

  - `paymentSettings.statementDescriptor` (any)
    Used to supply a dynamic statement descriptor for the payments created throughout the lifecycle of this subscription. Note that dynamic statement descriptors are not enabled by default and will be ignored if passed.
    Example: {"descriptor":"Ryft Ltd","city":"London"}

  - `createdTimestamp` (integer)
    The epoch timestamp (seconds) when the subscription was created
    Example: 1470989538

## Response 400 fields (application/json):

  - `requestId` (string)
    Example: "b83f2653-06d7-44a9-a548-5825e8186004"

  - `code` (string)
    Example: "400"

  - `errors` (array)

  - `errors.message` (string)
    Example: "Required property 'amount' not found in JSON"

## Response 404 fields (application/json):

  - `requestId` (string)
    Example: "b83f2653-06d7-44a9-a548-5825e8186004"

  - `code` (string)
    Example: "400"

  - `errors` (array)

  - `errors.message` (string)
    Example: "Required property 'amount' not found in JSON"

## Response 500 fields (application/json):

  - `requestId` (string)
    Example: "b83f2653-06d7-44a9-a548-5825e8186004"

  - `code` (string)
    Example: "400"

  - `errors` (array)

  - `errors.message` (string)
    Example: "Required property 'amount' not found in JSON"