Hosted-Pages

Zoho Billing provides a hosted payment page to integrate with your websites. You can securely integrate with Zoho Billing for collecting your customer's sensitive card information through the hosted page. These Hosted Pages will expire within one hour.

End Points

GET

/hostedpages/{hostedpage_id}

GET

/hostedpages

POST

/hostedpages/newsubscription

POST

/hostedpages/updatesubscription

POST

/hostedpages/updatecard

POST

/hostedpages/buyonetimeaddon

POST

/hostedpages/addpaymentmethod

POST

/hostedpages/invoicepayment

POST

/hostedpages/updatepaymentmethod

Retrieve a hosted page

Details of a specific hosted page. The data field will be populated with the subscription details in case of successfull subscription via Hostedpage. In case of fresh hosted pages the data field will be empty.
OAuth Scope : ZohoSubscriptions.hostedpages.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/hostedpages/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526"
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/hostedpages/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526")
  .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/hostedpages/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526', 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/hostedpages/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", 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/hostedpages/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
  "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/hostedpages/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "success",
    "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
    "status": "success",
    "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
    "action": "new_subscription",
    "expiring_time": "2016-06-05T00:11:16-0700",
    "created_time": "2016-06-05T23:10:16-0700",
    "custom_fields": [
        {
            "index": 1,
            "label": "string",
            "value": "string",
            "data_type": "string"
        }
    ],
    "data": {
        "subscription": {
            "subscription_id": "9030000079200",
            "name": "GatorHost-Basic",
            "status": "success",
            "amount": 186,
            "created_at": "2016-06-05",
            "current_term_starts_at": "2016-06-01",
            "current_term_ends_at": "2016-06-30",
            "next_billing_at": "2016-06-30",
            "expires_at": "2015-06-01",
            "interval": 1,
            "interval_unit": "months",
            "auto_collect": true,
            "created_time": "2016-06-05T23:10:16-0700",
            "updated_time": "2016-07-04T16:44:15-0700",
            "reference_id": "bowmanfurniture",
            "salesperson_id": "9877000000058001",
            "salesperson_name": "Franklin",
            "child_invoice_id": "90300000079210",
            "pricebook_id": "90300000070987",
            "currency_code": "CAD",
            "currency_symbol": "$",
            "end_of_term": false,
            "product_id": "9030000079065",
            "product_name": "Bowman Furniture",
            "plan": {
                "plan_code": "basic-monthly",
                "name": "GatorHost-Basic",
                "quantity": 1,
                "price": 20,
                "tags": [
                    {
                        "tag_id": 0,
                        "tag_option_id": 0
                    }
                ],
                "item_custom_fields": [
                    {
                        "label": "string",
                        "value": "string"
                    }
                ],
                "discount": 20,
                "total": 50,
                "setup_fee": 20,
                "description": "Monthly Basic plan.",
                "tax_id": "90300000023123"
            },
            "addons": [
                {
                    "addon_code": "Email-basic",
                    "name": "Monthly Addon",
                    "description": "Monthly Basic plan.",
                    "quantity": 1,
                    "tags": [
                        {
                            "tag_id": 0,
                            "tag_option_id": 0
                        }
                    ],
                    "item_custom_fields": [
                        {
                            "label": "string",
                            "value": "string"
                        }
                    ],
                    "price": 10,
                    "discount": null,
                    "total": null,
                    "tax_id": null
                }
            ],
            "taxes": [
                "string"
            ],
            "coupon": {
                "coupon_code": "Flat10",
                "discount_amount": 44
            },
            "card": {
                "card_id": "9030000079226",
                "last_four_digits": "2145",
                "payment_gateway": "payflow_pro",
                "expiry_month": 9,
                "expiry_year": 2030
            },
            "payment_terms": 0,
            "payment_terms_label": "Due On Receipt",
            "can_add_bank_account": true,
            "customer": {
                "customer_id": "903000000000099",
                "display_name": "Bowman Furniture",
                "first_name": "Benjamin",
                "last_name": "George",
                "email": "benjamin.george@bowmanfurniture.com",
                "company_name": "Bowman Furniture",
                "billing_address": {
                    "street": "Harrington Bay Street",
                    "city": "Salt Lake City",
                    "state": "CA",
                    "country": "U.S.A",
                    "zip": "92612",
                    "fax": "4527389"
                },
                "shipping_address": {
                    "attention": "Benjamin George",
                    "street": "Harrington Bay Street",
                    "city": "Salt Lake City",
                    "state": "CA",
                    "country": "U.S.A",
                    "zip": "92612",
                    "fax": "4527389"
                },
                "is_taxable": true,
                "tax_authority_name": "ATO",
                "tax_exemption_id": "903000006345",
                "payment_terms": 0,
                "payment_terms_label": "Due On Receipt"
            },
            "custom_fields": [
                {
                    "index": 1,
                    "label": "string",
                    "value": "string",
                    "data_type": "string"
                }
            ],
            "contactpersons": [
                {
                    "contactperson_id": "903000000000099"
                }
            ],
            "notes": [
                {
                    "note_id": "90300006700232",
                    "description": "",
                    "commented_by": "Benjamin",
                    "commented_time": "2016-06-11T17:57:13-0700"
                }
            ],
            "payment_gateways": [
                {
                    "payment_gateway": "payflow_pro"
                }
            ]
        },
        "invoice": {
            "invoice_id": "90300000079426",
            "number": "INV-384",
            "status": "success",
            "invoice_date": "2016-06-15",
            "due_date": "2016-06-15",
            "payment_expected_date": "10-05-2013",
            "ach_payment_initiated": true,
            "transaction_type": "invoice",
            "customer_id": "903000000000099",
            "customer_name": "Benjamin",
            "email": "benjamin.george@bowmanfurniture.com",
            "invoice_items": [
                {
                    "item_id": "90300000079434",
                    "name": "GatorHost-Basic",
                    "description": "Charges for this duration (from 16-April-2016 to 8-June-2016)",
                    "code": "0",
                    "price": 20,
                    "quantity": 1,
                    "discount_amount": 44,
                    "item_total": 400,
                    "tax_id": "90300000023123",
                    "tax_exemption_id": "903000006345",
                    "tax_exemption_code": "GST FREE"
                }
            ],
            "coupon": [
                {
                    "coupon_code": "Flat10",
                    "coupon_name": "Flat 10",
                    "discount_amount": 44
                }
            ],
            "credits": [
                {
                    "creditnote_id": "9030000079876",
                    "creditnotes_number": "CN-26",
                    "credited_date": "2016-06-15",
                    "credited_amount": 15
                }
            ],
            "total": 50,
            "payment_made": 370,
            "balance": 0,
            "credits_applied": 0,
            "write_off_amount": 0,
            "payments": [
                {
                    "payment_id": "9030000079467",
                    "payment_mode": "autotransaction",
                    "invoice_payment_id": "90300000079469",
                    "gateway_transaction_id": "B10E6E0F31BD",
                    "description": "Monthly Basic plan.",
                    "date": "2016-06-05",
                    "reference_number": "INV-384",
                    "amount": 186,
                    "exchange_rate": 2
                }
            ],
            "currency_code": "CAD",
            "currency_symbol": "$",
            "created_time": "2016-06-05T23:10:16-0700",
            "updated_time": "2016-07-04T16:44:15-0700",
            "salesperson_id": "9877000000058001",
            "salesperson_name": "Franklin",
            "invoice_url": "",
            "billing_address": {
                "city": "Salt Lake City",
                "state": "CA",
                "zip": "92612",
                "country": "U.S.A",
                "fax": "4527389"
            },
            "shipping_address": {
                "attention": "Benjamin George",
                "street": "Harrington Bay Street",
                "city": "Salt Lake City",
                "state": "CA",
                "country": "U.S.A",
                "zip": "92612",
                "fax": "4527389"
            },
            "comments": [
                {
                    "comment_id": "90300000003133",
                    "description": "Invoice has been marked as void",
                    "commented_by_id": "90300003002099",
                    "commented_by": "Benjamin",
                    "comment_type": "system",
                    "date": null,
                    "time": "2016-06-11T17:57:13-0700",
                    "operation_type": "add",
                    "transaction_id": "90300000079467",
                    "transaction_type": "invoice"
                }
            ],
            "custom_fields": [
                {
                    "index": 1,
                    "label": "string",
                    "value": "string",
                    "data_type": "string"
                }
            ]
        }
    }
}

