britecore_sdk

Getting Started

  • Project overview
    • Quick Start
      • 1. Install
      • 2. Configure
      • 3. Use
      • About API Client Initialization
    • Features
    • Documentation
    • Installation & Configuration
      • Requirements
      • Install
      • Configuration
    • What This Package Provides
      • API Wrappers
      • Utilities
      • Optional Extras
    • Using Async Wrappers
      • Native async transport (optional)
    • Development
      • Install for Development
      • Run Tests
      • Linting & Type Checking
      • Release Publishing (GitHub Actions)
      • Contributing
    • Architecture
    • Support & Links
    • Project Links
  • BriteCore SDK Examples
    • Quick Start Examples
      • 1. complete_workflow.py - Start Here!
      • 2. configuration_examples.py - Setup & Config
    • Advanced Examples
      • 3. advanced_error_handling.py - Robust Error Handling
      • 4. async_operations.py - Async & Concurrent Processing
    • Domain-Specific Examples
      • 5. basic_api_usage.py - Core API Operations
      • 6. batch_quote_creation.py - Batch Operations
      • 7. multi_tenancy_example.py - Multi-Site Operations
      • 8. rate_limiting_example.py - Rate Limit Handling
      • 9. staged_workflow_creation.py - Complex Workflows
      • 10. stitched_line_extract.py - Complex Data
    • Setup Instructions
      • 1. Install Dependencies
      • 2. Configure Credentials
      • 3. Verify Setup
    • Running Examples
      • Basic Example (No API calls)
      • With Live API Calls
      • Async Example
      • Error Handling Example
      • Dry-Run Mode (Test without sending)
    • Pattern Reference
    • Common Tasks
      • Creating a Policy
      • Querying Multiple Policies Concurrently
      • Handling Rate Limits
      • Using Different Environments
      • Testing Without Real API Calls
    • Troubleshooting
      • “Authentication failed”
      • “Rate limit exceeded”
      • “Connection refused”
    • Documentation Links

Learn by Doing

  • Common patterns
    • Pattern 1: Policy Lookup with Fallback
    • Pattern 2: Batch Contact Import with Validation
    • Pattern 3: Rate Limit Aware Loops
    • Pattern 3b: Dry-Run Request Preview
    • Pattern 4: Pagination Through Large Result Sets
    • Pattern 5: Batch Operations with Progress Tracking
    • Pattern 6: Conditional Policy Updates
    • Pattern 7: Error Recovery with Retry
    • Pattern 8: Extract and Transform Responses
    • Pattern 9: Async Bulk Operations
    • Pattern 10: Context-Based Configuration
    • Tips and Best Practices
    • See Also
  • Configuration Guide
    • Overview
    • Config Files
      • Canonical precedence table
      • SDK package default files (mainly for source clones)
      • settings.toml (Public)
      • .secrets.toml (Private)
    • Loading Configuration
      • Automatic (Recommended)
      • Via get_api_client() (Lazy, Recommended)
    • Environment Variables
    • Required Keys by Auth Mode
      • API Key Auth
      • OAuth Auth
    • Optional Utility Keys
      • Interactive menu behavior in IDE consoles
    • Validation
    • Per-Environment Setup
      • Development
      • CI/CD Pipelines
      • Production
        • API-only deployment checklist
    • Troubleshooting
      • “Config not loading” or “Key not found”
      • Auth failures
    • Adding New Sites
    • Private Maps Behavior
    • See Also
  • Architecture roadmap
    • Overview
    • Breaking Changes & Migration Path
      • Phase 1: Client Lifecycle Redesign
        • Current State (legacy)
        • v2.0.0 Target
        • Implementation Strategy
        • Acceptance Criteria
      • Phase 2: Typed Response Models
        • Current State (legacy)
        • v2.0.0 Target
        • Response Model Structure
        • Implementation Strategy
        • Acceptance Criteria
      • Phase 3: Standardized Error Model
        • Current State (legacy)
        • v2.0.0 Target
        • Exception Hierarchy (v2.0.0)
        • Implementation Strategy
        • Acceptance Criteria
      • Phase 4: Transport Boundary & Middleware
        • Current State (legacy)
        • v2.0.0 Target
        • Implementation Strategy
        • Acceptance Criteria
      • Phase 5: Pagination Ergonomics
        • Current State (legacy)
        • v2.0.0 Target
        • Iterator Implementation
        • Implementation Strategy
        • Acceptance Criteria
      • Phase 6: Legacy Cleanup
        • Current State (legacy)
        • v2.0.0 Target
        • What Gets Removed
        • Migration Helpers Module
        • Implementation Strategy
        • Acceptance Criteria
    • Implementation Timeline
      • Week 1-2: Foundation
      • Week 3-4: Type Safety
      • Week 5-6: Extensibility
    • Version Strategy
      • 1.6.0 (Minor - Deprecations)
      • 1.7.0 (Minor - Foundation)
      • v2.0.0 (Major - Breaking)
    • Testing Strategy
    • Documentation Updates
    • Success Metrics
    • See Also
  • Response Caching Strategy
    • Overview
    • When to Enable Caching
      • ✅ Good Use Cases
      • ❌ Poor Use Cases
    • Configuration
      • Per-Request Configuration
      • Global Configuration
    • Cache Behavior
      • Key Generation
      • Cache Invalidation
    • Performance Considerations
      • Memory Usage
      • TTL Tuning
    • Caching Strategies
      • Strategy 1: Read-Through Cache
      • Strategy 2: Write-Through Cache
      • Strategy 3: Time-Based Invalidation
      • Strategy 4: Selective Caching
    • Troubleshooting
      • “Getting stale data from cache”
      • “Cache consuming too much memory”
      • “Cache hits are low”
    • Best Practices
    • See Also
  • Async Caching Guide
    • Where async wrappers live
    • Transport modes
      • Threaded transport (default)
      • httpx native async transport
    • Default behavior
    • Exact usage
    • Cache controls (RequestParameters)
    • Async dry-run behavior
    • Manage cache manually
    • Notes
  • Optional extras
    • async-http — native async HTTP transport
      • Usage
    • typed-config — pydantic-validated settings view
      • Usage
    • interactive — menu-driven CLI utilities
    • Installing multiple extras

