--- title: "Integration Workflows" description: "Choose the right integration approach for your business" url: https://www.fenerum.com/en-DK/docs/api/guides/typical-workflow/ updated_at: "2025-12-22T00:00:00" --- ## Overview Fenerum offers flexible integration options to match your business needs. Choose the approach that best fits your use case: **Choose Your Integration Approach:** - [UI-First Integration](#ui-first-integration) — Use Fenerum UI, export data to BI - [Hybrid Integration](#hybrid-integration) — Self-Service + API for backend - [Full API Integration](#full-api-integration) — Complete headless integration (Recommended for B2B SaaS) --- ## UI-First Integration **Best for:** Small teams, startups, or businesses that want to use Fenerum's built-in features with minimal development work. ### How It Works 1. **Manage everything in Fenerum UI** - Create accounts, subscriptions, and plans through the web interface - Issue invoices and manage billing manually or with automation rules - Monitor metrics with built-in dashboards 1. **Export data via API for analytics** - Use read-only API endpoints to pull data into your BI tools - Common endpoints: `/api/v1/accounts/`, `/api/v1/invoices/`, `/api/v1/subscriptions/` - Sync data to your data warehouse for custom reporting ### Key Benefits - **Quick setup** - No integration code needed - **Full feature access** - Use all Fenerum features through the UI - **Simple analytics** - Export data when you need it ### Example: Export Invoices ```bash curl https://app.fenerum.com/api/v1/invoices/?created_date__gte=2025-01-01 \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: BIExport" ``` --- ## Hybrid Integration **Best for:** Businesses that want to automate backend operations while offering customers a self-service portal. ### How It Works 1. **Customer-facing: Fenerum Self-Service** - Customers manage their own payment methods through [Self-Service](https://www.fenerum.com/en-DK/docs/organization/settings/self-service.md) - Add/remove cards, update billing info, view invoices - No development needed on your side 1. **Backend: API Integration** - Automatically create accounts and subscriptions via API when customers sign up - Sync usage data, update quantities, manage lifecycle events - Handle complex business logic in your application ### Integration Flow ``` Your App (Backend) Fenerum API Customer │ │ │ │ Create Account │ │ ├──────────────────────────► │ │ │ │ │ │ Create Subscription │ │ ├──────────────────────────► │ │ │ │ │ │ Generate Self-Service Link │ │ ├──────────────────────────► │ │ │ ◄────────────────────────┤ │ │ │ │ │ Redirect Customer to Self-Service │ ├──────────────────────────────────────────────────► │ │ │ │ │ │ Add Payment Card │ │ │ ◄──────────────────── │ ``` ### Example: Generate Self-Service Link ```bash curl -X POST https://app.fenerum.com/api/self-service/initiate-organization/ \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: YourApp" \ -H "Content-Type: application/json" \ -d '{ "email": "customer@example.com" }' ``` ```json { "url": "https://yourcompany.hostedsignup.com/auth/login?token=..." } ``` See the [Self-Service guide](https://www.fenerum.com/en-DK/docs/organization/settings/self-service.md) for complete setup instructions. --- ## Full API Integration **Best for:** B2B SaaS companies that want complete control and a fully branded experience. **✨ Recommended for B2B SaaS** - Your customers never see or interact with Fenerum directly. Everything happens through your application with Stripe or QuickPay handling payment collection. ### How It Works Complete headless integration where all billing operations are managed programmatically: - **Account management** - Create/update customer accounts via API - **Subscription lifecycle** - Start, upgrade, downgrade, cancel subscriptions - **Payment collection** - Use Stripe or QuickPay directly (see [Accepting Payments](https://www.fenerum.com/en-DK/docs/api/guides/payments.md)) - **Usage tracking** - Report usage data for metered billing - **Invoicing** - Automatic invoice generation and delivery ### Critical: Creation Order **Always create resources in this order:** 1. **Account** - Your customer 1. **Contracts** _(optional)_ - Special pricing or volume discounts with tiers 1. **Payment Method** - Stripe or QuickPay card registration 1. **Subscription** - Active plan usage ### Step 1: Create Account ```bash curl -X POST https://app.fenerum.com/api/v1/accounts/ \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: YourApp" \ -H "X-User: admin@yourapp.com" \ -H "Content-Type: application/json" \ -d '{ "code": "CUST001", "name": "Acme Corporation", "email": "billing@acme.com", "type": "company", "legal_address": "123 Main Street", "legal_zipcode": "12345", "legal_city": "Copenhagen", "legal_country": "DK" }' ``` ```json { "uuid": "123e4567-e89b-12d3-a456-426614174000", "code": "CUST001", "name": "Acme Corporation", "email": "billing@acme.com", "type": "company" } ``` ### Step 2: Add Contracts (Optional) If the customer has negotiated special pricing or volume discounts, create a contract with discount tiers: ```bash # First, create the contract curl -X POST https://app.fenerum.com/api/v1/accounts/CUST001/contracts/ \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: YourApp" \ -H "Content-Type: application/json" \ -d '{ "plan_terms": "plan-terms-uuid", "start_date": "2025-01-01", "end_date": "2025-12-31" }' ``` ```json { "uuid": "contract-uuid-here", "plan_terms": "plan-terms-uuid", "start_date": "2025-01-01", "end_date": "2025-12-31" } ``` Then add discount tiers to the contract: ```bash # Add a tier: 15% discount when quantity >= 10 curl -X POST https://app.fenerum.com/api/v1/accounts/CUST001/contracts/contract-uuid-here/tiers/ \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: YourApp" \ -H "Content-Type: application/json" \ -d '{ "minimum_quantity": 10, "discount": "15.00", "discount_type": "percentage" }' ``` ### Step 3: Register Payment Method Use Stripe or QuickPay to collect payment card details, then register the token with Fenerum: **For Stripe:** ```bash curl -X POST https://app.fenerum.com/api/v1/paymentcards/ \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: YourApp" \ -H "Content-Type: application/json" \ -d '{ "account": "123e4567-e89b-12d3-a456-426614174000", "token": "pm_1234567890", "gateway": "stripe" }' ``` **For QuickPay:** ```bash curl -X POST https://app.fenerum.com/api/v1/paymentcards/ \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: YourApp" \ -H "Content-Type: application/json" \ -d '{ "account": "123e4567-e89b-12d3-a456-426614174000", "token": "12345678", "gateway": "quickpay" }' ``` See the [Accepting Payments guide](https://www.fenerum.com/en-DK/docs/api/guides/payments.md) for complete payment integration examples. ### Step 4: Create Subscription Finally, create the subscription to start billing: ```bash curl -X POST https://app.fenerum.com/api/v1/subscriptions/ \ -H "Authorization: Token your-token-here" \ -H "X-Client-System: YourApp" \ -H "X-User: admin@yourapp.com" \ -H "Content-Type: application/json" \ -d '{ "account": "CUST001", "terms": "plan-terms-uuid", "quantity": 5, "collection_method": "card", "start_date": "2025-01-01" }' ``` ```json { "uuid": "sub-uuid-here", "account": "CUST001", "terms": "plan-terms-uuid", "quantity": 5, "collection_method": "card", "status": "active", "current_period_start": "2025-01-01", "current_period_end": "2025-02-01" } ``` ### Complete Integration Example Here's the full flow in order: ```python import requests # Configuration FENERUM_TOKEN = 'your-token-here' FENERUM_BASE_URL = 'https://app.fenerum.com/api/v1' headers = { 'Authorization': f'Token {FENERUM_TOKEN}', 'X-Client-System': 'YourApp', 'X-User': 'admin@yourapp.com', 'Content-Type': 'application/json' } # Step 1: Create Account account_response = requests.post( f'{FENERUM_BASE_URL}/accounts/', headers=headers, json={ 'code': 'CUST001', 'name': 'Acme Corporation', 'email': 'billing@acme.com', 'type': 'company', 'legal_address': '123 Main Street', 'legal_zipcode': '12345', 'legal_city': 'Copenhagen', 'legal_country': 'DK' } ) account = account_response.json() account_uuid = account['uuid'] # Step 2: Add Contract with discount tiers (optional) contract_response = requests.post( f'{FENERUM_BASE_URL}/accounts/CUST001/contracts/', headers=headers, json={ 'plan_terms': 'plan-terms-uuid', 'start_date': '2025-01-01', 'end_date': '2025-12-31' } ) contract = contract_response.json() # Add a discount tier: 15% off when quantity >= 10 tier_response = requests.post( f'{FENERUM_BASE_URL}/accounts/CUST001/contracts/{contract["uuid"]}/tiers/', headers=headers, json={ 'minimum_quantity': 10, 'discount': '15.00', 'discount_type': 'percentage' } ) # Step 3: Register Payment Method # (After collecting card via Stripe/QuickPay) card_response = requests.post( f'{FENERUM_BASE_URL}/paymentcards/', headers=headers, json={ 'account': account_uuid, 'token': 'pm_1234567890', # From Stripe 'gateway': 'stripe' } ) # Step 4: Create Subscription subscription_response = requests.post( f'{FENERUM_BASE_URL}/subscriptions/', headers=headers, json={ 'account': 'CUST001', 'terms': 'plan-terms-uuid', 'quantity': 5, 'collection_method': 'card', 'start_date': '2025-01-01' } ) subscription = subscription_response.json() print(f"Created subscription: {subscription['uuid']}") ``` ### Key Benefits - **Full control** - Complete programmatic control over billing - **Branded experience** - Customers never leave your application - **Flexible workflows** - Implement any business logic you need - **Scalable** - Automate everything from onboarding to cancellation ### Next Steps - [Authentication](https://www.fenerum.com/en-DK/docs/api/guides/authentication.md) - Set up API credentials - [Accepting Payments](https://www.fenerum.com/en-DK/docs/api/guides/payments.md) - Integrate Stripe or QuickPay - [Error Handling](https://www.fenerum.com/en-DK/docs/api/guides/errors.md) - Handle API errors gracefully - [API Reference](https://www.fenerum.com/en-DK/docs/api.md) - Complete endpoint documentation --- ## Need Help Choosing? **Start small, scale up:** 1. Begin with **UI-First Integration** to learn Fenerum 1. Add **Hybrid Integration** when you need customer self-service 1. Move to **Full API Integration** as your business scales Contact our support team if you need help deciding which approach is right for you. --- ## Navigation Up: [Subscription management & financial insights on autopilot](https://www.fenerum.com/en-DK/index.md) › [Documentation](https://www.fenerum.com/en-DK/docs.md) › [API Documentation](https://www.fenerum.com/en-DK/docs/api.md) Full site index: https://www.fenerum.com/llms.txt