List of HostedPages

Retrieve the list of all hosted pages.
OAuth Scope : ZohoSubscriptions.hostedpages.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/hostedpages"
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/hostedpages")
  .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/hostedpages', 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/hostedpages", 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/hostedpages",
  "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/hostedpages \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "success",
    "hosted_pages": [
        {
            "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
            "status": "success",
            "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
            "action": "new_subscription",
            "expiring_time": "2016-06-05T00:11:16-0700",
            "created_time": "2016-06-05T23:10:16-0700"
        },
        {...},
        {...}
    ]
}

Create a subscription

Create a hosted page for a new subscription. To create a subscription for a new customer, you have to pass the customer object. To create a subscription for a existing customer pass the customer_id of that customer.
OAuth Scope : ZohoSubscriptions.hostedpages.CREATE

Arguments

customer_id

(Required) for creating a hostedpage for existing customer.

Customer ID of the customer for whom a subscription needs to be created.

pricebook_id

string

A Pricebook that has currency same as that of the customer

customer

object

(Required) for creating a subscription for new customer.

Customer object of the customer for whom you want to create a subscription. Each object contains display_name, company_name, first_name, last_name, email, fax, currency_code and billing_address.

Show Sub-Attributes

display_name

string

(Required)

This will be name which will be displayed in the interface and invoices.

