Order PUT API Documentation

Purpose

This API allows updating billing preferences for a specific line item within an existing order. It enables users to modify how and when billing occurs for that particular item, including parameters like billing mode, charging period, start date, and pro-rata configurations.

Use Case

This API is typically used when a user needs to adjust the billing schedule or payment alignment for an item in an active order. For example, if a customer changes from postpaid to prepaid billing, or if billing should start on a specific date, this API updates those details accordingly.

Path Parameters

Parameter	Type	Description
order_id	String	Unique identifier of the order to which the line item belongs.
line_uuid	String	Unique identifier of the line item whose billing preferences are being updated.

Query Parameters

This endpoint does not accept query parameters.

Request Body

                JSON
              

                      {
    "order": {
        "line": {
            "item_properties": {
                "billing_mode": "IN_ADVANCE",
                "charging_period": "Same as billing period",
                "fixed_start_date": "YYYY-MM-DD",
                "charging_and_billing_alignment": "false",
                "pro_rata_partial_charging_period": "true",
                "pro_rata_partial_pricing_period": "true",
                "pro_rata_partial_unit": "true"
            }
        }
    }
}

                    

Attribute	Type	Description
order	Object	Root object containing order-level data.
line	Object	Represents the specific line item whose billing settings are being modified.
item_properties	Object	Holds all billing configuration options for the line item.
billing_mode	String	Defines when the billing occurs for the item. Accepted values: IN_ADVANCE, IN_ARREARS.
charging_period	String	Specifies the charging period, typically aligned with the billing period.
fixed_start_date	Date	Date when billing should start, if not aligned with the order start date.
charging_and_billing_alignment	Boolean	Indicates whether charging and billing periods should be synchronized.
pro_rata_partial_charging_period	Boolean	Determines if partial charging periods should be billed on a pro-rata basis.
pro_rata_partial_pricing_period	Boolean	Determines if partial pricing periods should be calculated on a pro-rata basis.
pro_rata_partial_unit	Boolean	Indicates whether partial units are billed proportionally based on usage.

Response

A successful request returns a complete order object reflecting the updated billing preferences. The order status, item details, and configuration parameters are included to confirm the modification. The response shows the updated order line item, including its revised billing mode, ensuring that the order remains active and properly aligned with new billing rules.

Response Body

                JSON
              

                      {
    "order": {
        "status": "ACTIVE",
        "id": "ORD-XXXXX-0001",
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "version": "2",
        "name": "Sample Order",
        "currency": {
            "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "AUD",
            "link": "{{domain}}/api/v3/settings/currencies/{{currency_uuid}}"
        },
        "time_zone": {
            "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "Australia/Melbourne",
            "link": "{{domain}}/api/v3/settings/time_zones/{{timezone_uuid}}"
        },
        "billing_start_date": "ORDER_START_DATE",
        "order_start_date": "YYYY-MM-DDTHH:MM:SSZ",
        "next_billing_from_date": "YYYY-MM-DD HH:MM:SS.000000",
        "price_tax_inclusive": "false",
        "created_by": "UserName",
        "created_on": "YYYY-MM-DDTHH:MM:SSZ",
        "last_updated_by": "System",
        "last_updated_on": "YYYY-MM-DDTHH:MM:SSZ",
        "lines": [
            {
                "item_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "item_id": "ITEM-0001",
                "item_name": "Sample Item",
                "item_order_quantity": "5.000000",
                "item_type": "FAMILY",
                "item_charge_type": "RECURRING",
                "item_properties": {
                    "billing_mode": "IN_ADVANCE"
                }
            }
        ]
    }
}

                    

Attribute	Type	Description
order	Object	Represents the order record containing updated billing information.
status	String	Current state of the order after the update (example: ACTIVE).
id	String	System-generated unique identifier for the order.
uuid	UUID	Universal unique identifier for the order.
version	String	Version number indicating the latest update of the order record.
name	String	Display name of the order.
currency	Object	Currency used for billing, including its reference link.
time_zone	Object	The time zone under which billing and order operations are scheduled.
billing_start_date	String	Defines the starting point of billing relative to order start.
order_start_date	DateTime	Date and time when the order becomes effective.
next_billing_from_date	DateTime	Date from which the next billing cycle begins.
price_tax_inclusive	Boolean	Indicates whether prices include tax.
created_by	String	User or system that created the order.
created_on	DateTime	Timestamp when the order was created.
last_updated_by	String	User or process that last updated the record.
last_updated_on	DateTime	Timestamp of the last update.
lines	Array	Collection of order line items.
item_uuid	UUID	Unique identifier of the specific item.
item_id	String	System-generated item identifier.
item_name	String	Display name of the item in the order.
item_order_quantity	Number	Total quantity of the item ordered.
item_type	String	Specifies the type of item (example: FAMILY, PRODUCT).
item_charge_type	String	Indicates how the item is charged (example: RECURRING).
item_properties	Object	Contains the item’s billing and pricing configuration.
billing_mode	String	Updated billing mode (example: IN_ADVANCE or IN_ARREARS).

Update Billing Preferences for Order Line: /orders/{order_id}/lines/{line_uuid}/billing-preferences