Order PATCH API Documentation

Purpose

This endpoint updates the billing preferences of a specific order, including invoice settings, payment options, fulfillment rules, and consolidation behavior.

Use Case

The endpoint is used to change the billing preferences that how a specific order should be invoiced and paid. For example, if an admin wants to switch an order from manual to automatic billing, change the payment processor from cheque to cash or others, update the invoice term to "Net -7", this endpoint allows them to perform those updates dynamically.

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 should include a new set of billing preference values under the order > properties object.

                JSON
              

                      {
  "order": {
    "properties": {
      "communication_profile": "STRING_VALUE",
      "invoice_mode": "STRING_VALUE",
      "invoice_term": "STRING_VALUE",
      "billing_period": "STRING_VALUE",
      "payment_processor": "STRING_VALUE",
      "payment_mode": "STRING_VALUE",
      "payment_term": "STRING_VALUE",
      "payment_term_alignment": "STRING_VALUE",
      "fulfillment_mode": "STRING_VALUE",
      "fulfillment_term": "STRING_VALUE",
      "pro_rata_partial_charging_period": "BOOLEAN",
      "pro_rata_partial_pricing_period": "BOOLEAN",
      "pro_rata_partial_unit": "BOOLEAN"
    }
  }
}
                    

Attribute	Type	Description
communication_profile	String	Name of the communication profile.
invoice_mode	String	Invoicing mode (MANUAL, AUTOMATIC).
invoice_term	String	Terms of the invoice
billing_period	String	Period for recurring billing
payment_processor	String	Processor used to handle payments.
payment_mode	String	Payment mode (MANUAL, AUTOMATIC).
payment_term	String	Payment term .
payment_term_alignment	String	Alignment rule for payment terms.
fulfillment_mode	String	Mode of order fulfillment
fulfillment_term	String	Term for fulfilling the order

Response

The endpoint returns the updated billing preferences of the order, including both submitted and system-managed fields like consolidation settings. These preferences define how the order will be invoiced, paid, and fulfilled moving forward.

Response Body

                JSON
              

                      {
  "order": {
    "properties": {
      "communication_profile": "STRING_VALUE",
      "invoice_mode": "STRING_VALUE",
      "invoice_term": "STRING_VALUE",
      "billing_period": "STRING_VALUE",
      "consolidate_invoice": "BOOLEAN",
      "consolidate_key": "STRING_VALUE",
      "payment_processor": "STRING_VALUE",
      "payment_mode": "STRING_VALUE",
      "payment_term": "STRING_VALUE",
      "payment_term_alignment": "STRING_VALUE",
      "fulfillment_mode": "STRING_VALUE",
      "fulfillment_term": "STRING_VALUE"
    }
  }
}
                    

Attribute	Type	Description
communication_profile	String	Updated communication profile used for this order.
invoice_mode	String	Invoice generation mode .
invoice_term	String	Terms under which the invoice is considered due.
billing_period	String	Updated billing frequency for the order.
consolidate_invoice	String	Whether invoices should be consolidated .
consolidate_key	String	Identifier used for invoice consolidation grouping.
payment_processor	String	Payment processor to use .
payment_mode	String	Mode of payment execution .
payment_term	String	Payment due terms.
payment_term_alignment	String	Alignment for calculating payment terms.
fulfillment_mode	String	How the order will be fulfilled .
fulfillment_term	String	Timeline or terms for fulfillment .

Purpose

This API is used to update general order information such as name, display name, description, purchase order reference, origin, and invoice notes. It allows partial modification of existing order data without altering billing, workflow, or order line configurations.

Use Case

This API is typically used when a user needs to modify order details after creation, for example, updating the order name to match a new version, changing the description to reflect additional details, updating customer purchase order references, or adding invoice notes. It provides flexibility to keep order information up to date as the order progresses through its lifecycle.

Path Parameters

Parameter	Type	Description
order_id	String	Unique identifier of the order whose information is being updated.