salutation

string

Salutation of the customer.

first_name

string

First name of the customer.

last_name

string

Last name of the customer.

string

(Required)

Email address of the customer.

company_name

string

Registered name of the company the customer represents.

billing_address

object

Customer's billing address object. It contains attention, street, city, state, zip, country and fax.

Show Sub-Attributes

attention

string

Attention of the customer's billing address.

street

string

Street of the customer’s billing address.

city

string

City of the customer’s billing address.

state

string

State of the customer’s billing address.

country

string

Country of the customer’s billing address.

zip

string

Zip code of the customer’s billing address.

fax

string

Fax number of the customer's billing address.

shipping_address

object

Customer's shipping address object. It contains attention, street, city, state, zip, country and fax.

Show Sub-Attributes

attention

string

Attention of the customer’s shipping address.

street

string

Street of the customer’s shipping address.

city

string

City of the customer’s shipping address.

state

string

State of the customer’s shipping address.

country

string

Country of the customer’s shipping address.

zip

string

Zip code of the customer’s shipping address.

fax

string

Fax number of the customer’s shipping address.

pricebook_id

string

A Pricebook that has currency same as that of the customer

payment_terms

integer

Payment Due details for the invoices.

payment_terms_label

string

Label for the paymet due details.

exchange_rate

double

, default is the exchange rate provided in settings.

This will be the exchange rate provided for the organization's currency and the customer's currency. The subscription fee would be the multiplicative product of the original price and the exchange rate.

currency_code

string

Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Billing organization will be used for billing. currency_id and currency_symbol are set automatically in accordance to the currency_code.

vat_treatment

string

VAT only

VAT treatment for the credit-note. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is `uk`. If the customer is in a EU country & if he is VAT registered then his VAT treatment is `eu_vat_registered`, if he resides in EU & if he is not VAT registered then his VAT treatment is `eu_vat_not_registered` and if he resides outside the EU then his VAT treatment is `non_eu`.

vat_reg_no

string

VAT only

VAT Registration number of a contact with VAT treatment as eu_vat_registered. Length should be between 2 and 12 characters. (This node is only available for EU VAT registered customers.)

country_code

string

VAT only

Two letter country code of a contact with VAT treatment as eu_vat_registered. (This node is only available for EU VAT registered customers.)

is_taxable

string

Sales Tax , GST only

Set to true if customer's transactions must be tax inclusive.

tax_id

string

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_authority_id

string

(Required)

Sales Tax only

Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.

tax_authority_name

string

(Required)

Sales Tax only

Unique name of the tax authority.

tax_exemption_id

string

Sales Tax , GST only

Unique ID of the tax exemption.

tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption.

default_templates

object

Default templates associated with the customer.

Show Sub-Attributes

invoice_template_id

string

Unique Id used to denote the invoice template.

creditnote_template_id

string

Unique Id used to denote the credit note template.

place_of_contact

string

(Required) for non composite scheme indian GST registered organization

India GST only

gst_no

string

India GST only

GSTIN Number for the customer.

gst_treatment

string

India GST only

GST Treatment for the customer.
Allowed values for gst_treatment :
business_gst, business_none, consumer, overseas
business_gst - For a GST Registered business owner.
business_none - For a GST unregistered business owner.
consumer - For a consumer.
overseas - Customer for whom you export your goods/services.

contactpersons

array

List of contact person objects. Each object contains contactperson_id and email.

Show Sub-Attributes

contactperson_id

string

(Required)

Contact person ID of the customer’s contact person.

plan

object

(Required)

Plan object for which the subscription is to be created/updated. This contains plan_code, name, price, exclude_setup_fee, quantity, exclude_setup_fee, exclude_trial, billing_cycles and trial_days.

Show Sub-Attributes

plan_code

string

(Required)

Plan code of the plan that is to be subscribed to the customer.

plan_description

string

Description of the plan exclusive to this subscription. This will be displayed in place of the plan name in invoices generated for this subscription.

price

double

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

setup_fee

double

, default is 0 only if exclude_setup_fee is true

Setup fee for the plan.

setup_fee_tax_id

string

Unique ID for tax of setup fee. setup_fee_tax_id must be empty for applying tax Exemption.

quantity

integer

Required quantity of the chosen plan.

tags

array

Show Sub-Attributes

tag_id

long

ID of the Tag

tag_option_id

long

Id of the Tag Option

item_custom_fields

array

Custom fields for a item.

Show Sub-Attributes

label

string

Label of the Custom Field

value

string

Value of the Custom Field

tax_id

(Required) for applying tax or tax exemption to a plan

Unique ID of Tax or Tax Group that must be associated with the plan. tax_id must be empty for applying tax Exemption.

tax_exemption_id

string

Sales Tax , GST only

Unique ID of the tax exemption.

tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption.

