Sign in

v1

latestOpenAPI 3.0.02026-08-0696238481.7 KB
Subscriptions

Pause a subscription by Id

Used to schedule a pause for a Subscription. Only 'Active' subscriptions can be paused, though the details for already 'Paused' subscriptions can also be edited. The subscription will remain in 'Active' and will be moved to 'Paused' when it was next due to be billed. The reason or duration of the pause can be edited by calling this endpoint again, even after it has moved to 'Paused'. After a pause is scheduled but whilst still in 'Active', the pause can be unscheduled via the 'unschedule' flag.

patch/subscriptions/{subscriptionId}/pause

Path parameters

subscriptionIdstring required
Example:sub_01FCTS1XMKH9FF43CAFA4CXT3P

Subscription to pause

Request body

reasonstring nullable

Optional field describing why the subscription is being paused.

resumeAtTimestampnumber nullable

The epoch timestamp (seconds) when the subscription should resume collecting payments. If not specified, the subscription will remain paused indefinitely until a /resume API call is made.

unscheduleboolean nullable

A flag used to unschedule an already scheduled pause, resulting in the customer being billed as normal (as they were before). This can only be 'true' if the subscription is still 'Active', a pause has been scheduled and no other fields are provided. To resume an already 'Paused' subscription then either update the 'resumeAtTimestamp' or call /resume.

Example request

{
  "reason": "Offering service for free to customer",
  "resumeAtTimestamp": 1470989538
}

Response

The subscription was paused 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
}