Events

Events can be used to let you know when something happens in your organization. Every happening in your organization will be recorded as a new Event. For example, when a new payment is received, we will create a payment_thankyou event; when a subscription is created, we will create a subscription_created event.

You can retrieve these events individually or as a list using our API. If you want to update the data on your server when an event occurs, you can use webhooks to send these event objects directly to an endpoint on your application’s server. Learn more about webhooks.

End Points

GET

/events/{event_id}

GET

/events

Attribute

event_id

string

Unique ID generated for a particular event

event_type

string

The type of event.

event_time

string

The time at which the event is created.

payload

string

Holds information about the event that occurred.

webhooks

array

List of objects holds information about the webhooks. Each object contains webhook_id, url, status and last_updated_time.

Show Sub-Attributes

webhook_id

string

The unique ID generated for a webhook by the server. This can be used as an identifier.

url

string

The URL for which the webhook is sent.

status

string

Status of the webhook. This can be success, scheduled or failure.

last_updated_time

string

The time at which the webhook was last sent.

{
    "event_id": "90300000005337",
    "event_type": "subscription_activation",
    "event_time": "2016-06-05T18:28:20-0700",
    "payload": "{...}",
    "webhooks": [
        {
            "webhook_id": "9030000020202",
            "url": "http://gatehost/webhooks/newsubscription/add",
            "status": "success",
            "last_updated_time": "2016-07-01T20:28:20-0700"
        }
    ]
}

Retrieve an event

Details of an existing event.
OAuth Scope : ZohoSubscriptions.webhooks.READ

headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/events/90300000005337"
type: GET
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/events/90300000005337")
  .get()
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/billing/v1/events/90300000005337', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = {
    'X-com-zoho-subscriptions-organizationid': "10234695",
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
    }

conn.request("GET", "/billing/v1/events/90300000005337", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/events/90300000005337",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url https://www.zohoapis.com/billing/v1/events/90300000005337 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "success",
    "event": {
        "event_id": "90300000005337",
        "event_type": "subscription_activation",
        "event_time": "2016-06-05T18:28:20-0700",
        "payload": "{...}",
        "webhooks": [
            {
                "webhook_id": "9030000020202",
                "url": "http://gatehost/webhooks/newsubscription/add",
                "status": "success",
                "last_updated_time": "2016-07-01T20:28:20-0700"
            }
        ]
    }
}

List of events

List of all events.
OAuth Scope : ZohoSubscriptions.webhooks.READ

headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/events"
type: GET
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/events")
  .get()
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/billing/v1/events', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = {
    'X-com-zoho-subscriptions-organizationid': "10234695",
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
    }

conn.request("GET", "/billing/v1/events", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/events",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url https://www.zohoapis.com/billing/v1/events \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "success",
    "events": [
        {
            "event_id": "90300000005337",
            "event_type": "subscription_activation",
            "event_time": "2016-06-05T18:28:20-0700"
        },
        {...},
        {...}
    ]
}

Event Types

The following are the list of events that Zoho Billing currently supports.

Note: For backdated subscriptions, events will not be created for any actions that occur in a date previous than the current date.

OAuth Scope : ZohoSubscriptions.webhooks.READ

Events

subscription_created

string

Triggered when a subscription is created

trial_expiring

string

Triggered 3 days before when a subscription trial is about to expire

subscription_activation

string

Triggered when a subscription gets to Live state

subscription_ahead

string

Triggered 3 days before a subscription is about to renew

subscription_renewed

string

Triggered when a subscription is renewed

billing_date_changed

string

Triggered when the billing date for a subscription is changed

subscription_upgraded

string

Triggered when a subscription plan is upgraded from a lower to a higher plan

subscription_downgraded

string

Triggered when a subscription plan is downgraded from a higher to a lower plan

subscription_unpaid

string

Triggered when a subscription is marked as unpaid.

subscription_cancelled

string

Triggers when a subscription is cancelled.

subscription_reactivated

string

Triggered when a subscription is reactivated from the cancelled state.

subscription_cancellation_scheduled

string

Triggers when a subscription is chose to cancel at the next renewal.

subscription_move_to_free_scheduled

string

Triggers when a subscription is chosen to move to free plan at the next renewal.

subscription_expiring

string

Triggered 3 days before a subscriptions is about expire

subscription_expired

string

Triggers when a subscription is expired

subscription_deleted

string

Triggers when a subscription is deleted

invoice_created

string

Triggers when an invoice is raised

creditnote_added

string

Triggers when a credit note is added

payment_thankyou

string

Triggers when a payment for an invoice is recieved

payment_refunded

string

Triggers when a payment is refunded

payment_declined

string

Triggers when a payment for an invoice fails

card_expired

string

Triggers when a customer card is expired

card_expiring

string

Triggered 15 days before a customer card expires

card_deleted

string

Triggered when a customer card is deleted