Helper Methods API Reference¶

Products Helper¶

Products ¶

Products(client: StockTrimClient)

Bases: Base

Product catalog management.

Provides operations for managing products in StockTrim.

Source code in stocktrim_public_api_client/helpers/base.py

def __init__(self, client: StockTrimClient) -> None:
    """Initialize with a client instance.

    Args:
        client: The StockTrimClient instance to use for API calls.
    """
    self._client = client

create `async` ¶

create(product: ProductsRequestDto) -> ProductsResponseDto

Create a new product.

Parameters:

Name	Type	Description	Default
`product`	`ProductsRequestDto`	Product data to create.	required

Returns:

Type	Description
`ProductsResponseDto`	Created ProductsResponseDto object.

Example

from stocktrim_public_api_client.generated.models import ( ... ProductsRequestDto, ... ) product = await client.products.create( ... ProductsRequestDto(code="WIDGET-001", description="Widget") ... )

Source code in stocktrim_public_api_client/helpers/products.py

async def create(self, product: ProductsRequestDto) -> ProductsResponseDto:
    """Create a new product.

    Args:
        product: Product data to create.

    Returns:
        Created ProductsResponseDto object.

    Example:
        >>> from stocktrim_public_api_client.generated.models import (
        ...     ProductsRequestDto,
        ... )
        >>> product = await client.products.create(
        ...     ProductsRequestDto(code="WIDGET-001", description="Widget")
        ... )
    """
    response = await post_api_products.asyncio_detailed(
        client=self._client,
        body=product,
    )
    return cast(ProductsResponseDto, unwrap(response))

delete `async` ¶

delete(product_id: str | Unset = UNSET) -> None

Delete product(s).

Parameters:

Name	Type	Description	Default
`product_id`	`str \| Unset`	Optional product ID to delete. If not provided, may delete all products (use with caution).	`UNSET`

Example

await client.products.delete(product_id="123")

Source code in stocktrim_public_api_client/helpers/products.py

async def delete(self, product_id: str | Unset = UNSET) -> None:
    """Delete product(s).

    Args:
        product_id: Optional product ID to delete. If not provided, may delete
            all products (use with caution).

    Example:
        >>> await client.products.delete(product_id="123")
    """
    await delete_api_products.asyncio_detailed(
        client=self._client,
        product_id=product_id,
    )

exists `async` ¶

exists(code: str) -> bool

Check if a product with given code exists.

Parameters:

Name	Type	Description	Default
`code`	`str`	The product code to check.	required

Returns:

Type	Description
`bool`	True if product exists, False otherwise.

Example

if await client.products.exists("WIDGET-001"): ... print("Product already exists")

Source code in stocktrim_public_api_client/helpers/products.py

async def exists(self, code: str) -> bool:
    """Check if a product with given code exists.

    Args:
        code: The product code to check.

    Returns:
        True if product exists, False otherwise.

    Example:
        >>> if await client.products.exists("WIDGET-001"):
        ...     print("Product already exists")
    """
    product = await self.find_by_code(code)
    return product is not None

find_by_code `async` ¶

find_by_code(code: str) -> ProductsResponseDto | None

Find a single product by exact code match.

This is a convenience method that wraps get_all() and returns the first matching product or None if not found.

Parameters:

Name	Type	Description	Default
`code`	`str`	The exact product code to search for.	required

Returns:

Type	Description
`ProductsResponseDto \| None`	ProductsResponseDto if found, None otherwise.

Example

product = await client.products.find_by_code("WIDGET-001") if product: ... print(f"Found: {product.description}")

Source code in stocktrim_public_api_client/helpers/products.py

async def find_by_code(self, code: str) -> ProductsResponseDto | None:
    """Find a single product by exact code match.

    This is a convenience method that wraps get_all() and returns the first
    matching product or None if not found.

    Args:
        code: The exact product code to search for.

    Returns:
        ProductsResponseDto if found, None otherwise.

    Example:
        >>> product = await client.products.find_by_code("WIDGET-001")
        >>> if product:
        ...     print(f"Found: {product.description}")
    """
    products = await self.get_all(code=code)
    return products[0] if products else None

find_by_exact_code `async` ¶

find_by_exact_code(code: str) -> list[ProductsResponseDto]

Find products by exact code match, returning a list.

This method provides the same functionality as find_by_code() but returns a list for consistency with search patterns. Since the API only supports exact matching, this will return 0 or 1 products.

Parameters:

Name	Type	Description	Default
`code`	`str`	The exact product code to search for.	required

Returns:

Type	Description
`list[ProductsResponseDto]`	List containing the matching product (0 or 1 item).

Example

products = await client.products.find_by_exact_code("WIDGET-001") if products: ... print(f"Found: {products[0].description}")

Source code in stocktrim_public_api_client/helpers/products.py

async def find_by_exact_code(self, code: str) -> list[ProductsResponseDto]:
    """Find products by exact code match, returning a list.

    This method provides the same functionality as find_by_code() but returns
    a list for consistency with search patterns. Since the API only supports
    exact matching, this will return 0 or 1 products.

    Args:
        code: The exact product code to search for.

    Returns:
        List containing the matching product (0 or 1 item).

    Example:
        >>> products = await client.products.find_by_exact_code("WIDGET-001")
        >>> if products:
        ...     print(f"Found: {products[0].description}")
    """
    return await self.get_all(code=code)

get_all `async` ¶

get_all(
    code: str | Unset = UNSET, page_no: str | Unset = UNSET
) -> list[ProductsResponseDto]

Get all products, optionally filtered by exact code match or page.

Parameters:

