Sign in

v1

latestOpenAPI 3.1.02026-07-24120106.5 KB

Create a subscription

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

post/billing/subscriptions

Headers

merchantstring required

Merchant ID

Request body

customerIdstring required

Auto-generated identifier of the customer.

planIdstring required

Auto-generated identifier of the plan.

paymentMethodTokenstring

The payment method token generated by the vault.

markAsPendingboolean

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.

startDatestring

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.

namestring

The name of the plan to subscribe the customer to. Max of 50 characters.

accountingCodestring

Specify an accounting code to categorise revenue collected from the subscription's payment. Max of 50 characters.

intervalstring

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.

intervalUnitstring

Specifies frequency of billing. Valid values are day, week or month. If no value is provided, the default value is week.

billingStartstring

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

billingEndstring

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.

firstBillingstring

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.

metadataobject

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

autoPaymentboolean

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.

customerEmailNotificationboolean

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

idstring
customerIdstring
planIdstring
namestring
statusstring
startDatestring
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:endDate","oasType":"schema","type":"unknown"}
paymentMethodTokenstring
accountingCodestring
nextBillingDatestring
intervalinteger
intervalUnitstring
totalBillingCyclesinteger
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:remainingToPay","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:remainingBillingCycles","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:endTargetAmount","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:endTargetBillingCycles","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:cancelledDate","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:failedPaymentHandling","oasType":"schema","type":"unknown"}
failedAttemptsCountinteger
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:metadata","oasType":"schema","type":"unknown"}
createdOnstring
autoPaymentboolean
{"stackTrail":"paths:/billing/subscriptions:post:responses:200:content:application/json:schema:properties:setupPayments","oasType":"schema","type":"unknown"}

Example response

{
  "id": "f1de945f-df84-4108-9dee-e8fd8508fa2e",
  "customerId": "55220ffc-bc5a-4f50-adaf-fa58c061ebd1",
  "planId": "8ff2e3ea-aaa9-4978-8e2a-319d67e8f302",
  "name": "high_st_monthly_plan",
  "status": "ACTIVE",
  "startDate": "2019-03-11",
  "paymentMethodToken": "8dbf38bf-81c6-40d6-be1f-6aa80736d5bb",
  "accountingCode": "customer_plan",
  "amount": {
    "currency": "NZD",
    "value": 200
  },
  "nextBillingDate": "2019-05-01",
  "nextFutureInvoice": {
    "subscriptionId": "f1de945f-df84-4108-9dee-e8fd8508fa2e",
    "date": "2019-05-01",
    "cycleStartDate": "2019-05-01",
    "cycleEndDate": "2019-05-31",
    "items": [
      {
        "description": "high_st_monthly_plan",
        "amount": {
          "currency": "NZD",
          "value": 200
        },
        "type": "subscription_payment",
        "accountingCode": "customer_plan"
      }
    ],
    "amount": {
      "currency": "NZD",
      "value": 201.24
    },
    "totalTax": {
      "currency": "NZD"
    }
  },
  "interval": 1,
  "intervalUnit": "MONTH",
  "totalPaid": {
    "currency": "NZD",
    "value": 200
  },
  "totalBillingCycles": 1,
  "totalPastDue": {
    "currency": "NZD"
  },
  "totalDiscounted": {
    "currency": "NZD"
  },
  "createdOn": "2019-03-10T20:11:08.192",
  "autoPayment": true
}