Get subscription events

Endpoint for getting Subscription Events.

info

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

GET /api/v1/groups/{group_id}/revere_pay/{linked_account_id}/recurring/subscription/{subscription_id}/events

Query Parameters

Name	Description	Type
limit	Optional parameter to limit the number of results in the query	uint64
offset	The number of items to skip before starting to collect the result set.	uint64

Response Fields

Name	Description	Type
id	Unique identifier of the event.	string
event_type	Type of the subscription event. See Event Types below.	string
initiated_by	Who or what initiated the event. Possible values: merchant, end_user, plan, customer, recurring_system.	string
user_id	ID of the user who initiated the event, when applicable.	string
user_name	Name of the user who initiated the event, when applicable.	string
changes	The subscription fields that changed, each with their old and new value.	object
details	Additional details about the event, depending on its type.	object
created_at	Timestamp of when the event was recorded.	string

Event Types

Value	Description
created	Recorded when the subscription has been created.
updated	Recorded when the subscription has been updated.
charged	Recorded when the subscription has been successfully charged.
charge_failed	Recorded when a subscription charge attempt has failed.
completed	Recorded when the subscription has completed after its duration is exhausted.
declined	Recorded when the subscription has been declined after exceeding the maximum retry count.
canceled	Recorded when the subscription has been canceled.
cancel_scheduled	Recorded when the subscription has been scheduled to cancel at the next bill date.
paused	Recorded when the subscription has been paused.
resumed	Recorded when the subscription has been resumed after having been paused.
deleted	Recorded when the subscription has been deleted.
proration_created	Recorded when a proration event has been created for the subscription.
plan_propagated	Recorded when subscription changes have been propagated from the plan.
notification_sent	Recorded when a subscription notification has been sent.
notification_failed	Recorded when a subscription notification failed to send.

Details Fields

The details object's fields depend on the event's event_type. It is omitted entirely for event types not listed below (created, updated, canceled, paused, resumed, deleted, completed, declined, plan_propagated).

Field	Description	Populated for
amount	The monetary amount associated with the event, in cents.	charged, proration_created, charge_failed
currency	The currency of amount.	charged, proration_created, charge_failed
amount_kind	The kind of amount charged (standard, initial, proration, or trial).	charged, proration_created, charge_failed
base_amount	The base amount before any proration adjustment.	charged
prorate_amount	The proration adjustment amount included in the charge.	charged, proration_created, charge_failed
transaction_id	ID of the transaction related to the event.	charged, proration_created (when the immediate proration charge succeeds), charge_failed
proration_event_id	ID of the related proration event.	proration_created, charge_failed (when caused by a proration charge)
proration_trigger	What triggered the proration (amount_change, plan_change, resume, cancel, plan_propagation).	proration_created, charge_failed (when caused by a proration charge)
proration_behavior	The proration behavior applied (create_prorations, immediate_action).	proration_created, charge_failed (when caused by a proration charge)
credit_amount	The credit portion of the proration adjustment.	proration_created, charge_failed (when caused by a proration charge)
charge_amount	The charge portion of the proration adjustment.	proration_created, charge_failed (when caused by a proration charge)
days_remaining	Days remaining in the billing period when the proration was calculated.	proration_created, charge_failed (when caused by a proration charge)
days_in_period	Total days in the billing period used for the proration calculation.	proration_created, charge_failed (when caused by a proration charge)
error_message	The error returned by the failed charge attempt, or the failed notification send.	charge_failed, notification_failed
attempt	The current retry attempt number for the charge.	charge_failed (except when caused by a proration charge)
max_retry_count	The maximum number of charge retry attempts allowed.	charge_failed (except when caused by a proration charge)
cancel_at_date	The date the subscription is scheduled to cancel.	cancel_scheduled
notification_type	The type of notification sent.	notification_sent, notification_failed
notification_channel	The channel the notification was sent through.	notification_sent, notification_failed
notification_recipient_email	The recipient email address of the notification.	notification_sent, notification_failed
error_reason	The reason the notification failed to send.	notification_failed

Response

Code	Description
200	Success
400	Bad Request
500	Internal Error

Example Usage

JavaScript

plans.js

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

var requestOptions = {
	method: 'GET',
	headers: headers,
	redirect: 'follow'
};
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}/events?limit=10&offset=0`;
fetch(url, requestOptions)
	.then((response) => response.text())
	.then((result) => console.log(result))
	.catch((error) => console.log('error', error));

Python

plans.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+"/events?limit=10&offset=0"

headers = {
  'Authorization': 'API_KEY'
}

response = requests.request("GET", url, headers=headers)

print(response.text)

Go

plans.go

package main

import (
	"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 + "/events?limit=10&offset=0"

	client := &http.Client{}
	req, _ := http.NewRequest("GET", url, nil)
	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 Success Response

{
	"data": {
		"items": [
			{
				"id": "0f1c5e64-6b41-4a35-9a4e-2f5f0b7d1a90",
				"event_type": "declined",
				"initiated_by": "recurring_system",
				"changes": {
					"status": {
						"old": "declining",
						"new": "declined"
					}
				},
				"created_at": "2024-04-18T00:00:00Z"
			},
			{
				"id": "b2a4e6c8-1f7d-4c3e-9a5b-6d8e2f1c4a90",
				"event_type": "proration_created",
				"initiated_by": "merchant",
				"details": {
					"amount": 5714,
					"currency": "USD",
					"amount_kind": "proration",
					"prorate_amount": 5714,
					"proration_event_id": "0f1c5e64-6b41-4a35-9a4e-2f5f0b7d1a90",
					"proration_trigger": "amount_change",
					"proration_behavior": "create_prorations",
					"credit_amount": 11429,
					"charge_amount": 17143,
					"days_remaining": 4,
					"days_in_period": 7
				},
				"created_at": "2024-04-14T09:12:44.512331Z"
			},
			{
				"id": "8c2f0d51-7b13-4a2e-9f60-1d4c8b7a5e39",
				"event_type": "completed",
				"initiated_by": "recurring_system",
				"changes": {
					"status": {
						"old": "active",
						"new": "completed"
					}
				},
				"created_at": "2024-04-11T00:00:00Z"
			}
		],
		"total_count": 3
	}
}