Zoho Billing
Zoho Billing is a comprehensive tool from Zoho that combines invoicing, expense management, project billing, and recurring billing.
Data integration: Skyvia supports importing data to and from Zoho Billing, exporting Zoho Billing data to CSV files, replicating Zoho Billing data to relational databases, and synchronizing Zoho Billing data with other cloud apps and relational databases.
Backup: Skyvia Backup does not support Zoho Billing.
Query: Skyvia Query supports Zoho Billing.
Establishing Connection
To create a connection to Zoho Billing, sign in with Zoho and specify your Organization ID.
Getting Credentials
Organization ID
To obtain the Organization ID, perform the following actions:
- Go to Zoho Billing UI.
- Click the user name in the top right corner of the page.
-
Copy the Organization ID value.
Creating Connection
To connect to Zoho Billing, perform the following steps:
-
Click Sign In with Zoho Billing in the Connection Editor.
-
Enter your Zoho credentials.
-
Grant Skyvia the requested permission.
-
Select your Zoho Data Center if it differs from the default one. By default, it is set to US.
-
Specify the Organization Id
Additional Connection Parameters
Suppress Extended Requests
For some objects, Zoho Billing API returns only part of the fields when querying multiple records. To query values of lacking fields, Skyvia performs additional extended requests. Such API requests can be performed for each record of such an object. However, this can decrease performance and significantly increase the number of API calls used.
The additional fields are the following:
| OBJECT | FIELD |
|---|---|
| ContactPersons | Fax, Department, Designation, Skype, IsAddedInPortal, CanInvite, CommunicationPreference_IsEmailEnabled, CommunicationPreference_IsSmsEnabled, CommunicationPreference_IsWhatsappEnabled, CreatedDate, UpdatedDate |
| Coupons | CouponsetId, CouponName, IsActive, DiscountType, MaxRedemptionCount, MaxRedemptionCountPerUser, ExpiryTime, ApplyToPlans, ApplyToAddons, CreatedTimeFormatted, CouponCodes, MinimumOrderValue |
| CreditNotes | CreditnoteItems, LineItems |
| Customers | Salutation, BillingAddress*, ShippingAddress*, Twitter, Facebook, Skype, CustomFields, PrimaryContactpersonId, CanAddCard, CanAddBankAccount, Notes* |
| Events | Payload, Webhooks |
| Products | ProductDigest, ItemsAssociated, AutonumberEnabled, PrefixString, NextNumber, UpdatedDate |
| UnbilledCharges | UnbilledChargeItems, Coupons |
You can select the Suppress Extended Requests checkbox to reduce the number of API calls.
Skyvia sends additional web requests when querying custom fields. Custom fields are unavailable when querying with the selected Suppress Extended Requests checkbox. Unselect the Suppress Extended Requests checkbox to query custom fields.
Connector Specifics
Object Peculiarities
Objects with Complex Structure
The following Zoho Billing objects contain text fields in JSON array format:
| Object | Fields |
|---|---|
| Plans | Tags, Addons |
| Customers | Tags, Documents |
| Addons | PriceBrackets, Tags, Plans, ItemTaxPreferences |
| Coupons | Plans, Addons |
| Invoices | InvoiceItems, Coupons, Credits, Payments, Comments, Documents |
| Subscriptions | Addons, Taxes, ContactPersons, Notes, PaymentGateways |
| Payments | Invoices |
| UnbilledCharges | UnbilledChargeItems, Coupons |
| CreditNotes | CreditnoteItems, Invoices, Taxes |
| Events | Webhooks |
You can use our Nested Objects mapping feature in the Import integrations to insert or update the nested values in such fields. Select the Nested Objects checkbox in Import to enable this feature.
Subscriptions
If you insert subscription records for the existing customer, map the CustomerId field.
If a customer doesn’t exist, map the fields with the Customer* prefixes in the names.
The UPDATE operation requires mapping the Card_CardId field.
Addons
The PriceBrackets object stores an array of nested fields that are required for mapping. Requirements change based on the PricingScheme field value.
| PricingScheme | PriceBrackets fields required for mapping | PriceBrackets fields you should not map |
|---|---|---|
| Volume | Price, StartQuantity, EndQuantity | |
| Tier | Price, StartQuantity, EndQuantity | |
| Package | Price, EndQuantity | StartQuantity |
| Unit | Price | StartQuantity, EndQuantity |
StartQuantity, and EndQuantity fields will have null values if you map them when the PricingScheme equals Package or Unit. In this case, marking them for mapping may cause an “Invalid value passed for start_quantity” error. To avoid it, create a separate Import Task for each PricingScheme.
CustomFields
Skyvia supports custom fields for the following objects Plans, Customers, Addons, Invoices, Subscriptions, Payments, CreditNotes.
Custom fields may have the following types:
| Zoho Billing Data Type | DbType |
|---|---|
| String, Email, Url, Phone, Autonumber, Dropdown, Multiselect, Multiline | String |
| Date | Date |
| Date_time | DateTime |
| Check_box | Boolean |
| Number, Lookup | Int64 |
| Decimal | Decimal |
| Percent | Double |
| Amount | In Zoho Billing UI such field value contains currency and the amount itself. Skyvia represents such custom fields by two separate objects of Double and String types. For example, the Amount custom field value looks like UAH595.59. In the connector it is represented by the String field with value UAH595.59 and Double field with value 595.59. |
| Attachment | Int64. Custom field of the Attachment type contains the Id of the corresponding record in the Document object. You should add record to the Documents object first. Then you can use this Documents record Id as a value for custom fields of the Attachment type. |
Incremental Replication and Synchronization
Skyvia supports Replication with Incremental Updates for the Addons, Cards, ContactPersons, Coupons, CreditNotes, Customers,Documents, Plans, Products, Subscriptions, Taxes, UnbilledCharges, Invoices.
Skyvia supports Synchronization for the objects ContactPersons, Customers, Products, Subscriptions.
DML Operations Support
| Operation | Object |
|---|---|
| INSERT, UPDATE, DELETE | Addons, ContactPersons, Coupons, Customers, Payments, Plans, Products, Subscriptions |
| INSERT, DELETE | CreditNotes, Documents |
| DELETE | Cards, UnbilledCharges |
Stored Procedures
Skyvia represents part of the supported Zoho Billing features as stored procedures. You can call a stored procedure, for example, as a text of the command in the ExecuteCommand action in a Target component of a Data Flow or in Query.
ConvertInvoiceToOpen
The following command changes the status of the invoice to open.
call ConvertInvoiceToOpen(:invoice_id)
VoidAnInvoice
The following command marks an invoice status as void.
call VoidAnInvoice(:invoice_id)
EmailAnInvoice
The following command sends an invoice in an email.
call EmailAnInvoice(:invoice_id, :to_mail_ids, :cc_mail_ids, :subject, :body)
| Parameter | Description |
|---|---|
| Invoice_id | The invoice identifier |
| To_mail_ids | The recipients’ email addresses in array format. For example, ["jone.smith@somedomain.com", "jane.smith@somdomain.com"] |
| Cc_mail_ids | The email addresses to send invoice copies to in array format. For example, ["jone.smith@somedomain.com", "jane.smith@somdomain.com"] |
| Subject | The email subject |
| Body | The message body |
CollectChargeViaBankAccount
The following command charges a customer for an invoice using an existing bank account.
call CollectChargeViaBankAccount(:invoice_id, :account_id)
WriteOffInvoice
The following command writes off an invoice.
call WriteOffInvoice(:invoice_id)
CancelWriteOff
The following command cancels the write-off amount of an invoice.
call CancelWriteOff(:invoice_id)
CancelSubscription
Use the following command to cancel the subscription.
call CancelSubscription(:subscription_id, :cancel_at_end)
You can cancel your subscription immediately or at the end of the current term based on the value of the cancel_at_end parameter.
If the cancel_at_end is set to true, then the subscription status is changed to non_renewing, and if it is false, the status would be canceled.
ReactivateSubscription
Use the following command to reactivate a subscription that currently has non-renewing status.
сall ReactivateSubscription(:subscription_id)
ApplyCouponToSubscription
The following command applies a coupon to an existing subscription.
call ApplyCouponToSubscription(:subscription_id, :coupon_id)
RemoveCouponFromSubscription
To remove the coupon associated with a subscription, use the following command.
call RemoveCouponFromSubscription(:subscription_id)
UpdateCustomerCardDetails
Use the following command to update the card details of a customer. Once updated, the past card will no longer be charged.
call UpdateCustomerCardDetails(:subscription_id, :card_id, :auto_collect)
RemoveCardFromSubscription
To delete a card associated with the subscription, use the following command. The subscription will become an offline subscription.
call RemoveCardFromSubscription(:subscription_id)
ConvertUnbilledChargeToInvoice
The following command converts unbilled charges to an invoice manually instead of waiting for the next renewal.
call ConvertUnbilledChargeToInvoice(:unbilled_charge_id)
EmailCreditNote
The following command sends a credit note in an email.
call EmailCreditNote(:creditnote_id, :to_mail_ids, :cc_mail_ids, :subject, :body)
| Parameter | Description |
|---|---|
| Creditnote_id | The credit note identifier |
| To_mail_ids | The recipients’ email addresses in array format. For example, ["jone.smith@somedomain.com", "jane.smith@somdomain.com"] |
| Cc_mail_ids | The email addresses to send credit note copy to in array format. For example, ["jone.smith@somedomain.com", "jane.smith@somdomain.com"] |
| Subject | The email subject |
| Body | The message body |
VoidCreditNote
The following command marks credit note status as void.
call VoidCreditNote(:creditnote_id)
OpenVoidedCreditNote
To convert a voided credit note to open, use the following command.
call OpenVoidedCreditNote(:creditnote_id)
Supported Actions
Skyvia supports all the common actions for Zoho Billing.