bigcommerce_get_order / bigcommerce_find

bigcommerce_get_order(context: dict, order_number: str) -> dict | None
bigcommerce_find_orders(context: dict, email: str, limit: int = 10) -> list[dict]

Thin helpers for the most common BigCommerce read: finding a customer's order. They read the business's BigCommerce connection with get_integration_credentials, call the BigCommerce v2 Orders API and return the orders as BigCommerce returns them; see the BigCommerce API reference for every field. Each order also carries its products, shipping_addresses and shipments (with tracking numbers) inline, instead of the API's resource links. A few fields a support bot should never see are left out: the customer's IP address and stored payment references.

BigCommerce order numbers are numeric, so anything else returns None. Both helpers raise ValueError if BigCommerce isn't connected and requests.HTTPError if BigCommerce rejects the request.

The full source is below. Copy it into your own action when you need something it doesn't do.

`bigcommerce_get_order`

Name	Type	Description
`context`	`dict`	The context object passed to your action
`order_number`	`str`	The order number as the customer gave it. Spaces and a leading `#` are ignored

Returns the matching order, or None.

`bigcommerce_find_orders`

Name	Type	Description
`context`	`dict`	The context object passed to your action
`email`	`str`	The customer's email address
`limit`	`int`	Maximum number of orders, newest first (10)

Returns a list of orders, newest first. Empty if there are none.

Example

def execute_action(context):
    order = bigcommerce_get_order(context, context["args"]["orderId"])
    if order is None:
        return {"success": False, "message": "The order could not be found."}
    return {"success": True, "orders": [order]}

Businesses moved off the built-in order lookups get this as their getOrderDetailsByOrderId action, together with a getOrderDetailsByEmail action that calls bigcommerce_find_orders. They are ordinary Python actions you can read and change.

bigcommerce_order_widget(context) renders the saved order ID and customer email lookups as a basic sidebar panel without order buttons. See Order widgets for setup, custom mappings and the shared presentation source.

Source

import re

import requests

# Never returned: the customer's IP address and stored payment references.
_BIGCOMMERCE_ORDER_HIDDEN = {"ip_address", "ip_address_v6", "payment_provider_id", "credit_card_type"}


def _bigcommerce_store(context):
    """The current business's BigCommerce connection: {"storeHash", "token"}."""
    business = context.get("business") or {}
    slug = business.get("slug") or (context.get("conversation") or {}).get("businessSlug")
    if not slug:
        raise ValueError("The business is not available in the context")
    store = (get_integration_credentials(context).get(slug) or {}).get("bigCommerce")
    if not store:
        raise ValueError("BigCommerce is not connected for this business")
    return store


def _bigcommerce_get(store, path, params=None):
    response = requests.get(
        f"https://api.bigcommerce.com/stores/{store['storeHash']}/v2/{path}",
        headers={"X-Auth-Token": store["token"], "Accept": "application/json"},
        params=params or {},
        timeout=20,
    )
    # The v2 API answers 204 No Content for an empty list.
    if response.status_code in (204, 404):
        return None
    response.raise_for_status()
    return response.json()


def _bigcommerce_expand(store, order):
    """The order with its products, shipping addresses and shipments inlined."""
    order = {k: v for k, v in order.items() if k not in _BIGCOMMERCE_ORDER_HIDDEN}
    for resource in ("products", "shipping_addresses", "shipments"):
        order[resource] = _bigcommerce_get(store, f"orders/{order['id']}/{resource}") or []
    return order


def bigcommerce_get_order(context, order_number):
    """The BigCommerce order with this number, or None."""
    store = _bigcommerce_store(context)
    number = re.sub(r"\s+", "", str(order_number)).lstrip("#")
    if not number.isdigit():
        return None
    order = _bigcommerce_get(store, f"orders/{number}")
    return _bigcommerce_expand(store, order) if order else None


def bigcommerce_find_orders(context, email, limit=10):
    """The customer's BigCommerce orders by email, newest first."""
    store = _bigcommerce_store(context)
    orders = _bigcommerce_get(store, "orders", {"email": email.strip(), "sort": "date_created:desc", "limit": limit}) or []
    return [_bigcommerce_expand(store, order) for order in orders[:limit]]


def _bigcommerce_widget_order(order):
    return {
        "id": order.get("id"), "status": order.get("status"),
        "email": (order.get("billing_address") or {}).get("email"),
        "total": order.get("total_inc_tax"), "currency": order.get("currency_code"), "placed_at": order.get("date_created"),
        "products": [{"name": p.get("name"), "quantity": p.get("quantity"), "sku": p.get("sku"), "total": p.get("total_inc_tax")}
                     for p in order.get("products") or []],
        "shipments": [{"carrier": s.get("shipping_provider") or s.get("tracking_carrier"), "tracking_number": s.get("tracking_number")}
                      for s in order.get("shipments") or []],
    }


def bigcommerce_order_widget(context):
    """Read-only sidebar orders from the saved order ID and customer's email."""
    return order_widget(context, get_order=bigcommerce_get_order, find_orders=bigcommerce_find_orders, map_order=_bigcommerce_widget_order)

bigcommerce_get_order / bigcommerce_find_orders

`bigcommerce_get_order`

`bigcommerce_find_orders`

Example

Read-only sidebar

Source

On this page