EZezypay

Create a subscription

Changed on
post/billing/subscriptions

Request

  • Base URL
    https://api-sandbox.ezypay.com/v2
  • URL
    https://api-sandbox.ezypay.com/v2/billing/subscriptions
  • Auth
    OAuth 2
    Client credentials
    Token URL: https://identity-sandbox.ezypay.com/token

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 intervalUnit = week OR intervalUnit = day
  • day_of_month - Subscriptions will start on specific day in the month as defined in billingStartValue. Only supported if interval = month
billingStartValuestring nullable

Value for billingStart.

  • immediate: not required (default null).
  • day_of_week: monday, tuesday, wednesday, thursday, friday, saturday or sunday (case-insensitive). Default monday: the schedule starts on the next Monday. Requires intervalUnit = week.
  • day_of_month: a whole number 1–31 (digits only). Default 1: the schedule starts on the next 1st of the month. 29, 30 or 31 are moved to the last day of shorter months. Requires intervalUnit = 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.
billingEndValuestring nullable

Value for billingEnd. Required when billingEnd is set to anything other than ongoing.

  • ongoing: not required (default null).
  • amount_collected: total amount to collect before the subscription ends, e.g. "500.00".
  • billing_cycles: number of billing cycles before the subscription ends, e.g. "12". For a one-off subscription use "1".
  • end_date: last billing date in YYYY-MM-DD format.
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.

Example request

{
  "billingStartValue": "15",
  "billingEndValue": "12"
}

Response

200

idstring
customerIdstring
planIdstring
namestring
statusstring
startDatestring
endDateunknown
paymentMethodTokenstring
accountingCodestring
nextBillingDatestring
intervalinteger
intervalUnitstring
totalBillingCyclesinteger
remainingToPayunknown
remainingBillingCyclesunknown
endTargetAmountunknown
endTargetBillingCyclesunknown
cancelledDateunknown
failedPaymentHandlingunknown
failedAttemptsCountinteger
metadataunknown
createdOnstring
autoPaymentboolean
setupPaymentsunknown

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
}

Changes

  • 924be4030f56Revision changes
    • breaking

      the request property type changed from object to array

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • warning

      removed the request property /

    • info

      added the new optional request property

    • info

      added the new optional request property