Name	Type	Description	Default
`code`	`str \| Unset`	Optional product code for exact match filtering. The StockTrim API only supports exact code matches, not prefix or partial matching.	`UNSET`
`page_no`	`str \| Unset`	Optional page number for pagination.	`UNSET`

Returns:

Type	Description
`list[ProductsResponseDto]`	List of ProductsResponseDto objects. Returns empty list if no products
`list[ProductsResponseDto]`	match the filter.

Example

products = await client.products.get_all() products = await client.products.get_all( ... code="WIDGET-001" ... ) # Exact match only

Source code in stocktrim_public_api_client/helpers/products.py

async def get_all(
    self,
    code: str | Unset = UNSET,
    page_no: str | Unset = UNSET,
) -> list[ProductsResponseDto]:
    """Get all products, optionally filtered by exact code match or page.

    Args:
        code: Optional product code for exact match filtering. The StockTrim API
            only supports exact code matches, not prefix or partial matching.
        page_no: Optional page number for pagination.

    Returns:
        List of ProductsResponseDto objects. Returns empty list if no products
        match the filter.

    Example:
        >>> products = await client.products.get_all()
        >>> products = await client.products.get_all(
        ...     code="WIDGET-001"
        ... )  # Exact match only
    """
    response = await get_api_products.asyncio_detailed(
        client=self._client,
        code=code,
        page_no=page_no,
    )
    # StockTrim API returns 404 when no products match the exact code filter.
    # This is non-standard REST behavior (should be 200 with empty array), but we handle it
    # by treating 404 as "no results" and returning an empty list for a consistent interface.
    # Note: The API only supports exact code matching, not prefix/partial matching.
    if response.status_code == 404:
        return []
    result = unwrap(response)
    # unwrap() returns the actual type or raises an exception on error
    return result if isinstance(result, list) else []  # type: ignore[return-value]

get_all_paginated `async` ¶

get_all_paginated() -> list[ProductsResponseDto]

Get ALL products by paginating through all pages.

This method automatically handles pagination to fetch the complete product catalog from StockTrim.

Returns:

Type	Description
`list[ProductsResponseDto]`	List of all ProductsResponseDto objects across all pages.

Example

all_products = await client.products.get_all_paginated() print(f"Total products: {len(all_products)}")

Source code in stocktrim_public_api_client/helpers/products.py

async def get_all_paginated(self) -> list[ProductsResponseDto]:
    """Get ALL products by paginating through all pages.

    This method automatically handles pagination to fetch the complete
    product catalog from StockTrim.

    Returns:
        List of all ProductsResponseDto objects across all pages.

    Example:
        >>> all_products = await client.products.get_all_paginated()
        >>> print(f"Total products: {len(all_products)}")
    """
    all_products = []
    page_no = "0"

    while True:
        products_page = await self.get_all(page_no=page_no)
        if not products_page:
            break

        all_products.extend(products_page)

        # StockTrim API uses string page numbers and doesn't document pagination
        # We'll assume if we get fewer results, we're done
        # Typical page size appears to be 50
        if len(products_page) < 50:
            break

        page_no = str(int(page_no) + 1)

    return all_products

Customers Helper¶

Customers ¶

Customers(client: StockTrimClient)

Bases: Base

Customer management.

Provides operations for managing customers in StockTrim.

Source code in stocktrim_public_api_client/helpers/base.py

def __init__(self, client: StockTrimClient) -> None:
    """Initialize with a client instance.

    Args:
        client: The StockTrimClient instance to use for API calls.
    """
    self._client = client

exists `async` ¶

exists(code: str) -> bool

Check if a customer with given code exists.

Parameters:

Name	Type	Description	Default
`code`	`str`	The customer code to check.	required

Returns:

Type	Description
`bool`	True if customer exists, False otherwise.

Example

if await client.customers.exists("CUST-001"): ... print("Customer exists")

Source code in stocktrim_public_api_client/helpers/customers.py

async def exists(self, code: str) -> bool:
    """Check if a customer with given code exists.

    Args:
        code: The customer code to check.

    Returns:
        True if customer exists, False otherwise.

    Example:
        >>> if await client.customers.exists("CUST-001"):
        ...     print("Customer exists")
    """
    try:
        await self.get(code)
        return True
    except Exception:
        return False

find_or_create `async` ¶

find_or_create(code: str, **defaults) -> CustomerDto

Get customer by code, or create if doesn't exist.

Parameters:

Name	Type	Description	Default
`code`	`str`	The customer code.	required
`**defaults`		Default values to use when creating the customer.	`{}`

Returns:

Type	Description
`CustomerDto`	CustomerDto object (existing or newly created).

Example

customer = await client.customers.find_or_create( ... "CUST-001", name="New Customer", email="customer@example.com" ... )

Source code in stocktrim_public_api_client/helpers/customers.py

async def find_or_create(self, code: str, **defaults) -> CustomerDto:
    """Get customer by code, or create if doesn't exist.

    Args:
        code: The customer code.
        **defaults: Default values to use when creating the customer.

    Returns:
        CustomerDto object (existing or newly created).

    Example:
        >>> customer = await client.customers.find_or_create(
        ...     "CUST-001", name="New Customer", email="customer@example.com"
        ... )
    """
    try:
        return await self.get(code)
    except Exception:
        # Customer doesn't exist, create it
        new_customer = CustomerDto(code=code, **defaults)
        await self.update(new_customer)
        return await self.get(code)

get `async` ¶

get(code: str) -> CustomerDto

Get a specific customer by code.

Parameters:

Name	Type	Description	Default
`code`	`str`	The customer code.	required

Returns:

Type	Description
`CustomerDto`	CustomerDto object.

Example

customer = await client.customers.get("CUST-001")

Source code in stocktrim_public_api_client/helpers/customers.py