Query Parameters

This endpoint does not accept query parameters.

Request Body

                JSON
              

                      {
    "order": {
        "name": "ORDER_NAME_PLACEHOLDER",
        "display_name": "DISPLAY_NAME_PLACEHOLDER",
        "description": "ORDER_DESCRIPTION_PLACEHOLDER",
        "customer_purchase_order_id": "CUSTOMER_PO_ID_PLACEHOLDER",
        "origin": "ORDER_ORIGIN_PLACEHOLDER",
        "invoice_note": "INVOICE_NOTE_PLACEHOLDER"
    }
}

                    

Attribute	Type	Description
order	Object	Root object that contains all order details to be updated.
name	String	Updated name of the order.
display_name	String	Display name of the order visible in user interfaces or reports.
description	String	Detailed description or note providing context for the order.
customer_purchase_order_id	String	Customer’s external purchase order reference ID linked to this order.
origin	String	Specifies the origin or source context from which the order was created.
invoice_note	String	Note or comment that appears on the invoices related to this order.

Response

A successful request returns the updated order object with all modified attributes. The response includes essential order information such as name, display name, description, invoice note, purchase order reference, and metadata like timestamps, user details, and currency. It confirms that the order’s information has been successfully updated while maintaining its active status and preserving all other order properties, billing data, and associations.

Response Body

                JSON
              

                      {
  "order": {
    "status": "ORDER_STATUS",
    "id": "ORDER_ID",
    "pre_order": "BOOLEAN",
    "quote_order": "BOOLEAN",
    "name": "ORDER_NAME",
    "display_name": "DISPLAY_NAME",
    "description": "ORDER_DESCRIPTION",
    "referral_account": "REFERRAL_ACCOUNT",
    "customer_purchase_order_id": "CUSTOMER_PO_ID",
    "shipping_profile": {},
    "shipping_cost": "SHIPPING_COST",
    "discount_profile": "DISCOUNT_PROFILE",
    "origin": "ORDER_ORIGIN",
    "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",
    "communication_preference": [
      {
        "media": "COMM_MEDIA",
        "isEnabled": "BOOLEAN"
      }
    ],
    "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": {
      "name": "BILLING_NAME",
      "address_line_1": "ADDRESS_LINE_1",
      "address_line_2": "ADDRESS_LINE_2",
      "address_line_3": "ADDRESS_LINE_3",
      "address_line_4": "ADDRESS_LINE_4",
      "address_line_5": "ADDRESS_LINE_5",
      "post_code": "POST_CODE",
      "city": "CITY",
      "state": "STATE",
      "country": "COUNTRY"
    },
    "shipping_address": {},
    "created_by": "CREATED_BY",
    "created_on": "CREATED_TIMESTAMP",
    "last_updated_by": "LAST_UPDATED_BY",
    "last_updated_on": "LAST_UPDATED_TIMESTAMP",
    "uuid": "ORDER_UUID",
    "version": "ORDER_VERSION",
    "account_id": "ACCOUNT_ID",
    "account_name": "ACCOUNT_NAME",
    "allow_contract": "BOOLEAN",
    "custom_attributes": [
      { "name": "CUSTOM_ATTRIBUTE_NAME", "value": "CUSTOM_ATTRIBUTE_VALUE" }
    ],
    "custom_objects": [],
    "currency_id": "CURRENCY_ID",
    "invoice_id": "INVOICE_ID",
    "total": "ORDER_TOTAL",
    "subtotal": "ORDER_SUBTOTAL",
    "tax": "ORDER_TAX"
  }
}
                    