How-To Guides

  • Batch quote creation
    • Overview
    • Problem Statement
    • Quick Start
      • Synchronous Batch (Simple)
      • Asynchronous Batch (For Web Services)
    • API Reference
      • Synchronous: create_full_quotes_batch()
      • Asynchronous: acreate_full_quotes_batch()
    • Usage Patterns
      • Pattern 1: Simple Batch Creation
      • Pattern 2: Chunked Batch for Very Large Volumes
      • Pattern 3: Async with Progress Tracking
      • Pattern 4: Fail-Fast for Transactions
    • Performance Tuning
      • Choosing max_workers / max_concurrent
      • Example Tuning Session
    • Error Handling
      • Partial Success Workflow
      • Retry with Exponential Backoff
    • Comparison: Sync vs. Async
    • Integration with Rate Limiting
    • Real-World Example: Nightly Batch Job
    • Troubleshooting
      • Issue: Slow Batch Execution
      • Issue: 429 (Too Many Requests) Errors
      • Issue: Connection Pool Exhausted
      • Issue: Memory Usage Grows During Batch
    • Performance Benchmarks
    • See Also
  • Rate limiting
    • Overview
    • Why Use Rate Limiting?
    • Quick Start
      • Enable Rate Limiting at Client Initialization
      • Configure Rate Limiting Parameters
      • Use via RequestParameters
    • Configuration
      • Via settings.toml (recommended for most users)
      • Via init_client Parameters
      • Via Environment Variables
    • Configuration Parameters
      • Recommended Settings
    • How It Works
      • Token Bucket Algorithm
      • Example
      • Adaptive Backoff
    • Logging
      • INFO Level: Backoff Events
      • DEBUG Level: Rate Limit Delays
    • Monitoring Rate Limiter State
      • Check Current State
      • State Fields
      • String Representation
    • Advanced Usage
      • Reset Rate Limiter
      • Manually Trigger Backoff
      • Access Direct Rate Limiter Methods
    • Best Practices
      • 1. Start Conservative, Adjust Based on Feedback
      • 2. Use Different Settings Per Environment
      • 3. Monitor Rate Limiter Logs
      • 4. Don’t Bypass Rate Limiter Unnecessarily
      • 5. Handle RateLimitError Gracefully
    • Comparison: Client-Side vs Server-Side Rate Limiting
    • Troubleshooting
      • Rate Limiter Seems Too Aggressive (Requests Waiting a Long Time)
      • Getting 429 Errors Despite Rate Limiter Enabled
      • Rate Limiter Backing Off After 429
    • See Also
  • Events and webhooks
    • Overview
    • Core principles
    • Envelope and payload handling
    • Idempotency pattern
    • Retry coordination
    • Correlation and observability
    • Webhook framework and listener setup
      • Event payload structure
      • Common event topics
      • Signature verification
    • Integration webhooks reference
      • Integration point codes
      • Checking integration point availability
      • Integration data persistence
    • Related SDK modules and docs
    • Practical checklist
  • Multi-tenancy
    • Overview
    • Pattern 1: Module-Level Client with Reset (Simplest)
    • Pattern 2: Explicit Inline Credentials + use_api_client (Recommended)
    • Pattern 3: Context Manager for Isolated Operations
    • Pattern 4: Long-Lived Clients in a Service Registry
    • Pattern 5: Configuration File per Environment
    • Best Practices
      • 1. Use Explicit Credentials for Independent Sites
      • 2. Store Credentials in Environment Variables or Secure Vaults
      • 3. Use Context Manager for Request Isolation
      • 4. Don’t Mix Module-Level and Explicit Initialization
      • 5. Include Site Name in Logs and Traces
    • Concurrent Multi-Tenancy with Async
    • Testing Multi-Tenancy
    • Common Patterns by Use Case
    • Troubleshooting
      • “Different sites returning same data”
      • “Connection pool exhausted”
      • “Site config not found”
    • See Also
  • Staged workflows
    • Why Staged Workflows?
    • Quick Start
      • Synchronous (ThreadPoolExecutor)
      • Asynchronous (asyncio)
    • Job Format
    • Result Format
    • Concurrency Parameters
    • fail_fast Behavior
    • Rate Limiting Integration
    • Adding New Stages
    • See Also
  • Line extract stitching
    • Background: Why Stitching?
    • Important: Timeout Guidance
    • Quick Start
      • Synchronous
      • Asynchronous
    • Line Tuple Format
    • Concurrency Guidance
    • Result Format
    • Error Handling
    • Single-Line Extract
    • See Also
  • Implementation example
    • Overview
    • What Changed
      • 1. Enhanced Exception Base Class
      • 2. Smart Hint Generation
      • 3. Error Hints Module
    • Example Usage
      • Configuration Error with Hint
      • Authentication Error with Hint
      • Custom Hint
    • Benefits
    • Technical Details
      • New Exception Base Class Signature
      • Auto-Hint Generation
      • Backward Compatibility
    • Testing
      • Test Error Messages with Hints
      • Test Error Hints Module
    • Files Modified/Created
    • Integration with Existing Code
      • In API Client Initialization
      • In Settings Resolution
    • Future Enhancements
      • Phase 2 (Not in this iteration)
      • Phase 3
    • Documentation
      • For SDK Users
      • For SDK Contributors
      • For Developers
    • Metrics
      • Before Implementation
      • After Implementation
    • Rollout Plan
    • Conclusion
  • Observability
    • Overview
    • Logging Basics
      • Default Behavior (No Handler)
      • App-Owned Logging (Recommended)
      • SDK-Managed Logging (Optional)
    • X-SDK-Request-ID Headers
      • Capturing Correlation IDs in Your App
      • Accessing Correlation IDs from Exceptions
    • Debug Logging Levels
      • Level: INFO (Default)
      • Level: DEBUG
      • Level: WARNING
    • Authentication Mode Detection
    • Structured Logging with Context
    • Rate Limiting & Retry Observability
    • Async Cache Observability
    • Dry-Run Mode for Testing
    • Monitoring in Production
      • Recommended Logging Setup
      • Metrics to Monitor
    • Correlation ID Propagation (Distributed Tracing)
    • Troubleshooting with Logs
      • “No output from SDK”
      • “Which auth mode is being used?”
      • “Requests are timing out”
      • “Rate limit is being hit”
    • See Also