async def get(self, code: str) -> CustomerDto:
    """Get a specific customer by code.

    Args:
        code: The customer code.

    Returns:
        CustomerDto object.

    Example:
        >>> customer = await client.customers.get("CUST-001")
    """
    response = await get_api_customers_code.asyncio_detailed(
        client=self._client,
        code=code,
    )
    return cast(CustomerDto, unwrap(response))

get_all `async` ¶

get_all() -> list[CustomerDto]

Get all customers.

Returns:

Type	Description
`list[CustomerDto]`	List of CustomerDto objects.

Example

customers = await client.customers.get_all()

Source code in stocktrim_public_api_client/helpers/customers.py

async def get_all(self) -> list[CustomerDto]:
    """Get all customers.

    Returns:
        List of CustomerDto objects.

    Example:
        >>> customers = await client.customers.get_all()
    """
    response = await get_api_customers.asyncio_detailed(client=self._client)
    result = unwrap(response)
    # unwrap() returns the actual type or raises an exception on error
    # Type checker sees the union but at runtime we get the expected type
    return result if isinstance(result, list) else []  # type: ignore[return-value]

update `async` ¶

update(customer: CustomerDto) -> list[CustomerDto]

Update a customer (create or update based on code).

Parameters:

Name	Type	Description	Default
`customer`	`CustomerDto`	Customer data to update.	required

Returns:

Type	Description
`list[CustomerDto]`	List of updated CustomerDto objects.

Example

from stocktrim_public_api_client.generated.models import CustomerDto updated = await client.customers.update( ... CustomerDto(code="CUST-001", name="Updated Name") ... )

Source code in stocktrim_public_api_client/helpers/customers.py

async def update(self, customer: CustomerDto) -> list[CustomerDto]:
    """Update a customer (create or update based on code).

    Args:
        customer: Customer data to update.

    Returns:
        List of updated CustomerDto objects.

    Example:
        >>> from stocktrim_public_api_client.generated.models import CustomerDto
        >>> updated = await client.customers.update(
        ...     CustomerDto(code="CUST-001", name="Updated Name")
        ... )
    """
    response = await put_api_customers.asyncio_detailed(
        client=self._client,
        body=customer,
    )
    result = unwrap(response)
    if isinstance(result, list):
        return cast(list[CustomerDto], result)
    return []

Suppliers Helper¶

Suppliers ¶

Suppliers(client: StockTrimClient)

Bases: Base

Supplier management.

Provides operations for managing suppliers in StockTrim.

Source code in stocktrim_public_api_client/helpers/base.py

def __init__(self, client: StockTrimClient) -> None:
    """Initialize with a client instance.

    Args:
        client: The StockTrimClient instance to use for API calls.
    """
    self._client = client

create `async` ¶

create(
    suppliers: list[SupplierRequestDto],
) -> list[SupplierResponseDto]

Create new suppliers.

Parameters:

Name	Type	Description	Default
`suppliers`	`list[SupplierRequestDto]`	List of supplier data to create.	required

Returns:

Type	Description
`list[SupplierResponseDto]`	List of created SupplierResponseDto objects.

Example

from stocktrim_public_api_client.generated.models import ( ... SupplierRequestDto, ... ) suppliers = await client.suppliers.create( ... [ ... SupplierRequestDto(code="SUP-001", name="Supplier One"), ... SupplierRequestDto(code="SUP-002", name="Supplier Two"), ... ] ... )

Source code in stocktrim_public_api_client/helpers/suppliers.py

async def create(
    self, suppliers: list[SupplierRequestDto]
) -> list[SupplierResponseDto]:
    """Create new suppliers.

    Args:
        suppliers: List of supplier data to create.

    Returns:
        List of created SupplierResponseDto objects.

    Example:
        >>> from stocktrim_public_api_client.generated.models import (
        ...     SupplierRequestDto,
        ... )
        >>> suppliers = await client.suppliers.create(
        ...     [
        ...         SupplierRequestDto(code="SUP-001", name="Supplier One"),
        ...         SupplierRequestDto(code="SUP-002", name="Supplier Two"),
        ...     ]
        ... )
    """
    response = await post_api_suppliers.asyncio_detailed(
        client=self._client,
        body=suppliers,
    )
    result = unwrap(response)
    # unwrap() returns the actual type or raises an exception on error
    return result if isinstance(result, list) else []  # type: ignore[return-value]

create_one `async` ¶

create_one(
    supplier: SupplierRequestDto,
) -> SupplierResponseDto | None

Create a single supplier.

This is a convenience wrapper around the batch create() method that accepts a single supplier instead of a list.

Parameters:

Name	Type	Description	Default
`supplier`	`SupplierRequestDto`	Supplier data to create.	required

Returns:

Type	Description
`SupplierResponseDto \| None`	Created SupplierResponseDto object, or None if creation failed.

Example

from stocktrim_public_api_client.generated.models import ( ... SupplierRequestDto, ... ) supplier = await client.suppliers.create_one( ... SupplierRequestDto(code="SUP-001", name="New Supplier") ... )

Source code in stocktrim_public_api_client/helpers/suppliers.py

async def create_one(
    self, supplier: SupplierRequestDto
) -> SupplierResponseDto | None:
    """Create a single supplier.

    This is a convenience wrapper around the batch create() method
    that accepts a single supplier instead of a list.

    Args:
        supplier: Supplier data to create.

    Returns:
        Created SupplierResponseDto object, or None if creation failed.

    Example:
        >>> from stocktrim_public_api_client.generated.models import (
        ...     SupplierRequestDto,
        ... )
        >>> supplier = await client.suppliers.create_one(
        ...     SupplierRequestDto(code="SUP-001", name="New Supplier")
        ... )
    """
    results = await self.create([supplier])
    return results[0] if results else None

