n8n-nodes-zoho-billing

n8n community node for Zoho Billing (Subscriptions/Plans/Addons/Coupons APIs) using OAuth2 with refresh-token handling delegated to n8n.

OAuth2 behavior

• Credential extends oAuth2Api
• Authentication calls use this.helpers.requestOAuth2('zohoBillingOAuth2Api', ...)
• No manual refresh-token logic is implemented in node code
• authQueryParameters=access_type=offline
• authentication=body

Base URL resolution order

1. Credential override: Billing API Base URL
2. oauthTokenData.api_domain from OAuth token data
3. Fallback derived from selected regional OAuth URL (authUrl / accessTokenUrl)

Requests are built as {resolvedBaseUrl}/billing/v1{endpoint}.

Official references used per implemented operation

Platform and auth/base rules

• Zoho Billing Introduction (API root endpoint, multi-data-center domains, org header):
  • https://www.zoho.com/billing/api/v1/introduction/

Organization loadOptions

• List organizations:
  • https://www.zoho.com/billing/api/v1/organizations/#list-organizations
  • Endpoint: GET /organizations
  • Scope: ZohoSubscriptions.settings.READ

Subscription operations (implemented)

Source: official Zoho Billing Subscriptions OpenAPI document (subscription.yml) downloaded from vendor documentation.

Ambiguity note: the public page URL https://www.zoho.com/billing/api/v1/subscriptions/ returned a 404 from this environment during implementation, so operation details were taken from a vendor-downloaded subscription.yml provided from that documentation page. No endpoints were inferred.

• Get Many:
  • paths./subscriptions.get
  • Endpoint: GET /subscriptions
  • Query params used: customer_id, reference_contains, filter_by, page, per_page
  • Scope: ZohoSubscriptions.subscriptions.READ
• Get:
  • paths./subscriptions/{subscription_id}.get
  • Endpoint: GET /subscriptions/{subscription_id}
  • Scope: ZohoSubscriptions.subscriptions.READ
• Update:
  • paths./subscriptions/{subscription_id}.put
  • Endpoint: PUT /subscriptions/{subscription_id}
  • Scope: ZohoSubscriptions.subscriptions.UPDATE
• Cancel:
  • paths./subscriptions/{subscription_id}/cancel.post
  • Endpoint: POST /subscriptions/{subscription_id}/cancel
  • Query param used: cancel_at_end
  • Scope: ZohoSubscriptions.subscriptions.CREATE
• Reactivate:
  • paths./subscriptions/{subscription_id}/reactivate.post
  • Endpoint: POST /subscriptions/{subscription_id}/reactivate
  • Scope: ZohoSubscriptions.subscriptions.CREATE

Plan operations (implemented)

Source: official Zoho Billing Subscriptions OpenAPI document (subscription.yml) downloaded from vendor documentation.

• Create:
  • paths./plans.post
  • Endpoint: POST /plans
• Get Many:
  • paths./plans.get
  • Endpoint: GET /plans
• Get:
  • paths./plans/{plan_code}.get
  • Endpoint: GET /plans/{plan_code}
• Update:
  • paths./plans/{plan_code}.put
  • Endpoint: PUT /plans/{plan_code}

Addon operations (implemented)

Source: official Zoho Billing Subscriptions OpenAPI document (subscription.yml) downloaded from vendor documentation.

• Create:
  • paths./addons.post
  • Endpoint: POST /addons
• Get Many:
  • paths./addons.get
  • Endpoint: GET /addons
• Get:
  • paths./addons/{addon_code}.get
  • Endpoint: GET /addons/{addon_code}
• Update:
  • paths./addons/{addon_code}.put
  • Endpoint: PUT /addons/{addon_code}

Coupon operations (implemented)

Source: official Zoho Billing Subscriptions OpenAPI document (subscription.yml) downloaded from vendor documentation.

• Create:
  • paths./coupons.post
  • Endpoint: POST /coupons
• Get Many:
  • paths./coupons.get
  • Endpoint: GET /coupons
• Get:
  • paths./coupons/{coupon_code}.get
  • Endpoint: GET /coupons/{coupon_code}
• Update:
  • paths./coupons/{coupon_code}.put
  • Endpoint: PUT /coupons/{coupon_code}

Trigger operations (implemented)

Source: official Zoho Billing Events OpenAPI document (events.yml) downloaded from vendor documentation.

• Webhook event taxonomy used for local filtering:
  • x-additionalInfo.Event Types
• Webhook delivery behavior reference:
  • info.description (states events can be sent directly to an endpoint using webhooks)
  • https://www.zoho.com/billing/help/settings/automation.html

Implemented trigger node: Zoho Billing Trigger (webhook receiver).
The node receives webhook callbacks on an n8n webhook URL and can filter events by documented event types.

Note on API management endpoints: the provided events.yml includes only read endpoints (GET /events and GET /events/{event_id}) and does not define webhook create/update/delete management endpoints, so webhook registration is expected to be configured in Zoho Billing automation settings.

Header behavior

For subscription and event trigger operations, the header below is sent exactly as documented:

• X-com-zoho-subscriptions-organizationid: {organizationId}

The node loads organization IDs dynamically using GET /organizations.