Subscriptions
A subscription enables you to charge customers at specified intervals for a plan of their choice.
Attribute
live
, trial
, dunning
, unpaid
, non_renewing
, cancelled
, creation_failed
, cancelled_from_dunning
, expired
, trial_expired
or future
.billing_cycle
is set for a plan. A subscription expires on the last day of the last billing cycle.months
or years
. For interval=2 and interval_unit=months, the customer is billed every two months.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.end_of_term
is set to false. If end_of_term
is set to true, the subscription changes take effect only after the current term of the subscription ends.plan_code
, name
, price
, quantity
.exclude_setup_fee
is true
is_taxable
is true
.exclude_trial
is true
addon_code
, name
, price
and quantity
.coupon_code
and discount_amount
applied to the invoice total.payment_gateway
, last_four_digits
, expiry_month
and expiry_year
.test_gateway
, payflow_pro
, stripe
, 2checkout
, authorize_net
, payments_pro
, forte
, worldpay
, wepay
.display_name
, company_name
, first_name
, last_name
, email
, fax
, currency_code
and billing_address
.attention
, street
, city
, state
,zip
, country
and fax
.attention
, street
, city
, state
,zip
, country
and fax
.is_taxable
is true
.contactperson_id
.note_id
, description
, commented_by
and commented_time
test_gateway
, payflow_pro
, stripe
, 2checkout
, authorize_net
, payments_pro
, forte
, worldpay
, wepay
.Create a subscription
Create 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.subscriptions.CREATE
Arguments
display_name
, company_name
, first_name
, last_name
, email
, fax
, currency_code
and billing_address
.attention
, street
, city
, state
,zip
, country
and fax
.attention
, street
, city
, state
,zip
, country
and fax
.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.uk
. If the customer is in an EU country & VAT registered, you are resides in Northen Ireland and selling Goods then his VAT treatment is eu_vat_registered
, if he resides outside of the UK then his VAT treatment is overseas
(For Pre Brexit, this can be split as eu_vat_registered
, eu_vat_not_registered
and non_eu
).eu_vat_registered
. (This node is only available for EU VAT registered customers.)is_taxable
is true
.contactperson_id
.auto_collect
is true
plan_code
, name
, price
, quantity
.exclude_setup_fee
is true
setup_fee_tax_id
must be empty for applying tax Exemption.tax_id
must be empty for applying tax Exemption.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.exclude_trial
is true
addon_code
, name
, price
and quantity
.tax_id
must be empty for applying tax Exemption.test_gateway
, payflow_pro
, stripe
, 2checkout
, authorize_net
, payments_pro
, forte
, worldpay
, wepay
.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
.auto_collect
node is true and any other payment method is not specified
List all subscriptions
List of subscriptions that match the given subscription status.
To list the subscriptions of a particular customer append a param customer_id={customer_id}
.
To list subscriptions based on Reference#, append the param reference_contains={reference_value}
.
OAuth Scope : ZohoSubscriptions.subscriptions.READ
Query Parameters
All
, ACTIVE
, LIVE
, FUTURE
, TRIAL
, PAST_DUE
, UNPAID
, NON_RENEWING
, CANCELLED_FROM_DUNNING
, CANCELLED
, EXPIRED
, TRIAL_EXPIRED
, CANCELLED_LAST_MONTH
, CANCELLED_THIS_MONTH
. To list subscriptions based on Online/Offline, pass the
filter_by
param value as SubscriptionMode.ONLINE
or SubscriptionMode.OFFLINE
. Update a subscription
Update details of an existing subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.UPDATE
Arguments
auto_collect
is true.
plan_code
, name
, price
, quantity
.exclude_setup_fee
is true
tax_id
must be empty for applying tax Exemption.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.exclude_trial
is true
addon_code
, name
, price
and quantity
.tax_id
must be empty for applying tax Exemption.end_of_term
is set to false. If end_of_term
is set to true, the subscription changes take effect only after the current term of the subscription ends.contactperson_id
.test_gateway
, payflow_pro
, stripe
, 2checkout
, authorize_net
, payments_pro
, forte
, worldpay
, wepay
.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
.auto_collect
node is true and any other payment method is not specified
Retrieve a subscription
Details of an existing subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.READ
Delete a subscription
Delete an existing subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.DELETE
Cancel a subscription
Your subscription can be either cancelled immediately or at the end of the current term based on the value of `cancel_at_end`.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Query Parameters
Reactivate subscription
Reactivate a subscription. You can reactivate a subscription only if the `status` of the subscription is non-renewing.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
View Scheduled Changes
To view the End of Term changes.
OAuth Scope : ZohoSubscriptions.subscriptions.READ
Subscription Activities
List of all the recent activities associated to a subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.READ
Buy one-time addon
Include a one-time addon in the subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
addon_code
, name
, price
and quantity
.tax_id
must be empty for applying tax Exemption.Associate a coupon
Apply a coupon to a subscription which has been already created.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Remove a coupon
To remove coupon associated with a subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.DELETE
Update Card
Update the card details of a customer. Once updated, the past card will no longer be charged.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
auto_collect
node is true and any other payment method is not specified
Remove Card
Delete a card associated with the subscription. The subscription will become an offline subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.DELETE
Add Charge
Charge a one-time amount for the subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Add contact person
Associate a contact person with the subscription. Only an existing contact person can be associated.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
contactperson_id
.Postpone renewal
A subscription renewal date (billing date) can be postponed thereby extending the subscription term. Also, subscription renewal can only be postponed and not preponed.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Add/Edit description for a item in line items list
Add/Edit description to a particular plan or addon in the line items list.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Change to Online/Offline mode
Change the status of a particular subscription to Online/Offline mode. If auto_collect
is false, the subscription is in Offline mode. If auto_collect
is true, the subscription is in Online mode.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Update Reference
Update reference id to easily identify and keep track of your subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Update Sales Person
Update a sales person associated with a particular subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Update Custom Fields
Update the custom fields associated with a particular subscription.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Add a note
Notes related to the subscription can be added by the user at anytime.
OAuth Scope : ZohoSubscriptions.subscriptions.CREATE
Arguments
Delete a note
Delete a specific note.
OAuth Scope : ZohoSubscriptions.subscriptions.DELETE