Docs
Back to FenerumSign In

Integration Workflows

Overview

Fenerum offers flexible integration options to match your business needs. Choose the approach that best fits your use case:

Choose Your Integration Approach:

account svg

UI-First Integration

Use Fenerum UI, export data to BI

Hybrid Integration

Self-Service + API for backend

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

  2. 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

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
    • Add/remove cards, update billing info, view invoices
    • No development needed on your side

  2. 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   │
     │                            │ ◄──────────────────── │
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"
  }'
{
  "url": "https://yourcompany.hostedsignup.com/auth/login?token=..."
}

See the Self-Service guide 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)
  • 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
  2. Contracts (optional) - Special pricing or volume discounts with tiers
  3. Payment Method - Stripe or QuickPay card registration
  4. Subscription - Active plan usage

Step 1: Create Account

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"
  }'
{
  "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:

# 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"
  }'
{
  "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:

# 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:

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:

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 for complete payment integration examples.

Step 4: Create Subscription

Finally, create the subscription to start billing:

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"
  }'
{
  "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:

<!-- focus-start -->
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()
<!-- focus-end -->

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

Need Help Choosing?

Start small, scale up:

  1. Begin with UI-First Integration to learn Fenerum
  2. Add Hybrid Integration when you need customer self-service
  3. Move to Full API Integration as your business scales

Contact our support team if you need help deciding which approach is right for you.

Next
The {resourceName} object
background logo

We invoice 2 billion DKK annually for our customers. Let's put your invoicing on autopilot today!

Book a demo