Billing Flows

Billing Flows are logical billing streams that group charges together. Examples include "Image API Usage", "Premium Feature X", or "Data Processing". Flows control whether charges are active or paused.

Step 1 – Get an API Key

Go to the dashboard and open Developers / Settings → API keys (where you already manage keys). Create a server-side key if you don't have one. Store this key securely as MESHPAY_API_KEY in your backend.

You will use this key in the Authorization header:

Authorization: Bearer <MESHPAY_API_KEY>

Step 2 – Create a Billing Flow

You can create flows via dashboard or API.

Option A – Dashboard

1. Go to API Billing → Flows
2. Click New Flow
3. Fill in:
   • Name – e.g. "Image API Usage"
   • Description – optional
   • Accounting Currency – optional (for reporting only; charges can use any currency)
4. Click Save

You'll be redirected to the Flow detail page (Configuration / API Access / Test Requests).

Option B – API

Request Body

Code Examples

import requests
import os

url = "https://api.orvion.sh/v1/billing/flows"
headers = {
  "Authorization": f"Bearer {os.environ['MESHPAY_API_KEY']}",
  "Content-Type": "application/json"
}

data = {
  "name": "Image API Usage",
  "description": "Charges per processed image.",
  "accounting_currency": "EUR"  # Optional - for reporting only
}

response = requests.post(url, json=data, headers=headers)
flow = response.json()
print(f"Flow created: {flow['id']}")

Response

Returns the created flow object:

{
  "id": "flow_123",
  "name": "Image API Usage",
  "description": "Charges per processed image.",
  "accounting_currency": "EUR",
  "status": "active",
  "created_at": "2025-11-27T12:00:00Z"
}

Save the id (e.g. flow_123) – you'll use it as flow_id in charge calls.

Flow Properties

Status

Flows can be in one of two states:

• active (default) - Charges can be created for this flow
• paused - Charges are blocked (returns 403 when attempting to create charges)

Fields

• id - Unique identifier for the flow (e.g., flow_123)
• name - Display name for the flow
• description - Optional description
• accounting_currency - Optional currency code for reporting/analytics (does NOT constrain charge currencies)
• status - Current status (active or paused)
• organization_id - Organization that owns this flow
• created_at - Timestamp when the flow was created

Error Scenarios

400 Bad Request

• Missing required field (name)
• Invalid JSON in request body

401 Unauthorized

• Missing or invalid API key
• API key does not have permission to create flows

422 Unprocessable Entity

• Invalid accounting_currency format
• Validation errors

Next Steps

• Create your first charge using the flow ID
• View transactions for this flow
• Test charges from the dashboard

Related Documentation

• API Billing Overview - Core concepts
• Charges API - Creating charges for a flow
• Transactions - Viewing flow transactions