Introduction

The "Partner API" provides partner with the ability to perform all GET operations that can be executed within the Partner Store. This API is designed using REST priniciples, ensuring that URLs are predictable and intuitive, making it straightforward to write queries and retrieve data related to your partner store. As per REST standards, the API adheres to HTTP rules, with every resource represented by a unique URL, which can be accessed via the "API Root Endpoint"

https://store.zoho.com/api/v1/partner

Getting Started

To begin using the Partner API, ensuring that the following pre-requisites are met:

A valid username and password

An authentication Token (OAuthToken)

Generating an OAuth

The Partner API uses the OAuth 2.0 protocol for authorization and authentication of API calls. To generate an OAuth token, you must first create a "Client ID" and "Client Secret" through Zoho's Self Client feature, accessible via the following URL:

https://api-console.zoho.com/

​

After obtaining your "Client ID" and "Client Secret", generate OAuth code with the necessary scopes to obtain both an access token and a refresh token. You should generate OAuth tokens with following scopes:

ZohoPayments.transactions.READ

ZohoPayments.subscriptions.READ

ZohoPayments.leads.READ

Multiple scopes can be mentioned as required.

Retrieving Access and Refresh Tokens:

To generate an access token using the authorization code, use the following "POST" request:

https://accounts.zoho.com/oauth/v2/token?code=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&grant_type=authorization_code

To retrieve an access token using the refresh token, use the following "POST" request

https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecd474019e31d52d2f94aad6c5cb7.4638677ebc14f2f2ee0b6dfb6cebdc&client_id=1000.0SRSZSY37WMZ69405H3TMYI2239V&client_secret=fb0196010f2b70df8db2a173ca2cf59388798abf&grant_type=refresh_token

The generated access token will remain valid for one hour.

Multiple Data Centres

The Partner Store is hosted across multiple data centres. When accessing the Partner API, it is crucial to use the correct domain based on your region. Below is a list of available data centres and their corresponding base API URLs:

HTTP Methods

The Partner API follows appropriate HTTP verbs for every action. However, at present, only "GET' actions are supported. In future releases, "POST" and "PUT" methods will be available to support additional actions.

Response

All responses from the Partner API will be returned in JSON format.

Error Handling:

Any errors encountered during API calls will be communicated via error messages in the response, allowing you to diagnose and resolve issues efficiently.

Pagination

The Partner API supports pagination for retreiving list of resources such as subscriptions, transactions, and leads. Each API request returns a maximum of 200 items by default, and pagination information is included in the response headers under the "has_more" node. You can navigate through pages using the 'page' parameter and control the number of records returned by using the "per_page" parameter.

API Call Limit

To ensure optimal performance and availabilty, the following limits apply to API calls

Calls per minute : A maximum of 100 API requests per minute are allowed.

Transaction Start Date: You can only retrieve transaction starting from January 1. 2019. Transactions prior to this date cannot be fetched using the API.

Subscriptions API

The Subscription API allows you to retrieve a list of all the subscriptions in your partner store with pagination. Below is an example of how to use this API

GET /subscriptions

scope : ZohoPayments.subscriptions.READ, ZohoPayments.fullaccess.READ

The following are the attributes and values that you can provide to get the subscription list.

Sample Response

The Unique ID for the Subscription API is subscription_id.

The following are the attributes and values that you will in the response.

Active Subscriptions

List all the active subscriptions with the pagination.

GET /subscriptions/status/active

Inactive Subscriptions

List all the inactive subscriptions with the pagination

GET /subscriptions/status/inactive

Specific Subscription

List the details of a specific subscription

GET /subscriptions/{subscription_id}

Example request : /subscriptions/14000000293023

Sample Response :

Transactions of a subscription

List all the transactions of a specific subscription

GET /subscriptions/{subscription_id}/transactions

The following are the attributes and values that you can provide to get the transaction list of a subscription.

Sample response for a list of transactions for a specific subscription.

The Unique ID for the Transaction API is transaction_id.

The following are the attributes and values that you will in the response.

Invoiced Transactions  of a subscription

List all the invoiced transactions of a subscription with the pagination.

GET /subscriptions/{subscription_id}/transactions/status/invoiced

The following are the attributes and values that you can use to list the invoiced transactions of a subscription.

Sample response for a invoiced transaction

Transactions API:

List all the transactions with the pagination.

scope : ZohoPayments.transactions.READ,ZohoPayments.fullaccess.READ

GET /transactions

The following are the attributes and values that you can use to list all the transactions.

Invoiced Transactions

List all the invoiced transactions

GET /transactions/status/invoiced

Specific Transaction

List the details of a specific transaction.

GET /transactions/{transaction_id}

Invoiced Transaction

List the details of a transaction with the invoiced entity, invoice amount and invoice number (if invoiced).

GET /transactions/{:transaction_id}/status/invoiced

Invoice Attachment

List the invoice attachment for a transaction.

GET /transactions/{:transaction_id}/invoice/attachment

The API call is limited to 10 requests/minute.

Leads API

List all the leads that have tagged in your partner store with the pagination.

scope : ZohoPayments.leads.READ,ZohoPayments.fullaccess.READ

GET /leads

The following are the attributes and values that you can use to list all the leads.

Sample response

The Unique ID for the Leads API is lead_id.

Details of a specific lead

List the details of a specific lead.

GET /leads/{lead_id}

Sample Request to get list of transactions using access_token

$ curl https://store.zoho.com/api/v1/partner/transactions

      -H  'Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'

Commission API

 Get the list of commissions with pagination

scope : ZohoPayments.commissions.READ,ZohoPayments.fullaccess.READ

GET /commissions

The following are the attributes and values that you can use to list all the commissions.

The pagination details will be part of the response. 

Sample response