API Reference

  • Overview
    • Notable SDK additions
    • Package exports
    • API clients
      • LoadClientSettings
        • LoadClientSettings.load_config()
      • BritecoreAPIClient
        • BritecoreAPIClient.init_client()
        • BritecoreAPIClient.process_result()
        • BritecoreAPIClient.do_request()
        • BritecoreAPIClient.multiple_parameter_verification()
        • BritecoreAPIClient.json_dict_builder()
        • BritecoreAPIClient.create_full_quotes_batch()
        • BritecoreAPIClient.create_contacts_batch()
        • BritecoreAPIClient.create_policies_batch()
        • BritecoreAPIClient.create_risks_batch()
      • RequestParameters
        • RequestParameters.request_timeout
        • RequestParameters.request_retries
        • RequestParameters.request_headers
        • RequestParameters.cache_enabled
        • RequestParameters.cache_ttl_seconds
        • RequestParameters.cache_namespace
        • RequestParameters.cache_key_parts
        • RequestParameters.cache_bypass
        • RequestParameters.cache_invalidate_on_success
        • RequestParameters.dedupe_in_flight
        • RequestParameters.dry_run
        • RequestParameters.dry_run_include_sensitive_headers
        • RequestParameters.rate_limiter_bypass
      • AsyncBritecoreAPIClient
        • AsyncBritecoreAPIClient.aget_client()
        • AsyncBritecoreAPIClient.clear_cache()
        • AsyncBritecoreAPIClient.invalidate_cache_namespaces()
        • AsyncBritecoreAPIClient.aprocess_result()
        • AsyncBritecoreAPIClient.ado_request()
        • AsyncBritecoreAPIClient.acreate_full_quotes_batch()
        • AsyncBritecoreAPIClient.acreate_contacts_batch()
        • AsyncBritecoreAPIClient.acreate_policies_batch()
        • AsyncBritecoreAPIClient.acreate_risks_batch()
      • build_cache_key()
      • CacheEntry
        • CacheEntry.value
        • CacheEntry.expires_at
        • CacheEntry.namespace
        • CacheEntry.created_at
        • CacheEntry.is_expired()
      • RequestCache
        • RequestCache.get()
        • RequestCache.set()
        • RequestCache.invalidate_namespace()
        • RequestCache.invalidate_namespaces()
        • RequestCache.clear()
        • RequestCache.prune_expired()
    • Exceptions
      • v2.0.0 Enhanced Error Model
      • BritecoreError
        • BritecoreError.Base
        • BritecoreError.NoDataReturned
        • BritecoreError.NoTokenReturned
        • BritecoreError.InvalidPhoneNumber
        • BritecoreError.InvalidEmailAddress
        • BritecoreError.InvalidAddress
        • BritecoreError.BritecoreKeyError
        • BritecoreError.NoSiteError
        • BritecoreError.MissingParameter
        • BritecoreError.ConflictingParameters
        • BritecoreError.AuthenticationError
        • BritecoreError.RateLimitError
        • BritecoreError.ServerError
        • BritecoreError.ValidationError
        • BritecoreError.NotFoundError
        • BritecoreError.ConflictError
        • BritecoreError.ConfigurationError
        • BritecoreError.RequestTimeoutError
      • BritecoreBaseError
      • NoDataReturned
      • NoTokenReturned
      • AuthenticationError
      • RateLimitError
      • ServerError
      • ValidationError
      • NotFoundError
      • ConflictError
      • ConfigurationError
      • RequestTimeoutError
      • BritecoreKeyError
      • NoSiteError
      • MissingParameter
      • ConflictingParameters
      • InvalidPhoneNumber
      • InvalidEmailAddress
      • InvalidAddress
    • Utilities
      • HealthcheckResult
        • HealthcheckResult.ok
        • HealthcheckResult.site
        • HealthcheckResult.auth_mode
        • HealthcheckResult.config_ok
        • HealthcheckResult.api_ok
        • HealthcheckResult.message
      • run_healthcheck()
      • main()
    • V2 package exports
      • Sync domain modules
      • Async helpers and batch aliases
      • create_contacts_batch()
      • create_full_quotes_batch()
      • create_policies_batch()
      • create_risks_batch()
      • aadd_contact_to_role()
      • aadd_line_item()
      • acreate_contacts_batch()
      • acreate_full_quote()
      • acreate_full_quotes_batch()
      • acreate_policies_batch()
      • acreate_policy()
      • acreate_risk()
      • acreate_risks_batch()
      • afind_contact_by_params()
      • aget_contact()
      • aget_quote()
      • anew_contact()
      • anew_mortgagee()
      • anew_revision_contact()
      • arate_revision()
      • arate_risk()
      • aretrieve_policy()
      • aretrieve_policy_contact_info()
      • aretrieve_policy_ids()
      • aretrieve_policy_snapshot()
      • aretrieve_policy_terms()
      • aretrieve_revision_details()
      • aretrieve_risk_details()
      • aretrieve_risks()
      • astore_mortgagee()
      • aupdate_contact()
      • aupdate_property_location()
      • aupdate_rating_information()
    • Workflow package exports
      • Staged workflow helpers
      • Batch helpers
      • BatchContactCreateResult
        • BatchContactCreateResult.index
        • BatchContactCreateResult.success
        • BatchContactCreateResult.contact_data
        • BatchContactCreateResult.contact_id
        • BatchContactCreateResult.error
      • BatchPolicyCreateResult
        • BatchPolicyCreateResult.index
        • BatchPolicyCreateResult.success
        • BatchPolicyCreateResult.policy_data
        • BatchPolicyCreateResult.revision_id
        • BatchPolicyCreateResult.error
      • BatchQuoteCreateResult
        • BatchQuoteCreateResult.index
        • BatchQuoteCreateResult.success
        • BatchQuoteCreateResult.quote_data
        • BatchQuoteCreateResult.quote_id
        • BatchQuoteCreateResult.error
      • BatchRiskCreateResult
        • BatchRiskCreateResult.index
        • BatchRiskCreateResult.success
        • BatchRiskCreateResult.risk_data
        • BatchRiskCreateResult.risk_id
        • BatchRiskCreateResult.error
      • StagedWorkflowJob
        • StagedWorkflowJob.contact_payload
        • StagedWorkflowJob.quote_payload
        • StagedWorkflowJob.policy_payload
        • StagedWorkflowJob.risk_payloads
      • StagedWorkflowResult
        • StagedWorkflowResult.index
        • StagedWorkflowResult.success
        • StagedWorkflowResult.contact_id
        • StagedWorkflowResult.contact_data
        • StagedWorkflowResult.quote_id
        • StagedWorkflowResult.quote_data
        • StagedWorkflowResult.revision_id
        • StagedWorkflowResult.policy_data
        • StagedWorkflowResult.risk_ids
        • StagedWorkflowResult.risk_results
        • StagedWorkflowResult.error
        • StagedWorkflowResult.failed_stage
      • acreate_contacts_batch()
      • acreate_entities_staged_batch()
      • acreate_full_quotes_batch()
      • acreate_policies_batch()
      • acreate_risks_batch()
      • create_contacts_batch()
      • create_entities_staged_batch()
      • create_full_quotes_batch()
      • create_policies_batch()
      • create_risks_batch()
    • API Domains
  • API Domains
    • Quotes and Policies APIs
      • Quotes
        • Quotes module
        • Quote module
        • Related modules
      • Policies
        • Policies module
        • Lines module
        • Coverages module
        • Related modules
    • Claims and Contacts APIs
      • Claims
        • Claims module
        • Claim contacts module
        • Claim properties module
        • Claim vehicles module
        • Related modules
      • Contacts
        • Contacts module
        • Named insureds module
        • Insured module
    • Auto APIs
      • Vehicles module
        • add_additional_interest()
        • check_vehicle_prefill_fallback_configured()
        • create_vehicle()
        • delete_additional_interest()
        • delete_vehicle()
        • get_additional_interest()
        • get_vehicle()
        • list_additional_interests_for_vehicle()
        • list_custom_fields_types()
        • list_vehicles_for_quote()
        • update_additional_interest()
        • update_vehicle()
        • vehicle_prefill_fallback()
      • Drivers module
        • create_driver()
        • delete_driver()
        • get_driver()
        • list_custom_fields_types()
        • list_driver_integration_reports()
        • list_drivers_for_quote()
        • update_driver()
      • Violations module
        • create_driver_mvr_report_file()
        • create_violation()
        • create_violations()
        • delete_violation()
        • dispute_violation()
        • get_violation()
        • list_violation_for_driver()
        • remove_violation_dispute()
        • update_violation()
      • Watercrafts module
        • create_watercraft()
        • delete_watercraft()
        • get_watercraft()
        • list_custom_fields_types()
        • list_watercrafts_for_quote()
        • update_watercraft()
    • Spatial APIs
      • Geometries module
        • create_geometry()
        • delete_geometry()
        • get_geometries()
        • get_geometry()
        • update_geometry()
      • Geometry module
        • get_zip_geometry()
    • Financial and Operations APIs
      • Billing, Payments, and Commissions
        • Billing module
        • Payments module
        • Commissions module
        • Related modules
      • Documents and Deliverables
        • Deliverables module
        • Files module
        • Related modules
      • Operations and Workflow
        • Inspections module
        • Notes module
        • Tasks module
        • Related modules
    • Platform, Data, and Async APIs
      • Reporting and Administration
        • Reports module
        • Configurations module
        • Permissions module
        • Related modules
      • Data, Integrations, and Background Jobs
        • Imports module
        • Integrations module
        • Background jobs module
        • Related modules
      • Async Endpoints
        • Async quotes module
        • Async contacts module
        • Async policies module
        • Async lines module

