Release

Record vehicle releases from custody. This resource handles the action of releasing a vehicle — distinct from Releasability, which manages whether a vehicle can be released.

Overview

The Release resource records that a vehicle has been physically released from custody. This creates an immutable ledger event and publishes a custody.vehicle.released event to EventBridge.

• Releasability = "Can this vehicle be released?" (query and update releasability status)
• Release = "This vehicle has been released." (action/event)

Methods

release()

Record a vehicle release from custody.

Returns: VehicleReleaseResponse

Raises: ValidationError (400), NotFoundError (404), InvalidStateError (409), StorageError (500), AuthenticationError (401), ServiceUnavailableError (503)

Example:

from vecu_custody import CustodyClient

client = CustodyClient.sandbox(token="your-jwt-token")

result = client.release.release(
    "1HGBH41JXMN109186",
    authorization_id="AUTH-12345678",
    release_method="web_verifier",
)

print(f"Released: {result.message}")
print(f"VIN: {result.vin}")
print(f"Authorization: {result.authorization_id}")

With location coordinates:

result = client.release.release(
    "1HGBH41JXMN109186",
    authorization_id="AUTH-12345678",
    release_method="mobile_verifier",
    latitude=33.6407,
    longitude=-84.4527,
)

Response Objects

VehicleReleaseResponse

Returned by release().

Parameters

release_method

The release_method parameter is a string identifying how the vehicle was released. Valid values are defined by the custody service. Passing an invalid value will result in a ValidationError (HTTP 400) from the service.

Location Coordinates

The optional latitude and longitude parameters record where the vehicle was released. Both must be provided together if used.

Common Use Cases

Release After Gate Verification

from vecu_custody import CustodyClient

client = CustodyClient.sandbox(token="your-jwt-token")

# Check releasability first
status = client.releasability.get(
    "1HGBH41JXMN109186",
    origin="1180 Lake Hearn Dr NE, Atlanta, GA 30342"
)

if status.is_releasable:
    # Record the release
    result = client.release.release(
        "1HGBH41JXMN109186",
        authorization_id="AUTH-12345678",
        release_method="mobile_verifier",
        latitude=33.8463,
        longitude=-84.3621,
    )
    print(f"Vehicle released: {result.message}")
else:
    print(f"Cannot release. Blockers: {status.blockers}")

Async Release

from vecu_custody.aio import AsyncCustodyClient

async with AsyncCustodyClient.sandbox(token="your-jwt-token") as client:
    result = await client.release.release(
        "1HGBH41JXMN109186",
        authorization_id="AUTH-12345678",
        release_method="web_verifier",
    )
    print(f"Released: {result.message}")

Error Handling

from vecu_custody import CustodyClient
from vecu_custody.exceptions import (
    InvalidStateError,
    NotFoundError,
    StorageError,
    ValidationError,
    AuthenticationError,
    CustodyError,
)

client = CustodyClient.sandbox(token="your-jwt-token")

try:
    result = client.release.release(
        "1HGBH41JXMN109186",
        authorization_id="AUTH-12345678",
        release_method="web_verifier",
    )
    print(f"Released: {result.message}")

    # Check for non-fatal warnings
    if result.warnings:
        for warning in result.warnings:
            print(f"Warning: {warning}")
except NotFoundError as e:
    # Authorization not found or VIN mismatch
    print(f"Not found: {e.message}")
except InvalidStateError as e:
    # Authorization already released, cancelled, expired, or revoked
    print(f"Invalid state: {e.message}")
except StorageError as e:
    # Ledger write or transaction failure
    print(f"Storage error: {e.message}")
except ValidationError as e:
    # Invalid VIN, missing fields, or invalid release_method
    print(f"Validation error: {e.message}")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except CustodyError as e:
    print(f"API error: {e.message}")

Next Steps

• Releasability - Query and update vehicle releasability status
• Custody Permits - Manage custody authorizations
• Transfers - Record custody transfers