Upgrade an Existing Order: /orders/{order_id}/upgrade
Purpose
This API upgrades an existing active order to a higher-tier package or product configuration. It allows users to specify an effective date for the upgrade, modify billing period properties, and include new or updated line items. The upgrade process generates an updated order instance reflecting new pricing, product details, and contractual terms.
Use Case
This API is used when an account or customer needs to move to a higher plan or add enhanced product features within an existing subscription. Typical scenarios include upgrading from a basic to a premium plan, increasing the service quantity, or adjusting billing cycles. The API ensures that the transition is recorded with accurate billing and operational terms.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | string | The unique identifier of the existing order to be upgraded. Example: ORD-AU1894-0015 |
Query Parameters
This endpoint does not accept any query parameters.
Request Body
{
"effective_date": "EFFECTIVE_DATE",
"properties": {
"billing_period": "BILLING_PERIOD",
"proforma_properties": {
"acceptance_required": true,
"payment_required": true,
"acceptance_term": "ACCEPTANCE_TERM",
"acceptance_date": "ACCEPTANCE_DATE_SELECTOR",
"terms_and_conditions": "TERMS_AND_CONDITIONS_TEXT"
}
},
"lines": [
{
"charge_item_uuid": "CHARGE_ITEM_UUID",
"item_uuid": "ITEM_UUID",
"package_name": "PACKAGE_NAME",
"item_quantity": "ITEM_QUANTITY",
"item_price_snapshot": {
"pricing_rule": {
"price": "ITEM_PRICE"
}
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
| effective_date | string | The date from which the upgrade becomes effective (ISO 8601 format). |
| properties | object | Contains general and proforma-related configuration for the upgrade. |
| properties.billing_period | string | The billing period for the upgraded order (example: 1 Month). |
| properties.proforma_properties | object | Contains settings for acceptance, payment, and terms. |
| properties.proforma_properties.acceptance_required | boolean | Indicates if acceptance is required before activation. |
| properties.proforma_properties.payment_required | boolean | Indicates if payment is required upon acceptance. |
| properties.proforma_properties.acceptance_term | string | The term duration for acceptance (example: 1 Month). |
| properties.proforma_properties.acceptance_date | string | Defines how the acceptance date is determined (example: AcceptanceDate, ProFormaInvoicePaymentDate). |
| properties.proforma_properties.terms_and_conditions | string | The text describing the acceptance terms and conditions. |
| lines | array | List of order line items to be added or modified during the upgrade. |
| lines.charge_item_uuid | string | The unique identifier of the charge item. |
| lines.item_uuid | string | The unique identifier of the item being upgraded or added. |
| lines.package_name | string | The name of the product package associated with this line item. |
| lines.item_quantity | string | Quantity of the item being ordered. |
| lines.item_price_snapshot | object | Snapshot of the pricing configuration used for the upgraded item. |
| lines.item_price_snapshot.pricing_rule.price | string | The price applied to the item during upgrade. |
Response
The API returns details of the upgraded order, including the updated order ID, status, customer account details, billing and pricing information, communication preferences, and all order line items. It also includes key performance indicators and metadata about order creation and modification. The response confirms that the upgrade has been successfully applied and provides visibility into all related order configurations and financial details.
Response Body
{
"operation": "OPERATION_TYPE",
"order": {
"status": "ORDER_STATUS",
"id": "ORDER_ID",
"pre_order": "BOOLEAN",
"quote_order": "BOOLEAN",
"name": "ORDER_NAME",
"display_name": "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": "CUSTOM_FORM_UUID",
"name": "CUSTOM_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",
"communication_preference": [
{
"media": "MEDIA_TYPE",
"isEnabled": "BOOLEAN"
}
],
"billing_start_date": "BILLING_START_DATE",
"order_start_date": "ORDER_START_DATE",
"next_billing_from_date": "NEXT_BILLING_FROM_DATE",
"next_billing_from_date_utc": "NEXT_BILLING_FROM_DATE_UTC",
"price_tax_inclusive": "BOOLEAN",
"billing_address": {},
"shipping_address": {},
"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",
"account_id": "ACCOUNT_ID",
"account_name": "ACCOUNT_NAME",
"allow_contract": "BOOLEAN",
"contract_properties": {
"require_customer_acceptance": "BOOLEAN",
"requires_payment_method": "BOOLEAN",
"initial_contract_term": "CONTRACT_TERM",
"renew_automatically": "BOOLEAN",
"allow_early_termination": "BOOLEAN",
"termination_accounting_code": "CODE",
"allow_postponement": "BOOLEAN",
"allow_trial": "BOOLEAN",
"allow_downgrade": "BOOLEAN",
"allow_upgrade": "BOOLEAN",
"termination_notice_period": "NOTICE_PERIOD"
},
"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": "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": "ITEM_QUANTITY",
"shipping_cost": "SHIPPING_COST",
"item_invoice_note": "INVOICE_NOTE",
"item_description": "ITEM_DESCRIPTION",
"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": "FIXED_START_DATE",
"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": "PRICE_AMOUNT",
"uom": "UNIT_OF_MEASURE",
"price_period": "PRICE_PERIOD",
"pricing_schedule": "SCHEDULE",
"pricing_level": "LEVEL",
"pricing_method": "METHOD"
}
},
"item_sale_tax_configuration": {
"sale_price_is_based_on": "BASE_TYPE",
"tax_code": {
"uuid": "TAX_CODE_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE",
"link": "TAX_LINK"
}
},
"isTaxExemptWhenSold": "BOOLEAN",
"item_price_tax": {
"uuid": "TAX_UUID",
"code": "TAX_CODE",
"rate": "TAX_RATE",
"link": "TAX_LINK"
},
"item_accounting_code": {
"sales_revenue": "ACCOUNT_CODE"
},
"version": "VERSION",
"expected_delivery_date": "DELIVERY_DATE",
"package_name": "PACKAGE_NAME",
"discount": "DISCOUNT_AMOUNT",
"total": "TOTAL_AMOUNT",
"subtotal": "SUBTOTAL_AMOUNT",
"tax": "TAX_AMOUNT"
}
],
"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_INVOICES",
"next_invoice_issueDate": "NEXT_INVOICE_DATE",
"last_reactivated_on": "REACTIVATED_DATE",
"last_cancelled_on": "CANCELLED_DATE",
"last_changed_on": "CHANGED_DATE",
"last_deleted_on": "DELETED_DATE"
},
"line_items": []
}
}
| Attribute | Type | Description |
|---|---|---|
| operation | string | The type of operation performed (example: UPGRADE). |
| order | object | Contains all details of the upgraded order. |
| order.status | string | Current status of the order after the upgrade (example: ACTIVE). |
| order.id | string | Unique identifier of the upgraded order. |
| order.name | string | Name or title of the order. |
| order.account_id | string | Account ID associated with the order. |
| order.account_name | string | Account name associated with the order. |
| order.currency | object | Currency details used in the order. |
| order.lines | array | List of order line items after upgrade. |
| order.lines.item_name | string | Name of the item included in the order. |
| order.lines.total | string | Total amount for the specific line item. |
| order.total | string | Total amount for the entire order. |
| order.subtotal | string | Subtotal amount before taxes. |
| order.tax | string | Tax amount applied to the order. |
| order.kpis | object | Key performance indicators for financial and operational tracking. |
Accept an Order: /orders/{order_id}/accept
Purpose
This API endpoint is used to accept a pending order within the system. When an order is awaiting acceptance (for example, after a pro forma invoice or approval step), this API confirms the acceptance and triggers any associated business logic such as invoice creation or payment initiation.
Use Case
The API is typically used when a customer or system action finalizes an order agreement. Upon acceptance, the platform generates an official invoice and flags whether a payment is required. This endpoint is useful for automating the acceptance workflow of subscription upgrades, renewals, or custom contracts that require explicit user or system confirmation.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | string | The unique identifier of the order to be accepted. |
Query Parameters
This endpoint does not accept any query parameters.
Request Body
This API does not require a request body.
Response
When the request is successful, the API responds with a confirmation message indicating that the order has been accepted. It also returns the newly generated invoice ID and a boolean flag specifying whether payment is required. A successful response confirms that the order’s acceptance process has been completed, including any associated financial actions or state transitions.
Response Body
{
"message": "Acceptance has been created successfully",
"invoice_id": "INV-XXXXXXXX",
"payment_required": true
}
| Attribute | Type | Description |
|---|---|---|
| message | string | A confirmation message indicating that the order acceptance was completed successfully. |
| invoice_id | string | The unique identifier of the generated invoice associated with this order acceptance. |
| payment_required | boolean | Indicates whether a payment is required for the accepted order. |
Apply Payment to a Proforma Invoice: /proforma-invoices/{proforma_invoice_id}/payments
Purpose
This API endpoint allows the application of a payment to an existing Pro Forma Invoice. It records the payment details, such as payment date, method, amount, and reference, and links the payment to the corresponding Pro Forma Invoice in the system. This operation is essential in financial workflows where Pro Forma Invoices are issued for prepayment before final invoicing or service activation.
Use Case
This API is typically used when a customer or system user needs to record a payment made against a Pro Forma Invoice. For example, in billing systems, Pro Forma Invoices act as a pre-invoice or quotation. When the customer makes a payment, this endpoint ensures that the transaction is tracked, marked as paid, and associated correctly with the corresponding Pro Forma Invoice. It is often used in automated billing processes, integrations with payment processors, or manual payment reconciliations.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| proforma_invoice_id | string | The unique identifier of the Pro Forma Invoice to which the payment will be applied. |
Query Parameters
This endpoint does not accept query parameters.
Request Body
{
"payment": {
"date": "YYYY-MM-DD",
"note": "NOTE_TEXT",
"payment_note": "PAYMENT_NOTE_TEXT",
"payment_applied": [
{
"processor": "PAYMENT_METHOD",
"amount": "PAYMENT_AMOUNT",
"reference": "REFERENCE_CODE"
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
| payment | object | Contains all details related to the payment being applied. |
| payment.date | string | The date when the payment was made (format: YYYY-MM-DD). |
| payment.note | string | A general note related to the payment, for internal or reference purposes. |
| payment.payment_note | string | Additional remarks or descriptive note about the payment transaction. |
| payment.payment_applied | array | A list of payment applications detailing processor, amount, and reference information. |
| payment.payment_applied.processor | string | The payment method or processor used (example: Cash, Credit Card, Bank Transfer). |
| payment.payment_applied.amount | string | The total payment amount applied to the Pro Forma Invoice. |
| payment.payment_applied.reference | string | (Optional) A reference or transaction ID associated with the payment, such as a receipt number or bank reference. |
Response
When the payment is successfully recorded, the API returns a confirmation message along with a unique identifier for the applied payment. This indicates that the payment has been successfully linked to the specified Pro Forma Invoice and the system has updated the related accounting records. The response helps confirm that the payment process has completed and can be used for audit tracking or user confirmation.
Response Body
{
"message": "Pro Forma Payment has been applied successfully",
"payment_id": "PFPMT-XXXXXXXX"
}
| Attribute | Type | Description |
|---|---|---|
| message | string | A confirmation message indicating the successful application of the payment. |
| payment_id | string | The unique identifier generated for the applied payment record in the system. |