Attribute	Type	Description
order	Object	The main object containing updated order information.
status	String	Current status of the order (example: ACTIVE).
id	String	System-generated unique order identifier.
pre_order	Boolean	Indicates whether the order was created as a pre-order.
quote_order	Boolean	Indicates whether the order originated from a quote.
name	String	Updated order name after modification.
display_name	String	Updated display name of the order.
description	String	Updated order description.
referral_account	String	Linked referral account, if applicable.
customer_purchase_order_id	String	Updated external purchase order reference.
shipping_profile	Object	Contains shipping profile details associated with the order.
shipping_cost	String	Total shipping cost applied to the order.
discount_profile	Object	Applied discount configuration, if any.
origin	String	Updated order origin source.
custom_forms	Object	Form configuration attached to this order.
currency	Object	Currency information including reference links.
time_zone	Object	Time zone information associated with the order.
invoice_note	String	Updated note added for invoicing purposes.
billing_start_date	String	Reference to when billing begins relative to the order.
order_start_date	DateTime	The order’s activation or start date.
next_billing_from_date	DateTime	Date for the next billing cycle initiation.
next_billing_from_date_utc	DateTime	UTC version of the next billing date.
price_tax_inclusive	Boolean	Indicates if the order price includes tax.
billing_address	Object	Billing address details for the order.
shipping_address	Object	Shipping address details for the order.
created_by	String	Username or system that created the order.
created_on	DateTime	Timestamp when the order was originally created.
last_updated_by	String	User or process that last updated the order.
last_updated_on	DateTime	Timestamp of the most recent update.
uuid	UUID	Universal unique identifier for the order.
version	String	Version number of the order record.
account_id	String	Associated account identifier.
account_name	String	Display name of the account related to the order.
allow_contract	Boolean	Indicates if contracts are allowed for this order.
custom_attributes	Array	List of custom attribute fields associated with the order.
custom_objects	Array	List of custom objects linked to the order.
currency_id	String	Internal currency identifier.
invoice_id	String	Identifier of the related invoice.
total	String	Total order amount after taxes and discounts.
subtotal	String	Total order amount before taxes and discounts.
tax	String	Tax amount applied to the order.

Purpose

This API is used to update specific details of an existing line item within an order, such as the item name, invoice note, or description. It allows users to modify line-level information after an order has been created, ensuring that all item-related data remains accurate and consistent with operational requirements.

Use Case

Businesses may use this API to adjust details of products or services listed in an order when updates occur. For example, renaming an item, adding additional descriptions, or appending invoice notes for billing clarity. This is commonly used in order management systems where line items need correction or enrichment before invoicing or fulfillment.

Path Parameters

Parameter	Type	Description
order_id	String	Unique identifier of the order to which the line belongs.
line_uuid	String	Unique identifier of the specific order line item to be updated.

Query Parameters

This endpoint does not accept query parameters.

Request Body

                JSON
              

                      {
  "order": {
    "line": {
      "item_name": "ITEM_NAME",
      "item_invoice_note": "ITEM_INVOICE_NOTE",
      "item_description": "ITEM_DESCRIPTION"
    }
  }
}
                    

Attribute	Type	Description
order	Object	Container for order-related information.
line	Object	Contains data specific to the order line being updated.
item_name	String	The display name of the item to be updated.
item_invoice_note	String	A note to be added to the item’s invoice details.
item_description	String	A detailed description of the item.

Response

The API returns the updated order and line details. It includes the modified item information along with related charge details, pricing structure, tax information, and key performance indicators (KPIs) associated with the order. This comprehensive response allows systems to synchronize order data in real time, ensuring financial and operational accuracy across billing, inventory, and reporting modules.

