Change Orders

Access via client.change_orders.

signtraker.change_orders.ChangeOrdersClient

ChangeOrdersClient(api_key: Optional[str] = None, base_url: Optional[str] = None, *, subdomain: Optional[str] = None, timeout_seconds: Optional[float] = None, max_retries: Optional[int] = None, retry_backoff_seconds: Optional[float] = None)

Bases: BaseClient

Client for the /api/changeorders endpoints.

Source code in signtraker/base_client.py

def __init__(
    self,
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    *,
    subdomain: Optional[str] = None,
    timeout_seconds: Optional[float] = None,
    max_retries: Optional[int] = None,
    retry_backoff_seconds: Optional[float] = None,
) -> None:
    """Initialize the base client.

    The base URL is resolved from the first available of: ``base_url``,
    ``subdomain`` (expanded to ``https://{subdomain}.signtraker.com``), the
    ``SIGNTRAKER_BASE_URL`` env var, or the ``SIGNTRAKER_SUBDOMAIN`` env var.

    Args:
        api_key: API key. Falls back to the ``SIGNTRAKER_API_KEY`` env var.
        base_url: Full API base URL (e.g.
            ``"https://acme.signtraker.com"``). Overrides ``subdomain``.
        subdomain: Tenant subdomain used to build the base URL when
            ``base_url`` is not provided.
        timeout_seconds: Per-request timeout. Falls back to env/default.
        max_retries: Retry attempts for transient failures.
        retry_backoff_seconds: Base backoff between retries (exponential).

    Raises:
        AuthenticationError: If no API key can be resolved.
        SignTrakerConfigError: If no base URL or subdomain can be resolved.
    """
    self.api_key = api_key or _getenv_with_alias(ENV_API_KEY, ENV_API_KEY_ALT)
    if not self.api_key:
        raise AuthenticationError(
            "API key is required. Set SIGNTRAKER_API_KEY or pass api_key."
        )
    self.base_url = self._resolve_base_url(base_url, subdomain)
    self.timeout_seconds = (
        float(timeout_seconds)
        if timeout_seconds is not None
        else _parse_env_float(ENV_TIMEOUT_SECONDS, DEFAULT_TIMEOUT_SECONDS)
    )
    self.max_retries = (
        int(max_retries)
        if max_retries is not None
        else _parse_env_int(ENV_MAX_RETRIES, DEFAULT_MAX_RETRIES)
    )
    self.retry_backoff_seconds = (
        float(retry_backoff_seconds)
        if retry_backoff_seconds is not None
        else _parse_env_float(
            ENV_RETRY_BACKOFF_SECONDS, DEFAULT_RETRY_BACKOFF_SECONDS
        )
    )
    self.session = requests.Session()
    self.session.headers.update(
        {
            "Authorization": f"ST-API {self.api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        }
    )

list_change_orders

list_change_orders(*, filter: Optional[str] = None, top: Optional[int] = None, skip: Optional[int] = None, orderby: Optional[ODataValue] = None, select: Optional[ODataValue] = None) -> List[Dict[str, Any]]

List change orders.

Parameters:

Name	Type	Description	Default
filter	Optional[str]	OData $filter expression.	None
top	Optional[int]	OData $top (maximum number of records to return).	None
skip	Optional[int]	OData $skip (number of records to skip).	None
orderby	Optional[ODataValue]	OData $orderby value or sequence of fields.	None
select	Optional[ODataValue]	OData $select value or sequence of fields.	None

Returns:

Type	Description
List[Dict[str, Any]]	The list of change order records.

Raises:

Type	Description
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/change_orders.py

def list_change_orders(
    self,
    *,
    filter: Optional[str] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    orderby: Optional[ODataValue] = None,
    select: Optional[ODataValue] = None,
) -> List[Dict[str, Any]]:
    """List change orders.

    Args:
        filter: OData ``$filter`` expression.
        top: OData ``$top`` (maximum number of records to return).
        skip: OData ``$skip`` (number of records to skip).
        orderby: OData ``$orderby`` value or sequence of fields.
        select: OData ``$select`` value or sequence of fields.

    Returns:
        The list of change order records.

    Raises:
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    params = build_odata_params(
        filter=filter, top=top, skip=skip, orderby=orderby, select=select
    )
    return cast(List[Dict[str, Any]], self.get("api/changeorders", params))

get_change_order

get_change_order(change_order_id: int) -> Dict[str, Any]

Get a single change order by ID.

Parameters:

Name	Type	Description	Default
change_order_id	int	Unique identifier of the change order.	required

Returns:

Type	Description
Dict[str, Any]	The change order record.

Raises:

Type	Description
NotFoundError	If the change order does not exist.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/change_orders.py

def get_change_order(self, change_order_id: int) -> Dict[str, Any]:
    """Get a single change order by ID.

    Args:
        change_order_id: Unique identifier of the change order.

    Returns:
        The change order record.

    Raises:
        NotFoundError: If the change order does not exist.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(Dict[str, Any], self.get(f"api/changeorders/{change_order_id}"))

create_change_order

create_change_order(change_order: Dict[str, Any]) -> Dict[str, Any]

Create a change order.

Note

This functionality applies to National Accounts only; individual Licensee portals do not have Order Presets available.

Parameters:

Name	Type	Description	Default
change_order	Dict[str, Any]	The payload, including InstallId, PresetId, and OverridePriceLimit.	required

Returns:

Type	Description
Dict[str, Any]	The created change order record.

Raises:

Type	Description
ValidationError	If the payload is invalid.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/change_orders.py

def create_change_order(self, change_order: Dict[str, Any]) -> Dict[str, Any]:
    """Create a change order.

    Note:
        This functionality applies to National Accounts only; individual
        Licensee portals do not have Order Presets available.

    Args:
        change_order: The payload, including ``InstallId``, ``PresetId``,
            and ``OverridePriceLimit``.

    Returns:
        The created change order record.

    Raises:
        ValidationError: If the payload is invalid.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(
        Dict[str, Any],
        self.post("api/changeorders", json_data=change_order),
    )