Quickstart

Get started with the Fenerum API in minutes. This guide walks you through the basics of authentication and creating your first resources.

Core Concepts

Before diving into the API, understand these fundamental objects:

Account

An Account represents your customer—the entity you bill for your services. Each account can have multiple subscriptions, invoices, and payment methods.

Key attributes:

• code - Your unique identifier for the customer (e.g., CUST001)
• name - Customer or company name
• email - Billing contact email
• type - Either company or person

Example:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "code": "CUST001",
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "type": "company"
}

Plan

A Plan is a product or service that your organization offers. Think of it as a template for what you're selling.

Examples:

• "Professional Plan"
• "Enterprise License"
• "Cloud Storage"

A plan itself doesn't have pricing—that's where PlanTerms come in.

PlanTerms

PlanTerms define the concrete pricing and billing conditions for a Plan. A single plan can have multiple terms (e.g., monthly vs. yearly pricing).

Key attributes:

• price - The amount to charge
• currency - Currency code (USD, EUR, DKK, etc.)
• interval_type - Billing period: day, month, or year
• interval_count - Number of intervals (e.g., 1 for monthly, 12 for yearly)
• backwards_charging - When false, charge at period start (most common). When true, charge at period end.

Example:

{
  "uuid": "plan-terms-uuid",
  "price": "99.00",
  "currency": "USD",
  "interval_type": "month",
  "interval_count": 1,
  "backwards_charging": false,
  "active": true
}

Subscription

A Subscription represents an Account's active usage of a Plan. This is where the customer and the plan come together.

Key attributes:

• account - Which customer is subscribed
• terms - Which PlanTerms they're using
• quantity - How many units (for per-seat pricing)
• collection_method - How to collect payment: invoice, card, or direct_debit
• status - Current state: active, cancelled, paused, etc.

Example:

{
  "uuid": "sub-uuid",
  "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"
}

Setup

Get Your API Token

1. Go to Settings → Integrations
2. Click Create API user in the Fenerum section
3. Copy your token and store it securely

Keep your token secret! Never commit it to version control or expose it in client-side code.

Quick Example

Here's how to create a customer and start billing them:

1. Create an Account

curl -X POST https://app.fenerum.com/api/v1/accounts/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "X-Client-System: MyApp" \
  -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"
}

2. Create a Subscription

curl -X POST https://app.fenerum.com/api/v1/subscriptions/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "X-Client-System: MyApp" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "CUST001",
    "terms": "YOUR_PLAN_TERMS_UUID",
    "quantity": 5,
    "collection_method": "invoice",
    "start_date": "2025-01-01"
  }'

{
  "uuid": "sub-uuid",
  "account": "CUST001",
  "terms": "YOUR_PLAN_TERMS_UUID",
  "quantity": 5,
  "collection_method": "invoice",
  "status": "active",
  "current_period_start": "2025-01-01",
  "current_period_end": "2025-02-01"
}

Next Steps

Now that you understand the basics, explore these guides:

• Integration Workflows - Choose the right integration approach for your business
• Authentication - Learn about required headers and security best practices
• Accepting Payments - Integrate Stripe or QuickPay for payment collection
• API Reference - Complete endpoint documentation

Common Questions

How do I find my Plan UUID?

Use the Plans endpoint:

curl https://app.fenerum.com/api/v1/plans/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "X-Client-System: MyApp"

The response includes all plans and their associated PlanTerms with UUIDs.

What's the difference between code and uuid?

• code - Your custom identifier for the resource (you choose it)
• uuid - Fenerum's unique identifier (system-generated)

You can use either in API requests, but code is often more convenient since you control it.

Need help?

Contact our support team or check out the complete API documentation.