Overview
Arlo Health supports two billing modes: pay-per-use and subscription. Understanding these modes is essential for handling the payment gate during consultations.
Billing Modes
| Mode | Price | Description |
|---|
| Pay per use | $30/consultation | Pay only when you need care |
| Subscription | $100/year | Unlimited consultations |
Checking Billing Status
Use get_subscription_status to check the user’s current billing configuration:
{
"billingMode": "PAY_AS_YOU_GO",
"paymentStatus": "ACTIVE",
"paymentOptions": [
{
"id": "payment_option_id_1",
"title": "Annual Subscription",
"price": "$100/year",
"priceAmountCents": 9999,
"billingMode": "SUBSCRIPTION",
"interval": "year"
},
{
"id": "payment_option_id_2",
"title": "Pay Per Use",
"price": "$30/consultation",
"priceAmountCents": 3000,
"billingMode": "PAY_AS_YOU_GO"
}
]
}
Billing Mode Values
| Mode | Description |
|---|
NONE | No payment method configured |
PAY_AS_YOU_GO | Pay $30 per consultation |
SUBSCRIPTION | Active subscription |
LEGACY | Grandfathered billing plan from earlier pricing. Treat as SUBSCRIPTION — user has access to consultations without additional payment setup. |
Payment Status Values
| Status | Description |
|---|
PENDING | Payment setup in progress |
ACTIVE | Payment method active and valid |
FAILED | Payment failed (card declined, etc.) |
CANCELLED | Subscription cancelled |
ACTIVE_UNTIL_EXPIRY | Cancelled but active until period ends |
Payment Gate
When a consultation reaches PAYMENT_REQUIRED status, the paymentGate object indicates what action is needed:
{
"status": "PAYMENT_REQUIRED",
"paymentGate": {
"consultationSummary": "Based on your symptoms, Arlo can help with...",
"paymentType": "pay_per_use",
"ctaText": "Connect with Provider - $30",
"gateType": "PAY_PER_USE"
}
}
Payment Types
| Type | Required Action |
|---|
pay_per_use | Confirm connection to provider |
subscription_required | Set up payment (subscription or pay per use) |
Pay-Per-Use Flow
Consultation reaches PAYMENT_REQUIRED
Triage is complete and the user is ready to connect with a provider
Present summary to user
Show the consultationSummary from the payment gate
User confirms
User agrees to proceed with the $30 consultation fee
Call confirm_provider_connection
This places a $30 hold on the user’s card
User enters MATCHING queue
Status changes to MATCHING while finding a provider
If the payment hold fails, prompt the user to update their payment method via create_payment_setup, then retry.
Example
const status = await getConsultationStatus({ conversationId });
if (status.status === "PAYMENT_REQUIRED") {
const { paymentGate } = status;
if (paymentGate.paymentType === "pay_per_use") {
// Present summary to user
await showUser(paymentGate.consultationSummary);
// Get user confirmation
const confirmed = await askUser("Proceed for $30?");
if (confirmed) {
await confirmProviderConnection({ conversationId });
}
}
}
Subscription Flow
Check paymentType
Verify paymentType is subscription_required
Get subscription options
Call get_subscription_status to retrieve available plans
Create payment setup
Call create_payment_setup with the user’s chosen plan
User completes Stripe checkout
Direct user to the returned paymentUrl to enter payment details
Activate subscription
Call subscribe to activate the subscription
Proceed with consultation
Consultation will automatically begin matching to provider
Example
if (paymentGate.paymentType === "subscription_required") {
// Get subscription options
const { paymentOptions } = await getSubscriptionStatus();
// Let user choose a plan
const chosenPlan = await askUser("Choose a plan:", paymentOptions);
// Get Stripe checkout URL
const { paymentUrl } = await createPaymentSetup({
paymentOptionId: chosenPlan.id
});
// Direct user to complete checkout
await showUser(`Complete payment: ${paymentUrl}`);
// Wait for completion (webhook or polling)
await waitForPaymentComplete();
// Activate subscription
await subscribe();
}
Stripe Integration
Arlo uses Stripe for payment processing. All payment setup happens through Stripe’s hosted checkout.
Checkout Flow
- Call
create_payment_setup to get checkout URL
- User opens URL in browser
- Stripe handles card entry securely
- User completes checkout
- Stripe notifies Arlo
- Payment is automatically activated
Security
- Card details never pass through Arlo or your agent
- All payment data handled by Stripe
- PCI compliance maintained by Stripe
Canceling Subscriptions
Use cancel_subscription to cancel an active subscription:
const result = await cancelSubscription();
// { billingMode: "SUBSCRIPTION", paymentStatus: "ACTIVE_UNTIL_EXPIRY" }
Cancellation cannot be undone via the API. The user would need to resubscribe.
What Happens
- Subscription cancels at end of current billing period
- User retains access until period ends
- Status changes to
ACTIVE_UNTIL_EXPIRY
- After period ends, status becomes
CANCELLED
Payment Errors
Common Errors
| Error | Cause | Resolution |
|---|
payment_hold_failed | Card declined | User updates payment method |
insufficient_funds | Not enough balance | User uses different card |
card_expired | Card has expired | User updates payment method |
subscription_required | No valid subscription | Set up subscription |
Handling Payment Failures
try {
await confirmProviderConnection({ conversationId });
} catch (error) {
if (error.code === "payment_hold_failed") {
// Direct user to update payment method
const { paymentUrl } = await createPaymentSetup();
await showUser(`Update payment method: ${paymentUrl}`);
}
}
