Create Order: /orders
Purpose
This API is used to create a new order in the system. An order defines the commercial agreement between a customer and the business, detailing products or services, pricing, quantities, and contractual properties such as billing cycles, payment terms, and contract configurations. The API supports the inclusion of contract-related attributes, line items, and pricing details at the time of order creation.
Use Case
Businesses use this API to automate order creation during sales or subscription processes. It allows users to generate new customer orders that include multiple products or services, apply discounts, set billing periods, and define contract terms such as renewal and downgrade rules. For example, this API can be used to create recurring subscription orders, contract-based service agreements, or one-time product purchases with configurable pricing and terms.
Path Parameters
This endpoint does not require path parameters.
Query Parameters
This endpoint does not accept query parameters.
Request Body
{
"order": {
"name": "Contract Discount Check 0.0.5",
// "display_name": "order dis",
// "description": "tax configuration",
// "account_id": "2OIQ4LKQACP",
// "redemption_code": "EB_ABCD",
// "discount_amount": "100",
// "discount_percentage": "10",
//"shipping_profile": "PP",
"account_id": "2561EE",
"allow_contract": "True",
"contract_properties": {
// "require_customer_acceptance": "False",
// "requires_payment_method": "False",
"initial_contract_term": "1 Year",
// "renew_automatically": "True",
// "auto_renewal_ends_on": "2024-09-17", // do not work
// // "auto_renewal_ends_on": "1 Day", // do not work
// // "specify_period":"1 week", // do not work
// "auto_renewal_term": "1 Week",
// // "auto_renewal_require_customer_acceptance": "True",
// "allow_early_termination": "TRUE",
// "early_termination_minimum_period": "1 Day",
// "apply_early_termination_charge": "False",
// // "early_termination_charge_type": "Percentage",
// // "termination_percentage_charge": "12.000000",
// // "termination_accounting_code": "Event Charge",
// "allow_postponement": "True",
// "maximum_duration_per_postponement": "1 Day",
// "maximum_postponement_count": "1",
// "allow_trial": "True",
// "start_contract_after_trial_ends": "true",
// "trial_period": "1 day",
// "trial_end_date": "2024-09-17",
// "trial_requires_payment_method": "True",
"allow_downgrade": "True",
// "period_before_downgrade": "1 Day",
// "allow_downgrade_charge": "False",
"downgrade_charge_type": "Fixed",
// "downgrade_charge_fixed": "23.000000",
// "downgrade_charge_percentage": "99",
// "downgrade_billing_period_count": "10",
"allow_upgrade": "True"
},
"lines": [
{
"item_id": "ITEM-0001",
"package_name": "family",
"item_order_quantity": "1",
// "discount": "5",
// "discount_type": "FIXED",
"item_price_snapshot": {
"pricing_rule": {
"price": "149.00"
}
}
// "item_price_tax": {
// "uuid": "e7dc5a26-ba38-41c9-8294-46e404b8d366",
// "code": "Tax",
// "rate": "0.000000"
// }
}
]
}
}{
"order": {
// "id": "ORD-ACC-T9XN-0231",
"account_id": "{{account_id}}",
"currency": "AUD",
// "redemption_code": "ITEM-0007",
// "communication_preference": [
// {
// "media": "EMAIL",
// "isEnabled": "true"
// },
// {
// "media": "POSTAL_EMAIL",
// "isEnabled": "true"
// },
// {
// "media": "TEXT_MESSAGE",
// "isEnabled": "true"
// },
// {
// "media": "VOICE_MAIL",
// "isEnabled": "true"
// }
// ],
"lines": [
{
"item_id": "ITEM-0001",
"package_name": "family",
"item_order_quantity": "-10",
"item_price_snapshot": {
"pricing_rule": {
"price": "100.0"
}
}
}
]
}
}{
"order": {
"account_id": "2561EE",
"lines": [
{
"item_id": "ITEM-0001",
"package_name": "family",
// "item_order_quantity": "10",
// "item_custom_attributes": [],
"item_price_snapshot": {
"pricing_rule": {
"price": "150"
// "uom": "Hectare",
// "warehouse": "warehouse 999",
// "pricing_schedule": "2024-01-12 00:00:00-2023-01-14 00:00:00",
// "pricing_level": "gold"
}
},
// "item_price_tax": {
// "uuid": "A658C712-DC95-4276-A6B5-5EAF072565DF"
// "code":"GST",
// "rate":"12.00"
},
{
"item_id": "ITEM-0002",
"package_name": "standard",
// "item_order_quantity": "10",
// "item_custom_attributes": [],
"item_price_snapshot": {
"pricing_rule": {
"price": "150"
// "uom": "Hectare",
// "warehouse": "warehouse 999",
// "pricing_schedule": "2024-01-12 00:00:00-2023-01-14 00:00:00",
// "pricing_level": "gold"
}
},
// "item_price_tax": {
// "uuid": "A658C712-DC95-4276-A6B5-5EAF072565DF",
// "code": "GST",
// "rate": "12.00"
// }
}
]
}
}{
"order": {
"account_id": "AADVVI",
"quote_order": "true",
"properties": {
"proforma_properties": {
"acceptance_required": true,
"acceptance_term": "1 Day",
"acceptance_mode": "MANUAL"
},
"invoice_mode": "MANUAL"
},
"lines": [
{
"item_accounting_code": "Sales Revenue",
"item_name": "Test Item",
"item_invoice_note": "note",
"item_order_quantity": "2",
"item_price": "31"
}
],
"custom_attributes": [
{
"name": "Job_ID",
"value": "trumpxyz"
}
]
}
}Response
When the order is successfully created, the API returns a complete order object containing all configuration details, including system-generated identifiers, timestamps, and calculated totals. The response confirms that the order has been recorded with its associated customer account, product lines, pricing details, contract settings, and related billing configurations. It also includes default system properties such as currency, billing periods, tax configurations, and references to linked invoices and items.
Response Body
{
"order": {
"status": "ACTIVE",
"id": "ORD-2561EE-0600",
"pre_order": "false",
"quote_order": "false",
"name": "Contract Discount Check 0.0.5",
"display_name": "Contract Discount Check 0.0.5",
"description": "",
"referral_account": "",
"customer_purchase_order_id": "",
"shipping_profile": {},
"shipping_cost": "0.000000",
"discount_profile": null,
"origin": "",
"custom_forms": {
"uuid": "cdabab76-ae49-4567-b2da-9d6b60b6a7ed",
"name": "Default for Order"
},
"currency": {
"uuid": "4f444464-defa-4180-a18e-e2bf4b5a84a1",
"name": "AUD",
"link": "https://dev-api.exsited.com/api/v1/currencies/4f444464-defa-4180-a18e-e2bf4b5a84a1"
},
"time_zone": {
"uuid": "990e82c3-8cc6-4cc6-a69c-77f9caaa8b61",
"name": "Australia/Melbourne",
"link": "https://dev-api.exsited.com/api/v1/time_zones/990e82c3-8cc6-4cc6-a69c-77f9caaa8b61"
},
"invoice_note": "",
"billing_start_date": "ORDER_START_DATE",
"order_start_date": "2025-11-03T00:00:00Z",
"next_billing_from_date": "2025-12-03 00:00:00.000000",
"next_billing_from_date_utc": "2025-12-02T13:00:00Z",
"price_tax_inclusive": "false",
"billing_address": {},
"shipping_address": {},
"created_by": "test5",
"created_on": "2025-11-03T10:36:53Z",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "a3aab472-6c94-48a7-9ad4-b80432413395",
"version": "1",
"account_id": "2561EE",
"account_name": "basic/express - data",
"allow_contract": "true",
"contract_properties": {
"require_customer_acceptance": "false",
"requires_payment_method": "false",
"initial_contract_term": "1 Year",
"renew_automatically": "false",
"allow_early_termination": "false",
"termination_accounting_code": "",
"allow_postponement": "false",
"allow_trial": "false",
"allow_downgrade": "true",
"period_before_downgrade": "",
"allow_downgrade_charge": "false",
"downgrade_charge_type": "Fixed",
"downgrade_charge_fixed": "",
"allow_upgrade": "true",
"termination_notice_period": ""
},
"custom_attributes": [],
"custom_objects": [],
"currency_id": "1",
"properties": {
"communication_profile": "",
"invoice_mode": "AUTOMATIC",
"invoice_term": "Billing Start Date",
"billing_period": "1 Month",
"consolidate_invoice": "false",
"payment_processor": "Cash",
"payment_mode": "MANUAL",
"payment_term": "Net 30",
"payment_term_alignment": "BILLING_DATE",
"fulfillment_mode": "MANUAL",
"fulfillment_term": "Immediately"
},
"invoice_id": "INV-2561EE-0671",
"lines": [
{
"charge_item_uuid": "28655b88-22c5-42a9-b853-ab102193e6f6",
"item_uuid": "a07f3435-6899-4b62-9f0f-5afc198bcf30",
"item_id": "ITEM-0001",
"item_name": "family item - family",
"item_order_quantity": "1.000000",
"shipping_cost": "0.00",
"item_invoice_note": "",
"item_description": "",
"item_type": "FAMILY",
"item_charge_type": "RECURRING",
"item_custom_attributes": [],
"item_properties": {
"billing_mode": "IN_ADVANCE",
"fixed_start_date": "",
"pro_rata_partial_unit": "false"
},
"item_price_snapshot": {
"pricing_rule": {
"uuid": "2535569c-7eff-47bd-9f5c-0b625eb65452",
"version": "3",
"price_type": "PER_UNIT_PRICING",
"price": "149.000000",
"uom": "",
"price_period": "",
"pricing_schedule": "",
"pricing_level": "",
"pricing_method": "0.000000",
"warehouse": "BareHouse"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "",
"tax_code": {
"uuid": "",
"code": "",
"rate": "",
"link": ""
}
},
"isTaxExemptWhenSold": "false",
"item_price_tax": {
"uuid": "58a36f3d-efaa-4ce7-bfc5-ce20c7330e6a",
"code": "No Tax",
"rate": 0.0000,
"link": "https://dev-api.exsited.com/api/v3/settings/taxes/58a36f3d-efaa-4ce7-bfc5-ce20c7330e6a"
},
"item_accounting_code": {
"sales_revenue": ""
},
"version": "1",
"expected_delivery_date": "",
"package_name": "family",
"purchase_order_id": "",
"purchase_invoice_id": "",
"discount": 0,
"total": "149",
"subtotal": "149",
"tax": "0"
}
],
"total": "149",
"subtotal": "149",
"tax": "0",
"kpis": {
"start_date": "",
"estimated_total": 0,
"total_revenue": 0,
"monthly_recurring_revenue": 0,
"total_collected": 0,
"total_outstanding": 0,
"total_due": 0,
"last_invoice_issue_date": "",
"last_invoice_total": 0,
"total_invoice": 0,
"next_invoice_issueDate": "",
"last_reactivated_on": "",
"last_cancelled_on": "",
"last_changed_on": "",
"last_deleted_on": ""
},
"line_items": []
}
}{
"order": {
// "id": "ORD-ACC-T9XN-0231",
"account_id": "{{account_id}}",
"currency": "AUD",
// "redemption_code": "ITEM-0007",
// "communication_preference": [
// {
// "media": "EMAIL",
// "isEnabled": "true"
// },
// {
// "media": "POSTAL_EMAIL",
// "isEnabled": "true"
// },
// {
// "media": "TEXT_MESSAGE",
// "isEnabled": "true"
// },
// {
// "media": "VOICE_MAIL",
// "isEnabled": "true"
// }
// ],
"lines": [
{
"item_id": "ITEM-0001",
"package_name": "family",
"item_order_quantity": "-10",
"item_price_snapshot": {
"pricing_rule": {
"price": "100.0"
}
}
}
]
}
}{
"order": {
"status": "ACTIVE",
"id": "ORD-2561EE-0603",
"pre_order": "false",
"quote_order": "false",
"name": "basic/express - data - family item",
"display_name": "basic/express - data - family item",
"description": "",
"referral_account": "",
"customer_purchase_order_id": "",
"shipping_profile": {},
"shipping_cost": "0.000000",
"discount_profile": null,
"origin": "",
"custom_forms": {
"uuid": "cdabab76-ae49-4567-b2da-9d6b60b6a7ed",
"name": "Default for Order"
},
"currency": {
"uuid": "4f444464-defa-4180-a18e-e2bf4b5a84a1",
"name": "AUD",
"link": "https://dev-api.exsited.com/api/v1/currencies/4f444464-defa-4180-a18e-e2bf4b5a84a1"
},
"time_zone": {
"uuid": "990e82c3-8cc6-4cc6-a69c-77f9caaa8b61",
"name": "Australia/Melbourne",
"link": "https://dev-api.exsited.com/api/v1/time_zones/990e82c3-8cc6-4cc6-a69c-77f9caaa8b61"
},
"invoice_note": "",
"billing_start_date": "ORDER_START_DATE",
"order_start_date": "2025-11-03T00:00:00Z",
"next_billing_from_date": "2025-12-03 00:00:00.000000",
"next_billing_from_date_utc": "2025-12-02T13:00:00Z",
"price_tax_inclusive": "false",
"billing_address": {},
"shipping_address": {},
"created_by": "test5",
"created_on": "2025-11-03T11:23:47Z",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "2e6f557d-96fa-4d72-af14-4ea964896ffd",
"version": "1",
"account_id": "2561EE",
"account_name": "basic/express - data",
"allow_contract": "false",
"custom_attributes": [],
"custom_objects": [],
"currency_id": "1",
"properties": {
"communication_profile": "",
"invoice_mode": "AUTOMATIC",
"invoice_term": "Billing Start Date",
"billing_period": "1 Month",
"consolidate_invoice": "false",
"payment_processor": "Cash",
"payment_mode": "MANUAL",
"payment_term": "Net 30",
"payment_term_alignment": "BILLING_DATE",
"fulfillment_mode": "MANUAL",
"fulfillment_term": "Immediately"
},
"invoice_id": "INV-2561EE-0674",
"lines": [
{
"charge_item_uuid": "ca695116-dd3a-4a43-a722-c85337826e32",
"item_uuid": "a07f3435-6899-4b62-9f0f-5afc198bcf30",
"item_id": "ITEM-0001",
"item_name": "family item - family",
"item_order_quantity": "1.000000",
"shipping_cost": "0.00",
"item_invoice_note": "",
"item_description": "",
"item_type": "FAMILY",
"item_charge_type": "RECURRING",
"item_custom_attributes": [],
"item_properties": {
"billing_mode": "IN_ADVANCE",
"fixed_start_date": "",
"pro_rata_partial_unit": "false"
},
"item_price_snapshot": {
"pricing_rule": {
"uuid": "2535569c-7eff-47bd-9f5c-0b625eb65452",
"version": "3",
"price_type": "PER_UNIT_PRICING",
"price": "150.000000",
"uom": "",
"price_period": "",
"pricing_schedule": "",
"pricing_level": "",
"pricing_method": "0.000000",
"warehouse": "BareHouse"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "",
"tax_code": {
"uuid": "",
"code": "",
"rate": "",
"link": ""
}
},
"isTaxExemptWhenSold": "false",
"item_price_tax": {
"uuid": "58a36f3d-efaa-4ce7-bfc5-ce20c7330e6a",
"code": "No Tax",
"rate": 0.0000,
"link": "https://dev-api.exsited.com/api/v3/settings/taxes/58a36f3d-efaa-4ce7-bfc5-ce20c7330e6a"
},
"item_accounting_code": {
"sales_revenue": ""
},
"version": "1",
"expected_delivery_date": "",
"package_name": "family",
"purchase_order_id": "",
"purchase_invoice_id": "",
"discount": 0,
"total": "150",
"subtotal": "150",
"tax": "0"
},
{
"charge_item_uuid": "581d1aa8-dc90-477a-a25d-3f4a8c7b94a8",
"item_uuid": "43cc872a-8baf-4b7b-9fa1-e7b454116e20",
"item_id": "ITEM-0002",
"item_name": "item 1",
"item_order_quantity": "1.000000",
"shipping_cost": "0.00",
"item_invoice_note": "",
"item_description": "",
"item_type": "STANDARD",
"item_charge_type": "RECURRING",
"item_custom_attributes": [],
"item_properties": {
"billing_mode": "IN_ADVANCE",
"fixed_start_date": "",
"pro_rata_partial_unit": "false"
},
"item_price_snapshot": {
"pricing_rule": {
"uuid": "981011da-b57c-48b3-b105-9471c1dd264d",
"version": "2",
"price_type": "PER_UNIT_PRICING",
"price": "150.000000",
"uom": "",
"price_period": "",
"pricing_schedule": "",
"pricing_level": "",
"pricing_method": "0.000000",
"warehouse": "BareHouse"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "SALES_TAX",
"tax_code": {
"uuid": "",
"code": "",
"rate": "",
"link": ""
}
},
"isTaxExemptWhenSold": "false",
"item_price_tax": {
"uuid": "58a36f3d-efaa-4ce7-bfc5-ce20c7330e6a",
"code": "No Tax",
"rate": 0.0000,
"link": "https://dev-api.exsited.com/api/v3/settings/taxes/58a36f3d-efaa-4ce7-bfc5-ce20c7330e6a"
},
"item_accounting_code": {
"sales_revenue": ""
},
"version": "1",
"expected_delivery_date": "",
"purchase_order_id": "",
"purchase_invoice_id": "",
"discount": 0,
"total": "150",
"subtotal": "150",
"tax": "0"
}
],
"total": "300",
"subtotal": "300",
"tax": "0",
"kpis": {
"start_date": "",
"estimated_total": 0,
"total_revenue": 0,
"monthly_recurring_revenue": 0,
"total_collected": 0,
"total_outstanding": 0,
"total_due": 0,
"last_invoice_issue_date": "",
"last_invoice_total": 0,
"total_invoice": 0,
"next_invoice_issueDate": "",
"last_reactivated_on": "",
"last_cancelled_on": "",
"last_changed_on": "",
"last_deleted_on": ""
},
"line_items": []
}
}{
"order": {
"status": "ACTIVE",
"id": "ORD-AADVVI-0649",
"pre_order": "false",
"quote_order": "true",
"quote_converted": "false",
"order_type": "QUOTE",
"name": "Test Hasan - Test Item",
"display_name": "Test Hasan - Test Item",
"description": "",
"referral_account": "",
"customer_purchase_order_id": "",
"shipping_profile": {},
"shipping_cost": "0.000000",
"discount_profile": null,
"origin": "",
"custom_forms": {
"uuid": "10f519f1-fbb6-4aad-b2a5-424e38efbf46",
"name": "Default for Order"
},
"currency": {
"uuid": "a0f921e3-921c-4e93-ba69-bb796fdc4a07",
"name": "AUD",
"link": "https://dev-api.exsited.com/api/v1/currencies/a0f921e3-921c-4e93-ba69-bb796fdc4a07"
},
"time_zone": {
"uuid": "57e820b5-260b-4fdf-abc9-b3fdcb7a71c8",
"name": "Australia/Melbourne",
"link": "https://dev-api.exsited.com/api/v1/time_zones/57e820b5-260b-4fdf-abc9-b3fdcb7a71c8"
},
"invoice_note": "",
"default_warehouse": "Default Warehouse",
"billing_start_date": "ORDER_START_DATE",
"order_start_date": "2026-01-25T00:00:00Z",
"next_billing_from_date": "",
"price_tax_inclusive": "false",
"billing_address": {},
"shipping_address": {},
"created_by": "Operon-dev",
"created_on": "2026-01-25T11:08:19Z",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "8d044150-1c75-4380-ba09-7d4f9a6fa700",
"version": "1",
"account_id": "AADVVI",
"account_name": "Test Hasan",
"allow_contract": "false",
"custom_attributes": [
{
"name": "Job_ID",
"value": "trumpxyz"
}
],
"custom_objects": [],
"currency_id": "1",
"properties": {
"communication_profile": "",
"invoice_mode": "MANUAL",
"invoice_term": "Billing Start Date",
"billing_period": "1 Day",
"consolidate_invoice": "false",
"payment_processor": "",
"payment_mode": "MANUAL",
"payment_term": "Net 30",
"payment_term_alignment": "",
"fulfillment_mode": "",
"fulfillment_term": "",
"proforma_properties": {
"acceptance_required": "true",
"payment_required": "false",
"acceptance_term": "1 Day",
"acceptance_date": "RequestDate",
"terms_and_conditions": ""
}
},
"invoice_id": "",
"lines": [
{
"charge_item_uuid": "6646c0bf-8434-4d19-9514-8b77fd33125d",
"item_uuid": "",
"item_id": "",
"item_name": "Test Item",
"item_order_quantity": "2.000000",
"shipping_cost": "0.00",
"item_invoice_note": "note",
"item_description": "",
"item_type": "",
"item_charge_type": "ONE_OFF",
"item_custom_attributes": [],
"item_price_snapshot": {
"pricing_rule": {
"uuid": "",
"version": "",
"price_type": "",
"price": "31.000000",
"uom": "",
"price_period": "",
"pricing_schedule": "",
"pricing_level": "",
"pricing_method": "0.000000"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "",
"tax_code": {
"uuid": "",
"code": "",
"rate": "",
"link": ""
}
},
"isTaxExemptWhenSold": "false",
"item_price_tax": {
"uuid": "d7feab49-c80c-4220-a80f-8b874c08526f",
"code": "No Tax",
"rate": 0.0000,
"link": "https://dev-api.exsited.com/api/v3/settings/taxes/d7feab49-c80c-4220-a80f-8b874c08526f"
},
"item_accounting_code": {
"sales_revenue": {
"name": "Sales Revenue"
}
},
"version": "1",
"expected_delivery_date": "",
"purchase_order_id": "",
"purchase_invoice_id": "",
"discount": 0,
"newTaxCodeSet": null,
"total": "31",
"subtotal": "31",
"tax": "0"
}
],
"total": "31",
"subtotal": "31",
"tax": "0",
"kpis": {
"estimated_total": 0,
"created_on": "",
"last_updated_on": ""
},
"line_items": [],
"activity_logs": [
{
"activity": "Operon-dev created Quote ORD-AADVVI-0649"
}
]
}
}Cancel an Order: /orders/{order_id}/cancel
Purpose
This endpoint cancels an existing order by marking its status as INACTIVE. The cancellation can take effect immediately or be scheduled for a future date based on the effective_date provided in the request.
Use Case
This endpoint is used when a customer or admin wants to stop an active recurring order. The function accepts an effective_date to control when the cancellation takes place. If the date is today , the order is immediately inactivated. If it is in the future, the order remains active until the scheduled cancellation date, allowing billing or service to continue for the current cycle.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | String | Unique identifier of the order. |
Query Parameters
No query parameters required for this endpoint.
Request Body
The request body includes the date when the cancellation should become effective. This allows support for both immediate and scheduled cancellations.
{
"order": {
"effective_date": "EFFECTIVE_DATE"
}
}| Attribute | Type | Description |
|---|---|---|
| order.effective_date | String | The date (YYYY-MM-DD) when the cancellation applies. |
Response
The API response confirms that the order has been successfully cancelled. It returns the updated order object, where the status is set to "INACTIVE", and includes associated metadata such as event_uuid, timestamps, item details, and all billing and fulfillment settings at the time of cancellation. Each line item is preserved with pricing, discount, and tax information to maintain a record of what was included in the order before it was cancelled. This comprehensive response ensures transparency and supports historical tracking of cancelled orders.
Response Body
{
"event_uuid": "EVENT_UUID",
"order": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"pre_order": "BOOLEAN",
"quote_order": "BOOLEAN",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"referral_account": "EMPTY",
"customer_purchase_order_id": "CUSTOMER_PO_ID",
"shipping_profile": {},
"shipping_cost": "DECIMAL_VALUE",
"discount_profile": null,
"origin": "ORDER_ORIGIN",
"custom_forms": {
"uuid": "CUSTOM_FORM_UUID",
"name": "CUSTOM_FORM_NAME"
},
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_CODE",
"link": "CURRENCY_API_LINK"
},
"time_zone": {
"uuid": "TIMEZONE_UUID",
"name": "TIMEZONE_NAME",
"link": "TIMEZONE_API_LINK"
},
"invoice_note": "INVOICE_NOTE",
"communication_preference": [
{
"media": "COMMUNICATION_MEDIA",
"isEnabled": "BOOLEAN"
}
],
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_TIMESTAMP",
"next_billing_from_date": "EMPTY",
"price_tax_inclusive": "BOOLEAN",
"billing_address": {},
"shipping_address": {},
"created_by": "CREATED_BY",
"created_on": "CREATION_TIMESTAMP",
"last_updated_by": "UPDATED_BY",
"last_updated_on": "UPDATE_TIMESTAMP",
"uuid": "ORDER_UUID",
"version": "VERSION",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"allow_contract": "BOOLEAN",
"custom_attributes": [],
"custom_objects": [],
"currency_id": "CURRENCY_ID",
"properties": {
"communication_profile": "COMMUNICATION_PROFILE",
"invoice_mode": "INVOICE_MODE",
"invoice_term": "INVOICE_TERM",
"billing_period": "BILLING_PERIOD",
"consolidate_invoice": "BOOLEAN",
"consolidate_key": "CONSOLIDATION_KEY",
"payment_processor": "PAYMENT_PROCESSOR",
"payment_mode": "PAYMENT_MODE",
"payment_term": "PAYMENT_TERM",
"payment_term_alignment": "PAYMENT_TERM_ALIGNMENT",
"fulfillment_mode": "FULFILLMENT_MODE",
"fulfillment_term": "FULFILLMENT_TERM"
},
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "DECIMAL_VALUE",
"shipping_cost": "DECIMAL_VALUE",
"item_invoice_note": "EMPTY",
"item_description": "EMPTY",
"item_type": "ITEM_TYPE",
"item_charge_type": "CHARGE_TYPE",
"item_custom_attributes": [],
"item_properties": {
"billing_mode": "BILLING_MODE",
"charging_period": "CHARGING_PERIOD",
"charging_start_date": "CHARGING_START_DATE",
"fixed_start_date": "EMPTY",
"charging_and_billing_alignment": "BOOLEAN",
"pro_rata_partial_charging_period": "BOOLEAN",
"pro_rata_partial_pricing_period": "BOOLEAN",
"pro_rata_partial_unit": "BOOLEAN"
},
"item_price_snapshot": {
"pricing_rule": {
"uuid": "PRICING_RULE_UUID",
"version": "VERSION",
"price_type": "PRICE_TYPE",
"price": "DECIMAL_VALUE",
"uom": "EMPTY",
"price_period": "EMPTY",
"pricing_schedule": "EMPTY",
"pricing_level": "EMPTY",
"pricing_method": "DECIMAL_VALUE",
"warehouse": "WAREHOUSE_NAME"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "TAX_BASIS",
"tax_code": {
"uuid": "EMPTY",
"code": "EMPTY",
"rate": "EMPTY",
"link": "EMPTY"
}
},
"isTaxExemptWhenSold": "BOOLEAN",
"item_price_tax": {
"uuid": "EMPTY",
"code": "EMPTY",
"rate": "DECIMAL_VALUE",
"link": "EMPTY"
},
"item_accounting_code": {
"sales_revenue": "EMPTY"
},
"version": "VERSION",
"expected_delivery_date": "EMPTY",
"discount": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE",
"subtotal": "DECIMAL_VALUE",
"tax": "DECIMAL_VALUE"
}
],
"total": "DECIMAL_VALUE",
"subtotal": "DECIMAL_VALUE",
"tax": "DECIMAL_VALUE",
"kpis": {
"start_date": "EMPTY",
"estimated_total": "DECIMAL_VALUE",
"total_revenue": "DECIMAL_VALUE",
"monthly_recurring_revenue": "DECIMAL_VALUE",
"total_collected": "DECIMAL_VALUE",
"total_outstanding": "DECIMAL_VALUE",
"total_due": "DECIMAL_VALUE",
"last_invoice_issue_date": "EMPTY",
"last_invoice_total": "DECIMAL_VALUE",
"total_invoice": "DECIMAL_VALUE",
"next_invoice_issueDate": "EMPTY",
"last_reactivated_on": "EMPTY",
"last_cancelled_on": "EMPTY",
"last_changed_on": "EMPTY",
"last_deleted_on": "EMPTY"
},
"line_items": []
}
}| Attribute | Type | Description |
|---|---|---|
| event_uuid | String | Unique identifier associated with the cancellation event. |
| order.status | String | Updated status of the order, set to "INACTIVE" after cancellation. |
| order.id | String | Unique identifier of the cancelled order. |
| order.name | String | Name or label of the order. |
| order.description | String | Description of the order content. |
| order.currency.name | String | Currency used for the order ("AUD"). |
| order.time_zone.name | String | Time zone configured for the order . |
| order.communication_preference | Array | List of communication methods enabled for the order . |
| order.created_by | String | Name of the user who created the order. |
| order.created_on | String | Timestamp of when the order was originally created. |
| order.last_updated_by | String | Name of the user who last modified the order. |
| order.last_updated_on | String | Timestamp of the most recent update to the order. |
| order.lines | Array | List of items in the order with pricing, quantity, and tax configurations. |
| order.total | String | Final total price of the order after applying discounts. |
| order.tax | String | Total tax amount applied to the order. |
| order.subtotal | String | Total amount before tax and discount. |
| order.properties | Object | Configuration of billing, payment, and fulfillment policies. |
| order.kpis | Object | Key performance indicators related to revenue, invoices, and collection. |
Reactivate an Order : /orders/{order_id}/reactivate
Purpose
This endpoint reactivate an order that was previously marked as inactive or cancelled. It updates the order’s status based on a provided effective date and schedules reactivation accordingly.
Use Case
The endpoint is used when a previously cancelled order needs to be reinstated. If the effective_date is the current date, the system will reactivate the order immediately. If the date is set in the future, the order remains in a pending state until that date arrives. This is especially useful for subscription or billing systems that allow temporary suspension of services with a scheduled reactivation.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | String | Unique identifier of the order. |
Query Parameters
No query parameters required for this endpoint.
Request Body
The request body includes the effective_date, which specifies when the order should become active again.
{
"account": {
"effective_date": "EFFECTIVE_DATE"
}
}| Attribute | Type | Description |
|---|---|---|
| order.effective_date | String | The date (YYYY-MM-DD) to reactivate the order. |
Response
The endpoint return a successful reactivation request object containing an event_uuid that uniquely identifies the reactivation event. This UUID can be used for tracking or audit purposes.
Response Body
{
"event_uuid": "EVENT_UUID"
}| Attribute | Type | Description |
|---|---|---|
| event_uuid | String | UUID representing the order reactivation event. |
Create Order Note: /orders/{order_id}/notes
Purpose
This endpoint creates a new note for a specific order. It supports both plain text notes and file attachments, making it useful for order-related documentation, attaching receipts, scanned documents, or additional remarks.
Use Case
- Add internal or customer-facing notes to an order.
- Attach supporting files (e.g., images, invoices, receipts) directly to an order.
- Maintain a timeline of comments and attachments for order tracking.
- Provide documentation for audits, compliance, or customer communication.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| order_id | string | Yes | Unique identifier of the order to which the note will be added. |
Query Parameters
This endpoint does not support query parameters.
Request Body
The request must be sent as multipart/form-data.
| Attribute | Type | Description |
|---|---|---|
| note | string | Content of the note. |
| file | file | File to attach with the note. Accepts common document and image formats. |
Response
On success, the API returns the order object containing a notes object with the UUID of the newly created note. This UUID can later be used to fetch note details, list attached files, or download specific files.
Response Body
{
"order": {
"notes": {
"uuid": "UUID"
}
}
}| Attribute | Type | Description |
|---|---|---|
| order | object | Container object holding the response data. |
| order.notes | object | Object representing the newly created note. |
| order.notes.uuid | string (UUID) | Unique identifier of the created note. |
Upload File Attachment to an Order Note: /orders/{order_id}/notes/{note_uuid}
Purpose
This API allows users to upload one or more files as attachments to an existing order note in the system. The uploaded files are associated with a specific order and note UUID, enabling users to maintain documentation or evidence (such as images, reports, or other files) directly within the order’s record.
Use Case
Businesses often need to attach files such as delivery receipts, photos, inspection documents, or reports to order notes for tracking or audit purposes. This API supports uploading files to an order note using multipart/form-data. Each uploaded file becomes part of the order note, which can be retrieved later for reference or verification.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | String | Unique identifier of the order to which the note belongs. |
| note_uuid | UUID | Unique identifier of the note where the file attachment will be uploaded. |
Query Parameters
This endpoint does not accept query parameters.
Request Body
The request must be sent as multipart/form-data.
| Attribute | Type | Description |
|---|---|---|
| file | File | File to attach with the note. Accepts common document and image formats such as PDF, PNG, JPG, DOCX, etc. Multiple files can be uploaded sequentially for the same note. |
Response
Upon successful upload, the API returns a confirmation response containing the order note details and a list of files associated with that note. Each file entry includes its name, confirming that the attachment has been successfully linked to the order note. The response ensures that the uploaded files are correctly stored and retrievable within the order record.
Response Body
{
"order": {
"notes": {
"content": "<p><NOTE_CONTENT></p>",
"files": [
{
"name": "<FILE_NAME_1>"
},
{
"name": "<FILE_NAME_2>"
}
]
}
}
}
| Attribute | Type | Description |
|---|---|---|
| order | Object | Contains details of the order associated with the uploaded note. |
| notes | Object | Represents the note record within the order. |
| content | String | The content or text body of the note. |
| files | Array | List of file objects attached to the note. |
| name | String | The filename of the uploaded file. |
Activate an Order: /orders/{order_id}/activate
Purpose
This endpoint activates an existing order by setting its effective activation date. Once activated, the order transitions to ACTIVE status and triggers billing logic, pricing schedules, communication preferences, and other configured order-level behaviors within the system.
Use Case
Use this endpoint when:
- An order has been created in Draft or Pending Activation state.
- The customer has approved the order and the activation date is confirmed.
- You need to start billing cycles, fulfillment workflows, recurring charges, and other automated processes tied to the order’s lifecycle.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | string | The unique identifier of the order to activate. |
Query Parameters
This endpoint does not accept query parameters.
Request Body
{
"order": {
"effective_date": "YYYY-MM-DD"
}
}
| Attribute | Type | Description |
|---|---|---|
| order | object | Wrapper object containing activation information. |
| order.effective_date | string (date) | The date on which the order becomes effective. Must follow YYYY-MM-DD format. |
Response
Upon successful activation, the API returns a detailed representation of the activated order. This includes the updated status (ACTIVE), computed billing dates, time zone information, communication preferences, pricing structures, order lines, KPIs, and internal system metadata. The response confirms that the order has transitioned from a non-active state into an active lifecycle state, enabling billing, fulfillment, and revenue processes.
Response Body
{
"order": {
"status": "ACTIVE",
"id": "ORDER_ID",
"pre_order": "BOOLEAN_VALUE",
"quote_order": "BOOLEAN_VALUE",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"referral_account": "REFERRAL_ACCOUNT_VALUE",
"customer_purchase_order_id": "CUSTOMER_PO_VALUE",
"shipping_profile": {},
"shipping_cost": "DECIMAL_VALUE",
"discount_profile": null,
"origin": "ORIGIN_VALUE",
"custom_forms": {
"uuid": "CUSTOM_FORM_UUID",
"name": "CUSTOM_FORM_NAME"
},
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_NAME",
"link": "CURRENCY_LINK"
},
"time_zone": {
"uuid": "TIME_ZONE_UUID",
"name": "TIME_ZONE_NAME",
"link": "TIME_ZONE_LINK"
},
"invoice_note": "INVOICE_NOTE_VALUE",
"communication_preference": [
{
"media": "MEDIA_TYPE",
"enabled": "BOOLEAN_VALUE"
}
],
"billing_start_date": "BILLING_START_DATE_VALUE",
"order_start_date": "ORDER_START_DATE_VALUE",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE_VALUE",
"next_billing_from_date_utc": "NEXT_BILLING_FROM_DATE_UTC_VALUE",
"price_tax_inclusive": "BOOLEAN_VALUE",
"billing_address": {},
"shipping_address": {},
"created_by": "CREATED_BY_USER",
"created_on": "CREATED_ON_TIMESTAMP",
"last_updated_by": "LAST_UPDATED_BY_USER",
"last_updated_on": "LAST_UPDATED_ON_TIMESTAMP",
"uuid": "ORDER_UUID",
"version": "VERSION_NUMBER",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"account_email_address": "ACCOUNT_EMAIL",
"allow_contract": "BOOLEAN_VALUE",
"custom_attributes": [],
"custom_objects": [],
"currency_id": "CURRENCY_ID",
"properties": {
"communication_profile": "COMM_PROFILE_VALUE",
"invoice_mode": "INVOICE_MODE_VALUE",
"invoice_term": "INVOICE_TERM_VALUE",
"billing_period": "BILLING_PERIOD_VALUE",
"consolidate_invoice": "BOOLEAN_VALUE",
"payment_processor": "PAYMENT_PROCESSOR_VALUE",
"payment_mode": "PAYMENT_MODE_VALUE",
"payment_term": "PAYMENT_TERM_VALUE",
"payment_term_alignment": "TERM_ALIGNMENT_VALUE",
"fulfillment_mode": "FULFILLMENT_MODE_VALUE",
"fulfillment_term": "FULFILLMENT_TERM_VALUE"
},
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "QUANTITY_VALUE",
"shipping_cost": "DECIMAL_VALUE",
"item_invoice_note": "ITEM_NOTE_VALUE",
"item_description": "ITEM_DESCRIPTION_VALUE",
"item_type": "ITEM_TYPE",
"item_charge_type": "CHARGE_TYPE",
"item_custom_attributes": [],
"item_properties": {
"billing_mode": "BILLING_MODE_VALUE"
},
"item_price_snapshot": {
"pricing_rule": {
"uuid": "PRICING_RULE_UUID",
"version": "RULE_VERSION",
"price_type": "PRICE_TYPE_VALUE",
"price": "PRICE_VALUE",
"uom": "UOM_VALUE",
"price_period": "PRICE_PERIOD_VALUE",
"pricing_schedule": "PRICING_SCHEDULE_VALUE",
"pricing_level": "PRICING_LEVEL_VALUE",
"pricing_method": "PRICING_METHOD_VALUE",
"warehouse": "WAREHOUSE_NAME"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "TAX_BASE_VALUE",
"tax_code": {
"uuid": "TAX_CODE_UUID",
"code": "TAX_CODE_VALUE",
"rate": "TAX_RATE_VALUE",
"link": "TAX_CODE_LINK"
}
},
"tax_exempt_when_sold": "BOOLEAN_VALUE",
"item_price_tax": {
"uuid": "TAX_UUID",
"code": "TAX_CODE_VALUE",
"rate": 0,
"link": "TAX_LINK"
},
"item_accounting_code": {
"sales_revenue": "ACCOUNTING_CODE_VALUE"
},
"version": "LINE_VERSION",
"expected_delivery_date": "EXPECTED_DELIVERY_DATE_VALUE",
"purchase_order_id": "PO_ID_VALUE",
"purchase_invoice_id": "PI_ID_VALUE"
}
],
"kpis": {
"start_date": "START_DATE_VALUE",
"estimated_total": 0,
"total_revenue": 0,
"monthly_recurring_revenue": 0,
"total_collected": 0,
"total_outstanding": 0,
"total_due": 0,
"last_invoice_issue_date": "LAST_INVOICE_ISSUE_DATE_VALUE",
"last_invoice_total": 0,
"total_invoice": 0,
"next_invoice_issue_date": "NEXT_INVOICE_DATE_VALUE",
"last_reactivated_on": "LAST_REACTIVATED_DATE_VALUE",
"last_cancelled_on": "LAST_CANCELLED_DATE_VALUE",
"last_changed_on": "LAST_CHANGED_DATE_VALUE",
"last_deleted_on": "LAST_DELETED_DATE_VALUE"
},
"line_items": []
}
}
| Attribute | Type | Description |
|---|---|---|
| order | object | Contains all activated order details. |
| order.status | string | The updated order status, set to ACTIVE. |
| order.id | string | System-generated order identifier. |
| order.pre_order | string | Indicates if the order is a pre-order. |
| order.quote_order | string | Indicates if the order is derived from a quote. |
| order.name | string | Order name. |
| order.display_name | string | Display name for UI. |
| order.description | string | Optional explanation or notes. |
| order.currency | object | Currency applied to the order. |
| order.time_zone | object | Time zone associated with the order. |
| order.billing_start_date | string | Calculated billing start date after activation. |
| order.order_start_date | string | Activation timestamp. |
| order.communication_preference | array | List of enabled communication channels. |
| order.properties | object | Billing, payment, and fulfillment settings. |
| order.lines | array | Order line items after activation. |
| order.kpis | object | Order KPIs and financial statistics. |
Modify an Existing Order: /orders/{order_id}/change
Purpose
This endpoint allows users to apply changes to an existing order by adding, removing, or modifying order line items. It also supports setting the effective date for when the changes become active. This enables billing adjustments, pricing updates, item quantity changes, and line item restructuring without recreating the order.
Use Case
- Updating an existing order after customer requests modifications.
- Increasing or decreasing quantities for specific items already in the order.
- Updating pricing structures due to promotions or pricing rule changes.
- Removing incorrect or no-longer-required order items.
- Adding new line items to an active order.
- Adjusting billing and invoicing by changing the effective date of the order update.
- Managing contract or subscription adjustments in mid-cycle.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | string | Unique identifier of the order to be modified. Required. |
Query Parameters
This endpoint does not accept query parameters.
Request Body
{
"order": {
"effective_date": "EFFECTIVE_DATE_PLACEHOLDER",
"lines": [
{
"op": "REMOVE_OR_CHANGE_OR_ADD",
"uuid": "LINE_ITEM_UUID_PLACEHOLDER",
"item_id": "ITEM_ID_PLACEHOLDER",
"item_order_quantity": "ITEM_QUANTITY_PLACEHOLDER",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE_PLACEHOLDER",
"uom": "UOM_PLACEHOLDER"
}
}
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
| order | object | Container object for order update details. |
| order.effective_date | string | Date (YYYY-MM-DD) on which the order change becomes effective. |
| order.lines | array | List of operations to perform on order line items. |
| order.lines[].op | string | Operation type: add, remove or change. |
| order.lines[].uuid | string | UUID of the charge item (required for remove and change). |
| order.lines[].item_id | string | Item ID for new line additions (required for add). |
| order.lines[].item_order_quantity | string | Quantity to add or update, depending on operation (op). |
| order.lines[].item_price_snapshot | object | Price structure to apply to the item. |
| order.lines[].item_price_snapshot.pricing_rule | object | Pricing rule snapshot at time of modification. |
| order.lines[].item_price_snapshot.pricing_rule.price | string | Price for the item. |
| order.lines[].item_price_snapshot.pricing_rule.uom | string | Unit of measurement (optional). |
Response
The response returns the updated order object along with a unique event UUID that represents this modification event. It includes refreshed order metadata, current billing and pricing information, updated timestamps, and the final state of all line items after the applied changes. The system recalculates totals, taxes, discounts, and other financial fields based on the modifications, ensuring the returned object always represents the authoritative up-to-date order snapshot.
Response Body
{
"event_uuid": "EVENT_UUID_PLACEHOLDER",
"order": {
"status": "STATUS_PLACEHOLDER",
"id": "ORDER_ID_PLACEHOLDER",
"pre_order": "BOOLEAN_PLACEHOLDER",
"quote_order": "BOOLEAN_PLACEHOLDER",
"name": "ORDER_NAME_PLACEHOLDER",
"display_name": "ORDER_DISPLAY_NAME_PLACEHOLDER",
"description": "DESCRIPTION_PLACEHOLDER",
"referral_account": "REFERRAL_ACCOUNT_PLACEHOLDER",
"customer_purchase_order_id": "CUSTOMER_PO_ID_PLACEHOLDER",
"shipping_profile": {},
"shipping_cost": "SHIPPING_COST_PLACEHOLDER",
"discount_profile": "DISCOUNT_PROFILE_PLACEHOLDER",
"origin": "ORIGIN_PLACEHOLDER",
"custom_forms": {
"uuid": "FORM_UUID_PLACEHOLDER",
"name": "FORM_NAME_PLACEHOLDER"
},
"currency": {
"uuid": "CURRENCY_UUID_PLACEHOLDER",
"name": "CURRENCY_NAME_PLACEHOLDER",
"link": "CURRENCY_LINK_PLACEHOLDER"
},
"time_zone": {
"uuid": "TIMEZONE_UUID_PLACEHOLDER",
"name": "TIMEZONE_NAME_PLACEHOLDER",
"link": "TIMEZONE_LINK_PLACEHOLDER"
},
"invoice_note": "INVOICE_NOTE_PLACEHOLDER",
"communication_preference": [],
"billing_start_date": "BILLING_START_DATE_PLACEHOLDER",
"order_start_date": "ORDER_START_DATE_PLACEHOLDER",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE_PLACEHOLDER",
"price_tax_inclusive": "BOOLEAN_PLACEHOLDER",
"billing_address": {},
"shipping_address": {},
"created_by": "CREATED_BY_PLACEHOLDER",
"created_on": "CREATED_ON_PLACEHOLDER",
"last_updated_by": "LAST_UPDATED_BY_PLACEHOLDER",
"last_updated_on": "LAST_UPDATED_ON_PLACEHOLDER",
"uuid": "ORDER_UUID_PLACEHOLDER",
"version": "ORDER_VERSION_PLACEHOLDER",
"account_id": "ACCOUNT_ID_PLACEHOLDER",
"account_name": "ACCOUNT_NAME_PLACEHOLDER",
"allow_contract": "BOOLEAN_PLACEHOLDER",
"custom_attributes": [],
"custom_objects": [],
"currency_id": "CURRENCY_ID_PLACEHOLDER",
"properties": {},
"invoice_id": "INVOICE_ID_PLACEHOLDER",
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID_PLACEHOLDER",
"item_uuid": "ITEM_UUID_PLACEHOLDER",
"item_id": "ITEM_ID_PLACEHOLDER",
"item_name": "ITEM_NAME_PLACEHOLDER",
"item_order_quantity": "ITEM_QUANTITY_PLACEHOLDER",
"shipping_cost": "SHIPPING_COST_PLACEHOLDER",
"item_invoice_note": "ITEM_INVOICE_NOTE_PLACEHOLDER",
"item_description": "ITEM_DESCRIPTION_PLACEHOLDER",
"item_type": "ITEM_TYPE_PLACEHOLDER",
"item_charge_type": "CHARGE_TYPE_PLACEHOLDER",
"item_custom_attributes": [],
"item_price_snapshot": {
"pricing_rule": {
"uuid": "PRICING_RULE_UUID_PLACEHOLDER",
"version": "PRICING_RULE_VERSION_PLACEHOLDER",
"price_type": "PRICE_TYPE_PLACEHOLDER",
"price": "PRICE_PLACEHOLDER",
"uom": "UOM_PLACEHOLDER",
"price_period": "PRICE_PERIOD_PLACEHOLDER",
"pricing_schedule": "PRICING_SCHEDULE_PLACEHOLDER",
"pricing_level": "PRICING_LEVEL_PLACEHOLDER",
"pricing_method": "PRICING_METHOD_PLACEHOLDER",
"warehouse": "WAREHOUSE_PLACEHOLDER"
}
},
"item_sale_tax_configuration": {},
"isTaxExemptWhenSold": "BOOLEAN_PLACEHOLDER",
"item_price_tax": {},
"item_accounting_code": {},
"version": "LINE_VERSION_PLACEHOLDER",
"expected_delivery_date": "DELIVERY_DATE_PLACEHOLDER",
"purchase_order_id": "PO_ID_PLACEHOLDER",
"purchase_invoice_id": "PI_ID_PLACEHOLDER",
"discount": "DISCOUNT_PLACEHOLDER",
"total": "LINE_TOTAL_PLACEHOLDER",
"subtotal": "LINE_SUBTOTAL_PLACEHOLDER",
"tax": "LINE_TAX_PLACEHOLDER"
}
],
"total": "ORDER_TOTAL_PLACEHOLDER",
"subtotal": "ORDER_SUBTOTAL_PLACEHOLDER",
"tax": "ORDER_TAX_PLACEHOLDER",
"kpis": {},
"line_items": []
}
}
| Attribute | Type | Description |
|---|---|---|
| event_uuid | string | Unique event UUID representing this order modification. |
| order | object | The complete updated order object with recalculated totals. |
| order.status | string | Status of the order (example: ACTIVE). |
| order.id | string | System-generated order identifier. |
| order.pre_order | string | Indicates if the order was created as a pre-order. |
| order.quote_order | string | Indicates if the order is a quotation order. |
| order.name | string | Order name. |
| order.display_name | string | Display-friendly order name. |
| order.description | string | Description of the order. |
| order.origin | string | Value showing where the order originated from. |
| order.custom_forms | object | Assigned custom form metadata. |
| order.currency | object | Currency information for the order. |
| order.time_zone | object | Time zone of the order/account. |
| order.billing_start_date | string | Order billing start date. |
| order.order_start_date | string | Effective order start date. |
| order.price_tax_inclusive | string | Indicates if prices include tax. |
| order.lines | array | All updated line items. |
| order.lines[].op | string | Operation applied: add/remove/change. |
| order.lines[].uuid | string | Charge item UUID. |
| order.lines[].item_id | string | Associated item ID. |
| order.lines[].item_order_quantity | string | Updated item quantity. |
| order.lines[].item_price_snapshot | object | Final snapshot of pricing rules. |
| order.total | string | Total order amount. |
| order.subtotal | string | Subtotal before tax. |
| order.tax | string | Total tax. |
| order.kpis | object | Key performance indicators for the order. |
Create Pre Order: /orders
Purpose
This API endpoint is used to create a new order within the system. It allows clients to define whether the order is a pre-order, specify the customer account, include line items, and optionally provide pricing or snapshot details. The API returns the fully constructed order object, including system-generated metadata such as IDs, UUIDs, pricing snapshots, billing configuration, KPIs, and other order-related details.
Use Case
- Creating a new customer order using the minimum required fields (account ID and line items).
- Creating a pre-order to reserve stock before fulfillment.
- Adding item quantities and automatically generating default pricing snapshots based on the item configuration.
- Preparing order data for subsequent invoicing, fulfillment, or contract creation.
- Validating billing parameters, order structure, and line item correctness before further processing.
Path Parameters
This endpoint does not accept path parameters.
Query Parameters
This endpoint does not accept query parameters.
Request Body
{
"order": {
"pre_order": "true_or_false",
"account_id": "ACCOUNT_ID_PLACEHOLDER",
"price_tax_inclusive": "true_or_false",
"lines": [
{
"item_id": "ITEM_ID_PLACEHOLDER",
"item_order_quantity": "QUANTITY_PLACEHOLDER"
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
| order | object | Wrapper object containing order details. |
| order.pre_order | string | Indicates whether this is a pre-order (true or false). |
| order.account_id | string | Unique ID of the customer account associated with the order. |
| order.price_tax_inclusive | string | Indicates whether item prices include tax. |
| order.lines | array | List of line items included in the order. |
| order.lines[].item_id | string | ID of the item being ordered. |
| order.lines[].item_order_quantity | string | Quantity of the item to order. |
Response
The response returns the full order object after successful creation. It includes system-generated IDs, UUIDs, start dates, time zone, currency details, billing rules, order properties, pricing snapshots, tax configuration, KPIs, and line item data. The response also confirms metadata such as who created the order, when it was created, internal versioning, and additional attributes or objects attached to the order. This allows the client to immediately work with a complete and validated order record along with all system-generated calculations and defaults.
Response Body
{
"order": {
"status": "STATUS_PLACEHOLDER",
"id": "ORDER_ID_PLACEHOLDER",
"pre_order": "true_or_false",
"quote_order": "true_or_false",
"name": "ORDER_NAME_PLACEHOLDER",
"display_name": "ORDER_DISPLAY_NAME_PLACEHOLDER",
"description": "",
"referral_account": "",
"customer_purchase_order_id": "",
"shipping_profile": {},
"shipping_cost": "SHIPPING_COST_PLACEHOLDER",
"discount_profile": null,
"origin": "",
"custom_forms": {
"uuid": "FORM_UUID_PLACEHOLDER",
"name": "FORM_NAME_PLACEHOLDER"
},
"currency": {
"uuid": "CURRENCY_UUID_PLACEHOLDER",
"name": "CURRENCY_NAME_PLACEHOLDER",
"link": "CURRENCY_LINK_PLACEHOLDER"
},
"time_zone": {
"uuid": "TIMEZONE_UUID_PLACEHOLDER",
"name": "TIMEZONE_NAME_PLACEHOLDER",
"link": "TIMEZONE_LINK_PLACEHOLDER"
},
"invoice_note": "",
"billing_start_date": "BILLING_START_DATE_PLACEHOLDER",
"order_start_date": "ORDER_START_DATE_PLACEHOLDER",
"next_billing_from_date": "",
"price_tax_inclusive": "true_or_false",
"billing_address": {},
"shipping_address": {},
"created_by": "CREATED_BY_PLACEHOLDER",
"created_on": "CREATED_ON_PLACEHOLDER",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "ORDER_UUID_PLACEHOLDER",
"version": "VERSION_NUMBER_PLACEHOLDER",
"account_id": "ACCOUNT_ID_PLACEHOLDER",
"account_name": "ACCOUNT_NAME_PLACEHOLDER",
"allow_contract": "true_or_false",
"custom_attributes": [],
"custom_objects": [],
"currency_id": "CURRENCY_ID_PLACEHOLDER",
"properties": {
"communication_profile": "",
"invoice_mode": "INVOICE_MODE_PLACEHOLDER",
"invoice_term": "INVOICE_TERM_PLACEHOLDER",
"billing_period": "BILLING_PERIOD_PLACEHOLDER",
"consolidate_invoice": "true_or_false",
"payment_processor": "PAYMENT_PROCESSOR_PLACEHOLDER",
"payment_mode": "PAYMENT_MODE_PLACEHOLDER",
"payment_term": "PAYMENT_TERM_PLACEHOLDER",
"payment_term_alignment": "ALIGNMENT_PLACEHOLDER",
"fulfillment_mode": "FULFILLMENT_MODE_PLACEHOLDER",
"fulfillment_term": "FULFILLMENT_TERM_PLACEHOLDER"
},
"invoice_id": "",
"lines": [],
"total": "TOTAL_PLACEHOLDER",
"subtotal": "SUBTOTAL_PLACEHOLDER",
"tax": "TAX_PLACEHOLDER",
"kpis": {
"start_date": "",
"estimated_total": 0,
"total_revenue": 0,
"monthly_recurring_revenue": 0,
"total_collected": 0,
"total_outstanding": 0,
"total_due": 0,
"last_invoice_issue_date": "",
"last_invoice_total": 0,
"total_invoice": 0,
"next_invoice_issueDate": "",
"last_reactivated_on": "",
"last_cancelled_on": "",
"last_changed_on": "",
"last_deleted_on": ""
},
"line_items": []
}
}
| Attribute | Type | Description |
|---|---|---|
| order | object | Wrapper object containing all order information. |
| order.status | string | Current status of the order (example: ACTIVE). |
| order.id | string | System-generated unique order ID. |
| order.pre_order | string | Indicates if this is a pre-order. |
| order.quote_order | string | Indicates if the order is a quotation. |
| order.name | string | Internal name of the order. |
| order.display_name | string | Human-readable order display name. |
| order.description | string | Optional order description. |
| order.referral_account | string | Referral account ID, if provided. |
| order.customer_purchase_order_id | string | External purchase order reference, if provided. |
| order.shipping_profile | object | Shipping configuration. |
| order.shipping_cost | string | Total shipping cost applied to the order. |
| order.discount_profile | object/null | Applied discount profile, if any. |
| order.origin | string | Defines the origin source of the order. |
| order.custom_forms | object | Form details linked to the order. |
| order.currency | object | Currency details used for the order. |
| order.time_zone | object | Time zone used for date/time calculations. |
| order.invoice_note | string | Note that will appear on invoices. |
| order.billing_start_date | string | Billing start date of the order. |
| order.order_start_date | string | Actual start date of the order. |
| order.next_billing_from_date | string | Next billing reference date. |
| order.price_tax_inclusive | string | Indicates if order prices include tax. |
| order.created_by | string | User who created the order. |
| order.created_on | string | Timestamp of order creation. |
| order.uuid | string | System-generated order UUID. |
| order.version | string | Internal revision version of the order. |
| order.account_id | string | Account ID linked to the order. |
| order.account_name | string | Account name linked to the order. |
| order.allow_contract | string | Whether the order can generate a contract. |
| order.custom_attributes | array | Custom attribute values for the order. |
| order.custom_objects | array | Custom objects for the order. |
| order.currency_id | string | Currency numeric ID. |
| order.properties | object | Billing and operational configuration for the order. |
| order.invoice_id | string | Related invoice ID if generated. |
| order.total | string | Total order value. |
| order.subtotal | string | Order subtotal. |
| order.tax | string | Total tax amount. |
| order.kpis | object | Performance indicators for the order. |
| order.line_items | array | Detailed line item breakdown. |
Change Order Workflow Status: /orders/{order_id}/change_status
Purpose
This API updates the workflow status of an existing order to Quote Approved, indicating that the customer has accepted the quoted terms and the order is approved to proceed to the next stage of the business workflow.
Use Case
This endpoint is used when a quote associated with an order has been accepted by the customer and the system needs to transition the order’s workflow state accordingly. It is commonly triggered after customer approval actions, automated approval flows, or internal confirmations to ensure the order lifecycle progresses correctly.
Path Parameters
| Attribute | Type | Description |
|---|---|---|
| order_id | String | Unique identifier of the order whose workflow status needs to be updated |
Query Parameters
This endpoint does not support query parameters
Request Body
{
"order": {
"workflow_status": "<WORKFLOW_STATUS>"
}
}
| Attribute | Type | Description |
|---|---|---|
| order | Object | Container object holding order-related update data |
| order.workflow_status | String | New workflow status to be applied to the order (e.g., Quote Approved) |
Response
On successful execution, the API confirms that the order’s workflow status has been updated successfully. The response indicates that the workflow transition has been completed without errors, ensuring the order is now aligned with the accepted quote state and ready for subsequent processing steps.
Response Body
{
"message": "<STATUS_MESSAGE>"
}
| Attribute | Type | Description |
|---|---|---|
| message | String | Confirmation message indicating successful workflow status change |
Convert Quote or Booking to Active Order: /orders/{order_id}/convert_to_order
Purpose
This API converts an existing quote or booking into an active order. Once converted, the order becomes operational within the system, enabling downstream processes such as invoicing, fulfillment, billing, and reporting.
Use Case
This endpoint is used when a customer-approved quote or booking needs to be finalized and activated as a standard order. It is typically triggered after quote acceptance, internal approval workflows, or automated order processing rules, ensuring the order enters the active lifecycle with all associated financial, billing, and item details preserved.
Path Parameters
| Attribute | Type | Description |
|---|---|---|
| order_id | String | Unique identifier of the quote or booking that needs to be converted into an active order |
Query Parameters
This endpoint does not support query parameters
Request Body
This endpoint does not require a request body
Response
Upon successful execution, the API returns the fully converted active order object. The response includes comprehensive order details such as status, identifiers, account information, billing configuration, currency, time zone, line items, pricing snapshots, tax configurations, financial totals, KPIs, and related metadata. This confirms that the quote or pre-order has been successfully converted into an active order and is ready for billing, fulfillment, and operational workflows.
Response Body
{
"order": {
"status": "<ORDER_STATUS>",
"id": "<ORDER_ID>",
"pre_order": "<BOOLEAN>",
"quote_order": "<BOOLEAN>",
"name": "<ORDER_NAME>",
"display_name": "<ORDER_DISPLAY_NAME>",
"description": "<DESCRIPTION>",
"referral_account": "<REFERRAL_ACCOUNT>",
"customer_purchase_order_id": "<CUSTOMER_PO_ID>",
"shipping_profile": {},
"shipping_cost": "<SHIPPING_COST>",
"discount_profile": "<DISCOUNT_PROFILE>",
"origin": "<ORIGIN>",
"custom_forms": {
"uuid": "<FORM_UUID>",
"name": "<FORM_NAME>"
},
"currency": {
"uuid": "<CURRENCY_UUID>",
"name": "<CURRENCY_NAME>",
"link": "<CURRENCY_LINK>"
},
"time_zone": {
"uuid": "<TIMEZONE_UUID>",
"name": "<TIMEZONE_NAME>",
"link": "<TIMEZONE_LINK>"
},
"invoice_note": "<INVOICE_NOTE>",
"default_warehouse": "<WAREHOUSE_NAME>",
"billing_start_date": "<BILLING_START_DATE>",
"order_start_date": "<ORDER_START_DATE>",
"next_billing_from_date": "<NEXT_BILLING_DATE>",
"price_tax_inclusive": "<BOOLEAN>",
"billing_address": {},
"shipping_address": {},
"created_by": "<CREATED_BY>",
"created_on": "<CREATED_TIMESTAMP>",
"last_updated_by": "<UPDATED_BY>",
"last_updated_on": "<UPDATED_TIMESTAMP>",
"uuid": "<ORDER_UUID>",
"version": "<VERSION>",
"account_id": "<ACCOUNT_ID>",
"account_name": "<ACCOUNT_NAME>",
"allow_contract": "<BOOLEAN>",
"custom_attributes": [],
"custom_objects": [],
"currency_id": "<CURRENCY_ID>",
"properties": {
"communication_profile": "<COMMUNICATION_PROFILE>",
"invoice_mode": "<INVOICE_MODE>",
"invoice_term": "<INVOICE_TERM>",
"billing_period": "<BILLING_PERIOD>",
"consolidate_invoice": "<BOOLEAN>",
"payment_processor": "<PAYMENT_PROCESSOR>",
"payment_mode": "<PAYMENT_MODE>",
"payment_term": "<PAYMENT_TERM>",
"payment_term_alignment": "<PAYMENT_TERM_ALIGNMENT>",
"fulfillment_mode": "<FULFILLMENT_MODE>",
"fulfillment_term": "<FULFILLMENT_TERM>"
},
"invoice_id": "<INVOICE_ID>",
"lines": [
{
"charge_item_uuid": "<CHARGE_ITEM_UUID>",
"item_uuid": "<ITEM_UUID>",
"item_id": "<ITEM_ID>",
"item_name": "<ITEM_NAME>",
"item_order_quantity": "<QUANTITY>",
"shipping_cost": "<ITEM_SHIPPING_COST>",
"item_invoice_note": "<ITEM_INVOICE_NOTE>",
"item_description": "<ITEM_DESCRIPTION>",
"item_type": "<ITEM_TYPE>",
"item_charge_type": "<ITEM_CHARGE_TYPE>",
"item_custom_attributes": [],
"item_price_snapshot": {
"pricing_rule": {
"uuid": "<PRICING_RULE_UUID>",
"version": "<PRICING_VERSION>",
"price_type": "<PRICE_TYPE>",
"price": "<PRICE>",
"uom": "<UOM>",
"price_period": "<PRICE_PERIOD>",
"pricing_schedule": "<PRICING_SCHEDULE>",
"pricing_level": "<PRICING_LEVEL>",
"pricing_method": "<PRICING_METHOD>"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "<TAX_BASIS>",
"tax_code": {
"uuid": "<TAX_UUID>",
"code": "<TAX_CODE>",
"rate": "<TAX_RATE>",
"link": "<TAX_LINK>"
}
},
"isTaxExemptWhenSold": "<BOOLEAN>",
"item_price_tax": {
"uuid": "<ITEM_TAX_UUID>",
"code": "<ITEM_TAX_CODE>",
"rate": "<ITEM_TAX_RATE>",
"link": "<ITEM_TAX_LINK>"
},
"item_accounting_code": {
"sales_revenue": "<SALES_REVENUE_CODE>"
},
"version": "<LINE_VERSION>",
"expected_delivery_date": "<DELIVERY_DATE>",
"purchase_order_id": "<PURCHASE_ORDER_ID>",
"purchase_invoice_id": "<PURCHASE_INVOICE_ID>",
"discount": "<DISCOUNT>",
"newTaxCodeSet": "<NEW_TAX_CODE>",
"total": "<LINE_TOTAL>",
"subtotal": "<LINE_SUBTOTAL>",
"tax": "<LINE_TAX>"
}
],
"total": "<ORDER_TOTAL>",
"subtotal": "<ORDER_SUBTOTAL>",
"tax": "<ORDER_TAX>",
"kpis": {
"start_date": "<START_DATE>",
"estimated_total": "<ESTIMATED_TOTAL>",
"total_revenue": "<TOTAL_REVENUE>",
"monthly_recurring_revenue": "<MRR>",
"total_collected": "<TOTAL_COLLECTED>",
"total_outstanding": "<TOTAL_OUTSTANDING>",
"total_due": "<TOTAL_DUE>",
"last_invoice_issue_date": "<LAST_INVOICE_DATE>",
"last_invoice_total": "<LAST_INVOICE_TOTAL>",
"total_invoice": "<TOTAL_INVOICE_COUNT>",
"next_invoice_issueDate": "<NEXT_INVOICE_DATE>",
"last_reactivated_on": "<LAST_REACTIVATED_DATE>",
"last_cancelled_on": "<LAST_CANCELLED_DATE>",
"last_changed_on": "<LAST_CHANGED_DATE>",
"last_deleted_on": "<LAST_DELETED_DATE>"
},
"line_items": []
}
}
| Attribute | Type | Description |
|---|---|---|
| order | Object | Container object holding the converted active order details |
| order.status | String | Current status of the order after conversion |
| order.id | String | System-generated order identifier |
| order.uuid | String | Universally unique identifier of the order |
| order.account_id | String | Identifier of the account associated with the order |
| order.currency | Object | Currency details applied to the order |
| order.time_zone | Object | Time zone configuration for order processing |
| order.lines | Array | List of order line items with pricing, tax, and quantity details |
| order.total | String | Total amount of the order |
| order.subtotal | String | Subtotal amount before tax |
| order.tax | String | Total tax applied to the order |
| order.kpis | Object | Key performance and financial indicators related to the order |
Discard a Draft Order: /orders/{id}/discard_draft
Purpose
Discard a draft order — typically a quote-typed order in PENDING_CREATE state — so it is permanently removed from the active workflow and no longer surfaces in normal order or quote lists. The request wraps an order object carrying a free-form note field that records why the draft is being discarded; the note is preserved for downstream audit consumption. On success, the API returns a small confirmation payload with a single message field acknowledging the discard. The action is terminal: a discarded draft cannot be later activated or recovered through this endpoint.
Use Case
Quote orders and other draft order types frequently sit in a holding state while sales, finance, or operations teams negotiate, review, or wait on customer acceptance. When a deal falls through, when a quote is superseded by a revised version, or when a draft has been created in error during a sync, the draft must be removed cleanly so it does not clutter dashboards, count toward pipeline metrics, or accidentally enter active billing. This endpoint provides that targeted, terminal discard operation. The note in the request lets the team capture the reason for the discard, which downstream audit logs and sales-ops reporting can later use to understand discard rates, common rejection reasons, and pipeline hygiene metrics.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the draft order to discard. |
Query Parameters
No query parameters required.
Request Body
{
"order": {
"note": "Reason for discarding this draft"
}
}Response
Returns a confirmation payload with a single message field on success. The message text confirms the discard (e.g. "Quote has been discarded successfully"). Errors follow the standard envelope: 404 if the order ID does not exist, 409/422 if the order is not in a discardable state (already activated, already discarded, or not a draft), 401/403 for authorisation failures, and 5xx for server-side failures.
Response Body
{
"message": "Quote has been discarded successfully"
}| Attribute | Type | Description |
|---|---|---|
| message | String | Human-readable confirmation that the draft was discarded. |
Activate a Draft Order: /orders/{id}/activate_draft
Purpose
Activate a draft order — typically a quote that has been accepted and is ready to enter the active billing and fulfilment workflow. The request wraps an order object carrying an effective_date and an optional note. The effective date controls when the activation is recognised by downstream billing and revenue recognition; the note provides a free-form audit trail. On success, the API returns the freshly activated record under a quote wrapper, with the order's complete state including its lines, properties (including proforma_properties such as acceptance term and required-payment flags), custom attributes, custom objects, KPIs, and audit fields, so the caller can immediately render the activated quote without an additional fetch.
Use Case
When a customer accepts a quote, the deal moves from negotiation into active billing and fulfilment. This transition is the natural breakpoint between sales and operations: until activation, the quote is provisional and editable; after activation, the order is live, billable, and tied to schedules, payments, and downstream automation. This endpoint performs that handoff. Capturing an effective date lets finance align the activation with the agreed billing start, and the note field provides a free-form audit trail (e.g., "Customer accepted via signed PO #12345"). Returning the full activated record in the response means the client can refresh its rendered view in one shot, avoiding race conditions where the UI could otherwise show stale draft state immediately after activation.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the draft order to activate. |
Query Parameters
No query parameters required.
Request Body
{
"order": {
"effective_date": "2026-02-19",
"note": "Created via API"
}
}Response
Returns the activated record wrapped under a quote object. The payload includes lifecycle status (typically PENDING_CREATE during the activation transition), the order ID and identity fields (name, display name, description), classification flags (pre_order, quote_order, quote_converted, order_type), people fields (manager, referral account, customer purchase order ID), shipping configuration (shipping profile, shipping cost), discount profile, origin, custom form binding, currency and time zone, billing and shipping addresses, default warehouse, billing/start/next-billing dates, price tax inclusivity flag, audit fields (created by/on, last updated by/on), UUID and version, account binding, custom attributes, custom objects, currency ID, the full properties block (invoice mode/term, billing period, payment processor/mode/term, fulfillment mode/term, consolidate-invoice flag, and the nested proforma_properties covering acceptance and payment requirements), invoice ID, lines array (with snapshot pricing, tax configuration, accounting code, totals), totals (subtotal, tax, total), KPI block (estimated total, lifecycle timestamps), and line items. Errors follow the standard envelope: 404 if the order is not found, 409/422 if the order is not in an activatable state, and 4xx/5xx as appropriate for permission and server failures.
Response Body
{
"quote": {
"status": "PENDING_CREATE",
"id": "ORD-IKOKZU-1197",
"pre_order": "false",
"quote_order": "true",
"quote_converted": "false",
"order_type": "QUOTE",
"name": "Quote for Random Guy -1",
"display_name": "Quote for Random Guy -1",
"description": "",
"manager": "",
"referral_account": "",
"customer_purchase_order_id": "",
"shipping_profile": {},
"shipping_cost": "0.000000",
"discount_profile": null,
"origin": "",
"custom_forms": {
"uuid": "10f519f1-fbb6-4aad-b2a5-424e38efbf46",
"name": "Default for Order"
},
"currency": {
"uuid": "a0f921e3-921c-4e93-ba69-bb796fdc4a07",
"name": "AUD",
"link": "https://dev-api.exsited.com/api/v1/currencies/a0f921e3-921c-4e93-ba69-bb796fdc4a07"
},
"time_zone": {
"uuid": "eada7aaa-f872-462c-ac63-593c5b11f5a6",
"name": "Australia/Sydney",
"link": "https://dev-api.exsited.com/api/v1/time_zones/eada7aaa-f872-462c-ac63-593c5b11f5a6"
},
"invoice_note": "",
"default_warehouse": "Warehouse 1",
"billing_start_date": "ORDER_START_DATE",
"order_start_date": "2026-04-16T00:00:00Z",
"next_billing_from_date": "",
"price_tax_inclusive": "false",
"billing_address": {},
"shipping_address": {},
"created_by": "Operon_Azim",
"created_on": "2026-03-31T07:14:13Z",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "61d824ee-be93-4d42-8214-13feb3cd483d",
"version": "1",
"account_id": "IKOKZU",
"account_name": "Random Guy",
"allow_contract": "false",
"custom_attributes": [
{
"name": "Job_Address",
"value": "AustraliaFrom Quote"
},
{
"name": "Quote_Version",
"value": "V1"
},
{
"name": "quote_description",
"value": "Desc q"
}
],
"custom_objects": [
{
"uuid": "ebd56bb3-1795-4463-9722-ea517f7f2ca3",
"name": "refund_requests",
"link": "https://dev-api.exsited.com/api/v2/orders/ORD-IKOKZU-1197/custom_objects/ebd56bb3-1795-4463-9722-ea517f7f2ca3?limit=10&offset=0"
}
],
"currency_id": "1",
"properties": {
"communication_profile": "",
"invoice_mode": "AUTOMATIC",
"invoice_term": "Billing Start Date",
"billing_period": "1 Day",
"consolidate_invoice": "false",
"payment_processor": "",
"payment_mode": "MANUAL",
"payment_term": "Net 30",
"payment_term_alignment": "",
"fulfillment_mode": "",
"fulfillment_term": "",
"proforma_properties": {
"acceptance_required": "true",
"payment_required": "false",
"acceptance_term": "3 Week",
"acceptance_date": "RequestDate",
"terms_and_conditions": ""
}
},
"invoice_id": "",
"lines": [
{
"item_serial_or_batch_number": "N/A",
"charge_item_uuid": "b1cb9f60-1795-4de3-befd-f796b2110bd9",
"item_uuid": "",
"item_id": "",
"item_name": "Desc i",
"item_order_quantity": "1.000000",
"shipping_cost": "0.00",
"item_invoice_note": "descitem",
"item_description": "",
"item_type": "",
"item_charge_type": "ONE_OFF",
"item_custom_attributes": [],
"item_price_snapshot": {
"pricing_rule": {
"uuid": "",
"version": "",
"price_type": "",
"price": "14.000000",
"uom": "",
"price_period": "",
"pricing_schedule": "",
"pricing_level": "",
"pricing_method": "0.000000"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "",
"tax_code": {
"uuid": "",
"code": "",
"rate": "",
"link": ""
}
},
"isTaxExemptWhenSold": "false",
"item_price_tax": {
"uuid": "d0942779-fa7a-4ae9-9295-2ae21bc9b05c",
"code": "GST",
"rate": "10.0000",
"link": "https://dev-api.exsited.com/api/v3/settings/taxes/d0942779-fa7a-4ae9-9295-2ae21bc9b05c"
},
"item_accounting_code": {
"sales_revenue": ""
},
"version": "1",
"expected_delivery_date": "",
"purchase_order_id": "",
"purchase_invoice_id": "",
"discount": 0,
"newTaxCodeSet": null,
"total": "14",
"subtotal": "14",
"tax": "1.27"
}
],
"total": "14",
"subtotal": "14",
"tax": "1.27272727272727272727",
"kpis": {
"estimated_total": 0,
"created_on": "",
"last_updated_on": ""
},
"line_items": []
}
}| Attribute | Type | Description |
|---|---|---|
| quote.status | String | Lifecycle status of the activated record. |
| quote.id | String | Order/quote identifier. |
| quote.pre_order | String | Pre-order classification flag. |
| quote.quote_order | String | Quote order classification flag. |
| quote.quote_converted | String | Whether this quote has been converted. |
| quote.order_type | String | Order type (e.g. QUOTE). |
| quote.name | String | Order name. |
| quote.display_name | String | Display name shown in UI. |
| quote.description | String | Free-form description. |
| quote.manager | String | Assigned manager. |
| quote.referral_account | String | Referral account reference. |
| quote.customer_purchase_order_id | String | Customer purchase order reference. |
| quote.shipping_profile | Object | Shipping profile binding. |
| quote.shipping_cost | String | Shipping cost. |
| quote.discount_profile | Object/null | Discount profile binding. |
| quote.origin | String | Order origin marker. |
| quote.custom_forms | Object | Custom form binding (uuid, name). |
| quote.currency | Object | Currency reference (uuid, name, link). |
| quote.time_zone | Object | Time zone reference (uuid, name, link). |
| quote.invoice_note | String | Default invoice note. |
| quote.default_warehouse | String | Default warehouse name. |
| quote.billing_start_date | String | Billing start. |
| quote.order_start_date | String | Order start. |
| quote.next_billing_from_date | String | Next billing trigger date. |
| quote.price_tax_inclusive | String | Whether prices include tax. |
| quote.billing_address | Object | Billing address. |
| quote.shipping_address | Object | Shipping address. |
| quote.created_by | String | Creator username. |
| quote.created_on | String (ISO 8601) | Creation timestamp. |
| quote.last_updated_by | String | Last editor. |
| quote.last_updated_on | String (ISO 8601) | Last update timestamp. |
| quote.uuid | String (UUID) | Order UUID. |
| quote.version | String | Order version number. |
| quote.account_id | String | Owning account ID. |
| quote.account_name | String | Owning account name. |
| quote.allow_contract | String | Whether contract is allowed. |
| quote.custom_attributes | Array | Custom attributes (name/value pairs). |
| quote.custom_objects | Array | Linked custom objects. |
| quote.currency_id | String | Currency identifier. |
| quote.properties | Object | Order properties block (invoice/payment/fulfillment terms, proforma_properties). |
| quote.properties.proforma_properties | Object | Proforma terms (acceptance/payment requirements, terms and conditions). |
| quote.invoice_id | String | Linked invoice ID, if any. |
| quote.lines | Array | Order line items with pricing snapshot, tax configuration, accounting code, totals. |
| quote.total | String | Order total. |
| quote.subtotal | String | Order subtotal. |
| quote.tax | String | Order tax amount. |
| quote.kpis | Object | KPI block (estimated total, lifecycle timestamps). |
| quote.line_items | Array | Line items collection (legacy/auxiliary). |
Convert a Quote to an Order: /orders/{id}/convert_to_order
Purpose
Convert a quote-typed order into a regular billable order, identified by the source order ID. The endpoint takes no request body — the conversion is driven entirely by the path parameter and the current state of the source quote. On success the API returns the post-conversion record under an order wrapper, accompanied by an event_uuid correlation token and an operation marker describing the lifecycle event that was performed. The returned order reflects the new lifecycle status, the freshly assigned order identity, line items copied from the quote (with pricing snapshot, tax configuration, accounting code, and totals), the account binding inherited from the source quote, billing/start/next-billing dates, currency and time zone references, custom attributes and objects, KPI block, audit fields, UUID, and version. The conversion is one-way — once a quote has been converted, the action cannot be reversed through this endpoint.
Use Case
Quote-to-order conversion is the canonical handoff point between sales and operations: until the conversion call lands, the record is a negotiable quote tied to proposal workflows; after conversion, it is a live order tied to billing schedules, fulfillment, and downstream automation. Sales operations call this endpoint when a customer formally accepts a quote and the deal needs to enter the active billing pipeline. CRM integrations invoke it from approval flows where the conversion is gated on an external signal (signed contract uploaded, deposit cleared, manager approval recorded). Migration scripts use it during tenant cutovers to bulk-convert pre-seeded quotes into orders aligned with the agreed activation schedule. Returning the freshly converted record in the response means the calling client can refresh its UI in a single round-trip without a follow-up GET, avoiding race conditions where the rendered view could otherwise show stale quote state immediately after conversion. Because the response also carries the event_uuid correlation token, downstream audit pipelines can stitch the conversion event into the broader lifecycle history without inferring it from timestamps.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the quote-typed order to convert. |
Query Parameters
No query parameters required.
Request Body
This endpoint does not require a request body.
Response
Returns the converted record wrapped under an order object, along with sibling fields event_uuid (correlation token for the conversion lifecycle event) and operation (marker describing the operation performed). The embedded order block exposes lifecycle status, identity (id, name, display_name, description, order_type), currency and time_zone references, billing/start/next-billing dates, account binding, line items with pricing snapshot and tax configuration, totals (subtotal, tax, total), custom attributes, KPI block (estimated_total and lifecycle timestamps), audit fields (created_by, created_on, last_updated_by, last_updated_on), UUID, and version. Errors follow the standard envelope: 404 if the order ID does not exist, 409/422 if the source order is not in a convertible state (already converted, wrong order type, missing required fields), 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"event_uuid": "EVENT_UUID",
"operation": "OPERATION",
"order": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"order_type": "ORDER_TYPE",
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_NAME"
},
"time_zone": {
"uuid": "TIMEZONE_UUID",
"name": "TIMEZONE_NAME"
},
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_DATE",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE",
"price_tax_inclusive": "PRICE_TAX_INCLUSIVE",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "ORDER_UUID",
"version": "VERSION",
"lines": [
{
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "ITEM_ORDER_QUANTITY",
"item_charge_type": "ITEM_CHARGE_TYPE",
"subtotal": "LINE_SUBTOTAL",
"tax": "LINE_TAX",
"total": "LINE_TOTAL",
"version": "LINE_VERSION"
}
],
"subtotal": "ORDER_SUBTOTAL",
"tax": "ORDER_TAX",
"total": "ORDER_TOTAL",
"custom_attributes": [],
"kpis": {
"estimated_total": 0,
"created_on": "CREATED_ON",
"last_updated_on": "LAST_UPDATED_ON"
}
}
}| Attribute | Type | Description |
|---|---|---|
| event_uuid | String (UUID) | Correlation token for the conversion lifecycle event. |
| operation | String | Marker describing the operation performed. |
| order.status | String | Lifecycle status of the converted order. |
| order.id | String | Order identifier. |
| order.name | String | Order name. |
| order.display_name | String | Display name shown in UI. |
| order.description | String | Free-form description. |
| order.order_type | String | Order type after conversion. |
| order.currency | Object | Currency reference (uuid, name). |
| order.time_zone | Object | Time zone reference (uuid, name). |
| order.billing_start_date | String | Billing start. |
| order.order_start_date | String | Order start. |
| order.next_billing_from_date | String | Next billing trigger date. |
| order.price_tax_inclusive | String | Whether prices include tax. |
| order.account_id | String | Owning account ID. |
| order.account_name | String | Owning account name. |
| order.created_by | String | Creator username. |
| order.created_on | String (ISO 8601) | Creation timestamp. |
| order.last_updated_by | String | Last editor. |
| order.last_updated_on | String (ISO 8601) | Last update timestamp. |
| order.uuid | String (UUID) | Order UUID. |
| order.version | String | Order version number. |
| order.lines | Array | Line items copied from the source quote. |
| order.subtotal | String | Order subtotal. |
| order.tax | String | Order tax amount. |
| order.total | String | Order total. |
| order.custom_attributes | Array | Custom attributes inherited from the quote. |
| order.kpis | Object | KPI block (estimated total, lifecycle timestamps). |
Accept an Order: /orders/{id}/accept
Purpose
Mark a pending order as accepted, identified by the order ID. The endpoint takes no request body — acceptance is driven entirely by the path parameter and the current state of the target order. On success the API returns a confirmation payload carrying a human-readable message, the invoice_id generated (or linked) by acceptance, a payment_required flag indicating whether downstream payment is needed before the order activates, and an activity_logs array recording the lifecycle events triggered by the acceptance call. Acceptance is the customer-side counterpart to internal activation: where activate transitions the order from pending into the active billing pipeline on the operator side, accept records the customer's formal commitment and may trigger automated invoice generation, payment collection, or downstream provisioning depending on tenant configuration.
Use Case
Orders that require explicit customer acceptance — typically quote-style orders or pro-forma orders flagged with an acceptance term — sit in a holding state until the customer confirms. Self-service portals call this endpoint when a customer clicks "Accept" on a pending order, transitioning it forward without requiring operator intervention. Sales-ops automation invokes it from approval workflows where an external system (DocuSign, e-signature platform, custom approval gate) signals acceptance back to Exsited, recording the formal customer commitment and surfacing the resulting invoice. Customer service consoles also expose it for agent-assisted acceptance flows when a customer confirms verbally and the agent records acceptance on their behalf. The returned payment_required flag tells the caller whether to trigger a payment collection screen immediately or whether the order can flow through to fulfillment without an upfront charge. The activity_logs array gives downstream audit pipelines a structured record of what happened during the acceptance call, ready for ingestion into compliance and reporting systems.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order to accept. |
Query Parameters
No query parameters required.
Request Body
This endpoint does not require a request body.
Response
Returns a confirmation payload with four fields: a human-readable message confirming the acceptance, the invoice_id generated or linked as a side-effect of acceptance, a payment_required boolean indicating whether downstream payment is needed before the order can fully activate, and an activity_logs array describing the lifecycle events triggered by the call. Errors follow the standard envelope: 404 if the order ID does not exist, 409/422 if the order is not in an acceptable state (already accepted, missing required fields, expired acceptance window), 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"message": "MESSAGE",
"invoice_id": "INVOICE_ID",
"payment_required": false,
"activity_logs": [
{
"activity": "ACTIVITY_MESSAGE"
}
]
}| Attribute | Type | Description |
|---|---|---|
| message | String | Human-readable confirmation that the order was accepted. |
| invoice_id | String | Identifier of the invoice generated or linked by acceptance. |
| payment_required | Boolean | Whether downstream payment is needed before the order activates. |
| activity_logs | Array | Lifecycle events triggered by acceptance. |
| activity_logs[].activity | String | Description of a single activity event. |
Preview an Order Change: /orders/{id}/change/preview
Purpose
Preview the financial and structural impact of a proposed order change without committing it, identified by the order ID. The request wraps the proposed change under an order root key carrying an effective_date, a lines array of change operations (each with op indicating the action — change, add, remove — plus the target charge_item_uuid and any updated quantity or pricing snapshot), and a properties block for order-level adjustments such as billing_period. The system simulates the change against the live order state and returns the post-change projection wrapped under a preview key, accompanied by an operation marker describing the simulated lifecycle event. The endpoint is read-only on the live order — no persisted state changes — making it safe to call repeatedly while iterating on a proposed change.
Use Case
Order amendments are high-stakes operations: changing a quantity, swapping a price, or adjusting a billing period can ripple through invoices, revenue recognition, and customer-facing totals in ways that are difficult to undo cleanly. Sales-ops, customer success, and finance teams rely on a preview step to surface those downstream effects before committing the change. Self-service portals call this endpoint when a customer adjusts a subscription so the UI can show the new totals, prorations, and next-billing impact alongside a confirmation button — only after explicit acceptance does the client invoke the matching change endpoint to persist the amendment. CRM workflows pipe proposed changes through the preview to validate that pricing logic, tax configuration, and billing cadence behave as expected before pushing the change live. Integrations syncing from external systems use the preview to confirm that a translated change request resolves cleanly on the Exsited side, avoiding partial commits if any line item fails validation. Because the response carries the same shape as a full order details fetch, callers can render the projected order state with existing rendering logic without a separate code path.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order whose change is being previewed. |
Query Parameters
No query parameters required.
Request Body
{
"order": {
"effective_date": "EFFECTIVE_DATE",
"lines": [
{
"op": "change",
"uuid": "CHARGE_ITEM_UUID",
"item_order_quantity": "ITEM_ORDER_QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE"
}
}
}
],
"properties": {
"billing_period": "BILLING_PERIOD"
}
}
}Response
Returns the post-change projection wrapped under a preview object, accompanied by an operation marker describing the simulated lifecycle event. The embedded preview block mirrors the shape of a standard order details fetch — lifecycle status, identity, currency and time_zone references, billing/start/next-billing dates, account binding, properties block (with the new billing_period applied), line items reflecting the proposed quantity and pricing changes, totals (subtotal, tax, total), and KPI block. No persisted state changes on the live order. Errors follow the standard envelope: 404 if the order ID does not exist, 422 for validation failures (invalid charge_item_uuid, malformed effective_date, conflicting line operations), 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"operation": "OPERATION",
"preview": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"uuid": "ORDER_UUID",
"version": "VERSION",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"order_type": "ORDER_TYPE",
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_NAME",
"link": "CURRENCY_LINK"
},
"time_zone": {
"uuid": "TIMEZONE_UUID",
"name": "TIMEZONE_NAME",
"link": "TIMEZONE_LINK"
},
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_DATE",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE",
"price_tax_inclusive": "PRICE_TAX_INCLUSIVE",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"properties": {
"billing_period": "BILLING_PERIOD",
"invoice_mode": "INVOICE_MODE",
"invoice_term": "INVOICE_TERM",
"payment_processor": "PAYMENT_PROCESSOR",
"payment_mode": "PAYMENT_MODE",
"payment_term": "PAYMENT_TERM",
"fulfillment_mode": "FULFILLMENT_MODE",
"fulfillment_term": "FULFILLMENT_TERM"
},
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "ITEM_ORDER_QUANTITY",
"item_charge_type": "ITEM_CHARGE_TYPE",
"item_price_snapshot": {
"pricing_rule": {
"uuid": "PRICING_RULE_UUID",
"version": "PRICING_VERSION",
"price_type": "PRICE_TYPE",
"price": "PRICE",
"uom": "UOM"
}
},
"item_price_tax": {
"uuid": "TAX_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE",
"link": "TAX_LINK"
},
"subtotal": "LINE_SUBTOTAL",
"tax": "LINE_TAX",
"total": "LINE_TOTAL",
"version": "LINE_VERSION"
}
],
"subtotal": "ORDER_SUBTOTAL",
"tax": "ORDER_TAX",
"total": "ORDER_TOTAL",
"kpis": {
"estimated_total": 0,
"created_on": "CREATED_ON",
"last_updated_on": "LAST_UPDATED_ON"
}
}
}| Attribute | Type | Description |
|---|---|---|
| operation | String | Marker describing the simulated lifecycle event. |
| preview.status | String | Projected lifecycle status after the change. |
| preview.id | String | Order identifier. |
| preview.uuid | String (UUID) | Order UUID. |
| preview.version | String | Order version number. |
| preview.name | String | Order name. |
| preview.display_name | String | Display name. |
| preview.description | String | Free-form description. |
| preview.order_type | String | Order type. |
| preview.currency | Object | Currency reference. |
| preview.time_zone | Object | Time zone reference. |
| preview.billing_start_date | String | Billing start. |
| preview.order_start_date | String | Order start. |
| preview.next_billing_from_date | String | Projected next billing trigger. |
| preview.price_tax_inclusive | String | Whether prices include tax. |
| preview.account_id | String | Owning account ID. |
| preview.account_name | String | Owning account name. |
| preview.properties | Object | Order properties block reflecting the proposed change. |
| preview.lines | Array | Projected line items after the change. |
| preview.subtotal | String | Projected subtotal. |
| preview.tax | String | Projected tax. |
| preview.total | String | Projected total. |
| preview.kpis | Object | KPI block (estimated total, lifecycle timestamps). |
Create a Preorder: /orders/preorder
Purpose
Create a preorder — an order placed for an item that is not yet available for general sale, typically used for upcoming releases, gated launches, or items with preOrder configuration enabled at the item level. The request wraps the order payload under an order root key carrying the same shape as a regular create call (account binding, line items, billing/start dates, currency, custom attributes, properties block) with the preOrder flag set so the system reserves the order against the preorder pipeline rather than the live billing pipeline. Items must have preorder configuration enabled before a preorder can be placed against them. On success the API returns the persisted preorder under an order wrapper, accompanied by an event_uuid correlation token, with the new order's identity, lifecycle status, line items, totals, KPIs, and audit fields ready for client rendering.
Use Case
Preorders are essential for product launches, scheduled-release subscriptions, and any sales motion where customers commit to an order before the item is generally available. Sales teams use this endpoint to capture early demand and lock in customers ahead of release dates, while marketing campaigns drive preorder volume to validate launch projections. Subscription-based businesses use preorders to seed billing schedules that activate on a future release date without flowing through the immediate billing pipeline. Integration platforms hooked into ecommerce frontends or CRM workflows call this endpoint when a customer commits to a preorder via an external storefront, persisting the commitment in Exsited as a real order record. Migration scripts also use this endpoint to seed preorders during tenant cutovers when historical preorder commitments must be preserved. The returned event_uuid lets downstream audit and analytics pipelines stitch the preorder event into broader lifecycle history.
Path Parameters
No path parameters required.
Query Parameters
No query parameters required.
Request Body
{
"order": {
"accountId": "ACCOUNT_ID",
"preOrder": "true",
"priceTaxInclusive": "true",
"lines": [
{
"item_id": "ITEM_ID",
"item_order_quantity": "ITEM_ORDER_QUANTITY"
}
]
}
}Response
Returns the persisted preorder wrapped under an order object, accompanied by an event_uuid correlation token for the lifecycle event. The embedded order block exposes lifecycle status, identity (id, name, display_name, description, order_type), preorder flag, currency and time_zone references, billing/start/next-billing dates, account binding, line items with pricing snapshot and tax configuration, totals (subtotal, tax, total), custom attributes, KPI block, audit fields, UUID, and version. Errors follow the standard envelope: 404 if the account ID does not exist, 422 if the line item does not have preorder configuration enabled or other validation failures occur, 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"event_uuid": "EVENT_UUID",
"order": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"order_type": "ORDER_TYPE",
"preOrder": "true",
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_NAME"
},
"time_zone": {
"uuid": "TIMEZONE_UUID",
"name": "TIMEZONE_NAME"
},
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_DATE",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE",
"price_tax_inclusive": "PRICE_TAX_INCLUSIVE",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"uuid": "ORDER_UUID",
"version": "VERSION",
"lines": [
{
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "ITEM_ORDER_QUANTITY",
"item_charge_type": "ITEM_CHARGE_TYPE",
"subtotal": "LINE_SUBTOTAL",
"tax": "LINE_TAX",
"total": "LINE_TOTAL",
"version": "LINE_VERSION"
}
],
"subtotal": "ORDER_SUBTOTAL",
"tax": "ORDER_TAX",
"total": "ORDER_TOTAL",
"custom_attributes": [],
"kpis": {
"estimated_total": 0,
"created_on": "CREATED_ON",
"last_updated_on": "LAST_UPDATED_ON"
}
}
}| Attribute | Type | Description |
|---|---|---|
| event_uuid | String (UUID) | Correlation token for the preorder lifecycle event. |
| order.status | String | Lifecycle status of the preorder. |
| order.id | String | Order identifier. |
| order.name | String | Order name. |
| order.display_name | String | Display name shown in UI. |
| order.description | String | Free-form description. |
| order.order_type | String | Order type. |
| order.preOrder | String | Preorder flag confirming the order was placed via the preorder pipeline. |
| order.currency | Object | Currency reference (uuid, name). |
| order.time_zone | Object | Time zone reference (uuid, name). |
| order.billing_start_date | String | Billing start. |
| order.order_start_date | String | Order start. |
| order.next_billing_from_date | String | Next billing trigger date. |
| order.price_tax_inclusive | String | Whether prices include tax. |
| order.account_id | String | Owning account ID. |
| order.account_name | String | Owning account name. |
| order.created_by | String | Creator username. |
| order.created_on | String (ISO 8601) | Creation timestamp. |
| order.last_updated_by | String | Last editor. |
| order.last_updated_on | String (ISO 8601) | Last update timestamp. |
| order.uuid | String (UUID) | Order UUID. |
| order.version | String | Order version number. |
| order.lines | Array | Preorder line items. |
| order.subtotal | String | Order subtotal. |
| order.tax | String | Order tax amount. |
| order.total | String | Order total. |
| order.custom_attributes | Array | Custom attributes for the preorder. |
| order.kpis | Object | KPI block (estimated total, lifecycle timestamps). |
Upgrade an Order: /orders/{id}/upgrade
Purpose
Upgrade an active order to a higher-tier plan or package, identified by the order ID. The request wraps the upgrade parameters at the root level: an effective_date controlling when the new plan takes effect (or effective_immediately for instant transition), an optional redemption_code, discount_percentage, and discount_amount for promotional pricing, an optional billing_period override, a lines array describing the new pricing snapshot for each upgraded charge item (charge_item_uuid identifies the existing line; package_name and pricing_rule describe the upgrade target), and an optional payment_information array specifying the payment method and amount for any prorated charge collected at upgrade. On success the API returns the post-upgrade record under an order wrapper, accompanied by an event_uuid correlation token and operation marker — distinct from the upgrade preview, which simulates without persisting.
Use Case
Plan upgrades are the most common revenue-expansion motion for subscription products: customers move from a basic to a pro tier, add seats, swap to a higher service level, or activate premium features. This endpoint is the canonical commit point for those transitions. Self-service portals call it after the customer accepts the upgrade quote rendered from the matching upgrade-preview response. Sales-ops and customer success automation triggers it from CRM workflows when an account hits an expansion trigger (usage threshold, contract renewal, manual upsell). Migration scripts use it during tenant cutovers to bulk-upgrade orders that need to land on a new plan structure aligned with the agreed activation schedule. The redemption_code, discount_percentage, and discount_amount fields support promotional pricing during the upgrade, while payment_information lets callers settle any prorated charge in the same call rather than chaining a separate payment request.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order being upgraded. |
Query Parameters
No query parameters required.
Request Body
{
"effective_date": "EFFECTIVE_DATE",
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"package_name": "PACKAGE_NAME",
"quantity": "QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE"
}
},
"isTaxExemptWhenSold": "false"
}
]
}Response
Returns the post-upgrade record wrapped under an order object, accompanied by event_uuid and operation correlation tokens. The embedded order block exposes lifecycle status, identity fields, currency and time_zone references, billing/start/next-billing dates, account binding, line items reflecting the upgraded pricing snapshot, totals, KPI block, and audit fields. Errors follow the standard envelope: 404 if the order ID does not exist, 422 for validation failures (invalid charge_item_uuid, malformed effective_date, unsupported upgrade path), 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"event_uuid": "EVENT_UUID",
"operation": "OPERATION",
"order": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"uuid": "ORDER_UUID",
"version": "VERSION",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"order_type": "ORDER_TYPE",
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_NAME"
},
"time_zone": {
"uuid": "TIMEZONE_UUID",
"name": "TIMEZONE_NAME"
},
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_DATE",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE",
"price_tax_inclusive": "PRICE_TAX_INCLUSIVE",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"lines": [
{
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "ITEM_ORDER_QUANTITY",
"item_charge_type": "ITEM_CHARGE_TYPE",
"subtotal": "LINE_SUBTOTAL",
"tax": "LINE_TAX",
"total": "LINE_TOTAL",
"version": "LINE_VERSION"
}
],
"subtotal": "ORDER_SUBTOTAL",
"tax": "ORDER_TAX",
"total": "ORDER_TOTAL",
"kpis": {
"estimated_total": 0,
"created_on": "CREATED_ON",
"last_updated_on": "LAST_UPDATED_ON"
}
}
}| Attribute | Type | Description |
|---|---|---|
| event_uuid | String (UUID) | Correlation token for the upgrade lifecycle event. |
| operation | String | Marker describing the operation performed. |
| order.status | String | Lifecycle status after the upgrade. |
| order.id | String | Order identifier. |
| order.uuid | String (UUID) | Order UUID. |
| order.version | String | Order version. |
| order.lines | Array | Line items reflecting the upgraded pricing snapshot. |
| order.subtotal | String | Order subtotal. |
| order.tax | String | Order tax. |
| order.total | String | Order total. |
| order.kpis | Object | KPI block. |
Preview an Order Upgrade: /orders/{id}/upgrade/preview
Purpose
Preview the financial impact of a proposed upgrade without committing it, identified by the order ID. The request shape matches the upgrade endpoint exactly — effective_date, optional effective_immediately, redemption_code, discount_percentage, discount_amount, billing_period, lines array with charge_item_uuid and new pricing snapshot, optional payment_information, and an optional properties block for order-level adjustments such as billing_period and invoice_mode. The system simulates the upgrade against the live order state and returns a slim totals projection wrapped under a preview key, accompanied by an operation marker. The endpoint is read-only on the live order — no persisted state changes — making it safe to call repeatedly while iterating on a proposed upgrade.
Use Case
Plan upgrades change customer-facing totals in non-trivial ways: prorated charges, swapped pricing rules, new billing cadences, and applied discounts all combine to produce a new total that customers and operators want to see before committing. Self-service portals call this endpoint when a user picks a higher tier so the UI can render the projected new total, the prorated amount due now, and the post-upgrade billing structure alongside a confirmation button — only after explicit acceptance does the client invoke the matching upgrade endpoint to persist. Sales-ops automation pipes proposed upgrades through the preview to validate that promotional codes resolve cleanly and that the resulting total matches what the operator quoted manually. CRM integrations use it to refresh expansion forecasts during pipeline reviews. Because the response is a slim totals object rather than a full order record, the call is fast and cheap to repeat as the user iterates on quantity or package selection.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order whose upgrade is being previewed. |
Query Parameters
No query parameters required.
Request Body
{
"effective_date": "EFFECTIVE_DATE",
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"package_name": "PACKAGE_NAME",
"quantity": "QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE"
}
}
}
]
}Response
Returns a slim totals projection wrapped under a preview object, accompanied by an operation marker. The preview block exposes sub_total, tax_total, discount_total, shipping_total, total, currency, old_total (the pre-upgrade total for comparison), total_changed (the delta), and total_due (the prorated amount payable now). No persisted state changes occur on the live order. Errors follow the standard envelope: 404 if the order ID does not exist, 422 for validation failures, 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"operation": "OPERATION",
"preview": {
"sub_total": "SUB_TOTAL",
"tax_total": "TAX_TOTAL",
"discount_total": "DISCOUNT_TOTAL",
"shipping_total": "SHIPPING_TOTAL",
"total": "TOTAL",
"currency": "CURRENCY",
"old_total": "OLD_TOTAL",
"total_changed": "TOTAL_CHANGED",
"total_due": "TOTAL_DUE"
}
}| Attribute | Type | Description |
|---|---|---|
| operation | String | Marker describing the simulated lifecycle event. |
| preview.sub_total | String | Projected subtotal. |
| preview.tax_total | String | Projected total tax. |
| preview.discount_total | String | Projected total discount applied. |
| preview.shipping_total | String | Projected shipping total. |
| preview.total | String | Projected new order total. |
| preview.currency | String | Currency code. |
| preview.old_total | String | Pre-upgrade total for comparison. |
| preview.total_changed | String | Delta between old and new total. |
| preview.total_due | String | Prorated amount payable now. |
Downgrade an Order: /orders/{id}/downgrade
Purpose
Downgrade an active order to a lower-tier plan or package, identified by the order ID. The request shape mirrors the upgrade endpoint — effective_date, optional effective_immediately, redemption_code, discount_percentage, discount_amount, billing_period, lines array with charge_item_uuid and the new lower-tier pricing snapshot, optional payment_information for any settlement, and an optional properties block for order-level adjustments. On success the API returns the post-downgrade record under an order wrapper, accompanied by an event_uuid correlation token and operation marker — distinct from the downgrade preview which simulates without persisting. Downgrades typically take effect at the next billing cycle by default unless effective_immediately is set, allowing the customer to retain higher-tier benefits through the end of the current billing period.
Use Case
Plan downgrades are the counterpart to upgrades and are equally important to support cleanly: customers reducing seats, switching to a basic tier, or stepping down from premium features must be able to do so without operator intervention or risk of incorrect billing. Self-service portals call this endpoint after the customer confirms the downgrade rendered from the matching downgrade-preview. Customer success workflows trigger it during retention conversations when a downgrade prevents churn. Billing automation may invoke it from automated rules — for example, dropping seat count after extended inactivity. The endpoint also supports refund or credit issuance via payment_information when downgrade-related credits need to be applied immediately. The properties block lets callers adjust order-level fields (such as billing_period) atomically with the downgrade rather than chaining a separate change call.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order being downgraded. |
Query Parameters
No query parameters required.
Request Body
{
"effective_date": "EFFECTIVE_DATE",
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"package_name": "PACKAGE_NAME",
"quantity": "QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE"
}
},
"isTaxExemptWhenSold": "false"
}
]
}Response
Returns the post-downgrade record wrapped under an order object with event_uuid and operation correlation tokens. The embedded order block exposes lifecycle status, identity, currency and time_zone references, billing/start/next-billing dates, account binding, line items reflecting the downgraded pricing snapshot, totals, KPI block, and audit fields. Errors follow the standard envelope: 404 if the order ID does not exist, 422 for validation failures (invalid charge_item_uuid, malformed effective_date, unsupported downgrade path), 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"event_uuid": "EVENT_UUID",
"operation": "OPERATION",
"order": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"uuid": "ORDER_UUID",
"version": "VERSION",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"order_type": "ORDER_TYPE",
"currency": {
"uuid": "CURRENCY_UUID",
"name": "CURRENCY_NAME"
},
"time_zone": {
"uuid": "TIMEZONE_UUID",
"name": "TIMEZONE_NAME"
},
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_DATE",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE",
"price_tax_inclusive": "PRICE_TAX_INCLUSIVE",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"lines": [
{
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "ITEM_ORDER_QUANTITY",
"item_charge_type": "ITEM_CHARGE_TYPE",
"subtotal": "LINE_SUBTOTAL",
"tax": "LINE_TAX",
"total": "LINE_TOTAL",
"version": "LINE_VERSION"
}
],
"subtotal": "ORDER_SUBTOTAL",
"tax": "ORDER_TAX",
"total": "ORDER_TOTAL",
"kpis": {
"estimated_total": 0,
"created_on": "CREATED_ON",
"last_updated_on": "LAST_UPDATED_ON"
}
}
}| Attribute | Type | Description |
|---|---|---|
| event_uuid | String (UUID) | Correlation token for the downgrade lifecycle event. |
| operation | String | Marker describing the operation performed. |
| order.status | String | Lifecycle status after the downgrade. |
| order.id | String | Order identifier. |
| order.uuid | String (UUID) | Order UUID. |
| order.version | String | Order version. |
| order.lines | Array | Line items reflecting the downgraded pricing snapshot. |
| order.subtotal | String | Order subtotal. |
| order.tax | String | Order tax. |
| order.total | String | Order total. |
| order.kpis | Object | KPI block. |
Preview an Order Downgrade: /orders/{id}/downgrade/preview
Purpose
Preview the financial impact of a proposed downgrade without committing it, identified by the order ID. The request shape matches the downgrade endpoint exactly — effective_date, optional effective_immediately, redemption_code, discount_percentage, discount_amount, billing_period, lines array with charge_item_uuid and new lower-tier pricing snapshot, optional payment_information, and an optional properties block for order-level adjustments. The system simulates the downgrade against the live order state and returns a slim totals projection wrapped under a preview key, accompanied by an operation marker. The endpoint is read-only on the live order — no persisted state changes — and safe to call repeatedly while iterating on a proposed downgrade.
Use Case
Downgrade previews surface the same totals math as upgrade previews but with the polarity inverted: the customer-facing total drops, the prorated credit (if any) appears as a negative on total_due, and the difference between the old and new total reflects the lost revenue. Self-service portals call this endpoint when a user picks a lower tier so the UI can render the new total, any credit due to the customer, and the post-downgrade billing structure alongside a confirmation button. Customer success teams use it during retention conversations to show customers the financial impact of downgrading rather than churning. Finance teams pipe proposed downgrades through the preview to validate that downgrade-related credits resolve cleanly before pushing the change live. Because the response is a slim totals object, the call is fast and cheap to repeat as the user iterates on tier selection.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order whose downgrade is being previewed. |
Query Parameters
No query parameters required.
Request Body
{
"effective_date": "EFFECTIVE_DATE",
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"package_name": "PACKAGE_NAME",
"quantity": "QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE"
}
}
}
]
}Response
Returns a slim totals projection wrapped under a preview object, accompanied by an operation marker. The preview block exposes sub_total, tax_total, discount_total, shipping_total, total, currency, old_total (pre-downgrade total for comparison), total_changed (the delta — typically negative for a downgrade), and total_due (prorated amount payable or refundable). No persisted state changes occur on the live order. Errors follow the standard envelope: 404 if the order ID does not exist, 422 for validation failures, 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"operation": "OPERATION",
"preview": {
"sub_total": "SUB_TOTAL",
"tax_total": "TAX_TOTAL",
"discount_total": "DISCOUNT_TOTAL",
"shipping_total": "SHIPPING_TOTAL",
"total": "TOTAL",
"currency": "CURRENCY",
"old_total": "OLD_TOTAL",
"total_changed": "TOTAL_CHANGED",
"total_due": "TOTAL_DUE"
}
}| Attribute | Type | Description |
|---|---|---|
| operation | String | Marker describing the simulated lifecycle event. |
| preview.sub_total | String | Projected subtotal. |
| preview.tax_total | String | Projected total tax. |
| preview.discount_total | String | Projected total discount applied. |
| preview.shipping_total | String | Projected shipping total. |
| preview.total | String | Projected new order total. |
| preview.currency | String | Currency code. |
| preview.old_total | String | Pre-downgrade total for comparison. |
| preview.total_changed | String | Delta between old and new total (typically negative). |
| preview.total_due | String | Prorated amount payable or refundable. |
Apply a Contract Adjustment to an Order: /orders/{id}/contract-adjustment
Purpose
Apply a contract adjustment to an active order, identified by the order ID. Contract adjustments are mid-term changes to a contractual order that modify pricing, quantities, or package selections without ending the contract or starting a new one. The request carries effective_date controlling when the adjustment takes effect (or effective_immediately for instant transition), optional redemption_code/discount_percentage/discount_amount for promotional pricing, optional billing_period override, a lines array describing the adjusted pricing snapshot (each entry carrying charge_item_uuid identifying the existing line plus the new package_name and pricing_rule), optional payment_information for any settlement, and an optional properties block for order-level adjustments. On success the API returns the post-adjustment projection wrapped under a preview key with totals reflecting the change, accompanied by an operation marker.
Use Case
Contract adjustments support mid-term changes to live contractual orders without the disruption of cancelling and reissuing the contract. Customers on multi-month or multi-year contracts often request package upgrades, quantity changes, or promotional pricing partway through their term — finance, customer success, and sales-ops teams use this endpoint to commit those changes cleanly. The endpoint differs from upgrade/downgrade in that the contract remains intact: the adjustment is recorded against the existing contract rather than creating a new lifecycle event. Self-service portals call it after the customer accepts the change rendered from the matching contract-adjustment-preview. CRM workflows trigger it when an account hits a renegotiation milestone. Migration scripts use it during tenant cutovers when contractual orders need pricing or package realignment without breaking continuity. The slim totals response lets callers immediately render the new financial state without an additional fetch.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order receiving the contract adjustment. |
Query Parameters
No query parameters required.
Request Body
{
"effective_date": "EFFECTIVE_DATE",
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"package_name": "PACKAGE_NAME",
"quantity": "QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE"
}
},
"isTaxExemptWhenSold": "false"
}
]
}Response
Returns the post-adjustment totals projection wrapped under a preview object, accompanied by an operation marker describing the lifecycle event. The preview block exposes sub_total, tax_total, discount_total, shipping_total, total, currency, old_total (pre-adjustment total for comparison), total_changed (the delta), and total_due (the prorated amount payable now). Errors follow the standard envelope: 404 if the order ID does not exist, 422 for validation failures (invalid charge_item_uuid, malformed effective_date, unsupported adjustment path), 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"operation": "OPERATION",
"preview": {
"sub_total": "SUB_TOTAL",
"tax_total": "TAX_TOTAL",
"discount_total": "DISCOUNT_TOTAL",
"shipping_total": "SHIPPING_TOTAL",
"total": "TOTAL",
"currency": "CURRENCY",
"old_total": "OLD_TOTAL",
"total_changed": "TOTAL_CHANGED",
"total_due": "TOTAL_DUE"
}
}| Attribute | Type | Description |
|---|---|---|
| operation | String | Marker describing the lifecycle event. |
| preview.sub_total | String | Post-adjustment subtotal. |
| preview.tax_total | String | Post-adjustment total tax. |
| preview.discount_total | String | Total discount applied. |
| preview.shipping_total | String | Shipping total. |
| preview.total | String | New order total. |
| preview.currency | String | Currency code. |
| preview.old_total | String | Pre-adjustment total for comparison. |
| preview.total_changed | String | Delta between old and new total. |
| preview.total_due | String | Prorated amount payable now. |
Preview a Contract Adjustment: /orders/{id}/contract-adjustment/preview
Purpose
Preview the financial impact of a proposed contract adjustment without committing it, identified by the order ID. The request shape mirrors the contract-adjustment endpoint exactly — effective_date, optional discount and promotional fields, a lines array with charge_item_uuid and new pricing snapshot, optional payment_information, and an optional properties block. The system simulates the adjustment against the live contract state and returns a slim totals projection under a preview key, accompanied by an operation marker. Read-only on the live order — no persisted state changes — making it safe to call repeatedly while iterating on a proposed adjustment.
Use Case
Contract adjustments change customer-facing totals mid-contract: package upgrades, quantity changes, and applied promotional pricing all combine to produce a new total that customers and operators want to see before committing. Self-service portals call this endpoint when a customer requests a mid-term change so the UI can render the projected new total, the prorated amount due, and the post-adjustment billing structure alongside a confirmation button — only after explicit acceptance does the client invoke the matching contract-adjustment endpoint. Sales-ops automation pipes proposed adjustments through the preview to validate that promotional codes resolve cleanly and that the resulting total matches what the operator quoted manually. Finance teams use it during renegotiation conversations to surface the financial impact before commitments are made. Because the response is a slim totals object, the call is fast and cheap to repeat as the customer iterates on package or quantity selection.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order whose contract adjustment is being previewed. |
Query Parameters
No query parameters required.
Request Body
{
"effective_date": "EFFECTIVE_DATE",
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"package_name": "PACKAGE_NAME",
"quantity": "QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "PRICE"
}
}
}
]
}Response
Returns a slim totals projection wrapped under a preview object, accompanied by an operation marker. The preview block exposes sub_total, tax_total, discount_total, shipping_total, total, currency, old_total (pre-adjustment total for comparison), total_changed (the delta), and total_due (the prorated amount payable now). No persisted state changes occur on the live order. Errors follow the standard envelope: 404 if the order ID does not exist, 422 for validation failures, 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"operation": "OPERATION",
"preview": {
"sub_total": "SUB_TOTAL",
"tax_total": "TAX_TOTAL",
"discount_total": "DISCOUNT_TOTAL",
"shipping_total": "SHIPPING_TOTAL",
"total": "TOTAL",
"currency": "CURRENCY",
"old_total": "OLD_TOTAL",
"total_changed": "TOTAL_CHANGED",
"total_due": "TOTAL_DUE"
}
}| Attribute | Type | Description |
|---|---|---|
| operation | String | Marker describing the simulated lifecycle event. |
| preview.sub_total | String | Projected subtotal. |
| preview.tax_total | String | Projected total tax. |
| preview.discount_total | String | Projected discount total. |
| preview.shipping_total | String | Projected shipping total. |
| preview.total | String | Projected new order total. |
| preview.currency | String | Currency code. |
| preview.old_total | String | Pre-adjustment total for comparison. |
| preview.total_changed | String | Delta between old and new total. |
| preview.total_due | String | Prorated amount payable now. |
Relinquish an Order: /orders/{id}/relinquish
Purpose
Relinquish an active order, identified by the order ID — typically applied to rental or asset-backed orders when the customer formally returns the asset or terminates the rental commitment before the natural end of the contract. The request wraps an order object carrying an effective_date controlling when the relinquishment takes effect. The endpoint records the customer's return of the asset, triggers any downstream prorations or refunds tied to early termination, and transitions the order to a relinquished lifecycle state. On success the API returns the post-relinquish record under an order wrapper with an event_uuid correlation token and operation marker, reflecting the new status, account binding, totals, and audit fields.
Use Case
Asset-backed and rental orders carry obligations on both sides — the customer commits to a billing schedule, the operator delivers an asset for use. When the customer wants to return the asset early, relinquishment is the formal mechanism that captures that act and updates billing accordingly. Equipment rental businesses use this endpoint when customers return rented equipment ahead of the contract end date, with the effective_date setting the precise return time for proration. Subscription services with hardware components (e.g., set-top boxes, IoT devices) call it when the customer returns the hardware as part of a cancellation flow. Operations teams use it during fleet recovery operations to record the formal return of assets. The endpoint differs from cancellation in that relinquishment specifically tracks asset return rather than just lifecycle termination — downstream automation may key off the relinquish event to trigger inspection, refurbishment, or restocking workflows that wouldn't fire on a generic cancel.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Unique identifier of the order being relinquished. |
Query Parameters
No query parameters required.
Request Body
{
"order": {
"effective_date": "EFFECTIVE_DATE"
}
}Response
Returns the post-relinquish record wrapped under an order object, accompanied by event_uuid and operation correlation tokens. The embedded order block exposes lifecycle status (typically relinquished), identity fields, currency and time_zone references, billing/start dates, account binding, line items, totals, custom attributes, KPI block, and audit fields. Errors follow the standard envelope: 404 if the order ID does not exist, 409/422 if the order is not in a relinquishable state, 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"event_uuid": "EVENT_UUID",
"operation": "OPERATION",
"order": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"uuid": "ORDER_UUID",
"version": "VERSION",
"name": "ORDER_NAME",
"display_name": "ORDER_DISPLAY_NAME",
"description": "ORDER_DESCRIPTION",
"order_type": "ORDER_TYPE",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_DATE",
"created_by": "CREATED_BY",
"created_on": "CREATED_ON",
"last_updated_by": "LAST_UPDATED_BY",
"last_updated_on": "LAST_UPDATED_ON",
"lines": [
{
"item_uuid": "ITEM_UUID",
"item_id": "ITEM_ID",
"item_name": "ITEM_NAME",
"item_order_quantity": "ITEM_ORDER_QUANTITY",
"subtotal": "LINE_SUBTOTAL",
"tax": "LINE_TAX",
"total": "LINE_TOTAL",
"version": "LINE_VERSION"
}
],
"subtotal": "ORDER_SUBTOTAL",
"tax": "ORDER_TAX",
"total": "ORDER_TOTAL",
"kpis": {
"estimated_total": 0,
"created_on": "CREATED_ON",
"last_updated_on": "LAST_UPDATED_ON"
}
}
}| Attribute | Type | Description |
|---|---|---|
| event_uuid | String (UUID) | Correlation token for the relinquish lifecycle event. |
| operation | String | Marker describing the operation performed. |
| order.status | String | Lifecycle status after relinquishment. |
| order.id | String | Order identifier. |
| order.uuid | String (UUID) | Order UUID. |
| order.version | String | Order version. |
| order.lines | Array | Line items on the relinquished order. |
| order.subtotal | String | Order subtotal. |
| order.tax | String | Order tax. |
| order.total | String | Order total. |
| order.kpis | Object | KPI block. |
Preview an Order Before Creation: /orders/preview
Purpose
Preview the financial totals of an order before committing to creation, identified by the wrapped order payload. The request mirrors the shape of the standard order-creation endpoint — account_id binding, price_tax_inclusive flag, and a lines array carrying item_id, quantity, and price for each line — but no persisted order record is created. The system evaluates the order against the live pricing engine, tax configuration, and discount rules, then returns a slim totals projection under a cart wrapper exposing subtotal, taxtotal, discounttotal, shippingtotal, total, currency, and an activity_logs array surfacing any informational warnings produced during evaluation. Read-only against persistent state — safe to call repeatedly while iterating on a draft order.
Use Case
Order capture flows commonly need to surface the projected total to the customer before submission so the customer can review pricing, tax, and discount application without committing to the purchase. Checkout pages call this endpoint after every line change so the displayed totals stay in sync with the cart contents — the customer adds or removes items, adjusts quantities, or applies a discount, and the UI re-renders the projected cart totals without writing anything to the order ledger. Sales-quoting tools use it to validate that a proposed order's totals match the operator's manual quote before the order is committed. Integration systems pipe candidate orders through the preview to detect mis-priced items, missing tax codes, or rule conflicts before they hit production data. Because the response is a slim cart object containing only totals and activity logs, the call is fast and cheap to repeat as the customer iterates on item selection and quantity.
Path Parameters
No path parameters required.
Query Parameters
No query parameters required.
Request Body
{
"order": {
"account_id": "ACCOUNT_ID",
"price_tax_inclusive": "PRICE_TAX_INCLUSIVE",
"lines": [
{
"item_id": "ITEM_ID",
"quantity": "QUANTITY",
"price": "PRICE"
}
]
}
}Response
Returns a slim totals projection wrapped under a cart object. The cart block exposes subtotal, taxtotal, discounttotal, shippingtotal, total, and currency code, alongside an activity_logs array carrying any informational messages produced during pricing evaluation (e.g., applied discounts, pricing rule traces, or warnings about missing tax codes). No persisted state changes occur — the live order ledger is untouched. Errors follow the standard envelope: 422 for validation failures (missing account_id, invalid item_id, malformed pricing), 401/403 for authorisation failures, and 5xx for server-side issues.
Response Body
{
"cart": {
"subtotal": "SUBTOTAL",
"taxtotal": "TAX_TOTAL",
"discounttotal": "DISCOUNT_TOTAL",
"shippingtotal": "SHIPPING_TOTAL",
"total": "TOTAL",
"currency": "CURRENCY",
"activity_logs": []
}
}| Attribute | Type | Description |
|---|---|---|
| cart.subtotal | String | Projected order subtotal before tax and discounts. |
| cart.taxtotal | String | Projected total tax across all lines. |
| cart.discounttotal | String | Projected total discount applied. |
| cart.shippingtotal | String | Projected shipping total. |
| cart.total | String | Projected grand total payable. |
| cart.currency | String | Currency code for projected totals. |
| cart.activity_logs | Array | Informational messages produced during pricing evaluation. |