setup_fee_tax_exemption_id

string

Sales Tax , GST only

Unique Tax Exemption ID that must be applied to setup fee.

setup_fee_tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption that must be applied to setup fee.

exclude_trial

boolean

This is set to true if the respective plan's trial period needs to be excluded for this subscription.

exclude_setup_fee

boolean

This is set to true if the respective plan's setup fee needs to be excluded for this subscription.

billing_cycles

integer

billing_cycles specified at the time of creation of the plan would be the default value. If this needs to be overridden for this particular subscription, a value can be provided here.

trial_days

integer

, default is 0 only if exclude_trial is true

Number of free trial days granted to a customer subscribed to this plan. Trial days for the subscription mentioned here will override the number of trial days provided at the time plan creation. This will be applicable even if exclude_trial=true.

addons

array

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

Show Sub-Attributes

addon_code

string

(Required)

Addon code of the addon.

addon_description

string

Description of the addon exclusive to this subscription. This will be displayed in place of the addon name in invoices generated for this subscription.

price

double

quantity

Required quantity of the chosen addon.

tags

array

Show Sub-Attributes

tag_id

long

ID of the Tag

tag_option_id

long

Id of the Tag Option

item_custom_fields

array

Custom fields for a item.

Show Sub-Attributes

label

string

Label of the Custom Field

value

string

Value of the Custom Field

tax_id

(Required) for applying tax or tax exemption to a addon

Unique ID of Tax or Tax Group that must be associated with the addon. tax_id must be empty for applying tax Exemption.

tax_exemption_id

string

Sales Tax , GST only

Unique ID of the tax exemption.

tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption.

reference_id

string

A string of your choice is required to easily identify and keep track of your subscriptions.

starts_at

string

Generally the subscription will start on the day it is created. But, the date can also be a future or past date depending upon your usecase. For future dates, the subscription status would be Future till the starts_at date. And for past dates, the subscription status can be Trial, Live or Expired depending on the subscription interval that you have selected.

custom_fields

array

Additional fields for the Hosted pages.

Show Sub-Attributes

label

string

Label of the Custom Field

value

string

Value of the Custom Field

coupon_code

string

The coupon code of the coupon which is to be applied to the subscription.

redirect_url

string

It specifies the url to which the customer will be redirected after successful transaction.

salesperson_name

string

Name of tha sales person assigned for the subscription.

can_charge_setup_fee_immediately

boolean

If set to "true", a separate invoice will be raised for the setup fee as soon as the subscription's trial period starts. Set the value as "false", or remove this optional argument if you want the setup fee to be billed at the end of the trial period, along with the other subscription related charges.

exchange_rate

double

, default is the exchange rate provided in settings.

place_of_supply

string

India GST only

Place of Supply for the customer's subscription.

gst_treatment

string

India GST only

gst_no

string

India GST only

GSTIN Number for the customer.

cfdi_usage

string

🇲🇽 only

Choose CFDI Usage. Allowed values:
acquisition_of_merchandise, return_discount_bonus, general_expense, buildings, furniture_office_equipment, transport_equipment, computer_equipmentdye_molds_tools, telephone_communication, satellite_communication, other_machinery_equipment, hospital_expense, medical_expense_disability, funeral_expense, donation, interest_mortage_loans, contribution_sar, medical_expense_insurance_pormium, school_transportation_expense, deposit_saving_account, payment_educational_service, no_tax_effect, payment, payroll.

payment_gateways

array

List of payment gateways configured for the customer.

Show Sub-Attributes

payment_gateway

string

Payment gateway through which payment needs to be made.

billing_address_id

string

ID of the respective billing address

shipping_address_id

string

ID of the respective Shipping address

branch_id

string

branch under which this transaction will fall under

parameters_data='{"field1":"value1","field2":"value2"}';
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/hostedpages/newsubscription"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/hostedpages/newsubscription")
  .post(body)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

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

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/billing/v1/hostedpages/newsubscription', 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")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

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

