Scheduleitems
The scheduleitems object captures the planned individual transactions that make up a schedule. This object enables merchants to create and make one-time adjustments to a scheduled transaction such as the amount or status of the transaction.
Scheduleitems 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 Scheduleitems
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}/scheduleitems/
This URI creates a new scheduleitem and returns a unique schedule_item_id. If the schedule_item_date or schedule_item_amount fields are not passed, the system automatically calculates these values based on the last scheduleitem and the schedule definition records. The value of the schedule_item_date field must be a future date. NOTE: Scheduleitems cannot be created for non-active or continuous schedules.
{
"schedule_id": "sch_ce7b86ea-7510-444e-bd46-431c8d175b7e",
"customer_token": "cst_h_TrrHANEU6XjmMV_EMVrA",
"paymethod_token": "mth_cp459q53Q0W5wJdMG35f1w",
"schedule_item_amount": 100.00,
"schedule_item_status": "scheduled",
"schedule_item_date": "12/21/2018"
}
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}/scheduleitems/' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--header 'Content-Type: application/json' \
--data '{
"schedule_id": "sch_ce7b86ea-7510-444e-bd46-431c8d175b7e",
"customer_token": "cst_h_TrrHANEU6XjmMV_EMVrA",
"paymethod_token": "mth_cp459q53Q0W5wJdMG35f1w",
"schedule_item_amount": 100.00,
"schedule_item_status": "scheduled",
"schedule_item_date": "12/21/2018"
}'
Example Response
GET All Scheduleitems for an Organization
{{baseURI}}/organizations/org_{{organizationID}}/scheduleitems/
This URI returns all scheduleitems for an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
location_id
customer_token
paymethod_token
schedule_id
schedule_item_amount
schedule_item_status
start_schedule_item_date / end_schedule_item_date
start_schedule_item_processed_date / end_schedule_item_processed_date
start_schedule_item_created_date / end_schedule_item_created_date
Note:Â Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/scheduleitems/' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
GET All Scheduleitems for a Location
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/scheduleitems/
This URI returns all scheduleitems for a Location. To narrow your search data using specific criteria, use the following parameters to filter your results:
- customer_token
- paymethod_token
- schedule_id
- schedule_item_amount
- schedule_item_status
- start_schedule_item_date / end_schedule_item_date
- start_schedule_item_processed_date / end_schedule_item_processed_date
- start_schedule_item_created_date / end_schedule_item_created_date
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/scheduleitems/' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
GET All Future Scheduleitems for a Customer Token
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/scheduleitems?filter=schedule_item_status+eq+'scheduled'
This URI returns all future scheduleitems for a particular customer using the customer_token.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/scheduleitems?filter=schedule_item_status%2Beq%2B%27scheduled%27' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
GET All Future Scheduleitems for a Paymethod Token
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/paymethods/mth_{{paymethodtoken}}/scheduleitems?filter=schedule_item_status+eq+'scheduled'
This URI returns all future scheduleitems for a particular paymethod using the paymethod_token.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/paymethods/mth_{{paymethodtoken}}/scheduleitems?filter=schedule_item_status%2Beq%2B%27scheduled%27' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
GET A Specific Scheduleitem
{{baseURI}}/organizations/org_{{organizationID}}/scheduleitems/sci_{{scheduleitemID}}
This URI returns a specific scheduleitem using the schedule_id parameter.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/scheduleitems/sci_{{scheduleitemID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
PUT Update a Scheduleitem
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/scheduleitems/sci_{{scheduleitemID}}
This URI updates the specified scheduleitem. Only scheduleitems with a future date value in the schedule_item_date field and a status of scheduled or suspended in the schedule_item_status field can be updated. If the status of a scheduleitem in a continuous schedule is changed to suspended, the status of the schedule definition will also be suspended. NOTE: Updates to the schedule_item_created_date and schedule_item_processed_date are not allowed.
{
"schedule_item_amount": 200.00
}
Example Request
{
"schedule_item_id": "sci_0d2d949e-b3a9-4e6d-a9c9-db358ae49cfa",
"location_id": "loc_192642",
"schedule_item_amount": 200,
"response": {
"environment": "live",
"response_desc": "Update Successful."
},
"links": {
"self": "https://api.forte.net/v3/scheduleitems/sci_0d2d949e-b3a9-4e6d-a9c9-db358ae49cfa"
}
}
Example Response
DELETE Scheduleitem
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}//scheduleitems/sci_{{scheduleitemID}}
This URI deletes the specified scheduleitem. Deleting a scheduleitem will not delete the schedule definition.
Example Request
curl --location -g --request DELETE 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}//scheduleitems/sci_{{scheduleitemID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response