# Create Subscription — Zoho Billing

> Create a new subscription. See the documentation

- Key: `zoho_subscriptions-create-subscription`
- Type: Action (Write)
- Version: 0.0.3
- App: Zoho Billing (`zoho_subscriptions`) — https://pipedream.com/apps/zoho-subscriptions.md
- This page (HTML): https://pipedream.com/apps/zoho-subscriptions/actions/create-subscription
- Hints: open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/zoho_subscriptions/actions/create-subscription/create-subscription.mjs

## Description

Create a new subscription. [See the documentation](https://www.zoho.com/billing/api/v1/subscription/#create-a-subscription)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `organizationId` | `string` | Yes | The Id of the organization you want to manage. Options are loaded from the connected account. |
| `addToUnbilledCharges` | `boolean` | No | When the value is given as true, the subscription would be created and charges for the current billing cycle will be put as unbilled. This can be converted to invoice at any later point of time. |
| `customerId` | `string` | Yes | Customer ID of the customer for whom a subscription needs to be created. Options are loaded from the connected account. |
| `paymentTerms` | `integer` | No | Payment Due details for the invoices. |
| `paymentTermsLabel` | `string` | No | Label for the paymet due details. |
| `customFields` | `object` | No | Additional fields for the invoices. |
| `contactpersons` | `string[]` | No | List of contact person Id. Options are loaded from the connected account. |
| `cardId` | `string` | No | Enter the card Id of the card which is to be updated. Options are loaded from the connected account. |
| `startsAt` | `string` | No | 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. Format: 0000-00-00 |
| `exchangeRate` | `string` | No | 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. |
| `placeOfSupply` | `string` | No | Place of Supply for the customer's subscription. India GST only. |
| `planCode` | `string` | Yes | Plan code of the plan that is to be subscribed to the customer. Options are loaded from the connected account. |
| `planDescription` | `string` | No | 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` | `string` | No | 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. |
| `setupFee` | `string` | No | Setup fee for the plan. |
| `setupFeeTaxId` | `string` | No | Unique ID for tax of setup fee. Setup Fee Tax Id must be empty for applying tax Exemption. |
| `itemCustomFields` | `object` | No | Custom fields for an item. |
| `quantity` | `integer` | No | Required quantity of the chosen plan. |
| `taxId` | `string` | No | Unique ID of Tax or Tax Group that must be associated with the plan. tax_id must be empty for applying tax Exemption. |
| `taxExemptionId` | `string` | No | Unique ID of the tax exemption. GST only |
| `taxExemptionCode` | `string` | No | Unique code of the tax exemption. GST only |
| `tdsTaxId` | `string` | No | ID of the TDS tax. Mexico only |
| `satItemKeyCode` | `string` | No | Add SAT Item Key Code for your goods/services. Download the CFDI Catalogs. Mexico only |
| `unitkeyCode` | `string` | No | Add SAT Unit Key Code for your goods/services. Download the CFDI Catalogs. Mexico only |
| `setupFeeTaxExemptionId` | `string` | No | Unique Tax Exemption ID that must be applied to setup fee. GST only |
| `setupFeeTaxExemptionCode` | `string` | No | Unique code of the tax exemption that must be applied to setup fee. GST only |
| `excludeTrial` | `boolean` | No | This is set to true if the respective plan's trial period needs to be excluded for this subscription. |
| `excludeSetupFee` | `boolean` | No | This is set to true if the respective plan's setup fee needs to be excluded for this subscription. |
| `billingCycles` | `integer` | No | 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. |
| `trialDays` | `integer` | No | 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. Default is 0 only if Exclude Trial is true |
| `addons` | `string[]` | No | List of addon objects which are to be included in the subscription. |
| `couponCode` | `string` | No | The coupon code of the coupon which is to be applied to the subscription. |
| `autoCollect` | `boolean` | Yes | Auto Collect is set to true for creating an online subscription which will charge the customer's card automatically on every renewal. To create an offline subscriptions, set Auto Collect to false. |
| `referenceId` | `string` | No | A string of your choice is required to easily identify and keep track of your subscriptions. |
| `salespersonName` | `string` | No | Name of the sales person assigned for the subscription. |
| `paymentGateways` | `string[]` | No | Payment gateway associated with the subscription. |
| `createBackdatedInvoice` | `boolean` | No | To allow creation of invoice for current billing cycle for back dated subscriptions. |
| `canChargeSetupFeeImmediately` | `boolean` | No | 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. |
| `templateId` | `string` | No | Default Invoice Template ID for all the invoices created from the subscription. |
| `cfdiUsage` | `string` | No | Choose CFDI Usage. Mexico only |
| `allowPartialPayments` | `boolean` | No | Boolean to check if partial payments are allowed for the contact. Mexico only |
| `accountId` | `string` | No | Account ID of the bank account from which payment is made by the customer. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "zoho_subscriptions",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "zoho_subscriptions-create-subscription",
  arguments: {
    organizationId: "Organization Id",
    addToUnbilledCharges: true,
  },
})
```

**TypeScript**

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "zoho_subscriptions-create-subscription",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    zoho_subscriptions: { authProvisionId: "apn_xxxxxxx" },
    organizationId: "Organization Id",
    addToUnbilledCharges: true,
  },
})

console.log(result)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "zoho_subscriptions-create-subscription",
    "configured_props": {
      "zoho_subscriptions": { "authProvisionId": "apn_xxxxxxx" },
      "organizationId": "Organization Id",
      "addToUnbilledCharges": true
    }
  }'
```

---

- App: https://pipedream.com/apps/zoho-subscriptions.md · All apps: https://pipedream.com/apps