conn.request("POST", "/billing/v1/hostedpages/newsubscription", payload, headers)

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

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

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/hostedpages/newsubscription",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

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.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/hostedpages/newsubscription \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "customer_id": null,
    "pricebook_id": "90300000070987",
    "customer": {
        "display_name": "Bowman Furniture",
        "salutation": "Mr.",
        "first_name": "Benjamin",
        "last_name": "George",
        "email": "benjamin.george@bowmanfurniture.com",
        "company_name": "Bowman Furniture",
        "billing_address": {
            "attention": "Benjamin George",
            "street": "Harrington Bay Street",
            "city": "Salt Lake City",
            "state": "CA",
            "country": "U.S.A",
            "zip": "92612",
            "fax": "4527389"
        },
        "shipping_address": {
            "attention": "Benjamin George",
            "street": "Harrington Bay Street",
            "city": "Salt Lake City",
            "state": "CA",
            "country": "U.S.A",
            "zip": "92612",
            "fax": "4527389"
        },
        "pricebook_id": "90300000070967",
        "payment_terms": 0,
        "payment_terms_label": "Due On Receipt",
        "exchange_rate": 2,
        "currency_code": "CAD",
        "vat_treatment": "non_eu",
        "vat_reg_no": 51423456782,
        "country_code": "DE",
        "is_taxable": true,
        "tax_id": "90300000023123",
        "tax_authority_id": "903000006345",
        "tax_authority_name": "ATO",
        "tax_exemption_id": "903000006345",
        "tax_exemption_code": "GST FREE",
        "default_templates": {
            "invoice_template_id": "90300000311340",
            "creditnote_template_id": "90300000232140"
        },
        "place_of_contact": "TN",
        "gst_no": "33AAAAA0000A1Z5",
        "gst_treatment": "business_gst"
    },
    "contactpersons": [
        {
            "contactperson_id": "903000000000099"
        }
    ],
    "plan": {
        "plan_code": "basic-monthly",
        "plan_description": "Monthly Basic plan",
        "price": 20,
        "setup_fee": 20,
        "setup_fee_tax_id": "9030000123123",
        "quantity": 1,
        "tags": [
            {
                "tag_id": 0,
                "tag_option_id": 0
            }
        ],
        "item_custom_fields": [
            {
                "label": "string",
                "value": "string"
            }
        ],
        "tax_id": null,
        "tax_exemption_id": "903000006345",
        "tax_exemption_code": "GST FREE",
        "setup_fee_tax_exemption_id": "9030000123098",
        "setup_fee_tax_exemption_code": "GST FREE",
        "exclude_trial": false,
        "exclude_setup_fee": false,
        "billing_cycles": -1,
        "trial_days": 0
    },
    "addons": [
        {
            "addon_code": "Email-basic",
            "addon_description": "Monthly addon.",
            "price": 20,
            "quantity": null,
            "tags": [
                {
                    "tag_id": 0,
                    "tag_option_id": 0
                }
            ],
            "item_custom_fields": [
                {
                    "label": "string",
                    "value": "string"
                }
            ],
            "tax_id": null,
            "tax_exemption_id": "903000006345",
            "tax_exemption_code": "GST FREE"
        }
    ],
    "reference_id": "bowmanfurniture",
    "starts_at": "2016-06-05",
    "custom_fields": [
        {
            "label": "string",
            "value": "string"
        }
    ],
    "coupon_code": "Flat10",
    "redirect_url": "http://www.zillum.com/products/piperhost",
    "salesperson_name": "Franklin",
    "can_charge_setup_fee_immediately": false,
    "exchange_rate": 2,
    "place_of_supply": "TN",
    "gst_treatment": "business_gst",
    "gst_no": "33AAAAA0000A1Z5",
    "cfdi_usage": "acquisition_of_merchandise",
    "payment_gateways": [
        {
            "payment_gateway": "payflow_pro"
        }
    ],
    "billing_address_id": 3002000001806,
    "shipping_address_id": 3002000001806,
    "branch_id": 3002000001806
}

{
    "code": 0,
    "message": "Hosted page has been created successfully.",
    "hostedpage": {
        "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
        "status": "success",
        "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
        "action": "new_subscription",
        "expiring_time": "2016-06-05T00:11:16-0700",
        "created_time": "2016-06-05T23:10:16-0700"
    }
}

Update a subscription

Create a hosted page for a updating a subscription.
OAuth Scope : ZohoSubscriptions.hostedpages.CREATE

Arguments

subscription_id

string

(Required)

Unique ID generated for a subscription.

plan

object

(Required)

Show Sub-Attributes

plan_code

string

(Required)

Plan code of the plan that is to be subscribed to the customer.

plan_description

string

Description of the plan exclusive to this subscription. This will be displayed in place of the plan name in invoices generated for this subscription.

price

double

setup_fee

double

, default is 0 only if exclude_setup_fee is true

Setup fee for the plan.

quantity

integer

Required quantity of the chosen plan.

tags

array

Show Sub-Attributes

tag_id

long

ID of the Tag

tag_option_id

long

Id of the Tag Option

item_custom_fields

array

Custom fields for a item.

Show Sub-Attributes

label

string

Label of the Custom Field

value

string

Value of the Custom Field

tax_id

(Required) for applying tax or tax exemption to a plan

Unique ID of Tax or Tax Group that must be associated with the plan. tax_id must be empty for applying tax Exemption.

tax_exemption_id

string

Sales Tax , GST only

Unique ID of the tax exemption.

tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption.

setup_fee_tax_exemption_id

string

Sales Tax , GST only

Unique Tax Exemption ID that must be applied to setup fee.

setup_fee_tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption that must be applied to setup fee.

exclude_trial

boolean

This is set to true if the respective plan's trial period needs to be excluded for this subscription.