Deployment & Operations

  • Map Files
    • What britecore_sdk/maps/ now provides
    • Where mapping data now lives
    • Security policy (unchanged)
    • Adding a new carrier system
  • Deployment & CI/CD Guide
    • Overview
    • Docker Deployment
      • Basic Dockerfile
      • Using Docker Compose
      • Health Check Endpoint
    • Kubernetes Deployment
      • Deployment Manifest
      • Store Credentials in a Secret
    • GitHub Actions CI/CD
      • Environment Setup
      • Test Workflow
      • Validate Configuration Before Deploy
    • AWS Lambda Deployment
      • Lambda Function Handler
      • Lambda Configuration
      • Deploy to Lambda
    • Google Cloud Functions Deployment
      • Cloud Function Code
    • GitLab CI/CD
      • .gitlab-ci.yml
    • Production Best Practices
      • 1. Use Explicit Credentials (No Config Files)
      • 2. Set Timeouts for Long-Running Requests
      • 3. Configure Logging for Production
      • 4. Monitor Request Latency
      • 5. Handle Rate Limits Gracefully
      • 6. Use Health Checks for Orchestration
    • Environment Variable Reference
    • Troubleshooting Deployment
      • “No module named britecore_sdk”
      • “BRITECORE_SDK_BASE_URL not set”
      • “Connection timeout”
      • “Rate limit 429 responses”
    • See Also
  • ReadTheDocs Versioning and Release Management
    • Overview
      • Current configuration
    • How versioning works
      • Release versions (git tags)
      • Branch tracking
      • Release matrix
    • Creating a new release
      • Step 1: Create a git tag
      • Step 2: Update version in pyproject.toml
      • Step 3: RTD build and activation
    • RTD web interface
      • Viewing builds
      • Configuring versions
    • FAQ
      • Q: Can users view docs for older releases?
      • Q: Will RTD build from all my branches?
      • Q: What if I want to hide an old version?
      • Q: Can I build docs for release candidates?
      • Q: Why do I only see latest and stable in the selector?
      • Q: How do I update docs for a released version?
    • Related documentation
  • CI/CD and Coverage Guide
    • Overview
    • GitHub Actions Workflows
      • Location
      • tests.yml — Test Matrix
      • lint.yml — Code Quality
      • docs.yml — Documentation Build
      • ci.yml — Coordination
    • DeepSource Integration
      • What it does
      • Enabled Analyzers
      • Setup (One-time)
      • Understanding DeepSource Results
      • Workflow
    • Coverage Reports
      • Codecov
      • DeepSource Coverage
      • Local Coverage Reports
    • Test Coverage Targets
    • Local Testing and Coverage
      • Install Dev Dependencies
      • Run All Tests
      • Run Specific Test Category
      • Check Coverage for Specific Module
      • Run Linters Locally
    • Troubleshooting CI
      • “DeepSource: Python” or “test-coverage” check is failing
      • Coverage drop between PRs
    • Best Practices
      • Before Pushing
      • In PRs
      • Merging
    • See Also
    • Bash Equivalents (Common Local Commands)
  • Documentation Build Troubleshooting
    • Quick diagnostic checklist
    • Common documentation build errors
      • Error: “adjacent transitions are not allowed”
      • Error: “Unknown substitution referenced”
      • Error: “Inline code cannot contain MyST substitutions”
      • Error: “Incomplete markup constructs”
      • Error: “Unknown role/directive”
      • Error: “Document title underline too short/too long”
    • Prevention: Git hooks and pre-commit
      • Enable pre-commit hooks
      • What the hooks check
      • Bypassing hooks (not recommended)
    • Best practices for documentation changes
    • Running pre-commit in different scenarios
      • Before commit (automatic if hooks installed)
      • Before push (also automatic)
      • Manual validation (for debugging)
      • In CI/GitHub Actions
    • Related documentation

