Proration preview

Endpoint for previewing the proration of a Subscription change. Nothing is saved and no money moves, the response only shows what the change would produce. See Proration for the rules behind the numbers.

info

Please be aware that this endpoint requires a Manage Transactions API Key.

POST /api/v1/groups/{group_id}/revere_pay/{linked_account_id}/recurring/subscription/{subscription_id}/proration-preview

Request Parameters

Every parameter is optional. An omitted parameter falls back to the current value of the Subscription.

Name	Description	Type	Required
amount	The recurring amount you plan to set on the Subscription.	uint64
initial_amount	The initial amount you plan to set on the Subscription.	uint64
proration_behavior	Behavior to preview with. Possible values: none, create_prorations, immediate_action. If it is omitted, the Plan's proration_behavior is used.	string
billing_cycle	The billing cycle you plan to set. A changed billing cycle makes proration impossible, the response comes back with the reason in error.	string
billing_factor	The billing factor you plan to set. A changed billing factor makes proration impossible, the response comes back with the reason in error.	uint64

Response Fields

Name	Description
proration_behavior	The behavior the preview was calculated with, after the Plan fallback was resolved.
change_date	The date the change would be applied on.
billing_period_start	Start of the current billing period.
billing_period_end	End of the current billing period, the next bill date.
days_in_period	Number of days in the current billing period.
days_remaining	Number of days left from the current billing period.
old_amount	The amount the current period was billed with.
new_amount	The amount you would set.
credit_amount	The unused part of old_amount.
charge_amount	The same remaining part of new_amount.
net_amount	charge_amount minus credit_amount. Positive means the customer owes, negative means the customer is credited.
immediate_charge_amount	The part of net_amount that would be charged right away. Only filled for immediate_action with a positive net_amount.
currency	Currency of the Subscription.
current_customer_balance	The Customer's pending proration balance before the change. If the Subscription has no Customer, only its own pending adjustments are counted.
resulting_customer_balance	The Customer's pending proration balance after the change.
error	Present only when the change cannot be prorated. It holds the reason, and every calculated amount stays zero.

Response

Code	Description
200	Success
400	Bad Request / Validation error
500	Internal Error

Example Usage

JavaScript

proration-preview.js

var headers = new Headers();
headers.append('Authorization', 'API_KEY');

var requestOptions = {
	method: 'POST',
	headers: headers,
	redirect: 'follow',
	body: {
		// request body data
	}
};
const group_id = '';
const linked_account_id = '';
const subscription_id = '';
const url = `https://api.reverepayments.dev/api/v1/groups/${group_id}/revere_pay/${linked_account_id}/recurring/subscription/${subscription_id}/proration-preview`;
fetch(url, requestOptions)
	.then((response) => response.text())
	.then((result) => console.log(result))
	.catch((error) => console.log('error', error));

Python

proration-preview.py

import requests

group_id = ""
linked_account_id = ""
subscription_id = ""
url = "https://api.reverepayments.dev/api/v1/groups/" + group_id + "/revere_pay/" + linked_account_id + "/recurring/subscription/" + subscription_id + "/proration-preview"

headers = {
  'Authorization': 'API_KEY'
}

response = requests.request("POST", url, headers=headers, json={
// request body data
})

print(response.text)

Go

proration-preview.go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {

	const group_id = ""
	const linked_account_id = ""
	const subscription_id = ""

	url := "https://api.reverepayments.dev/api/v1/groups/" + group_id + "/revere_pay/" + linked_account_id + "/recurring/subscription/" + subscription_id + "/proration-preview"

	client := &http.Client{}
	body := bytes.NewBuffer(nil)
	_ = json.NewEncoder(body).Encode(map[string]any{
		// body data
	})
	req, _ := http.NewRequest("POST", url, body)
	req.Header.Add("Authorization", "API_KEY")
	res, _ := client.Do(req)
	defer res.Body.Close()
	bytes, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err.Error())
		return
	}
	fmt.Println(string(bytes))
}

Example Request

{
	"amount": 5000,
	"proration_behavior": "create_prorations"
}

Example Success Response

{
	"data": {
		"proration_behavior": "create_prorations",
		"change_date": "2026-06-13T00:00:00Z",
		"billing_period_start": "2026-05-31T00:00:00Z",
		"billing_period_end": "2026-06-30T00:00:00Z",
		"days_in_period": 30,
		"days_remaining": 18,
		"old_amount": 2000,
		"new_amount": 5000,
		"credit_amount": 1200,
		"charge_amount": 3000,
		"net_amount": 1800,
		"immediate_charge_amount": 0,
		"currency": "USD",
		"current_customer_balance": 0,
		"resulting_customer_balance": 1800
	}
}