Sign in

v1

latestOpenAPI 3.0.02026-08-0696238481.7 KB
Subscriptions

Updates a subscription by Id

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

patch/subscriptions/{subscriptionId}

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

status'Pending' | 'Active' | 'Cancelled' | 'PastDue' | 'Ended' | 'Paused'
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
}