Appearance
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
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the add-on | |
description | string | "" | Description for the add-on | |
amount | integer | null | Amount to be added in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage 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) |
duration | integer | 0 | Number 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 }
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the add-on | |
description | string | "" | Description for the add-on | |
amount | integer | null | Amount to be added in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage 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) |
duration | integer | 0 | Number 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
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the discount | |
description | string | "" | Description for the discount | |
amount | integer | null | Amount to be discounted in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage 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) |
duration | integer | 0 | Number 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 }
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the discount | |
description | string | "" | Description for the discount | |
amount | integer | null | Amount to be discounted in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage 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) |
duration | integer | 0 | Number 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
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the plan | * |
description | string | "" | Description for the plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which 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_day | boolean | false | If true, this will set the billing day to the current day | |
duration | integer | 0 | Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled) | |
add_ons | array of objects | Enumerates add-ons for a recurring plan | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring plan | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration 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 }
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the plan | * |
description | string | "" | Description for the plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which 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_day | boolean | false | If true, this will set the billing day to the current day | |
duration | integer | 0 | Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled) | |
add_ons | array of objects | Enumerates add-ons for a recurring plan | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring plan | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration for the discount to be billed (optional, this overrides the discount value) | ||
update_subscriptions | boolean | false | If 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
Name | Type | Default | Description | Required |
---|---|---|---|---|
plan_id | string | "" | ID of the plan being subscribed to | |
description | string | "" | Description for the subscription | |
customer | object | Object containing details for the customer being subscribed to the plan | ||
customer .id | string | ID for the customer being subscribed to the billing plan | * | |
customer .payment_method_type | string | default payment method type | "card" or "ach" | |
customer .payment_method_id | string | default payment method id | ID of the customer's saved payment method to use for the billing plan | required if payment_method_type is present |
customer .billing_address_id | string | default billing address | ID of the customer's saved billing address to use for the billing plan | |
customer .shipping_address_id | string | default shipping address | ID of the customer's saved shipping address to use for the billing plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which 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_day | boolean | false | If true, this will set the billing day to the current day | |
duration | integer | 0 | Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled) | |
next_bill_date | string "YYYY-MM-DD" | The date of the next time the billing plan will be processed | ||
add_ons | array of objects | Enumerates add-ons for a recurring subscription | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring subscription | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration 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 }
Name | Type | Default | Description | Required |
---|---|---|---|---|
plan_id | string | "" | ID of the plan being subscribed to | |
description | string | "" | Description for the subscription | |
customer | object | Object containing details for the customer being subscribed to the plan | ||
customer .id | string | ID for the customer being subscribed to the billing plan | * | |
customer .payment_method_type | string | default payment method type | "card" or "ach" | |
customer .payment_method_id | string | default payment method id | ID of the customer's saved payment method to use for the billing plan | required if payment_method_type is present |
customer .billing_address_id | string | default billing address | ID of the customer's saved billing address to use for the billing plan | |
customer .shipping_address_id | string | default shipping address | ID of the customer's saved shipping address to use for the billing plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which 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_day | boolean | false | If true, this will set the billing day to the current day | |
duration | integer | 0 | Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled) | |
next_bill_date | string "YYYY-MM-DD" | The date of the next time the billing plan will be processed | ||
add_ons | array of objects | Enumerates add-ons for a recurring subscription | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring subscription | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration 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
Name | Default | Description |
---|---|---|
next_bill_date | Date 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
}