Response Body

                JSON
              

                      {
  "order": {
    "invoice_id": "INVOICE_ID",
    "charge": {
      "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": "ITEM_INVOICE_NOTE",
      "item_description": "ITEM_DESCRIPTION",
      "item_type": "ITEM_TYPE",
      "item_charge_type": "CHARGE_TYPE",
      "item_custom_attributes": [],
      "item_price_snapshot": {
        "pricing_rule": {
          "uuid": "PRICING_RULE_UUID",
          "version": "PRICING_RULE_VERSION",
          "price_type": "PRICE_TYPE",
          "price": "ITEM_PRICE",
          "uom": "UOM",
          "price_period": "PRICE_PERIOD",
          "pricing_schedule": "PRICING_SCHEDULE",
          "pricing_level": "PRICING_LEVEL",
          "pricing_method": "PRICING_METHOD",
          "warehouse": "WAREHOUSE"
        }
      },
      "item_sale_tax_configuration": {
        "sale_price_is_based_on": "SALE_PRICE_BASIS",
        "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": {
          "name": "SALES_REVENUE"
        }
      },
      "version": "CHARGE_VERSION",
      "expected_delivery_date": "DELIVERY_DATE",
      "purchase_order_id": "PURCHASE_ORDER_ID",
      "purchase_invoice_id": "PURCHASE_INVOICE_ID",
      "flat_discount": "FLAT_DISCOUNT",
      "item_sales_rate_id": "SALES_RATE_ID",
      "latestData0": "LATEST_DATA"
    }
  }
}
                    

Attribute	Type	Description
order	Object	Contains the updated order and related details.
invoice_id	String/Null	Identifier for the associated invoice, if available.
charge	Object	Contains information about the specific order line’s charge details.
charge_item_uuid	UUID	Unique identifier for the charged item.
item_uuid	UUID	Unique identifier for the item.
item_id	String	System-generated identifier of the item.
item_name	String	Updated name of the item.
item_order_quantity	String	Quantity of the item ordered.
shipping_cost	String	Shipping cost associated with the item.
item_invoice_note	String	Updated invoice note for the item.
item_description	String	Updated item description.
item_type	String	Classification type of the item (example: FAMILY).
item_charge_type	String	Type of item charge (example: RECURRING).
item_custom_attributes	Array	List of custom attributes related to the item.
item_properties	Object	Key-value properties that describe item billing and pricing behavior.
item_price_snapshot	Object	Contains snapshot details of pricing rules and structure.
item_sale_tax_configuration	Object	Contains configuration related to sales tax for the item.
isTaxExemptWhenSold	Boolean	Indicates if the item is exempt from tax when sold.
item_price_tax	Object	Contains tax details applicable to the item price.
item_accounting_code	Object	Contains accounting codes related to item sales revenue.
version	String	Version number of the line record.
expected_delivery_date	String	Expected date of item delivery.
package_name	String	Name of the package or group the item belongs to.
purchase_order_id	String	ID of the associated purchase order.
purchase_invoice_id	String	ID of the associated purchase invoice.
flat_discount	String	Flat discount applied to the item.
item_sales_rate_id	String	Identifier for the sales rate configuration.
latestData0	String	Additional internal or temporary data.
shipping_profile_id	String	Identifier of the shipping profile used.
pro_rata_partial_unit	String	Indicates whether partial unit prorating applies.
id	Integer	Numeric identifier for the order line.
perUnitPrice0	String	Per-unit price of the item.
total0	String	Total calculated price for the item.
warehouse_applicable	Boolean	Indicates whether the warehouse configuration applies.
rule_excess_price	String	Additional price for exceeding configured rules.
price_tax_inclusive	Boolean	Indicates whether the price includes tax.
back_order_quantity	String	Quantity of items on backorder.
tax_inclusive_rate	String	Tax-inclusive rate applied.
sales_rate_option	String	Method used to calculate sales rate (example: PER_UNIT).
price	String	Base price of the item.
tax_inclusive_based_on	String	Indicates whether tax is based on sales or purchase tax.
salesTaxName0	String	Name of the tax applied.
tax0	String	Tax amount applied.
sales_tax_code_id	String	Identifier of the applied tax code.
sales_tax_rate	String	Applied sales tax rate.
kpis	Object	Contains order-level key performance indicators and summary data.
line_items	Array	List of line items included in the order.

Update Order Billing Preferences: /orders/{order_id}/billing-preferences

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Update Order Information: /orders/{order_id}/information

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Update Order Line Information: /orders/{order_id}/lines/{line_uuid}/information

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body