Zoho Billing

  • Published on Sep 5, 2024
  • 4 minute(s) read
Prev Next

Zoho Billing API

API Documentation Link

Configuration Parameters

Any instance where an entry in the below configuration has a leading $ represents a parameter that needs to be replaced with a static value.

Parameters in this document:

  • $base_url - The Base URL will follow the below format:
    Data Center Base URL
    United States https://www.zohoapis.com
    Europe https://www.zohoapis.eu
    India https://www.zohoapis.in
    Australia https://www.zohoapis.com.au
    Japan https://www.zohoapis.jp
    Canada https://www.zohoapis.ca
  • $client_id and $client_secret - The Client ID and Client Secret will be used to authenticate calls to the Zoho Billing API. To obtain these parameters, you will need to register an application with Zoho's Developer Console by clicking Add Client ID. When registering, be sure to include https://platform.panoply.io/sources/callback.html as an Authorized Redirect URI. After completing the registration of your client, you will receive a Client ID and Client Secret. For a complete walkthrough of the Zoho Billing OAuth2.0 process, see Zoho documentation here.
  • $organization_id - The Organization ID is a unique identifier for your Zoho Billing organization. This value can be found by logging into your Zoho Billing account and selecting the dropdown on your Account Name in the upper-righthand corner.
  • $zoho_subscriptions_organizationid - The Zoho Billing Subscriptions Organization ID represents the unique identifier for your Zoho business. To obtain this value, you will need to do the following:
    • Login to the Zoho Billing Admin Console
    • Click the dropdown on the Organization's name
    • Click Manage Organizations
  • $resource_name - The Resource Name represents the name of the resource to be appended and used as part of the Destination Table name. The value that should be used here can be found in the API Resources table below.
  • $endpoint - The Endpoint represents the data that you would like to ingest into Panoply from the Zoho Billing API. The value of this parameter can be found in the API Resources section below.
  • $data_key - The Data Key represents the location of the data in the API response from Zoho Billing. The value that should be used here can be found in the API Resources table below.
  • $scope - The Scope represents the permission-level that is granted to a set of credentials, thus granting them access to different API endpoints. The value that should be used here can be found in the API Resources table below. If applying multiple scopes to a single Authentication process, each value will need to be comma-separated.
  • $primary_key - Primary Keys are used to ensure the uniqueness of the rows in a table. The Primary Key is comprised of one or more columns that can be used to identify the row in the data warehouse. The process guarantees that no two rows have the same value in their primary key. The value that should be used here can be found in the API Resources table below.
  • $auth_base_url - The Base URL will follow the below format:
    Data Center Base URL
    United States https://accounts.zoho.com
    Europe https://accounts.zoho.eu
    India https://accounts.zoho.in
    Australia https://accounts.zoho.com.au
    Japan https://accounts.zoho.jp
    Canada https://accounts.zohocloud.ca
  • $incremental_starting_value - The Incremental Starting Value represents the earliest date that data should be collected for, given in yyyy-mm-DD format. For example, if you would like your historical data to go back to the start of 2021, this value would be set to 2021-01-01.

API Resources

For a list of API Resources available for Zoho Billing, please refer to the list of endpoints found below:

Resource $resource_name $endpoint $data_key $scope $primary_key
Addons addons addons addons ZohoSubscriptions.addons.READ {addon_code}
Coupons coupons coupons coupons ZohoSubscriptions.coupons.READ {coupon_code}
Customers customers customers customers ZohoSubscriptions.customers.READ {customer_id}
Events events events events ZohoSubscriptions.webhooks.READ {event_id}
Expenses expenses expenses expenses ZohoSubscriptions.expenses.READ {expense_id}
Hosted Pages hosted_pages hostedpages hosted_pages ZohoSubscriptions.hostedpages.READ {hostedpage_id}
Invoices invoices invoices invoices ZohoSubscriptions.invoices.READ {invoice_id}
Items items items items ZohoSubscriptions.items.READ {item_id}
Plans plans plans plans ZohoSubscriptions.plans.READ {plan_code}
Products products products products ZohoSubscriptions.products.READ {product_id}
Projects projects projects projects ZohoSubscriptions.projects.READ {project_id}
Quotes estimates estimates estimates ZohoSubscriptions.quotes.READ {estimate_id}
Recurring Expenses recurring_expenses recurringexpenses recurring_expenses ZohoSubscriptions.expenses.READ {recurring_expense_id}
Subscriptions subscriptions subscriptions subscriptions ZohoSubscriptions.subscriptions.READ {subscription_id}
Tasks tasks tasks tasks ZohoSubscriptions.projects.READ {task_id}
Time Entries time_entries timeentries time_entries ZohoSubscriptions.projects.READ {time_entry_id}

Connector configuration

  • Base url: $base_url / billing/v1/$endpoint
  • Method: GET
  • Headers: {"X-com-zoho-subscriptions-organizationid":"{organization_id}"}
  • URL Parameters: per_page=200

In addition to page_size, the below URL Parameter should be included if you are using either the Expenses or Time Entries endpoints. This will be required for incremental collections, and therefore must be included.

  • Expenses: date_after={incval}
  • Time Entries: from_date={incval}
Additional URL Parameters

In addition to the per_page URL Parameter, additional URL Parameters can be provided as part of the URL Parameters entry to further specify the API call and impact the response that is ultimately ingested into Panoply. Additional URL Parameters can be found on each page linked in the API Resources table under the Query Parameters section of a given page. Each Additional URL Parameter should be appended using a & separator, such as per_page=200&filter_by=ALL.

  • Headers: {"X-com-zoho-subscriptions-organizationid":"$zoho_subscriptions_organizationid"}

Destination Table naming convention is ultimately up to you as the data owner. One common structure used for this API is zoho_billing_$resource_name.

Authorization

  • Authorization: OAuth2
  • Authorization URL: $auth_base_url/oauth/v2/auth?access_type=offline
  • Access Token URL: $auth_base_url/oauth/v2/token
  • Client Id: {client_id}
  • Client Secret: {client_secret}
  • Scope: $scope
  • Access Token header key: Zoho-oauthtoken
  • Token prefix: Bearer
  • Add to: Headers
    • Refresh access token
      • Enable: Checkbox.png
      • Refresh Token URL: $base_url/oauth/v2/token
      • Access token response key: access_token
      • Error status codes: 401; 403

Variables

  • Variables:
Variable name Variable value
organization_id $organization_id
  • Secured Variables:
Variable name Variable value
client_id $client_id
client_secret $client_secret

Pagination

  • Get next page value: Static (integer to be incremented)
  • Start page: 1
  • Page step: 1
  • Use next page value: As a URL parameter value
  • URL/body key: page
  • Stop iterating when: Stop key-value pair in response
  • Key in response: page_context.has_more_pages
  • Value in response: false

Advanced Settings

  • Disable configuration validation: Checkbox.png
  • Data key: $data_key
  • Primary Key: $primary_key
Incremental Key

The Incremental Key is only applicable to the Expenses and Time Entries endpoints:

Column name Column value
lastTimeSucceed $incremental_starting_value