delete `async` ¶

delete(supplier_code_or_name: str | Unset = UNSET) -> None

Delete supplier(s).

Parameters:

Name	Type	Description	Default
`supplier_code_or_name`	`str \| Unset`	Supplier code or name to delete.	`UNSET`

Example

await client.suppliers.delete(supplier_code_or_name="SUP-001")

Source code in stocktrim_public_api_client/helpers/suppliers.py

async def delete(self, supplier_code_or_name: str | Unset = UNSET) -> None:
    """Delete supplier(s).

    Args:
        supplier_code_or_name: Supplier code or name to delete.

    Example:
        >>> await client.suppliers.delete(supplier_code_or_name="SUP-001")
    """
    await delete_api_suppliers.asyncio_detailed(
        client=self._client,
        supplier_code_or_name=supplier_code_or_name,
    )

exists `async` ¶

exists(code: str) -> bool

Check if a supplier with given code exists.

Parameters:

Name	Type	Description	Default
`code`	`str`	The supplier code to check.	required

Returns:

Type	Description
`bool`	True if supplier exists, False otherwise.

Example

if await client.suppliers.exists("SUP-001"): ... print("Supplier exists")

Source code in stocktrim_public_api_client/helpers/suppliers.py

async def exists(self, code: str) -> bool:
    """Check if a supplier with given code exists.

    Args:
        code: The supplier code to check.

    Returns:
        True if supplier exists, False otherwise.

    Example:
        >>> if await client.suppliers.exists("SUP-001"):
        ...     print("Supplier exists")
    """
    supplier = await self.find_by_code(code)
    return supplier is not None

find_by_code `async` ¶

find_by_code(code: str) -> SupplierResponseDto | None

Find a single supplier by exact code match.

This method handles the API's inconsistent return type (single vs list) and always returns a single object or None.

Parameters:

Name	Type	Description	Default
`code`	`str`	The exact supplier code to search for.	required

Returns:

Type	Description
`SupplierResponseDto \| None`	SupplierResponseDto if found, None otherwise.

Example

supplier = await client.suppliers.find_by_code("SUP-001") if supplier: ... print(f"Found: {supplier.name}")

Source code in stocktrim_public_api_client/helpers/suppliers.py

async def find_by_code(self, code: str) -> SupplierResponseDto | None:
    """Find a single supplier by exact code match.

    This method handles the API's inconsistent return type (single vs list)
    and always returns a single object or None.

    Args:
        code: The exact supplier code to search for.

    Returns:
        SupplierResponseDto if found, None otherwise.

    Example:
        >>> supplier = await client.suppliers.find_by_code("SUP-001")
        >>> if supplier:
        ...     print(f"Found: {supplier.name}")
    """
    result = await self.get_all(code=code)
    # Handle API returning either single object or list
    if isinstance(result, list):
        return result[0] if result else None
    return result

get_all `async` ¶

get_all(
    code: str | Unset = UNSET,
) -> SupplierResponseDto | list[SupplierResponseDto]

Get suppliers, optionally filtered by code.

When code is not provided, uses the bulk endpoint to return all suppliers. When code is provided, uses the single supplier endpoint.

Note: The API has separate endpoints for these operations: - /api/SuppliersBulk returns a list of all suppliers - /api/Suppliers?code=X returns a single supplier

Parameters:

Name	Type	Description	Default
`code`	`str \| Unset`	Optional supplier code filter.	`UNSET`

Returns:

Type	Description
`SupplierResponseDto \| list[SupplierResponseDto]`	List of SupplierResponseDto when code is not provided,
`SupplierResponseDto \| list[SupplierResponseDto]`	or single SupplierResponseDto when code is provided.

Example

suppliers = await client.suppliers.get_all() # Returns list supplier = await client.suppliers.get_all( ... code="SUP-001" ... ) # Returns single object

Source code in stocktrim_public_api_client/helpers/suppliers.py

async def get_all(
    self,
    code: str | Unset = UNSET,
) -> SupplierResponseDto | list[SupplierResponseDto]:
    """Get suppliers, optionally filtered by code.

    When code is not provided, uses the bulk endpoint to return all suppliers.
    When code is provided, uses the single supplier endpoint.

    Note: The API has separate endpoints for these operations:
    - /api/SuppliersBulk returns a list of all suppliers
    - /api/Suppliers?code=X returns a single supplier

    Args:
        code: Optional supplier code filter.

    Returns:
        List of SupplierResponseDto when code is not provided,
        or single SupplierResponseDto when code is provided.

    Example:
        >>> suppliers = await client.suppliers.get_all()  # Returns list
        >>> supplier = await client.suppliers.get_all(
        ...     code="SUP-001"
        ... )  # Returns single object
    """
    if isinstance(code, Unset):
        # Use bulk endpoint to get all suppliers
        response = await get_api_suppliers_bulk.asyncio_detailed(
            client=self._client,
        )
    else:
        # Use single supplier endpoint with code filter
        response = await get_api_suppliers.asyncio_detailed(
            client=self._client,
            code=code,
        )

    return cast(
        SupplierResponseDto | list[SupplierResponseDto],
        unwrap(response),
    )

Sales Orders Helper¶

SalesOrders ¶

SalesOrders(client: StockTrimClient)

Bases: Base

Sales order management.

Provides operations for managing sales orders in StockTrim.

Source code in stocktrim_public_api_client/helpers/base.py

def __init__(self, client: StockTrimClient) -> None:
    """Initialize with a client instance.

    Args:
        client: The StockTrimClient instance to use for API calls.
    """
    self._client = client

create `async` ¶

create(
    order: SalesOrderRequestDto,
) -> SalesOrderResponseDto

