This article contains changes made within our APIs related to the January 2022 release.
Subscription API Changes:
New: For POST and PUT requests for Subscriptions, when “charge_start_date” and “charge_end_date” values for Subscription Plans are provided as null, the values for these fields will also be returned as null in the response body.
For GET requests for Subscriptions, “charge_start_date” and “charge_end_date” values for Subscription Plans are null in the response body if the dates align with the contract term of the subscription.
Note: Date values for Charge Start Date and Charge End Date will continue to be displayed in the Subscription Charge detail modal in the Ordway user interface. If the charge start/end dates are the “Same as Subscription”, the date values will reflect the contract term start and end dates.
Old: For POST and PUT requests for Subscriptions, when “charge_start_date” and “charge_end_date” values for Subscription Plans are provided as null, the value for “charge_start_date” matches the value for “current_term_start_date” and the value for “charge_end_date” matches the value for “current_term_end_date” in the response body.
For GET requests for Subscriptions, “charge_start_date” and “charge_end_date” values for Subscription Plans match the values of “current_term_start_date” and “current_term_end_date” in the response body if the dates align with the contract term of the subscription.
New Response Body (truncated):
{
"plans": [
{
"product_id": "P-00001",
"product_name": "Sample Product",
"plan_id": "PLN-00001",
"plan_name": "Bronze Plan",
"charge_id": "CHG-00001",
"charge_name": "Setup Fee",
"list_price": "100000",
"quantity": 1,
"included_units": 0,
"discount": 0,
"effective_price": "100000",
"type": "One time",
"billing_period": "",
"renewal_increment_percent": 0,
"charge_start_date": “”
"charge_end_date": ""
}
]
}
Separate Billing & Usage Periods - Plans section for Subscriptions
New: For POST, GET, and PUT requests under the Plans section for Subscriptions, a new attribute has been added for usage-based charges: 'usage_period' - Valid Values (Same as Billing Period or Charge Term). This attribute is only available when ‘Separate Billing and Usage Periods’ has been enabled in the Advanced Usage Settings.
Sample Payload:
{
"id": "S-00006",
"customer_id": "C-00002",
"status": "Draft",
"contract_effective_date": "2017-01-24T00:00:00.000Z",
"billing_start_date": "2017-02-23T00:00:00.000Z",
"service_start_date": "2017-01-24T00:00:00.000Z",
"order_placed_at": "2017-01-24T00:00:00.000Z",
"cancellation_date": "2017-01-24T00:00:00.000Z",
"auto_renew": true,
"currency": "USD",
"notes": "",
"version": 1,
"contract_term": "12",
"renewal_term": "Evergreen",
"separate_invoice": true,
"renewal_increment_percent": 0,
"plans": [
{
"product_id": "P-00001",
"product_name": "Sample Product",
"plan_id": "PLN-00001",
"plan_name": "Bronze Plan",
"charge_id": "CHG-00003",
"charge_name": "Minutes Used",
"list_price": "15",
"quantity": 1,
"included_units": 100,
"discount": 0,
"effective_price": "15",
"type": "Usage based",
"billing_period": "Monthly",
"usage_period": "Charge Term",
"renewal_increment_percent": 0,
"override_renewal_increment_percent": false
}
]
}
Separate Billing & Usage periods - Charges section for Plans
New: For POST, GET, and PUT requests under the Charges section for Plans, a new attribute has been added for usage-based charges: 'usage_period' - Valid Values (Same as Billing Period or Charge Term). This attribute is only available when ‘Separate Billing and Usage Periods’ has been enabled in the Advanced Usage Settings.
Sample Payload:
{
"id": "CHG-00452",
"product_id": "P-00332",
"name": "My charge",
"description": "this is my charge",
"type": "Usage based",
"prepayment_amount": 0,
"pricing_model": "Tiered",
"list_price": "1000",
"billing_period": "Monthly",
“usage_period”: “Same as Billing Period”,
"billing_period_start_alignment": "Service Start Date",
"billing_day": "Align with Billing Period",
"unit_of_measure": "",
"included_units": 0,
"tiers": []
}
Bulk Usage API Requests
New: Introduced a new endpoint for bulk usage. This new endpoint can be used Create, Update, and Delete. Valid values for type - ‘create/update/delete’
Endpoint: /api/v1/usages/bulk
Sample Payload:
{
"type": "create",
"usages": [
{
"date": "2021-12-22",
"quantity": 12,
"customer_id": "C-00001",
"subscription_id": "S-00004"
}
]
}
New Billing Run Processing Option
New: Introduced a new boolean for processing options for Billing Runs where no email is sent to a customer when their invoice total amount is equal to zero (Do not email if the total invoice amount is equal to zero).
Endpoint: /api/v1/billing_runs
Field Name: do_not_email_if_invoice_total_zero
{
"id": "BR-00005",
"target_date": "2017-05-01",
"invoice_date": "2017-05-01",
"filter_options": {
"customer": [
{
"id": "C-0001"
},
{
"name": {
"not": [
"cutomer_name1",
"cutomer_name2"
]
}
},
{
"status": {
"not": "in_active"
}
}
],
"subscription": [
{
"id": [
"S-00001",
"S-00002"
]
}
],
"order": [
{
"order_date": "2020-12-01"
},
{
"order_amount": {
"gt": 0
}
}
],
"plan": [
{
"id": "/.*PLN-00.*/"
}
],
"product": [
{
"price": {
"lt": 1000
}
}
],
"subscription_charge": [
{
"charge_id": [
"CHG-00001",
"CHG-00002"
]
},
{
"start_date": {
"gte": "2020-10-01"
}
},
{
"end_date": {
"lte": "2020-12-31"
}
}
]
},
"created_by": "no-reply@ordwaylabs.com",
"updated_by": "no-reply@ordwaylabs.com",
"created_date": "2018-09-04T21:16:36.731Z",
"updated_date": "2018-09-04T21:16:36.731Z",
"charge_type": "recurring",
"auto_post": true,
"send_after_post": true,
"do_not_email_if_auto_pay_is_on_with_payment_method": true,
"do_not_email_if_invoice_total_zero": true
"do_not_email_if_invoice_balance_zero": true,
}
Manage Prepayment Lines API
New: For PUT requests for Manage Prepayment Lines, the billing schedule id has been moved to the url. The url is now /billing_schedules/{id}/manage_prepayment_lines. In addition, lines has been updated to schedule_lines and qty has been updated to quantity.
Endpoint: /billing_schedules/{id}/manage_prepayment_lines
Sample Payload:
{
"schedule_lines": [
{
"start_date": "2020-03-26T00:00:00Z",
"end_date": null,
"charge_ready_date": "2020-03-11T00:00:00Z",
"quantity": 10,
"parent_link": null
}
],
}
Comments
0 comments
Please sign in to leave a comment.