ordercloud-python 2026.4.1__py3-none-any.whl

ordercloud/resources/cart.py

@@ -0,0 +1,613 @@
+# GENERATED by tools/codegen — DO NOT EDIT
+# Source: ordercloud-openapi-v3.json
+"""OrderCloud Cart API resource."""
+
+from __future__ import annotations
+from typing import Any, Optional, Union
+
+from ..models.address import Address
+from ..models.line_item import BundleItems, LineItem
+from ..models.order import Order, OrderPromotion, OrderShipMethodSelection, OrderWorksheet
+from ..models.payment import Payment, PaymentTransaction
+from ..models.promotion import EligiblePromotion, RefreshPromosResponse
+from ..models.shared import ListPage
+from .base import BaseResource
+
+__all__ = ["CartResource"]
+
+
+class CartResource(BaseResource):
+    """Operations on OrderCloud Cart."""
+
+    async def get(
+        self,
+    ) -> Order:
+        """Retrieve a cart
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.get("/cart")
+        return Order(**resp.json())
+
+    async def save(
+        self,
+        order: Union[Order, dict[str, Any]],
+    ) -> Order:
+        """Create or update a cart
+
+        Args:
+            order: A ``Order`` model or dict.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.put(
+            "/cart",
+            json=self._serialize(order),
+        )
+        return Order(**resp.json())
+
+    async def delete(
+        self,
+    ) -> None:
+        """Delete a cart"""
+        await self._http.delete("/cart")
+
+    async def patch(
+        self,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update a cart
+
+        Args:
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch("/cart", json=partial)
+        return Order(**resp.json())
+
+    async def set_active_cart(
+        self,
+        order_id: str,
+    ) -> None:
+        """Set an active cart
+
+        Args:
+            order_id: ID of the order.
+        """
+        await self._http.put(f"/cart/{order_id}")
+
+    async def apply_promotions(
+        self,
+    ) -> Order:
+        """Auto-apply promotions to the cart
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post("/cart/applypromotions")
+        return Order(**resp.json())
+
+    async def set_billing_address(
+        self,
+        address: Union[Address, dict[str, Any]],
+    ) -> Order:
+        """Set a billing address
+
+        Args:
+            address: A ``Address`` model or dict. Required fields: Street1, City, Country.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.put(
+            "/cart/billto",
+            json=self._serialize(address),
+        )
+        return Order(**resp.json())
+
+    async def patch_billing_address(
+        self,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update a cart billing address
+
+        Args:
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch("/cart/billto", json=partial)
+        return Order(**resp.json())
+
+    async def create_bundle_item(
+        self,
+        bundle_id: str,
+        bundle_items: Union[BundleItems, dict[str, Any]],
+    ) -> LineItem:
+        """Create a cart bundle item
+
+        Args:
+            bundle_id: ID of the bundle.
+            bundle_items: A ``BundleItems`` model or dict.
+
+        Returns:
+            The LineItem object.
+        """
+        resp = await self._http.post(
+            f"/cart/bundles/{bundle_id}", json=self._serialize(bundle_items)
+        )
+        return LineItem(**resp.json())
+
+    async def delete_bundle_item(
+        self,
+        bundle_id: str,
+        bundle_item_id: str,
+    ) -> None:
+        """Delete a cart bundle item
+
+        Args:
+            bundle_id: ID of the bundle.
+            bundle_item_id: ID of the bundle item.
+        """
+        await self._http.delete(f"/cart/bundles/{bundle_id}/{bundle_item_id}")
+
+    async def calculate(
+        self,
+    ) -> OrderWorksheet:
+        """Calculate the cart
+
+        Returns:
+            The OrderWorksheet object.
+        """
+        resp = await self._http.post("/cart/calculate")
+        return OrderWorksheet(**resp.json())
+
+    async def list_eligible_promotions(
+        self,
+        *,
+        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 the cart
+
+        Args:
+            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("/cart/eligiblepromotions", **params)
+        return self._parse_list(resp.json(), EligiblePromotion)
+
+    async def estimate_shipping(
+        self,
+    ) -> OrderWorksheet:
+        """Estimate shipping cost
+
+        Returns:
+            The OrderWorksheet object.
+        """
+        resp = await self._http.post("/cart/estimateshipping")
+        return OrderWorksheet(**resp.json())
+
+    async def patch_from_user(
+        self,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update a cart from user
+
+        Args:
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch("/cart/fromuser", json=partial)
+        return Order(**resp.json())
+
+    async def list_line_items(
+        self,
+        *,
+        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[LineItem]:
+        """List cart line items
+
+        Args:
+            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 LineItem 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("/cart/lineitems", **params)
+        return self._parse_list(resp.json(), LineItem)
+
+    async def create_line_item(
+        self,
+        line_item: Union[LineItem, dict[str, Any]],
+    ) -> LineItem:
+        """Create a cart line item
+
+        Args:
+            line_item: A ``LineItem`` model or dict. Required fields: ProductID.
+
+        Returns:
+            The LineItem object.
+        """
+        resp = await self._http.post("/cart/lineitems", json=self._serialize(line_item))
+        return LineItem(**resp.json())
+
+    async def get_line_item(
+        self,
+        line_item_id: str,
+    ) -> LineItem:
+        """Retrieve a cart line item
+
+        Args:
+            line_item_id: ID of the line item.
+
+        Returns:
+            The LineItem object.
+        """
+        resp = await self._http.get(f"/cart/lineitems/{line_item_id}")
+        return LineItem(**resp.json())
+
+    async def save_line_item(
+        self,
+        line_item_id: str,
+        line_item: Union[LineItem, dict[str, Any]],
+    ) -> LineItem:
+        """Create or update a cart line item
+
+        Args:
+            line_item_id: ID of the line item.
+            line_item: A ``LineItem`` model or dict. Required fields: ProductID.
+
+        Returns:
+            The LineItem object.
+        """
+        resp = await self._http.put(
+            f"/cart/lineitems/{line_item_id}",
+            json=self._serialize(line_item),
+        )
+        return LineItem(**resp.json())
+
+    async def delete_line_item(
+        self,
+        line_item_id: str,
+    ) -> None:
+        """Delete a cart line item
+
+        Args:
+            line_item_id: ID of the line item.
+        """
+        await self._http.delete(f"/cart/lineitems/{line_item_id}")
+
+    async def patch_line_item(
+        self,
+        line_item_id: str,
+        partial: dict[str, Any],
+    ) -> LineItem:
+        """Partially update a cart line item
+
+        Args:
+            line_item_id: ID of the line item.
+            partial: A dict of fields to update.
+
+        Returns:
+            The LineItem object.
+        """
+        resp = await self._http.patch(f"/cart/lineitems/{line_item_id}", json=partial)
+        return LineItem(**resp.json())
+
+    async def list_payments(
+        self,
+        *,
+        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[Payment]:
+        """List cart payments
+
+        Args:
+            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 Payment 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("/cart/payments", **params)
+        return self._parse_list(resp.json(), Payment)
+
+    async def create_payment(
+        self,
+        payment: Union[Payment, dict[str, Any]],
+    ) -> Payment:
+        """Create a cart payment
+
+        Args:
+            payment: A ``Payment`` model or dict.
+
+        Returns:
+            The Payment object.
+        """
+        resp = await self._http.post("/cart/payments", json=self._serialize(payment))
+        return Payment(**resp.json())
+
+    async def get_payment(
+        self,
+        payment_id: str,
+    ) -> Payment:
+        """Retrieve a cart payment
+
+        Args:
+            payment_id: ID of the payment.
+
+        Returns:
+            The Payment object.
+        """
+        resp = await self._http.get(f"/cart/payments/{payment_id}")
+        return Payment(**resp.json())
+
+    async def delete_payment(
+        self,
+        payment_id: str,
+    ) -> None:
+        """Delete a cart payment
+
+        Args:
+            payment_id: ID of the payment.
+        """
+        await self._http.delete(f"/cart/payments/{payment_id}")
+
+    async def patch_payment(
+        self,
+        payment_id: str,
+        partial: dict[str, Any],
+    ) -> Payment:
+        """Partially update a cart payment
+
+        Args:
+            payment_id: ID of the payment.
+            partial: A dict of fields to update.
+
+        Returns:
+            The Payment object.
+        """
+        resp = await self._http.patch(f"/cart/payments/{payment_id}", json=partial)
+        return Payment(**resp.json())
+
+    async def create_payment_transaction(
+        self,
+        payment_id: str,
+        payment_transaction: Union[PaymentTransaction, dict[str, Any]],
+    ) -> Payment:
+        """Create a cart payment transaction
+
+        Args:
+            payment_id: ID of the payment.
+            payment_transaction: A ``PaymentTransaction`` model or dict. Required fields: Type, DateExecuted.
+
+        Returns:
+            The Payment object.
+        """
+        resp = await self._http.post(
+            f"/cart/payments/{payment_id}/transactions", json=self._serialize(payment_transaction)
+        )
+        return Payment(**resp.json())
+
+    async def delete_payment_transaction(
+        self,
+        payment_id: str,
+        transaction_id: str,
+    ) -> None:
+        """Delete a cart payment transaction
+
+        Args:
+            payment_id: ID of the payment.
+            transaction_id: ID of the transaction.
+        """
+        await self._http.delete(f"/cart/payments/{payment_id}/transactions/{transaction_id}")
+
+    async def list_promotions(
+        self,
+        *,
+        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 cart promotions
+
+        Args:
+            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("/cart/promotions", **params)
+        return self._parse_list(resp.json(), OrderPromotion)
+
+    async def add_promotion(
+        self,
+        promo_code: str,
+    ) -> OrderPromotion:
+        """Add a promotion
+
+        Args:
+            promo_code: Promo code of the order promotion.
+
+        Returns:
+            The OrderPromotion object.
+        """
+        resp = await self._http.post(f"/cart/promotions/{promo_code}")
+        return OrderPromotion(**resp.json())
+
+    async def delete_promotion(
+        self,
+        promo_code: str,
+    ) -> None:
+        """Delete a cart promotion
+
+        Args:
+            promo_code: Promo code of the cart.
+        """
+        await self._http.delete(f"/cart/promotions/{promo_code}")
+
+    async def refresh_promotions(
+        self,
+    ) -> RefreshPromosResponse:
+        """Refresh promotions on the cart
+
+        Returns:
+            The RefreshPromosResponse object.
+        """
+        resp = await self._http.post("/cart/refreshpromotions")
+        return RefreshPromosResponse(**resp.json())
+
+    async def select_ship_methods(
+        self,
+        order_ship_method_selection: Union[OrderShipMethodSelection, dict[str, Any]],
+    ) -> OrderWorksheet:
+        """Select a ship method
+
+        Args:
+            order_ship_method_selection: A ``OrderShipMethodSelection`` model or dict.
+
+        Returns:
+            The OrderWorksheet object.
+        """
+        resp = await self._http.post(
+            "/cart/shipmethods", json=self._serialize(order_ship_method_selection)
+        )
+        return OrderWorksheet(**resp.json())
+
+    async def set_shipping_address(
+        self,
+        address: Union[Address, dict[str, Any]],
+    ) -> Order:
+        """Set a shipping address
+
+        Args:
+            address: A ``Address`` model or dict. Required fields: Street1, City, Country.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.put(
+            "/cart/shipto",
+            json=self._serialize(address),
+        )
+        return Order(**resp.json())
+
+    async def patch_shipping_address(
+        self,
+        partial: dict[str, Any],
+    ) -> Order:
+        """Partially update a cart shipping address
+
+        Args:
+            partial: A dict of fields to update.
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.patch("/cart/shipto", json=partial)
+        return Order(**resp.json())
+
+    async def submit(
+        self,
+    ) -> Order:
+        """Submit the cart
+
+        Returns:
+            The Order object.
+        """
+        resp = await self._http.post("/cart/submit")
+        return Order(**resp.json())
+
+    async def validate(
+        self,
+    ) -> None:
+        """Validate the cart in it's current state"""
+        await self._http.post("/cart/validate")
+
+    async def get_order_worksheet(
+        self,
+    ) -> OrderWorksheet:
+        """Retrieve a cart order worksheet
+
+        Returns:
+            The OrderWorksheet object.
+        """
+        resp = await self._http.get("/cart/worksheet")
+        return OrderWorksheet(**resp.json())