Create a new sales order using the idempotent bulk endpoint.

This method uses PUT /SalesOrdersBulk which is idempotent and safer for retries. It performs a create or update based on the external_reference_id field of the line item (SalesOrderRequestDto). The bulk request does not include an external reference ID at the header level; the API uses the value from the line item to determine whether to create or update.

Parameters:

Name	Type	Description	Default
`order`	`SalesOrderRequestDto`	Sales order data to create. Include `external_reference_id` for idempotent behavior.	required

Returns:

Type	Description
`SalesOrderResponseDto`	Created SalesOrderResponseDto object.

Example

from datetime import datetime from stocktrim_public_api_client.generated.models import ( ... SalesOrderRequestDto, ... ) order = await client.sales_orders.create( ... SalesOrderRequestDto( ... product_id="WIDGET-001", ... order_date=datetime.now(), ... quantity=10.0, ... external_reference_id="SO-001", ... ) ... )

Source code in stocktrim_public_api_client/helpers/sales_orders.py

async def create(self, order: SalesOrderRequestDto) -> SalesOrderResponseDto:
    """Create a new sales order using the idempotent bulk endpoint.

    This method uses PUT /SalesOrdersBulk which is idempotent and safer for retries.
    It performs a create or update based on the `external_reference_id` field of
    the line item (`SalesOrderRequestDto`). The bulk request does not include an
    external reference ID at the header level; the API uses the value from the
    line item to determine whether to create or update.

    Args:
        order: Sales order data to create. Include `external_reference_id` for
            idempotent behavior.

    Returns:
        Created SalesOrderResponseDto object.

    Example:
        >>> from datetime import datetime
        >>> from stocktrim_public_api_client.generated.models import (
        ...     SalesOrderRequestDto,
        ... )
        >>> order = await client.sales_orders.create(
        ...     SalesOrderRequestDto(
        ...         product_id="WIDGET-001",
        ...         order_date=datetime.now(),
        ...         quantity=10.0,
        ...         external_reference_id="SO-001",
        ...     )
        ... )
    """
    # Convert single order to bulk request with one line item
    bulk_request = SalesOrderWithLineItemsRequestDto(
        order_date=order.order_date,
        location_code=order.location_code,
        location_name=order.location_name,
        customer_code=order.customer_code,
        customer_name=order.customer_name,
        sale_order_line_items=[order],
    )
    response = await put_api_sales_orders_bulk.asyncio_detailed(
        client=self._client,
        body=bulk_request,
    )
    return cast(SalesOrderResponseDto, unwrap(response))

delete `async` ¶

delete(product_id: str | Unset = UNSET) -> None

Delete sales order(s), optionally filtered by product ID.

Parameters:

Name	Type	Description	Default
`product_id`	`str \| Unset`	Optional product ID to filter deletions.	`UNSET`

Example

await client.sales_orders.delete(product_id="123")

Source code in stocktrim_public_api_client/helpers/sales_orders.py

async def delete(self, product_id: str | Unset = UNSET) -> None:
    """Delete sales order(s), optionally filtered by product ID.

    Args:
        product_id: Optional product ID to filter deletions.

    Example:
        >>> await client.sales_orders.delete(product_id="123")
    """
    await delete_api_sales_orders.asyncio_detailed(
        client=self._client,
        product_id=product_id,
    )

delete_for_product `async` ¶

delete_for_product(product_id: str) -> None

Delete all sales orders for a specific product.

This is a convenience alias for delete() with clearer intent.

Parameters:

Name	Type	Description	Default
`product_id`	`str`	The product ID to delete orders for.	required

Example

await client.sales_orders.delete_for_product("123")

Source code in stocktrim_public_api_client/helpers/sales_orders.py

async def delete_for_product(self, product_id: str) -> None:
    """Delete all sales orders for a specific product.

    This is a convenience alias for delete() with clearer intent.

    Args:
        product_id: The product ID to delete orders for.

    Example:
        >>> await client.sales_orders.delete_for_product("123")
    """
    await self.delete(product_id=product_id)

get_all `async` ¶

get_all(
    product_id: str | Unset = UNSET,
) -> list[SalesOrderResponseDto]

Get all sales orders, optionally filtered by product ID.

Parameters:

Name	Type	Description	Default
`product_id`	`str \| Unset`	Optional product ID to filter by.	`UNSET`

Returns:

Type	Description
`list[SalesOrderResponseDto]`	List of SalesOrderResponseDto objects.

Example

orders = await client.sales_orders.get_all() orders = await client.sales_orders.get_all(product_id="123")

Source code in stocktrim_public_api_client/helpers/sales_orders.py

async def get_all(
    self,
    product_id: str | Unset = UNSET,
) -> list[SalesOrderResponseDto]:
    """Get all sales orders, optionally filtered by product ID.

    Args:
        product_id: Optional product ID to filter by.

    Returns:
        List of SalesOrderResponseDto objects.

    Example:
        >>> orders = await client.sales_orders.get_all()
        >>> orders = await client.sales_orders.get_all(product_id="123")
    """
    response = await get_api_sales_orders.asyncio_detailed(
        client=self._client,
        product_id=product_id,
    )
    result = unwrap(response)
    # unwrap() returns the actual type or raises an exception on error
    return result if isinstance(result, list) else []  # type: ignore[return-value]

get_for_product `async` ¶

get_for_product(
    product_id: str,
) -> list[SalesOrderResponseDto]

Get all sales orders for a specific product.

This is a convenience alias for get_all() with clearer intent.

Parameters:

Name	Type	Description	Default
`product_id`	`str`	The product ID to get orders for.	required

Returns:

Type	Description
`list[SalesOrderResponseDto]`	List of SalesOrderResponseDto objects for the product.

