ordercloud-python 2026.4.1__py3-none-any.whl

ordercloud/resources/orders.py

@@ -0,0 +1,689 @@
+# GENERATED by tools/codegen — DO NOT EDIT
+# Source: ordercloud-openapi-v3.json
+"""OrderCloud Orders API resource."""
+
+from __future__ import annotations
+from typing import Any, Optional, Union
+
+from ..models.address import Address
+from ..models.misc import OrderDirection, SearchType
+from ..models.order import Order, OrderApproval, OrderApprovalInfo, OrderPromotion, OrderSplitResult
+from ..models.promotion import EligiblePromotion, RefreshPromosResponse
+from ..models.shipment import Shipment
+from ..models.user import User
+from ..models.shared import ListPage
+from .base import BaseResource
+
+__all__ = ["OrdersResource"]
+
+
+class OrdersResource(BaseResource):
+    """Operations on OrderCloud Orders."""
+
+    async def list(
+        self,
+        direction: OrderDirection,
+        *,
+        buyer_id: Optional[str] = None,
+        supplier_id: Optional[str] = None,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        search_type: Optional[SearchType] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[Order]:
+        """List orders
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            buyer_id: ID of the buyer.
+            supplier_id: ID of the supplier.
+            from_: Lower bound of date range that the order was created.
+            to: Upper bound of date range that the order was created.
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            search_type: Type of search to perform.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of Order objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        if buyer_id is not None:
+            params["buyerID"] = buyer_id
+        if supplier_id is not None:
+            params["supplierID"] = supplier_id
+        if from_ is not None:
+            params["from"] = from_
+        if to is not None:
+            params["to"] = to
+        if search_type is not None:
+            params["searchType"] = search_type
+        resp = await self._http.get(f"/orders/{direction}", **params)
+        return self._parse_list(resp.json(), Order)
+
+    async def create(
+        self,
+        direction: OrderDirection,
+        order: Union[Order, dict[str, Any]],
+    ) -> Order:
+        """Create an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order: A ``Order`` model or dict.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(f"/orders/{direction}", json=self._serialize(order))
+        return Order(**resp.json())
+
+    async def get(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> Order:
+        """Retrieve an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.get(f"/orders/{direction}/{order_id}")
+        return Order(**resp.json())
+
+    async def save(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        order: Union[Order, dict[str, Any]],
+    ) -> Order:
+        """Create or update an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            order: A ``Order`` model or dict.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.put(
+            f"/orders/{direction}/{order_id}",
+            json=self._serialize(order),
+        )
+        return Order(**resp.json())
+
+    async def delete(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> None:
+        """Delete an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+        """
+        await self._http.delete(f"/orders/{direction}/{order_id}")
+
+    async def patch(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch(f"/orders/{direction}/{order_id}", json=partial)
+        return Order(**resp.json())
+
+    async def apply_promotions(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> Order:
+        """Auto-apply promotions to an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/applypromotions")
+        return Order(**resp.json())
+
+    async def list_approvals(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        *,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[OrderApproval]:
+        """List order approvals
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of OrderApproval objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        resp = await self._http.get(f"/orders/{direction}/{order_id}/approvals", **params)
+        return self._parse_list(resp.json(), OrderApproval)
+
+    async def approve(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        order_approval_info: Union[OrderApprovalInfo, dict[str, Any]],
+    ) -> Order:
+        """Approve an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            order_approval_info: A ``OrderApprovalInfo`` model or dict.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(
+            f"/orders/{direction}/{order_id}/approve", json=self._serialize(order_approval_info)
+        )
+        return Order(**resp.json())
+
+    async def set_billing_address(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        address: Union[Address, dict[str, Any]],
+    ) -> Order:
+        """Set a billing address
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            address: A ``Address`` model or dict. Required fields: Street1, City, Country.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.put(
+            f"/orders/{direction}/{order_id}/billto",
+            json=self._serialize(address),
+        )
+        return Order(**resp.json())
+
+    async def patch_billing_address(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update an order billing address
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch(f"/orders/{direction}/{order_id}/billto", json=partial)
+        return Order(**resp.json())
+
+    async def cancel(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> Order:
+        """Cancel an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/cancel")
+        return Order(**resp.json())
+
+    async def complete(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> Order:
+        """Complete an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/complete")
+        return Order(**resp.json())
+
+    async def decline(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        order_approval_info: Union[OrderApprovalInfo, dict[str, Any]],
+    ) -> Order:
+        """Decline an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            order_approval_info: A ``OrderApprovalInfo`` model or dict.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(
+            f"/orders/{direction}/{order_id}/decline", json=self._serialize(order_approval_info)
+        )
+        return Order(**resp.json())
+
+    async def list_eligible_approvers(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        *,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[User]:
+        """List order eligible approvers
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of User objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        resp = await self._http.get(f"/orders/{direction}/{order_id}/eligibleapprovers", **params)
+        return self._parse_list(resp.json(), User)
+
+    async def list_eligible_promotions(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        *,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[EligiblePromotion]:
+        """List eligible promotions for an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of EligiblePromotion objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        resp = await self._http.get(f"/orders/{direction}/{order_id}/eligiblepromotions", **params)
+        return self._parse_list(resp.json(), EligiblePromotion)
+
+    async def forward(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> OrderSplitResult:
+        """Forward an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The OrderSplitResult object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/forward")
+        return OrderSplitResult(**resp.json())
+
+    async def patch_from_user(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update an order from user
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch(f"/orders/{direction}/{order_id}/fromuser", json=partial)
+        return Order(**resp.json())
+
+    async def list_promotions(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        *,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[OrderPromotion]:
+        """List order promotions
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of OrderPromotion objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        resp = await self._http.get(f"/orders/{direction}/{order_id}/promotions", **params)
+        return self._parse_list(resp.json(), OrderPromotion)
+
+    async def add_promotion(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        promo_code: str,
+    ) -> OrderPromotion:
+        """Add a promotion to an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            promo_code: Promo code of the order promotion.
+
+        Returns:
+            The OrderPromotion object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/promotions/{promo_code}")
+        return OrderPromotion(**resp.json())
+
+    async def remove_promotion(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        promo_code: str,
+    ) -> Order:
+        """Remove a promotion from an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            promo_code: Promo code of the order.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.delete(f"/orders/{direction}/{order_id}/promotions/{promo_code}")
+        return Order(**resp.json())
+
+    async def refresh_promotions(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> RefreshPromosResponse:
+        """Refresh promotions on an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The RefreshPromosResponse object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/refreshpromotions")
+        return RefreshPromosResponse(**resp.json())
+
+    async def ship(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        shipment: Union[Shipment, dict[str, Any]],
+    ) -> Order:
+        """Create a new shipment containing all items on an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            shipment: A ``Shipment`` model or dict.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(
+            f"/orders/{direction}/{order_id}/ship", json=self._serialize(shipment)
+        )
+        return Order(**resp.json())
+
+    async def list_shipments(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        *,
+        search: Optional[str] = None,
+        search_on: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        page: Optional[int] = None,
+        page_size: Optional[int] = None,
+        filters: Optional[dict[str, Any]] = None,
+    ) -> ListPage[Shipment]:
+        """List shipments for an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            search: Word or phrase to search for.
+            search_on: Comma-delimited list of fields to search on.
+            sort_by: Comma-delimited list of fields to sort by.
+            page: Page of results to return. When paginating through many items (> page 30), we recommend the "Last ID" method, as outlined in the Advanced Querying documentation.
+            page_size: Number of results to return per page.
+            filters: An object or dictionary representing key/value pairs to apply as filters. Valid keys are top-level properties of the returned model or 'xp.???'
+
+        Returns:
+            A paginated list of Shipment objects.
+        """
+        params = self._build_list_params(
+            search=search,
+            search_on=search_on,
+            sort_by=sort_by,
+            page=page,
+            page_size=page_size,
+            filters=filters,
+        )
+        resp = await self._http.get(f"/orders/{direction}/{order_id}/shipments", **params)
+        return self._parse_list(resp.json(), Shipment)
+
+    async def set_shipping_address(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        address: Union[Address, dict[str, Any]],
+    ) -> Order:
+        """Set a shipping address
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            address: A ``Address`` model or dict. Required fields: Street1, City, Country.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.put(
+            f"/orders/{direction}/{order_id}/shipto",
+            json=self._serialize(address),
+        )
+        return Order(**resp.json())
+
+    async def patch_shipping_address(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update an order shipping address
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch(f"/orders/{direction}/{order_id}/shipto", json=partial)
+        return Order(**resp.json())
+
+    async def split(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> OrderSplitResult:
+        """Split an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The OrderSplitResult object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/split")
+        return OrderSplitResult(**resp.json())
+
+    async def submit(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> Order:
+        """Submit an order
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post(f"/orders/{direction}/{order_id}/submit")
+        return Order(**resp.json())
+
+    async def validate(
+        self,
+        direction: OrderDirection,
+        order_id: str,
+    ) -> None:
+        """Validate an order in its current state
+
+        Args:
+            direction: Direction of the order, from the current user's perspective.
+            order_id: ID of the order.
+        """
+        await self._http.post(f"/orders/{direction}/{order_id}/validate")