Contributing & Policies

  • Implementation checklist
    • Priority 1: Quick Wins
    • Priority 2: Developer Experience
    • Priority 3: Testing & Quality
    • Priority 4: Performance & Monitoring
    • Priority 5: Documentation & Examples
    • Priority 6: Advanced Features
    • Priority 7: Infrastructure & DevOps
    • Files Created (16 Total)
      • CLI (2)
      • API (4)
      • Testing (4)
      • Documentation (3)
      • Scripts (3)
      • Summary (1)
    • Files Modified (9 Total)
      • Core SDK (8)
      • Configuration (1)
      • Documentation (1)
    • Validation Results
    • Installation & Verification
      • Install editable package
      • Run quick check
      • Run tests with new fixtures
      • Check coverage
    • Next Steps for Users
    • Statistics
    • Quality Gate Status
  • AGENTS Guide
  • AGENTS.md
    • Scope and source of truth
    • Repo layout contract
    • Big-picture architecture
    • API module pattern (copy this when adding endpoints)
    • Docstring source policy
    • Configuration and integration points
    • Developer workflow in this repo
    • Logging
    • Pre-commit hooks and quality gates
      • Setup (first time only)
      • What runs automatically on git commit
      • What runs on git push
      • Preventing the documentation build failures
      • Manual invocation (for debugging)
      • Bypass (only when absolutely necessary)
    • Gotchas that affect agent changes

