---
title: "Create a subscription"
method: POST
path: "/billing/subscriptions"
---

# Create a subscription

`POST /billing/subscriptions`

Integrators will use this the create subscription API to create a specific payment plan for a customer. Using the subscription, Ezypay will automatically trigger payment collection depending on the frequency and amount configured in the subscription. By default, what is configured in the PLAN will be inherited by the Subscription. Any similar parameters provided when the subscription is created ("interval", "billingEnd", "billingEndValue") it will overwrite what was setup in the PLAN used. Subscriptions can be created with as PENDING activation or activated instantly. More details on what the Subscription can do can be found in the document below:https://developer.ezypay.com/docs/subscription-payment-scenarios

## Headers

- `merchant` string, required

## Request body

- object
  - `customerId` string, required — Auto-generated identifier of the customer.
  - `planId` string, required — Auto-generated identifier of the plan.
  - `paymentMethodToken` string — The payment method token generated by the vault.
  - `markAsPending` boolean — Default value is `false`. If set to `true`, creates a subscription with a Pending status. A pending subscription will ignore the subscription's `startDate` and no schedules will be created. The status can be changed to Active using the Activate a subscription API.
  - `startDate` string — The preferred start date of the subscription. The subscription start date cannot be back-dated. The default value follows the plan's start date. Supported format is YYYY-MM-DD.
  - `name` string — The name of the plan to subscribe the customer to. Max of 50 characters.
  - `accountingCode` string — Specify an accounting code to categorise revenue collected from the subscription's payment. Max of 50 characters.
  - `amount` object — The gross amount charged to the customer, inclusive of tax. Supports decimal values for cents. For example, $24.50 would be 24.50.
    - `currency` string, required — Three letter ISO 4217 currency code for the amount.
    - `value` number, double, required — The value of the amount. Must be positive value greater than zero.
    - `type` string — The type of the amount value. Supported values are: `percentage`, `fixed_amount`
  - `tax` object — If provided, each invoice generated for this subscription will include a tax rate.
    - `rate` number, double — Rate of the specified tax in percentage. Supported values are from 0 to 99.99.
  - `setupPayments` object — One-time setup payment applied to the subscription.
    - `amount` object — Setup payment amount.
      - `currency` string, required — Three letter ISO 4217 currency code for the amount.
      - `value` number, double, required — The value of the amount. Must be positive value greater than zero.
      - `type` string — The type of the amount value. Supported values are: `percentage`, `fixed_amount`
    - `tax` object — The tax that is applicable to the setup payment, if the amount is taxable.
      - `rate` number, double — Rate of the specified tax in percentage. Supported values are from 0 to 99.99.
    - `description` string — Description. Max of 255 characters.
    - `accountingCode` string — Specify an accounting code to categorise revenue collected from the setup payment. Max of 50 characters.
  - `interval` string — Number to be specified as interval to manipulate billing frequency. For example `interval=2` and `intervalUnit=week` would means billing every 2 weeks. If no value is provided, the default value is 1.
  - `intervalUnit` string — Specifies frequency of billing. Valid values are `day`, `week` or `month`. If no value is provided, the default value is `week`.
  - `billingStart` string — Specifies the default day the billing schedule starts for customers subscribed to the plan. Supported values are: `immediate` - Default value. Subscriptions will start on the same day. `day_of_week` - Subscriptions will start on a specific day as defined in `billingStartValue`. Only supported if `interval = week day_of_month` - Subscriptions will start on specific day in the month as defined in `billingStartValue`. Only supported if `interval = month`
  - `billingEnd` string — Specifies the rules to automate when a subscription ends. Supported values are: `ongoing` - Default value. Subscriptions created from this plan will have no end date and continue billing on an ongoing basis (until instructions are given to stop billing). `amount_collected` - Subscriptions will end when a specified amount is collected as defined in `billingEndValue`. `billing_cycles` - Subscriptions will end after a specified number of billing cycles as defined in `billingEndValue`. `end_date` - Subscriptions will end on date defined in `billingEndValue`.
  - `firstBilling` string — Specifies the rules to auto-calculate the billing charges for the first scheduled billing. The default value follows the plan's firstBilling. Supported values are: `full_amount` - The first billing will charge the full amount on the subscription as defined in the plan's amount. `prorate` - Prorate will be auto-calculated for the first billing in the subscription for the pro-rated period, with full recurring billing amount starting from the next billing cycle.
  - `firstBillingAmount` object — The amount to pay for the subscription's first scheduled billing.
    - `currency` string, required — Three letter ISO 4217 currency code for the amount.
    - `value` number, double, required — The value of the amount. Must be positive value greater than zero.
    - `type` string — The type of the amount value. Supported values are: `percentage`, `fixed_amount`
  - `metadata` object — Store additional data about the subscription object using key/value pairs format. Max of 40 characters for key name and 255 characters for key value
  - `autoPayment` boolean — Specify if auto payment processing occurs for invoices generated from the subscription. Supported value are: `true` - Default value. Invoices generated will automatically proceed to payment processing. `false` - Invoices are generated but will not automatically proceed to payment processing.
  - `customerEmailNotification` boolean — Specify if an email notification is sent to the customer informing them that the subscription was created or activated. Supported values are: `true` - An email notification will be sent to the customer to inform them that this subscription was created or activated no matter what was specified under the merchant notification settings. `false` - No email notification is sent to the customer to inform them that this subscription was created or activated no matter what was specified under the merchant notification settings. If not specified, follows what was defined in the merchant notification settings.

## Response `200`

200

- object
  - `id` string
  - `customerId` string
  - `planId` string
  - `name` string
  - `status` string
  - `startDate` string
  - `endDate` unknown
  - `paymentMethodToken` string
  - `accountingCode` string
  - `amount` object
    - `currency` string
    - `value` integer
    - `type` unknown
  - `tax` object
    - `rate` integer
  - `nextBillingDate` string
  - `nextFutureInvoice` object
    - `subscriptionId` string
    - `date` string
    - `cycleStartDate` string
    - `cycleEndDate` string
    - `items` object[]
      - `description` string
      - `amount` object
        - `currency` string
        - `value` integer
        - `type` unknown
      - `tax` object
        - `rate` integer
      - `type` string
      - `accountingCode` string
    - `amount` object
      - `currency` string
      - `value` number
      - `type` unknown
    - `totalTax` object
      - `currency` string
      - `value` integer
      - `type` unknown
  - `interval` integer
  - `intervalUnit` string
  - `totalPaid` object
    - `currency` string
    - `value` integer
    - `type` unknown
  - `totalBillingCycles` integer
  - `remainingToPay` unknown
  - `remainingBillingCycles` unknown
  - `endTargetAmount` unknown
  - `endTargetBillingCycles` unknown
  - `cancelledDate` unknown
  - `failedPaymentHandling` unknown
  - `failedAttemptsCount` integer
  - `totalPastDue` object
    - `currency` string
    - `value` integer
    - `type` unknown
  - `totalDiscounted` object
    - `currency` string
    - `value` integer
    - `type` unknown
  - `metadata` unknown
  - `createdOn` string
  - `autoPayment` boolean
  - `setupPayments` unknown

## Other responses

- `400` — 400

---

[API](https://skmtc.dev/ezypay/apis/vault.md) · [All operations](https://skmtc.dev/ezypay/apis/vault/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ezypay/vault/revisions/2ca692551cdf/schema)