Skip to main content

Pause and resume recurring programs

You can pause an active recurring program at any time during the billing cycle, but the pause will only start from the next billing cycle start date (pauseStartDate).

The following features help you pause a recurring program and manage it:

  • Schedule a pause
  • Resume a pause
  • Cancel a pause
  • Update an ongoing pause

Schedule a pause

You can pause an active recurring program by sending a POST request to the /pauses endpoint using the following required fields. This updates the pause status of the recurring program (recurringProgramPauseStatusCode) to PAUSE_SCHEDULED.

Required fields for a pause
Field name Description
recurringProgramId A system generated identifier that connects a consumer record to products/services offered by merchant. It describes what the customer has signed up for and how often they're charged for it.
pauseRemainingBillingCycles Identifies the number of cycles on recurring program pause. If not provided the pause will be set indefinitely. If zero is entered, the pause resume will be scheduled for next billing cycle.

HTTP method: POST

Endpoint: /pauses

Scenario: Scheduling a pause for 2 billing cycles that will start from the next billing cycle. 

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "pauseRemainingBillingCycles": 2
}

Response:

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "merchantId": "998152096533",
    "requestId": "265cc804-7994-423f-be9e-6e5d19fbbd60",
    "merchantRecurringProgramId": "xB7lAXy0vZ",
    "pauseInformation": {
        "pauseRequestedDate": "2024-05-01T00:46:55.879718031Z",
        "recurringProgramPauseStatusCode": "PAUSE_SCHEDULED",
        "pauseBillingCyclesTotalCount": 2,
        "pauseRemainingBillingCycles": "2",
        "pauseStartDate": "2024-05-02",
        "pauseEndDate": "2024-05-03"
    }
}

Resume a pause

You can resume a scheduled pause by sending a POST request to the /pauses endpoint with pauseRemainingBillingCycles = 0. This updates the pause status of the recurring program (recurringProgramPauseStatusCode) to RESUMED_SCHEDULED. The status updates to RESUMED at the start of the next billing cycle.

HTTP method: POST

Endpoint: /pauses

Scenario: Resume a scheduled pause on a recurring program.

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "pauseRemainingBillingCycles": 0
}

Response:

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "merchantId": "998152096534",
    "requestId": "73811608-f5c8-4ef9-adf0-1148e4389088",
    "merchantRecurringProgramId": "xB7lAXy0vZ",
    "pauseInformation": {
        "pauseRequestedDate": "2024-05-01T00:46:55.879718Z",
        "recurringProgramPauseStatusCode": "RESUMED",
        "pauseBillingCyclesTotalCount": 3,
        "pauseRemainingBillingCycles": "0",
        "pauseStartDate": "2024-05-02",
        "pauseEndDate": "2024-05-04"
    }
}

Cancel a pause

You can cancel a scheduled pause by sending a POST request to the /pauses endpoint with the pauseRemainingBillingCycles = 0. This updates the pause status of the recurring program (recurringProgramPauseStatusCode) to PAUSE_CANCELLED.

HTTP method: POST

Endpoint: /pauses

Scenario: Cancel a scheduled pause on a recurring program.

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "pauseRemainingBillingCycles": 0
}

Response:

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "merchantId": "998152096535",
    "requestId": "265cc804-7994-423f-be9e-6e5d19fbbd77",
    "merchantRecurringProgramId": "xB7lAXy0vZ",
    "pauseInformation": {
        "pauseRequestedDate": "2024-05-01T00:46:55.879718Z",
        "recurringProgramPauseStatusCode": "PAUSE_CANCELLED",
        "pauseBillingCyclesTotalCount": 0,
        "pauseRemainingBillingCycles": "0",
        "pauseStartDate": "2024-05-02",
        "pauseEndDate": "2024-05-03"
    }
}

Update an ongoing pause

You can update the pauseRemainingBillingCycles on an ongoing pause by sending a POST request to the /pauses to extend or reduce the pause duration.

HTTP method: POST

Endpoint: /pauses

Scenario: Update an ongoing pause (recurringProgramPauseStatusCode = PAUSE_ONGOING) to extend it by 3 billing cycles.

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "pauseRemainingBillingCycles": 3
}

Response:

Json
{
    "recurringProgramId": "xB7lAXy0vZ",
    "merchantId": "998152096536",
    "requestId": "265cc804-7994-423f-be9e-6e5d19fbbd55",
    "merchantRecurringProgramId": "xB7lAXy0vZ",
    "pauseInformation": {
        "pauseRequestedDate": "2024-05-01T00:46:55.879718Z",
        "recurringProgramPauseStatusCode": "PAUSE_ONGOING",
        "pauseBillingCyclesTotalCount": 6,
        "pauseRemainingBillingCycles": "3",
        "pauseStartDate": "2024-05-02",
        "pauseEndDate": "2024-05-07"
    }
}