Subscriptions

Updates a subscription by Id

Changed on Oct 29, 2026

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

patch/subscriptions/{subscriptionId}

Request

Base URL
https://sandbox-api.ryftpay.com/v1
URL
https://sandbox-api.ryftpay.com/v1/subscriptions/{subscriptionId}
Auth
API key in header Authorization

Path parameters

subscriptionIdstring required

Example:sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to retrieve

Request body

descriptionstring nullable

(optional) description that helps you personalise/identify the specific subscription

billingCycleTimestampnumber nullable

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.

metadataobject

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 request

{
  "price": {
    "amount": 5000,
    "interval": {
      "unit": "Months",
      "count": 1,
      "times": 12
    }
  },
  "paymentMethod": {
    "id": "pmt_01FCTS1XMKH9FF43CAFA4CXT3P"
  },
  "description": "Bob's monthly gym membership",
  "billingCycleTimestamp": 1631703901,
  "metadata": {
    "orderId": "1",
    "customerId": "123"
  },
  "shippingDetails": {
    "address": {
      "firstName": "Fox",
      "lastName": "Mulder",
      "lineOne": "Stonehenge",
      "postalCode": "SP4 7DE",
      "city": "Salisbury",
      "country": "GB"
    }
  },
  "paymentSettings": {
    "statementDescriptor": {
      "descriptor": "Ryft Ltd",
      "city": "London"
    }
  }
}

Response

The subscription was updated successfully

idstring

The ID of the subscription

descriptionstring nullable

(optional) description helps you personalise/identify the specific subscription

metadataobject nullable

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.

createdTimestampinteger

The epoch timestamp (seconds) when the subscription was created

Example response

{
  "id": "sub_01G0EYVFR02KBBVE2YWQ8AKMGJ",
  "status": "Active",
  "description": "Bob's monthly gym membership",
  "customer": {
    "id": "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentMethod": {
    "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ"
  },
  "paymentSessions": {
    "initial": {
      "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ",
      "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
      "requiredAction": {
        "type": "Redirect",
        "url": "https://ryftpay.com/3ds-auth"
      }
    },
    "latest": {
      "id": "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ",
      "clientSecret": "ps_01FCTS1XMKH9FF43CAFA4CXT3P_secret_b83f2653-06d7-44a9-a548-5825e8186004",
      "requiredAction": {
        "type": "Redirect",
        "url": "https://ryftpay.com/3ds-auth"
      }
    }
  },
  "price": {
    "amount": 5000,
    "currency": "GBP",
    "interval": {
      "unit": "Months",
      "count": 1,
      "times": 12
    }
  },
  "balance": {
    "amount": 5000
  },
  "pausePaymentDetail": {
    "reason": "Offering service for free to customer",
    "resumeAtTimestamp": 1470989538,
    "pausedAtTimestamp": 1470989538
  },
  "cancelDetail": {
    "reason": "Customer no longer wants to use the service",
    "cancelledAtTimestamp": 1480989538
  },
  "billingDetail": {
    "totalCycles": 12,
    "currentCycle": 4,
    "currentCycleStartTimestamp": 1480989538,
    "currentCycleEndTimestamp": 1480989538,
    "billingCycleTimestamp": 1480989538,
    "nextBillingTimestamp": 1480989538,
    "failureDetail": {
      "paymentAttempts": 2,
      "lastPaymentError": "insufficient_funds"
    }
  },
  "shippingDetails": {
    "address": {
      "firstName": "Fox",
      "lastName": "Mulder",
      "lineOne": "Stonehenge",
      "postalCode": "SP4 7DE",
      "city": "Salisbury",
      "country": "GB"
    }
  },
  "metadata": {
    "myCustomerId": "1"
  },
  "paymentSettings": {
    "statementDescriptor": {
      "descriptor": "Ryft Ltd",
      "city": "London"
    }
  },
  "createdTimestamp": 1470989538
}

Changes

Oct 29, 2026d73b6f121d8a Revision changes
- warning
  added the new 3ds_authentication_not_supported enum value to the // response property for the response status
- warning
  added the new authorisation_denied enum value to the // response property for the response status
- warning
  added the new in_person_terminal_action_cancelled enum value to the // response property for the response status
- warning
  added the new in_person_terminal_action_timeout enum value to the // response property for the response status
- warning
  added the new in_person_terminal_busy enum value to the // response property for the response status
- warning
  added the new in_person_terminal_not_available enum value to the // response property for the response status
- warning
  added the new payment_cancelled enum value to the // response property for the response status
- warning
  added the new recurring_series_terminated enum value to the // response property for the response status

Operation history