Skip to content

Recurring

This section provides detailed information on managing recurring billing, including creating, updating, retrieving, and deleting add-ons, discounts, plans, and subscriptions.

Add-Ons

Add-ons are used to adjust a recurring charge amount, either by a set amount or a percentage of the subscription amount.

Create Add-On

Create a new recurring plan add-on.

Request Method: POST

URL Endpoint: /api/recurring/addon

NameTypeDefaultDescriptionRequired
namestring""Display name for the add-on
descriptionstring""Description for the add-on
amountintegernullAmount to be added in cents (100 = $1.00)* (see note below)
percentageintegernullPercentage of original charge to be added (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)* (see note below)
durationinteger0Number of times for the add-on to be billed (use 0 if you want the add-on to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Get Add-On By ID

Retrieve details for the specified add-on.

Request Method: GET

URL Endpoint: /api/recurring/addon/{ add-on id }

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89ffdqj8m0o735i19i0",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:41:43.330315Z",
    "updated_at": "2017-11-20T15:41:43.330315Z"
  }
}

Get All Add-Ons

Retrieve details for all add-ons associated with the gateway account.

Request Method: GET

URL Endpoint: /api/recurring/addons

json
{
  "status": "success",
  "msg": "success",
  "data": [
    {
      "id": "b75cvl51tlv38t0o7o30",
      "updated_at": "2017-09-26T22:08:20Z"
    },
    {
      "id": "b779mpt1tlv96kdv2n20",
      "updated_at": "2017-10-09T20:39:41Z"
    },
    {
      "id": "b89ffdqj8m0o735i19i0",
      "updated_at": "2017-11-20T15:41:43Z"
    }
  ],
  "total_count": 3
}

Update Add-On

Edit details for the specified add-on.

Request Method: POST

URL Endpoint: /api/recurring/addon/{ add-on id }

NameTypeDefaultDescriptionRequired
namestring""Display name for the add-on
descriptionstring""Description for the add-on
amountintegernullAmount to be added in cents (100 = $1.00)* (see note below)
percentageintegernullPercentage of original charge to be added (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)* (see note below)
durationinteger0Number of times for the add-on to be billed (use 0 if you want the subscription to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Delete Add-On

Delete the specified add-on.

Request Method: DELETE

URL Endpoint: /api/recurring/addon/{ add-on id }

json
{
  "status": "success",
  "msg": "success",
  "data": null
}

Discounts

Create Discount

Create a new recurring plan discount. Discounts are used to adjust a recurring charge amount either by a set amount or a percentage of the subscription amount.

Request Method: POST

URL Endpoint: /api/recurring/discount

NameTypeDefaultDescriptionRequired
namestring""Display name for the discount
descriptionstring""Description for the discount
amountintegernullAmount to be discounted in cents (100 = $1.00)* (see note below)
percentageintegernullPercentage of original charge to be discounted (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)* (see note below)
durationinteger0Number of times for the discount to be billed (use 0 if you want the discount to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Get Discount By ID

Retrieve details for the specified discount.

Request Method: GET

URL Endpoint: /api/recurring/discount/{ discount id }

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89flfqj8m0o735i19ig",
    "name": "test discount",
    "description": "just a simple test discount",
    "amount": 100,
    "percentage": null,
    "duration": 0,
    "created_at": "2017-11-20T15:54:39.851636Z",
    "updated_at": "2017-11-20T15:54:39.851636Z"
  }
}

Get All Discounts

Retrieve the properties of all discounts for the gateway account associated with the API Key or JWT token provided in the Authorization header.

Request Method: GET

URL Endpoint: /api/recurring/discounts

json
{
  "status": "success",
  "msg": "success",
  "data": [
    {
      "id": "b89flfqj8m0o735i19ig",
      "name": "test discount",
      "description": "just a simple test discount",
      "amount": 100,
      "percentage": null,
      "duration": 0,
      "created_at": "2017-11-20T15:54:39.851636Z",
      "updated_at": "2017-11-20T15:54:39.851636Z"
    }
  ],
  "total_count": 1
}

Update Discount

Edit details for the specified discount.

Request Method: POST

URL Endpoint: /api/recurring/discount/{ discount id }

NameTypeDefaultDescriptionRequired
namestring""Display name for the discount
descriptionstring""Description for the discount
amountintegernullAmount to be discounted in cents (100 = $1.00)* (see note below)
percentageintegernullPercentage of original charge to be discounted (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%)* (see note below)
durationinteger0Number of times for the discount to be billed (use 0 if you want the discount to persist until cancelled)

