Skip to main content
POST
/
v1
/
billing-groups
Create a billing group
curl --request POST \
  --url https://api-eu.flexportal.io/v1/billing-groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "customerId": "cust_abc123",
  "groupName": "Acme Corp - IT Department",
  "billingDay": 15,
  "rentalIds": [
    "rental_001",
    "rental_002",
    "rental_003"
  ],
  "notes": "Net 30 payment terms agreed"
}
'
{
  "success": true,
  "message": "<string>",
  "billingGroup": {
    "billingGroupId": "<string>",
    "tenantId": "<string>",
    "customerId": "<string>",
    "groupName": "<string>",
    "billingDay": 14,
    "totalMonthlyAmount": 1,
    "currency": "<string>",
    "createdBy": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "rentalIds": [],
    "activeRentalCount": 0,
    "notes": "<string>"
  }
}

​
Overview

Create a billing group to consolidate multiple subscriptions into a single monthly invoice. This is ideal for B2B customers with multiple devices who prefer simplified billing.
Billing groups are typically used for business customers. Individual customers usually have separate billing per subscription.

​
Request Fields

FieldRequiredDescription
customerIdYesBusiness customer ID
groupNameYesDisplay name for the group
rentalIdsYesArray of subscription IDs to include
billingDayYesDay of month for billing (1-28)

​
Example Request

{
  "customerId": "cust_abc123",
  "groupName": "Acme Corp - IT Department",
  "rentalIds": [
    "sub_001",
    "sub_002",
    "sub_003"
  ],
  "billingDay": 15
}

​
What Happens

When you create a billing group:
  1. Group created with specified subscriptions
  2. Subscriptions linked to the billing group
  3. Future payments consolidated to billing day
  4. Monthly total calculated automatically

​
Billing Day Selection

Choose a billing day that works for the customer:
DayTypical Use
1Start of month billing
15Mid-month billing
25-28End of month (use 28 for all-month compatibility)
Use 28 or lower for billing day to ensure it exists in all months. Days 29-31 may cause issues in shorter months.

​
Example: Create Group for New Business Customer

async function setupBusinessBilling(customerId, groupName, subscriptionIds) {
  // Verify all subscriptions belong to this customer
  for (const subId of subscriptionIds) {
    const sub = await getSubscription(subId);
    if (sub.customerId !== customerId) {
      throw new Error(`Subscription ${subId} belongs to different customer`);
    }
  }

  // Create billing group
  return await createBillingGroup({
    customerId,
    groupName,
    rentalIds: subscriptionIds,
    billingDay: 1 // Bill on 1st of each month
  });
}

​
Error Handling

Error CodeCauseSolution
CUSTOMER_NOT_FOUNDInvalid customer IDVerify customer exists
SUBSCRIPTION_NOT_FOUNDInvalid subscription IDVerify subscription IDs
SUBSCRIPTION_DIFFERENT_CUSTOMERSubscription belongs to different customerOnly group same-customer subscriptions
INVALID_BILLING_DAYDay must be 1-28Use valid billing day

Authorizations

​
Authorization
string
header
required

API key obtained from FlexPortal dashboard

Headers

​
Tenant-ID
string
required

Your tenant identifier

Body

application/json
​
customerId
string
required
Minimum string length: 1
​
groupName
string
required
Minimum string length: 1
​
billingDay
integer
required
Required range: 1 <= x <= 28
​
rentalIds
string[]
required
Minimum array length: 1
​
notes
string

Response

Billing group created

​
success
enum<boolean>
required
Available options:
true
​
message
string
required
​
billingGroup
object
required