Schedules
The schedules object captures scheduled transactions for a merchant's organization or location and includes the summary sub-object. Merchants can specify a particular quantity of scheduled transactions or can set up continuous transactions that will occur until the schedule is suspended or deleted. Subscription billing enables merchants to bill customers automatically on a fixed schedule for a specific product or service. Scheduled transactions can only be created with customer_token and paymethod_token parameters.
Schedules Object
Parameter | Description | Type | Req |
organization_id | The identification number of the associated organization. For example, org_5551236. | string | R |
location_id | The identification number of the associated location. For example, loc_1234568. | string | R |
schedule_id | A unique string used to represent a schedule. For example, sch_2e5770ae-c120-414f-ae8c-d065753567e7. [max length = 40] | string | R |
customer_token | A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26] | string | R |
paymethod_token | A unique string used to represent a payment method. For example, mth_1578436587. [max length = 26] | string | R |
action | The supported transaction types include the following values: sale - Creates an ad-hoc or token transaction that will settle at the end of the day | string | R |
schedule_quantity | Indicates the quantity of transactions to perform. For continuous schedules, set the value of this field to 0. [max length = 6] | integer | R |
schedule_frequency | Indicates the frequency of the scheduled transactions. The supported values for this field include the following: one_time_future | string | R |
schedule_amount | Indicates the amount of each recurring transaction plus any sales taxes, shipping fees, tips or other extraneous amounts. For service fee transactions, use this parameter as the base amount for calculating a service fee. The value of this parameter depends on the value in the schedule_frequency parameter. [max length = 6] | decimal | O |
schedule_service_fee_amount | The amount of the service fee (i.e., convenience fee). | decimal | O |
schedule_authorization_amount | Indicates the amount of the recurring payment. For service fee transactions, this parameter is the resulting sum of the schedule_amount and the schedule_service_fee_amount values. | decimal | R |
schedule_start_date | Indicates the start day of the next recurring transaction in MM/DD/YYYY format. This date can be today's date or greater. NOTE: If the merchant does not specify this value, the system defaults to today's date. [max length = 10] | datetime | R |
schedule_created_date | The date the schedule was created. This parameter is return only. | datetime | -- |
customer_acct_code | The customer accounting code. This field only applies to credit card transactions. [max length = 17] | string | -- |
schedule_status | The current status of the schedule. The supported values for this field include the following: active - The schedule is active. | string | O |
item_description | The check number or other description of the item to be processed. [max length = 50] | string | O |
reference_id | A merchant-defined string that identifies the transaction. [max length = 50] | O | |
order_number | A merchant-assigned ID code that is returned with the transaction response. [max length = 26] | string | O |
customer_id | A merchant-defined string created at the customer level to identify the customer. [max length = 15] | string | O |
echeck | The eCheck Object | object | O |
echeck.sec_code | The Standard Entry Class code for the transaction. This field is required for echeck transactions. Additionally, the available options for this field depend on your merchant configuration [max length = 3] | string | R |
summary | The Summary Object | object | O |
summary.schedule_next_amount | The amount of the next scheduled transaction that will be processed. This parameter is return only. | decimal | -- |
summary.schedule_next_date | The next date when a scheduled transaction will be processed. This parameter is return only. | datetime | -- |
summary.schedule_last_amount | The authorization amount for the last scheduled transaction that Forte processed. This parameter is return only. | decimal | -- |
summary.schedule_last_date | The date and timestamp when Forte processed the last scheduled transaction. This parameter is return only. | datetime | -- |
summary.schedule_successful_amount | The total amount of the successful transactions for this schedule. This parameter is return only. | decimal | -- |
summary.schedule_successful_authorization_amount | The authorization amount of the last scheduled transaction that Forte successfully processed. This parameter is return only. | decimal | -- |
summary.schedule_successful_quantity | The total number of successful transactions for this schedule. This parameter is return only. | integer | -- |
summary.schedule_failed_amount | The total amount of failed transactions for this schedule. This parameter is return only. | decimal | -- |
summary.schedule_failed_quantity | The total number of failed transactions for this schedule. This parameter is return only. | integer | -- |
summary.scheduled_remaining_amount | The total amount of the remaining transactions for this schedule. This parameter is return only. | decimal | -- |
summary.scheduled_remaining_quantity | The total number of the remaining transactions for this schedule. This parameter is return only. | integer | -- |
summary.scheduled_suspended_amount | The total amount of the suspended transactions for this schedule. This parameter is return only. | decimal | -- |
summary.scheduled_suspended_quantity | The total number of suspended transactions for this schedule. This parameter is return only. | integer | -- |
xdata | The Xdata Object | object | O |
xdata.xdata_1-9 | Up to nine fields (1-9) of extra data that can be associated with a schedule or transaction. Each xdata_# field can contain up to 255 characters. | string | O |
POST Schedule for a Specific Customer
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/schedules
Creates a new schedule and returns a new unique schedule_id for the customer. NOTE: The paymethod_token parameter must be specified in the request.
{
"action": "sale",
"schedule_amount": 25.00,
"schedule_quantity": 0,
"schedule_frequency": "monthly",
"schedule_start_date": "12/11/2018",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w"
}
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/schedules' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"action": "sale",
"schedule_amount": 25.00,
"schedule_quantity": 0,
"schedule_frequency": "monthly",
"schedule_start_date": "12/11/2018",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w"
}'
Example Response
POST 12-Month Schedule
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and the paymethod_token parameters must be specified in the body of the request.
{
"customer_token":"cst_h_TrrHANEU6XjmMV_EMVrA",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w",
"action": "sale",
"schedule_quantity": "12",
"schedule_frequency": "monthly",
"schedule_amount": 25.00,
"schedule_start_date": "12/11/2018",
"reference_id":"INV-123",
"order_number":"98762222",
"item_description":"Car Payment",
"xdata": {
"xdata_1": "inv-321",
"xdata_2": "Southern Branch"
}
}
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"customer_token":"cst_h_TrrHANEU6XjmMV_EMVrA",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w",
"action": "sale",
"schedule_quantity": "12",
"schedule_frequency": "monthly",
"schedule_amount": 25.00,
"schedule_start_date": "12/11/2018",
"reference_id":"INV-123",
"order_number":"98762222",
"item_description":"Car Payment",
"xdata": {
"xdata_1": "inv-321",
"xdata_2": "Southern Branch"
}
}'
Example Response
POST Weekly Schedule
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and the paymethod_token parameters must be specified in the body of the request.
{
"action":"sale",
"customer_token":"cst_-XqiJZuQ6EmV41auwt_gyQ",
"paymethod_token":"mth_Dvphvlf4RUyJsvz9sXlVWQ",
"schedule_start_date":"2020-08-31T00:00:00",
"schedule_amount":50.00,
"schedule_frequency":"weekly",
"schedule_quantity":10,
"echeck"{
"sec_code":"ppd",
},
"schedule_service_fee_amount":"4.00",
"schedule_authorization_amount":"54.00"
}
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/schedules' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"action": "sale",
"schedule_amount": 25.00,
"schedule_quantity": 0,
"schedule_frequency": "monthly",
"schedule_start_date": "12/11/2018",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w"
}'
Example Response
POST One-Time Future Schedule
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and the paymethod_token parameters must be specified in the body of the request.
{
"customer_token": "cst_h_TrrHANEU6XjmMV_EMVrA",
"paymethod_token": "mth_cp459q53Q0W5wJdMG35f1w",
"action": "sale",
"schedule_frequency": "one_time_future",
"schedule_amount": 25.00,
"schedule_start_date": "12/11/2018",
"reference_id":"INV-123",
"order_number":"98762222",
"item_description":"DeLorean Payment",
"xdata": {
"xdata_1": "inv-321",
"xdata_2": "Southern Branch"
}
}
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/schedules' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"action": "sale",
"schedule_amount": 25.00,
"schedule_quantity": 0,
"schedule_frequency": "monthly",
"schedule_start_date": "12/11/2018",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w"
}'
Example Response
POST Continuous Schedule
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and paymethod_token parameters must be specified in the request.
{
"action": "sale",
"schedule_amount": 25.00,
"schedule_quantity": 0,
"schedule_frequency": "monthly",
"schedule_start_date": "12/11/2018",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w"
}
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/schedules' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"action": "sale",
"schedule_amount": 25.00,
"schedule_quantity": 0,
"schedule_frequency": "monthly",
"schedule_start_date": "12/11/2018",
"paymethod_token":"mth_cp459q53Q0W5wJdMG35f1w"
}'
Example Response
GET All Schedules for a Location
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules
This URI returns all schedules created for a location. To narrow your search data using specific criteria, use the following parameters to filter your results:
- schedule_id
- customer_token
- paymethod_token
- action
- schedule_quantity
- schedule_frequency
- schedule_status
- schedule_amount
- start_schedule_created_date / end_schedule_created_date
- start_schedule_start_date / end_schedule_start_date
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organization}}/locations/loc_{{location}}/schedules' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'
Example Response
GET All Schedules for a Customer
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/schedules
This URI returns all schedules associated with a particular customer_token.
Example Request
curl --location -g 'https://api.forte.net/v3 /v3/organizations/org_{{organization}}/locations/loc_{{location}}/customers/cst_{{customer_token}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'
Example Response
GET A Specific Schedule
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}
This URI returns a deleted schedule based on the schedule_id parameter and the schedule_status=deleted filter. The schedule detailed data that Forte returns includes schedule summary data that can be used to quickly find useful information about that schedule.
Example Request
curl --location -g 'https://api.forte.net/v3/v3/organizations/org_{{organization}}/locations/loc_{{location}}/schedules/sch_{{scheduleID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'
Example Response
GET A Deleted Schedule
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}/?filter=schedule_status+eq+deleted
This URI returns a deleted schedule based on the schedule_id parameter and the schedule_status=deleted filter. The schedule detailed data that Forte returns includes schedule summary data that can be used to quickly find useful information about that schedule.
 Â
Example Request
curl --location -g 'https://api.forte.net/v3/v3/organizations/org_{{organization}}/locations/loc_{{location}}/schedules/sch_{{scheduleID}}/?filter=schedule_status%2Beq%2Bdeleted' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'
Example Response
PUT Update a Schedule's Status
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}
Updates the status of the schedule definition. When you reactivate a suspended schedule, its scheduleitems dated at least one day in the future are automatically reactivated as well.
{
"schedule_status": "suspended"
}
Example Request
curl --location -g --request PUT 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"schedule_status": "suspended"
}'
Example Response
PUT Update a Schedule's Paymethod Token
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}
Updates the paymethod token of the schedule definition.
{
"paymethod_token":"mth_3urq2yQexUmRWD3v8SOqlg"
}
Example Request
curl --location -g --request PUT 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"paymethod_token":"mth_3urq2yQexUmRWD3v8SOqlg"
}'
Example Response
Delete Schedule
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}
This URI deletes the schedule associated with the provided schedule_id.
Example Request
curl --location -g --request DELETE 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response