exclude_setup_fee

boolean

This is set to true if the respective plan's setup fee needs to be excluded for this subscription.

billing_cycles

integer

billing_cycles specified at the time of creation of the plan would be the default value. If this needs to be overridden for this particular subscription, a value can be provided here.

trial_days

integer

, default is 0 only if exclude_trial is true

addons

array

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

Show Sub-Attributes

addon_code

string

(Required)

Addon code of the addon.

addon_description

string

Description of the addon exclusive to this subscription. This will be displayed in place of the addon name in invoices generated for this subscription.

price

double

quantity

Required quantity of the chosen addon.

tags

array

Show Sub-Attributes

tag_id

long

ID of the Tag

tag_option_id

long

Id of the Tag Option

item_custom_fields

array

Custom fields for a item.

Show Sub-Attributes

label

string

Label of the Custom Field

value

string

Value of the Custom Field

tax_id

(Required) for applying tax or tax exemption to a addon

Unique ID of Tax or Tax Group that must be associated with the addon. tax_id must be empty for applying tax Exemption.

tax_exemption_id

string

Sales Tax , GST only

Unique ID of the tax exemption.

tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption.

auto_collect

boolean

auto_collect is set to true for charging customer's card automatically.

reference_id

string

A string of your choice is required to easily identify and keep track of your subscriptions.

starts_at

string

custom_fields

array

Additional fields for the Hosted pages.

Show Sub-Attributes

label

string

Label of the Custom Field

value

string

Value of the Custom Field

coupon_code

string

The coupon code of the coupon which is to be applied to the subscription.

salesperson_name

string

Name of tha sales person assigned for the subscription.

can_charge_setup_fee_immediately

boolean

gst_treatment

string

India GST only

gst_no

string

India GST only

GSTIN Number for the customer.

cfdi_usage

string

🇲🇽 only

payment_gateways

array

List of payment gateways configured for the customer.

Show Sub-Attributes

payment_gateway

string

Payment gateway through which payment needs to be made.

exchange_rate

double

, default is the exchange rate provided in settings.

place_of_supply

string

India GST only

Place of Supply for the customer's subscription.

billing_address_id

string

ID of the respective billing address

shipping_address_id

string

ID of the respective Shipping address

branch_id

string

branch under which this transaction will fall under

redirect_url

string

It specifies the url to which the customer will be redirected after successful transaction.

parameters_data='{"field1":"value1","field2":"value2"}';
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/hostedpages/updatesubscription"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/hostedpages/updatesubscription")
  .post(body)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

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

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/billing/v1/hostedpages/updatesubscription', 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")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

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

conn.request("POST", "/billing/v1/hostedpages/updatesubscription", payload, headers)

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

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

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/hostedpages/updatesubscription",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

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.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/hostedpages/updatesubscription \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "subscription_id": "9030000079200",
    "plan": {
        "plan_code": "basic-monthly",
        "plan_description": "Monthly Basic plan",
        "price": 20,
        "setup_fee": 20,
        "quantity": 1,
        "tags": [
            {
                "tag_id": 0,
                "tag_option_id": 0
            }
        ],
        "item_custom_fields": [
            {
                "label": "string",
                "value": "string"
            }
        ],
        "tax_id": null,
        "tax_exemption_id": "903000006345",
        "tax_exemption_code": "GST FREE",
        "setup_fee_tax_exemption_id": "9030000123098",
        "setup_fee_tax_exemption_code": "GST FREE",
        "exclude_trial": false,
        "exclude_setup_fee": false,
        "billing_cycles": -1,
        "trial_days": 0
    },
    "addons": [
        {
            "addon_code": "Email-basic",
            "addon_description": "Monthly addon.",
            "price": 20,
            "quantity": null,
            "tags": [
                {
                    "tag_id": 0,
                    "tag_option_id": 0
                }
            ],
            "item_custom_fields": [
                {
                    "label": "string",
                    "value": "string"
                }
            ],
            "tax_id": null,
            "tax_exemption_id": "903000006345",
            "tax_exemption_code": "GST FREE"
        }
    ],
    "auto_collect": true,
    "reference_id": "bowmanfurniture",
    "starts_at": "2016-06-05",
    "custom_fields": [
        {
            "label": "string",
            "value": "string"
        }
    ],
    "coupon_code": "Flat10",
    "salesperson_name": "Franklin",
    "can_charge_setup_fee_immediately": false,
    "gst_treatment": "business_gst",
    "gst_no": "33AAAAA0000A1Z5",
    "cfdi_usage": "acquisition_of_merchandise",
    "payment_gateways": [
        {
            "payment_gateway": "payflow_pro"
        }
    ],
    "exchange_rate": 2,
    "place_of_supply": "TN",
    "billing_address_id": 3002000001806,
    "shipping_address_id": 3002000001806,
    "branch_id": 3002000001806,
    "redirect_url": "http://www.zillum.com/products/piperhost"
}