Example

orders = await client.sales_orders.get_for_product("123")

Source code in stocktrim_public_api_client/helpers/sales_orders.py

async def get_for_product(self, product_id: str) -> list[SalesOrderResponseDto]:
    """Get all sales orders for a specific product.

    This is a convenience alias for get_all() with clearer intent.

    Args:
        product_id: The product ID to get orders for.

    Returns:
        List of SalesOrderResponseDto objects for the product.

    Example:
        >>> orders = await client.sales_orders.get_for_product("123")
    """
    return await self.get_all(product_id=product_id)

Purchase Orders Helper¶

PurchaseOrders ¶

PurchaseOrders(client: StockTrimClient)

Bases: Base

Purchase order management.

Provides operations for managing purchase orders in StockTrim.

Source code in stocktrim_public_api_client/helpers/base.py

def __init__(self, client: StockTrimClient) -> None:
    """Initialize with a client instance.

    Args:
        client: The StockTrimClient instance to use for API calls.
    """
    self._client = client

create `async` ¶

create(
    order: PurchaseOrderRequestDto,
) -> PurchaseOrderResponseDto

Create a new purchase order.

Parameters:

Name	Type	Description	Default
`order`	`PurchaseOrderRequestDto`	Purchase order data to create.	required

Returns:

Type	Description
`PurchaseOrderResponseDto`	Created PurchaseOrderResponseDto object.

Example

from stocktrim_public_api_client.generated.models import ( ... PurchaseOrderRequestDto, ... ) order = await client.purchase_orders.create( ... PurchaseOrderRequestDto(reference_number="PO-001", ...) ... )

Source code in stocktrim_public_api_client/helpers/purchase_orders.py

async def create(self, order: PurchaseOrderRequestDto) -> PurchaseOrderResponseDto:
    """Create a new purchase order.

    Args:
        order: Purchase order data to create.

    Returns:
        Created PurchaseOrderResponseDto object.

    Example:
        >>> from stocktrim_public_api_client.generated.models import (
        ...     PurchaseOrderRequestDto,
        ... )
        >>> order = await client.purchase_orders.create(
        ...     PurchaseOrderRequestDto(reference_number="PO-001", ...)
        ... )
    """
    response = await post_api_purchase_orders.asyncio_detailed(
        client=self._client,
        body=order,
    )
    return cast(PurchaseOrderResponseDto, unwrap(response))

delete `async` ¶

delete(
    reference_number: str | Unset = UNSET,
) -> PurchaseOrderResponseDto | None

Delete purchase order(s).

Note: The API returns the deleted PurchaseOrderResponseDto object.

Parameters:

Name	Type	Description	Default
`reference_number`	`str \| Unset`	Reference number to delete.	`UNSET`

Returns:

Type	Description
`PurchaseOrderResponseDto \| None`	Deleted PurchaseOrderResponseDto object or None.

Example

deleted = await client.purchase_orders.delete(reference_number="PO-001")

Source code in stocktrim_public_api_client/helpers/purchase_orders.py

async def delete(
    self, reference_number: str | Unset = UNSET
) -> PurchaseOrderResponseDto | None:
    """Delete purchase order(s).

    Note: The API returns the deleted PurchaseOrderResponseDto object.

    Args:
        reference_number: Reference number to delete.

    Returns:
        Deleted PurchaseOrderResponseDto object or None.

    Example:
        >>> deleted = await client.purchase_orders.delete(reference_number="PO-001")
    """
    response = await delete_api_purchase_orders.asyncio_detailed(
        client=self._client,
        reference_number=reference_number,
    )
    result = unwrap(response)
    return cast(PurchaseOrderResponseDto, result) if result else None

exists `async` ¶

exists(reference_number: str) -> bool

Check if a purchase order with given reference number exists.

Parameters:

Name	Type	Description	Default
`reference_number`	`str`	The reference number to check.	required

Returns:

Type	Description
`bool`	True if order exists, False otherwise.

Example

if await client.purchase_orders.exists("PO-001"): ... print("Purchase order exists")

Source code in stocktrim_public_api_client/helpers/purchase_orders.py

async def exists(self, reference_number: str) -> bool:
    """Check if a purchase order with given reference number exists.

    Args:
        reference_number: The reference number to check.

    Returns:
        True if order exists, False otherwise.

    Example:
        >>> if await client.purchase_orders.exists("PO-001"):
        ...     print("Purchase order exists")
    """
    order = await self.find_by_reference(reference_number)
    return order is not None

find_by_reference `async` ¶

find_by_reference(
    reference_number: str,
) -> PurchaseOrderResponseDto | None

Find a single purchase order by reference number.

This method handles the API's inconsistent return type (single vs list) and always returns a single object or None.

Parameters:

Name	Type	Description	Default
`reference_number`	`str`	The purchase order reference number.	required

Returns:

Type	Description
`PurchaseOrderResponseDto \| None`	PurchaseOrderResponseDto if found, None otherwise.

Example

order = await client.purchase_orders.find_by_reference("PO-001") if order: ... print(f"Found order: {order.reference_number}")

Source code in stocktrim_public_api_client/helpers/purchase_orders.py

async def find_by_reference(
    self, reference_number: str
) -> PurchaseOrderResponseDto | None:
    """Find a single purchase order by reference number.

    This method handles the API's inconsistent return type (single vs list)
    and always returns a single object or None.

    Args:
        reference_number: The purchase order reference number.

    Returns:
        PurchaseOrderResponseDto if found, None otherwise.

    Example:
        >>> order = await client.purchase_orders.find_by_reference("PO-001")
        >>> if order:
        ...     print(f"Found order: {order.reference_number}")
    """
    result = await self.get_all(reference_number=reference_number)
    # Handle API returning either single object or list
    if isinstance(result, list):
        return result[0] if result else None
    return result

