SDK

commera.sdk is the stable Python API for plugins. Use it instead of Commera's internal modules, which can change in any release. Every read checks the session user's permissions.

The return shapes are TypedDicts in commera.sdk.types.

get_order

from commera.sdk import orders

order = orders.get_order("SAL-ORD-2026-00062", extra_fields=["my_app_status"])

Returns an Order dict:

Throws frappe.PermissionError when the user cannot read the order, frappe.DoesNotExistError when it does not exist, and frappe.ValidationError for a field that your plugin does not own.

get_orders

found = orders.get_orders(["SAL-ORD-2026-00062", "SAL-ORD-2026-00063"])

Returns a dict of Order keyed by the order name as a string. An order that the user cannot read, or that does not exist, is left out.

record_shipment

Records a shipment for an order: Commera creates or updates the order's Shipping Request for the AWB. It makes no Delivery Note. The order status, the order_fulfilled and order_delivered events, and the shopper's tracking page follow from it.

from commera.sdk import orders

orders.record_shipment(
	"SAL-ORD-2026-00062",
	awb="1234567890",
	carrier="Delhivery",
	tracking_url="https://example.com/track/1234567890",
	status="In Transit",
)

Returns the Shipping Request name.

• A status only moves forward. A lower status than the stored one is ignored. Delivered, Cancelled and Lost are final.
• Call it again with the same AWB to update the status, the tracking events and the tracking_url. Commera does not make a second shipment. A carrier on a later call is ignored: the first call sets it.
• Without provider, the shipment has no origin address, because the parcel left the partner's warehouse.

Throws ShippingNotInstalled (from commera.sdk.orders) when bwh_shipping is not installed, frappe.ValidationError for an empty AWB, an unknown status or an unknown provider, and frappe.PermissionError when the user cannot read the order.

get_items

from commera.sdk import catalog

items = catalog.get_items(["TSHIRT-RED-M", "TSHIRT-RED-L"])

Returns a dict of CatalogItem keyed by item code. A code that is not an Item is left out.

Throws frappe.PermissionError when the user cannot read Item.

get_cart and set_cart_fields

get_cart() returns the session shopper's cart, a guest's included, or None when they have no cart. The Cart dict has name, customer, currency, items (item_code, title, qty, rate, amount), total, grand_total and plugin_fields (every Quotation field that an installed Commera plugin owns).

set_cart_fields(values) saves your own Quotation fields on the cart, prices your fees again, and returns the checkout summary: subtotal, shipping, cod_charge, plugin_fees, taxes, discount_amount, rounding_adjustment, total, and the same figures for cash on delivery under cash_on_delivery.

import frappe
from commera.sdk import cart


@frappe.whitelist()
def set_gift_wrap(enabled: bool):
	return cart.set_cart_fields({"my_app_gift_wrap": int(enabled)})

set_cart_fields throws frappe.DoesNotExistError when the shopper has no cart, and frappe.ValidationError for a field that your plugin does not own, or when the cart is already paid or a payment for it is in progress.

as_plugin_user

A webhook from a partner arrives as Guest, with no permission to read orders. Run the SDK calls inside as_plugin_user:

import frappe
from commera.sdk import as_plugin_user, orders


@frappe.whitelist(allow_guest=True, methods=["POST"])
def shipment_webhook():
	payload = frappe.parse_json(frappe.request.get_data(as_text=True))
	# verify the partner's signature here before you trust the payload
	with as_plugin_user("my_app"):
		orders.record_shipment(payload["order"], awb=payload["awb"], tracking_url=payload.get("tracking_url"))

The plugin user holds every desk role. Verify the request before you enter the block. as_plugin_user throws when the plugin is not installed.

Next steps

• Events
• Compatibility
• Testing