{
    "code": 0,
    "message": "Hosted page has been created successfully.",
    "hostedpage": {
        "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
        "status": "success",
        "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
        "action": "Update subscription",
        "expiring_time": "2016-06-05T00:11:16-0700",
        "created_time": "2016-06-05T23:10:16-0700"
    }
}

Update card for a subscription

Create hosted page for updating card information for a subscription.
OAuth Scope : ZohoSubscriptions.hostedpages.CREATE

Arguments

subscription_id

string

(Required)

Unique ID generated for a subscription.

auto_collect

boolean

auto_collect is set to true for charging customer's card automatically.

redirect_url

string

It specifies the url to which the customer will be redirected after successful transaction.

payment_gateways

array

List of payment gateways configured for the customer.

Show Sub-Attributes

payment_gateway

string

Payment gateway through which payment needs to be made.

parameters_data='{"field1":"value1","field2":"value2"}';
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/hostedpages/updatecard"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/hostedpages/updatecard")
  .post(body)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

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

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/billing/v1/hostedpages/updatecard', 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")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

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

conn.request("POST", "/billing/v1/hostedpages/updatecard", payload, headers)

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

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

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/hostedpages/updatecard",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

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.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/hostedpages/updatecard \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "subscription_id": "9030000079200",
    "auto_collect": true,
    "redirect_url": "http://www.zillum.com/products/piperhost",
    "payment_gateways": [
        {
            "payment_gateway": "payflow_pro"
        }
    ]
}

{
    "code": 0,
    "message": "Hosted page has been created successfully.",
    "hostedpage": {
        "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
        "status": "success",
        "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
        "action": "Update Card",
        "expiring_time": "2016-06-05T00:11:16-0700",
        "created_time": "2016-06-05T23:10:16-0700"
    }
}

Buy one-time addon for a subscription

Create hosted page for buying a one-time addon for a subscription.
OAuth Scope : ZohoSubscriptions.hostedpages.CREATE

Arguments

subscription_id

string

(Required)

Unique ID generated for a subscription.

addons

array

(Required)

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

Show Sub-Attributes

addon_code

string

(Required)

Addon code of the addon.

quantity

integer

Required quantity of the chosen plan.

tags

array

Show Sub-Attributes

tag_id

long

ID of the Tag

tag_option_id

long

Id of the Tag Option

item_custom_fields

array

Custom fields for a item.

Show Sub-Attributes

label

string

Label of the Custom Field

value

string

Value of the Custom Field

price

double

tax_id

(Required) for applying tax or tax exemption to a addon

Unique ID of Tax or Tax Group that must be associated with the addon. tax_id must be empty for applying tax Exemption.

tax_exemption_id

string

Sales Tax , GST only

Unique ID of the tax exemption.

tax_exemption_code

string

Sales Tax , GST only

Unique code of the tax exemption.

product_type

string

VAT only

Product type for UK Edition.

redirect_url

string

It specifies the url to which the customer will be redirected after successful transaction.

coupon_code

The coupon code of the coupon which is to be applied to the one-time addon.

cfdi_usage

string

🇲🇽 only

exchange_rate

double

, default is the exchange rate provided in settings.

payment_gateways

array

List of payment gateways configured for the customer.

Show Sub-Attributes

payment_gateway

string

Payment gateway through which payment needs to be made.

parameters_data='{"field1":"value1","field2":"value2"}';
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/hostedpages/buyonetimeaddon"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/hostedpages/buyonetimeaddon")
  .post(body)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

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

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/billing/v1/hostedpages/buyonetimeaddon', 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")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

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

conn.request("POST", "/billing/v1/hostedpages/buyonetimeaddon", payload, headers)

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

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

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/hostedpages/buyonetimeaddon",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

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.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/hostedpages/buyonetimeaddon \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "subscription_id": "9030000079200",
    "addons": [
        {
            "addon_code": "Email-basic",
            "quantity": 1,
            "tags": [
                {
                    "tag_id": 0,
                    "tag_option_id": 0
                }
            ],
            "item_custom_fields": [
                {
                    "label": "string",
                    "value": "string"
                }
            ],
            "price": 20,
            "tax_id": null,
            "tax_exemption_id": "903000006345",
            "tax_exemption_code": "GST FREE",
            "product_type": "goods"
        }
    ],
    "redirect_url": "http://www.zillum.com/products/piperhost",
    "coupon_code": null,
    "cfdi_usage": "acquisition_of_merchandise",
    "exchange_rate": 2,
    "payment_gateways": [
        {
            "payment_gateway": "payflow_pro"
        }
    ]
}