get_all `async` ¶

get_all(
    reference_number: str | Unset = UNSET,
) -> (
    PurchaseOrderResponseDto
    | list[PurchaseOrderResponseDto]
)

Get purchase orders, optionally filtered by reference number.

Note: The API returns a single object when filtered by reference number, but this is inconsistent with other endpoints. We preserve the API's behavior here.

Parameters:

Name	Type	Description	Default
`reference_number`	`str \| Unset`	Optional reference number filter.	`UNSET`

Returns:

Type	Description
`PurchaseOrderResponseDto \| list[PurchaseOrderResponseDto]`	PurchaseOrderResponseDto or list of PurchaseOrderResponseDto objects.

Example

orders = await client.purchase_orders.get_all() order = await client.purchase_orders.get_all(reference_number="PO-001")

Source code in stocktrim_public_api_client/helpers/purchase_orders.py

async def get_all(
    self,
    reference_number: str | Unset = UNSET,
) -> PurchaseOrderResponseDto | list[PurchaseOrderResponseDto]:
    """Get purchase orders, optionally filtered by reference number.

    Note: The API returns a single object when filtered by reference number,
    but this is inconsistent with other endpoints. We preserve the API's
    behavior here.

    Args:
        reference_number: Optional reference number filter.

    Returns:
        PurchaseOrderResponseDto or list of PurchaseOrderResponseDto objects.

    Example:
        >>> orders = await client.purchase_orders.get_all()
        >>> order = await client.purchase_orders.get_all(reference_number="PO-001")
    """
    response = await get_api_purchase_orders.asyncio_detailed(
        client=self._client,
        reference_number=reference_number,
    )
    return cast(
        PurchaseOrderResponseDto | list[PurchaseOrderResponseDto],
        unwrap(response),
    )

Locations Helper¶

Locations ¶

Locations(client: StockTrimClient)

Bases: Base

Location management.

Provides operations for managing locations in StockTrim.

Source code in stocktrim_public_api_client/helpers/base.py

def __init__(self, client: StockTrimClient) -> None:
    """Initialize with a client instance.

    Args:
        client: The StockTrimClient instance to use for API calls.
    """
    self._client = client

create `async` ¶

create(location: LocationRequestDto) -> LocationResponseDto

Create a new location.

Note: The API returns a single object but it's unclear if it accepts a single object or array. We preserve the API's behavior here.

Parameters:

Name	Type	Description	Default
`location`	`LocationRequestDto`	Location data to create.	required

Returns:

Type	Description
`LocationResponseDto`	Created LocationResponseDto object.

Example

from stocktrim_public_api_client.generated.models import ( ... LocationRequestDto, ... ) location = await client.locations.create( ... LocationRequestDto(code="LOC-001", name="Warehouse A") ... )

Source code in stocktrim_public_api_client/helpers/locations.py

async def create(self, location: LocationRequestDto) -> LocationResponseDto:
    """Create a new location.

    Note: The API returns a single object but it's unclear if it accepts
    a single object or array. We preserve the API's behavior here.

    Args:
        location: Location data to create.

    Returns:
        Created LocationResponseDto object.

    Example:
        >>> from stocktrim_public_api_client.generated.models import (
        ...     LocationRequestDto,
        ... )
        >>> location = await client.locations.create(
        ...     LocationRequestDto(code="LOC-001", name="Warehouse A")
        ... )
    """
    response = await post_api_locations.asyncio_detailed(
        client=self._client,
        body=location,
    )
    return cast(LocationResponseDto, unwrap(response))

get_all `async` ¶

get_all(
    code: str | Unset = UNSET,
) -> LocationResponseDto | list[LocationResponseDto]

Get locations, optionally filtered by code.

Note: The API returns a single object when filtered by code, but this is inconsistent with other endpoints. We preserve the API's behavior here.

Parameters:

Name	Type	Description	Default
`code`	`str \| Unset`	Optional location code filter.	`UNSET`

Returns:

Type	Description
`LocationResponseDto \| list[LocationResponseDto]`	LocationResponseDto or list of LocationResponseDto objects.

Example

locations = await client.locations.get_all() location = await client.locations.get_all(code="LOC-001")

Source code in stocktrim_public_api_client/helpers/locations.py

async def get_all(
    self,
    code: str | Unset = UNSET,
) -> LocationResponseDto | list[LocationResponseDto]:
    """Get locations, optionally filtered by code.

    Note: The API returns a single object when filtered by code,
    but this is inconsistent with other endpoints. We preserve
    the API's behavior here.

    Args:
        code: Optional location code filter.

    Returns:
        LocationResponseDto or list of LocationResponseDto objects.

    Example:
        >>> locations = await client.locations.get_all()
        >>> location = await client.locations.get_all(code="LOC-001")
    """
    response = await get_api_locations.asyncio_detailed(
        client=self._client,
        code=code,
    )
    return cast(
        LocationResponseDto | list[LocationResponseDto],
        unwrap(response),
    )

Inventory Helper¶

Inventory ¶

Inventory(client: StockTrimClient)

Bases: Base

Inventory management.

Provides operations for managing inventory levels in StockTrim.

Source code in stocktrim_public_api_client/helpers/base.py

def __init__(self, client: StockTrimClient) -> None:
    """Initialize with a client instance.

    Args:
        client: The StockTrimClient instance to use for API calls.
    """
    self._client = client

set `async` ¶

set(
    inventory: SetInventoryRequest,
) -> PurchaseOrderResponseDto

Set stock on hand and stock on order for products.

Note: The API returns PurchaseOrderResponseDto which seems incorrect for an inventory operation, but we preserve the API's behavior here.