TIP

Either amount or percentage may be provided, but not both.

Delete Discount

Delete the specified discount.

Request Method: DELETE

URL Endpoint: /api/recurring/discount/{ discount id }

json
{
  "status": "success",
  "msg": "success",
  "data": null
}

Plans

Create Plan

Creates a new recurring plan with discounts and/or add-ons.

Request Method: POST

URL Endpoint: /api/recurring/plan

NameTypeDefaultDescriptionRequired
namestring""Display name for the plan*
descriptionstring""Description for the plan
amountintegernullAmount to be billed in cents (100 = $1.00)*
billing_cycle_intervalintegernullHow often to run the billing cycle (run every X months)*
billing_frequencystring literal"monthly"How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily")*
billing_daysstringnullWhich day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".*
charge_on_daybooleanfalseIf true, this will set the billing day to the current day
durationinteger0Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled)
add_onsarray of objectsEnumerates add-ons for a recurring plan
add_ons[#]
    .id
stringID of the referenced add_on
add_ons[#]
    .name
stringDisplay name for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .description
stringDescription for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .amount
intAmount to be added (optional, this overrides the add_ons value)
add_ons[#]
    .duration
intDuration for the add_on to be billed (optional, this overrides the add_ons value)
discountsarray of objectsEnumerates discounts for a recurring plan
discounts[#]
    .id
stringID of the referenced discount
discounts[#]
    .name
stringDisplay name for the discount (optional, this overrides the discount value)
discounts[#]
    .description
stringDescription for the discount (optional, this overrides the discount value)
discounts[#]
    .amount
intAmount to be discounted (optional, this overrides the discount value)
discounts[#]
    .duration
intDuration for the discount to be billed (optional, this overrides the discount value)

Get Plan By ID

Retrieve details for the specified plan.

Request Method: GET

URL Endpoint: /api/recurring/plan/{ plan id }

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89g35qj8m0o735i19jg",
    "name": "test plan",
    "description": "just a simple test plan",
    "amount": 100,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "total_add_ons": 100,
    "total_discounts": 50,
    "duration": 0,
    "add_ons": [
      {
        "id": "b75cvl51tlv38t0o7o30",
        "name": "test_addon",
        "description": "this will add to the cost of the subscription",
        "amount": 100,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "name": "test discount",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0,
        "created_at": null,
        "updated_at": null
      }
    ],
    "created_at": "2017-11-20T16:23:51.990051Z",
    "updated_at": "2017-11-20T16:23:51.990051Z"
  }
}

Get All Plans

Retrieve the properties of all plans for the gateway account associated with the API Key or JWT token provided in the Authorization header.

Request Method: GET

URL Endpoint: /api/recurring/plans

json
{
  "status": "success",
  "msg": "success",
  "data": [
    {
      "id": "b89g35qj8m0o735i19jg",
      "name": "test plan",
      "description": "just a simple test plan",
      "amount": 100,
      "billing_cycle_interval": 1,
      "billing_frequency": "twice_monthly",
      "billing_days": "1,15",
      "total_add_ons": 100,
      "total_discounts": 50,
      "duration": 0,
      "add_ons": [
        {
          "id": "b75cvl51tlv38t0o7o30",
          "name": "test_addon",
          "description": "this will add to the cost of the subscription",
          "amount": 100,
          "percentage": null,
          "duration": 0,
          "created_at": null,
          "updated_at": null
        }
      ],
      "discounts": [
        {
          "id": "b89flfqj8m0o735i19ig",
          "name": "test discount",
          "description": "this will discount the cost of the subscription",
          "amount": 50,
          "percentage": null,
          "duration": 0,
          "created_at": null,
          "updated_at": null
        }
      ],
      "created_at": "2017-11-20T16:23:52Z",
      "updated_at": "2017-11-20T16:23:52Z"
    }
  ],
  "total_count": 1
}

Update Plan

Edit details for the specified plan.

Request Method: POST

URL Endpoint: /api/recurring/plan/{ plan id }

NameTypeDefaultDescriptionRequired
namestring""Display name for the plan*
descriptionstring""Description for the plan
amountintegernullAmount to be billed in cents (100 = $1.00)*
billing_cycle_intervalintegernullHow often to run the billing cycle (run every X months)*
billing_frequencystring literal"monthly"How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily")*
billing_daysstringnullWhich day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".*
charge_on_daybooleanfalseIf true, this will set the billing day to the current day
durationinteger0Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled)
add_onsarray of objectsEnumerates add-ons for a recurring plan
add_ons[#]
    .id
stringID of the referenced add_on
add_ons[#]
    .name
stringDisplay name for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .description
stringDescription for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .amount
intAmount to be added (optional, this overrides the add_ons value)
add_ons[#]
    .duration
intDuration for the add_on to be billed (optional, this overrides the add_ons value)
discountsarray of objectsEnumerates discounts for a recurring plan
discounts[#]
    .id
stringID of the referenced discount
discounts[#]
    .name
stringDisplay name for the discount (optional, this overrides the discount value)
discounts[#]
    .description
stringDescription for the discount (optional, this overrides the discount value)
discounts[#]
    .amount
intAmount to be discounted (optional, this overrides the discount value)
discounts[#]
    .duration
intDuration for the discount to be billed (optional, this overrides the discount value)
update_subscriptionsbooleanfalseIf true, this will update the amount for all subscriptions that have this plan ID

Delete Plan

Delete the specified plan.

Request Method: DELETE

URL Endpoint: /api/recurring/plan/{ plan id }

json
{
  "status": "success",
  "msg": "success",
  "data": null
}

Subscriptions

Create Subscription

Creates a new subscription which applies a recurring billing plan to a customer.

Request Method: POST

URL Endpoint: /api/recurring/subscription

NameTypeDefaultDescriptionRequired
plan_idstring""ID of the plan being subscribed to
descriptionstring""Description for the subscription
customerobjectObject containing details for the customer being subscribed to the plan
customer
    .id
stringID for the customer being subscribed to the billing plan*
customer
    .payment_method_type
stringdefault payment method type"card" or "ach"
customer
    .payment_method_id
stringdefault payment method idID of the customer's saved payment method to use for the billing planrequired if payment_method_type is present
customer
    .billing_address_id
stringdefault billing addressID of the customer's saved billing address to use for the billing plan
customer
    .shipping_address_id
stringdefault shipping addressID of the customer's saved shipping address to use for the billing plan
amountintegernullAmount to be billed in cents (100 = $1.00)*
billing_cycle_intervalintegernullHow often to run the billing cycle (run every X months)*
billing_frequencystring literal"monthly"How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily")*
billing_daysstringnullWhich day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".*
charge_on_daybooleanfalseIf true, this will set the billing day to the current day
durationinteger0Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled)
next_bill_datestring "YYYY-MM-DD"The date of the next time the billing plan will be processed
add_onsarray of objectsEnumerates add-ons for a recurring subscription
add_ons[#]
    .id
stringID of the referenced add_on
add_ons[#]
    .name
stringDisplay name for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .description
stringDescription for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .amount
intAmount to be added (optional, this overrides the add_ons value)
add_ons[#]
    .duration
intDuration for the add_on to be billed (optional, this overrides the add_ons value)
discountsarray of objectsEnumerates discounts for a recurring subscription
discounts[#]
    .id
stringID of the referenced discount
discounts[#]
    .name
stringDisplay name for the discount (optional, this overrides the discount value)
discounts[#]
    .description
stringDescription for the discount (optional, this overrides the discount value)
discounts[#]
    .amount
intAmount to be discounted (optional, this overrides the discount value)
discounts[#]
    .duration
intDuration for the discount to be billed (optional, this overrides the discount value)

Get Subscription By ID

Retrieve details for the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b89gftaj8m0oft7upk80",
    "plan_id": "b89g35qj8m0o735i19jg",
    "description": "some description to describe the subscription",
    "customer": {
      "id": "b81ko5qq9qq5v460r9i0",
      "payment_method_type": "card",
      "payment_method_id": "b81ko5qq9qq5v460r9i0",
      "billing_address_id": "b81ko5qq9qq5v460r9i0",
      "shipping_address_id": "b81ko5qq9qq5v460r9i0"
    },
    "amount": 100,
    "total_adds": 0,
    "total_discounts": 50,
    "billing_cycle_interval": 1,
    "billing_frequency": "twice_monthly",
    "billing_days": "1,15",
    "duration": 0,
    "next_bill_date": "2017-11-22",
    "add_ons": null,
    "discounts": [
      {
        "id": "b89flfqj8m0o735i19ig",
        "description": "this will discount the cost of the subscription",
        "amount": 50,
        "percentage": null,
        "duration": 0
      }
    ],
    "created_at": "2017-11-20T16:51:01.798736Z",
    "updated_at": "2017-11-20T16:51:01.798736Z"
  }
}

Update Subscription

Edit details for the specified subscription.

Request Method: POST

URL Endpoint: /api/recurring/subscription/{ subscription id }

NameTypeDefaultDescriptionRequired
plan_idstring""ID of the plan being subscribed to
descriptionstring""Description for the subscription
customerobjectObject containing details for the customer being subscribed to the plan
customer
    .id
stringID for the customer being subscribed to the billing plan*
customer
    .payment_method_type
stringdefault payment method type"card" or "ach"
customer
    .payment_method_id
stringdefault payment method idID of the customer's saved payment method to use for the billing planrequired if payment_method_type is present
customer
    .billing_address_id
stringdefault billing addressID of the customer's saved billing address to use for the billing plan
customer
    .shipping_address_id
stringdefault shipping addressID of the customer's saved shipping address to use for the billing plan
amountintegernullAmount to be billed in cents (100 = $1.00)*
billing_cycle_intervalintegernullHow often to run the billing cycle (run every X months)*
billing_frequencystring literal"monthly"How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily")*
billing_daysstringnullWhich day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0".*
charge_on_daybooleanfalseIf true, this will set the billing day to the current day
durationinteger0Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled)
next_bill_datestring "YYYY-MM-DD"The date of the next time the billing plan will be processed
add_onsarray of objectsEnumerates add-ons for a recurring subscription
add_ons[#]
    .id
stringID of the referenced add_on
add_ons[#]
    .name
stringDisplay name for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .description
stringDescription for the add_on (optional, this overrides the add_ons value)
add_ons[#]
    .amount
intAmount to be added (optional, this overrides the add_ons value)
add_ons[#]
    .duration
intDuration for the add_on to be billed (optional, this overrides the add_ons value)
discountsarray of objectsEnumerates discounts for a recurring subscription
discounts[#]
    .id
stringID of the referenced discount
discounts[#]
    .name
stringDisplay name for the discount (optional, this overrides the discount value)
discounts[#]
    .description
stringDescription for the discount (optional, this overrides the discount value)
discounts[#]
    .amount
intAmount to be discounted (optional, this overrides the discount value)
discounts[#]
    .duration
intDuration for the discount to be billed (optional, this overrides the discount value)

Pause Subscription

Pause the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/paused

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "paused",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T20:45:50.953717Z",
    "charge_on_day": false
  }
}

Mark Subscription Past Due

Mark the specified subscription as past due.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/past_due

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cnb14e3ug2jpf9mtp6k0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "past_due",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-21",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-21T15:09:45Z",
    "updated_at": "2024-02-21T15:13:03.001456Z",
    "charge_on_day": false
  }
}

Cancel Subscription

Cancel the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/cancelled

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "cancelled",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T21:05:39.561726Z",
    "charge_on_day": false
  }
}

Activate Subscription

Activate the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/active

Query Params

NameDefaultDescription
next_bill_dateDate in 'YYYY-MM-DD' format
json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "active",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T21:10:36.976006Z",
    "charge_on_day": false
  }
}

Complete Subscription

Complete the specified subscription.

Request Method: GET

URL Endpoint: /api/recurring/subscription/{ subscription id }/status/completed

json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "cn9rrqbug2jpf9mtp6c0",
    "plan_id": "cn9rrkrug2jpf9mtp6bg",
    "plan_name": "",
    "status": "completed",
    "description": "",
    "customer_name": "",
    "shared": false,
    "customer": {
      "id": "cn9nrfbug2jpejn1kbeg",
      "payment_method_type": "",
      "payment_method_id": "",
      "billing_address_id": "",
      "shipping_address_id": ""
    },
    "amount": 100,
    "currency": "USD",
    "processor_id": "",
    "total_adds": 0,
    "total_discounts": 0,
    "billing_cycle_interval": 1,
    "billing_frequency": "monthly",
    "billing_days": "1",
    "duration": 0,
    "next_bill_date": "2024-02-19",
    "add_ons": null,
    "discounts": null,
    "expiration_date": "",
    "events": null,
    "created_at": "2024-02-19T20:45:30Z",
    "updated_at": "2024-02-19T21:25:01.161503Z",
    "charge_on_day": false
  }
}

Delete Subscription

Delete the specified subscription.

Request Method: DELETE

URL Endpoint: /api/recurring/subscription/{ subscription id }

json
{
  "status": "success",
  "msg": "success",
  "data": null
}