{
    "code": 0,
    "message": "Hosted page has been created successfully.",
    "hostedpage": {
        "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
        "status": "success",
        "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
        "action": "One time addon",
        "expiring_time": "2016-06-05T00:11:16-0700",
        "created_time": "2016-06-05T23:10:16-0700",
        "custom_fields": [
            {
                "index": 1,
                "value": "string",
                "label": "string",
                "data_type": "string"
            }
        ]
    }
}

Associate a Payment method for a customer

Add payment method for a customer
OAuth Scope : ZohoSubscriptions.hostedpages.CREATE

Arguments

customer_id

string

(Required)

Customer ID of the customer for whom a subscription needs to be created

redirect_url

string

It specifies the url to which the customer will be redirected after successful transaction.

payment_gateways

array

List of payment gateways configured for the customer.

Show Sub-Attributes

payment_gateway

string

Payment gateway through which payment needs to be made.

parameters_data='{"field1":"value1","field2":"value2"}';
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/hostedpages/addpaymentmethod"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/hostedpages/addpaymentmethod")
  .post(body)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

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

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/billing/v1/hostedpages/addpaymentmethod', 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")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

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

conn.request("POST", "/billing/v1/hostedpages/addpaymentmethod", payload, headers)

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

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

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/hostedpages/addpaymentmethod",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

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.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/hostedpages/addpaymentmethod \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "customer_id": "903000000000099",
    "redirect_url": "http://www.zillum.com/products/piperhost",
    "payment_gateways": [
        {
            "payment_gateway": "payflow_pro"
        }
    ]
}

{
    "code": 0,
    "message": "Hosted page has been created successfully.",
    "hostedpage": {
        "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
        "status": "success",
        "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
        "action": "Update payment method",
        "expiring_time": "2016-06-05T00:11:16-0700",
        "created_time": "2016-06-05T23:10:16-0700",
        "custom_fields": [
            {
                "index": 1,
                "value": "string",
                "label": "string",
                "data_type": "string"
            }
        ]
    }
}

Record a Invoice Payment

Create a Hosted page for recording a Invoice payment for a subscription
OAuth Scope : ZohoSubscriptions.hostedpages.CREATE

Arguments

invoice_id

string

(Required)

Unique ID generated for an invoice.

redirect_url

string

It specifies the url to which the customer will be redirected after successful transaction.

hostedpage_settings_id

string

Hostedpage Template ID for the Subscriptions

payment_gateways

array

List of payment gateways configured for the customer.

Show Sub-Attributes

payment_gateway

string

Payment gateway through which payment needs to be made.

parameters_data='{"field1":"value1","field2":"value2"}';
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/hostedpages/invoicepayment"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/hostedpages/invoicepayment")
  .post(body)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

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

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/billing/v1/hostedpages/invoicepayment', 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")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

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

conn.request("POST", "/billing/v1/hostedpages/invoicepayment", payload, headers)

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

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

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/hostedpages/invoicepayment",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

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.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/hostedpages/invoicepayment \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "invoice_id": "90300000079426",
    "redirect_url": "http://www.zillum.com/products/piperhost",
    "hostedpage_settings_id": "90300000079469",
    "payment_gateways": [
        {
            "payment_gateway": "payflow_pro"
        }
    ]
}

{
    "code": 0,
    "message": "Hosted page has been created successfully.",
    "hostedpage": {
        "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
        "status": "success",
        "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
        "action": "Invoice payment",
        "expiring_time": "2016-06-05T00:11:16-0700",
        "created_time": "2016-06-05T23:10:16-0700",
        "custom_fields": [
            {
                "index": 1,
                "value": "string",
                "label": "string",
                "data_type": "string"
            }
        ]
    }
}

Update customer payment details

Create a Hosted Payment Page to update customers card, bank account (ACH) or PayPal details
OAuth Scope : ZohoSubscriptions.hostedpages.CREATE

Arguments

card_id

string

(Required)

for card change only

Card number associated to the customer.

account_id

string

(Required)

for ACH change only

Bank account number associated to the customer for ACH payments.

paypal_id

string

(Required)

for paypal change only

PayPal account number associated to the customer.

parameters_data='{"field1":"value1","field2":"value2"}';
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/hostedpages/updatepaymentmethod"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/hostedpages/updatepaymentmethod")
  .post(body)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

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

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/billing/v1/hostedpages/updatepaymentmethod', 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")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

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

conn.request("POST", "/billing/v1/hostedpages/updatepaymentmethod", payload, headers)

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

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

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/hostedpages/updatepaymentmethod",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

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.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/hostedpages/updatepaymentmethod \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "card_id": "260400000102",
    "account_id": "410200001308",
    "paypal_id": "300200001806"
}

{
    "code": 0,
    "message": "Hosted page has been created successfully.",
    "hostedpage": {
        "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526",
        "status": "success",
        "url": "https://billing.zoho.com/hostedpage/2-8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout",
        "action": "Update payment method",
        "expiring_time": "2016-06-05T00:11:16-0700",
        "created_time": "2016-06-05T23:10:16-0700"
    }
}