Parameters:

Name	Type	Description	Default
`inventory`	`SetInventoryRequest`	Inventory data to set.	required

Returns:

Type	Description
`PurchaseOrderResponseDto`	PurchaseOrderResponseDto object (API inconsistency).

Example

from stocktrim_public_api_client.generated.models import ( ... SetInventoryRequest, ... ) result = await client.inventory.set( ... SetInventoryRequest(product_code="WIDGET-001", quantity=100) ... )

Source code in stocktrim_public_api_client/helpers/inventory.py

async def set(self, inventory: SetInventoryRequest) -> PurchaseOrderResponseDto:
    """Set stock on hand and stock on order for products.

    Note: The API returns PurchaseOrderResponseDto which seems incorrect
    for an inventory operation, but we preserve the API's behavior here.

    Args:
        inventory: Inventory data to set.

    Returns:
        PurchaseOrderResponseDto object (API inconsistency).

    Example:
        >>> from stocktrim_public_api_client.generated.models import (
        ...     SetInventoryRequest,
        ... )
        >>> result = await client.inventory.set(
        ...     SetInventoryRequest(product_code="WIDGET-001", quantity=100)
        ... )
    """
    response = await post_api_inventory.asyncio_detailed(
        client=self._client,
        body=inventory,
    )
    return cast(PurchaseOrderResponseDto, unwrap(response))

set_for_product `async` ¶

set_for_product(
    product_id: str,
    stock_on_hand: float | Unset = UNSET,
    stock_on_order: float | Unset = UNSET,
    location_code: str | None | Unset = UNSET,
    location_name: str | None | Unset = UNSET,
) -> PurchaseOrderResponseDto

Set inventory levels for a single product.

This is a convenience method that simplifies setting inventory for a single product by automatically creating the required request structure.

Parameters:

Name	Type	Description	Default
`product_id`	`str`	The product ID to set inventory for.	required
`stock_on_hand`	`float \| Unset`	Stock on hand quantity.	`UNSET`
`stock_on_order`	`float \| Unset`	Stock on order quantity.	`UNSET`
`location_code`	`str \| None \| Unset`	Optional location code.	`UNSET`
`location_name`	`str \| None \| Unset`	Optional location name.	`UNSET`

Returns:

Type	Description
`PurchaseOrderResponseDto`	PurchaseOrderResponseDto object (API inconsistency).

Example

result = await client.inventory.set_for_product( ... product_id="123", ... stock_on_hand=50.0, ... stock_on_order=100.0, ... location_code="WAREHOUSE-A", ... )

Source code in stocktrim_public_api_client/helpers/inventory.py

async def set_for_product(
    self,
    product_id: str,
    stock_on_hand: float | Unset = UNSET,
    stock_on_order: float | Unset = UNSET,
    location_code: str | None | Unset = UNSET,
    location_name: str | None | Unset = UNSET,
) -> PurchaseOrderResponseDto:
    """Set inventory levels for a single product.

    This is a convenience method that simplifies setting inventory for
    a single product by automatically creating the required request structure.

    Args:
        product_id: The product ID to set inventory for.
        stock_on_hand: Stock on hand quantity.
        stock_on_order: Stock on order quantity.
        location_code: Optional location code.
        location_name: Optional location name.

    Returns:
        PurchaseOrderResponseDto object (API inconsistency).

    Example:
        >>> result = await client.inventory.set_for_product(
        ...     product_id="123",
        ...     stock_on_hand=50.0,
        ...     stock_on_order=100.0,
        ...     location_code="WAREHOUSE-A",
        ... )
    """
    inventory_item = InventoryItem(
        product_id=product_id,
        stock_on_hand=stock_on_hand,
        stock_on_order=stock_on_order,
        location_code=location_code,
        location_name=location_name,
    )

    request = SetInventoryRequest(inventory=[inventory_item])
    return await self.set(request)

Helper Methods API Reference¶

Products Helper¶

Products ¶

create async ¶

delete async ¶

exists async ¶

find_by_code async ¶

find_by_exact_code async ¶

get_all async ¶

get_all_paginated async ¶

Customers Helper¶

Customers ¶

exists async ¶

find_or_create async ¶

get async ¶

get_all async ¶

update async ¶

Suppliers Helper¶

Suppliers ¶

create async ¶

create_one async ¶

delete async ¶

exists async ¶

find_by_code async ¶

get_all async ¶

Sales Orders Helper¶

SalesOrders ¶

create async ¶

delete async ¶

delete_for_product async ¶

get_all async ¶

get_for_product async ¶

Purchase Orders Helper¶

PurchaseOrders ¶

create async ¶

delete async ¶

exists async ¶

find_by_reference async ¶

get_all async ¶

Locations Helper¶

Locations ¶

create async ¶

get_all async ¶

Inventory Helper¶

Inventory ¶

set async ¶

set_for_product async ¶

create `async` ¶

delete `async` ¶

exists `async` ¶

find_by_code `async` ¶

find_by_exact_code `async` ¶

get_all `async` ¶

get_all_paginated `async` ¶

exists `async` ¶

find_or_create `async` ¶

get `async` ¶

get_all `async` ¶

update `async` ¶

create `async` ¶

create_one `async` ¶

delete `async` ¶

exists `async` ¶

find_by_code `async` ¶

get_all `async` ¶

create `async` ¶

delete `async` ¶

delete_for_product `async` ¶

get_all `async` ¶

get_for_product `async` ¶

create `async` ¶

delete `async` ¶

exists `async` ¶

find_by_reference `async` ¶

get_all `async` ¶

create `async` ¶

get_all `async` ¶

set `async` ¶

set_for_product `async` ¶