English · Русский

CommerceXL

Composable commerce backend foundation for the Orcestr ecosystem.

CommerceXL provides reusable catalog, order, balance and payment primitives for FastAPI, Pydantic 2 and SQLAlchemy 2 applications. The host application owns the database engine, sessions, users, authentication, CSRF policy, migrations and provider-specific callback routes.

Status

What Is Included

CommerceXL does not include a frontend, wallet integration, blockchain verifier or payment-provider credentials. Those belong in separate provider packages and host adapters.

Installation

pip install commercexl

Optional development dependencies:

pip install "commercexl[test]"
pip install "commercexl[dev]"

Quick Start

from decimal import Decimal

from commercexl import (
    BaseConfig,
    CommerceModule,
    DefaultOrderItemService,
    HandMadePaymentService,
    PaymentConfigBuilder,
    PaymentProviderRegistration,
    ProductOrderConfig,
    ProductOrderConfigBuilder,
)


class ProjectCommerceConfig(BaseConfig):
    PAYMENT_SYSTEMS = {"USD": ("handmade",)}
    MIN_TOP_UP_AMOUNTS = {"USD": Decimal("1")}
    CREDITS_CONVERTERS = {"USD": Decimal("10000")}


commerce = CommerceModule(
    config_class=ProjectCommerceConfig,
    product_orders=ProductOrderConfigBuilder(
        ProductOrderConfig(MyProductService, DefaultOrderItemService),
    ),
    payments=PaymentConfigBuilder(
        PaymentProviderRegistration(
            system="handmade",
            provider_kind="handmade",
            factory=HandMadePaymentService,
        ),
    ),
    public_base_url="https://commerce.example.com",
)

Provider registration is strict. A duplicate normalized system, a missing provider referenced by PAYMENT_SYSTEMS, or a factory returning the wrong service type fails during module construction.

FastAPI Integration

The host supplies an authenticated actor dependency and a mandatory mutation guard. For cookie-authenticated applications, the mutation guard is the host CSRF dependency.

from fastapi import Depends
from commercexl import CommerceHTTPConfig, CommerceUserActorDTO, create_router


async def get_commerce_actor(user=Depends(get_current_user)) -> CommerceUserActorDTO:
    return CommerceUserActorDTO(id=user.id, permissions=frozenset(user.permissions))


app.include_router(
    create_router(
        CommerceHTTPConfig(
            get_db_session_dependency=get_db_session,
            get_current_actor_dependency=get_commerce_actor,
            get_mutation_guard_dependency=check_csrf,
            get_commerce_module=lambda: commerce,
        ),
    ),
    prefix="/api/v1",
)

The optional filter_public_products hook receives the active AsyncSession and the already serialized list[ProductDTO]. It applies only to GET /products/, allowing a host to keep tenant-bound or otherwise host-orchestrated products out of the generic public catalog without changing CommerceXL product storage:

async def filter_public_products(session, products):
    hidden_kinds = await host_catalog.get_orchestrated_product_kinds(session)
    return [product for product in products if product.kind not in hidden_kinds]


CommerceHTTPConfig(
    # ...required dependencies...
    filter_public_products=filter_public_products,
)

With the default None, the endpoint returns the full serialized CommerceXL catalog as before. The hook does not affect internal serializers, balance-product lookup, gift certificates or order creation; hosts must still enforce checkout authorization independently.

The checkout is intentionally two-phase:

1. POST /orders/ creates a server-priced order and requires Idempotency-Key.
2. GET /orders/{order_id}/payment-options/ returns options available to that actor and order.
3. POST /orders/{order_id}/payment-attempts/ accepts only payment_option_id and another Idempotency-Key.
4. GET /payments/{payment_public_id}/ returns authoritative state without issuing a secret.
5. POST /payments/{payment_public_id}/checkout-action/ issues a fresh provider action.

Amounts are Decimal in Python and decimal strings in JSON. The client cannot submit the final payment amount, commercial currency or arbitrary provider system when creating an attempt. Each PaymentOptionDTO repeats the authoritative order-snapshot amount and currency, so a catalog price change after order creation cannot change the amount shown or paid for that order. Currency codes are host-defined strings (for example, fiat or application tokens), not a closed CommerceXL enum.

Provider Contract

Provider packages implement AbstractPaymentService or AbstractCallbackPaymentService and are registered through PaymentProviderRegistration. The stable provider-facing imports include PaymentCreateContext, PaymentCreateResult, PaymentOption, CheckoutAction, PaymentVerificationResult and PaymentState.

The canonical PaymentORM is the extension root for provider child tables. Providers do not mutate orders or mark them paid directly. A trusted callback/reconciliation adapter returns a typed verification result and passes it to PaymentRuntime.apply_verification(...) in the current DB session.

Checkout capability URLs and transaction-request bearer values must be issued by get_action(...); CommerceXL persists only non-secret action metadata. Safe provider evidence is claimed globally and payment changes write PaymentOutboxEventORM in the same transaction.

Database Migrations

CommerceXL does not ship application migrations. Add its metadata to the host Alembic setup and generate/review migrations in the host repository:

from commercexl import CommerceBase
from my_project.db import Base

target_metadata = [Base.metadata, CommerceBase.metadata]

Version 0.3 is a deliberate breaking schema/API release. Follow the 0.2 to 0.3 migration guide before upgrading production data.

Documentation

• Integration guide
• 0.3 migration guide
• Promocodes
• Gift certificates
• Release guide

Development

uv sync --all-extras
uv run pytest -q
uv build

License

Licensed under the Mozilla Public License 2.0. Commercial use is permitted; changes to MPL-covered files remain subject to the MPL. See NOTICE and TRADEMARKS.md.

Orcestr Ecosystem

• Orcestr
• Orcestr Auth
• Orcestr UI
• Orcestr OS