Reference & Migration

  • Migration Guide: SDK v1 → v2
    • Overview of Changes
    • Before (v1) vs After (v2)
      • Client Initialization
        • Before (v1 - Eager):
        • After (v2 - Lazy & Preferred):
      • Endpoint Wrappers
        • Before (v1):
        • After (v2 - Preferred, v1 still works):
      • Exception Handling
        • Before (v1):
        • After (v2 - Flat imports preferred):
      • Model Classes
        • Before (v1):
        • After (v2):
      • Async Operations
        • Before (v1 - Not available):
        • After (v2):
    • Step-by-Step Migration
      • Step 1: Update Imports
      • Step 2: Update Client Initialization
      • Step 3: Update Exception Handling
      • Step 4: Update Validator Usage
      • Step 5: Enable Logging (Optional)
    • Breaking Changes
      • 1. Lazy Client Initialization
      • 2. Exception Hierarchy
      • 3. Module Removal: britecore_sdk.classes
    • Compatibility Notes
      • v1 Endpoints Still Supported
      • Configuration
    • Testing Migration
      • Before (v1 Tests):
      • After (v2 Tests - Using New Fixtures):
    • Troubleshooting Migration Issues
      • Issue: “ImportError: cannot import name ‘X’ from britecore_sdk.classes”
      • Issue: “Client not initialized” on first request
      • Issue: Type hints not working in IDE
    • Performance Improvements in v2
    • Timeline for Deprecations
    • Migration Checklist
    • Getting Help
    • See Also
  • POST Contract Probing
    • Safety Rules
    • Probe Plan Format
    • Run
    • Output
  • Endpoint Verification Snapshot (2026-04-28)
    • Scope
    • Summary
      • Older v1 wrapper status
    • Verification Commands Used
    • Known Gap Paths (Tracked)
    • Caveat
  • Reference Projects
    • Why These Projects
    • Recommended References
      • 1) stripe/stripe-python
      • 2) slackapi/python-slack-sdk
      • 3) twilio/twilio-python
      • 4) sendgrid/sendgrid-python
      • 5) plaid/plaid-python
    • Generator and Spec Tooling References
      • 6) openapi-generators/openapi-python-client
      • 7) OpenAPITools/openapi-generator
    • Mapping to britecore_sdk Roadmap
    • Notes
britecore_sdk
  • API Domains
  • Financial and Operations APIs
  • Billing, Payments, and Commissions APIs
  • View page source

Billing, Payments, and Commissions APIs

  • Billing module
  • Payments module
  • Commissions module

Related modules

  • Premium finance companies module
  • Return premium module
  • Term credit scores module
  • Accounting module
Previous Next

© Copyright 2026, britecore_sdk contributors.

Built with Sphinx using a theme provided by Read the Docs.