Charge

📖 Overview

internal/api/v1/billing/services/charge.service.js powers marketplace-style purchases that bill the connected account immediately and optionally start new subscriptions on the parent account. It supports previewing pricing, executing charges with either legacy sources or modern payment methods, provisioning add-ons, and logging OneBalance usage.

Primary Controller: charge.controller.js

🗄️ Collections & Models

• shared/models/account.js (_account) – Validates parent/sub-account eligibility and Yext status.
• shared/models/onebalance.js (onebalance) – Fetches rebill config to determine internal cost.
• shared/models/onebalance-usage_logs.js – Records cost events for both sub-account and parent.
• shared/models/queues.js (queue) – Queues post-purchase automation jobs.
• shared/models/store-price.js / store-subscription.js / store-cart.js – Resolve pricing metadata and persist cart state.
• shared/models/user.js – Locates parent owner for queue attribution.
• shared/models/stripe-key.js – Supplies connected account access tokens.

📚 Full schema references live under ../../database/collections.

🔗 External Services

• Stripe – Charges API, Payment Intents API, Subscriptions API, Invoices API.
• DashClicks Router (API_BASE_URL) – Proxy for Twilio number pricing and customer creation.
• Twilio Search Endpoint – Determines tiered pricing for phone number purchases.

🔄 Data Flow

flowchart TD
    UI[Marketplace UI] -->|POST /checkout| Controller
    Controller --> Service
    Service -->|Connected token| Stripe[Stripe API]
    Service --> Onebalance[(OneBalance)]
    Service --> StorePrice
    Service --> QueueManager
    Stripe --> WebhookService

🧠 Core Behaviours

• Calculates internal cost based on OneBalance rebill settings before charging the customer.
• Supports type=preview to upsert a single-item cart and return a formatted quote without billing.
• Distinguishes between legacy card sources and PaymentMethod IDs, calling the appropriate Stripe API.
• Automatically creates a parent-account subscription mirroring the sub-account purchase for internal accounting.
• Enqueues downstream provisioning jobs (phone number activation, listing enablement) via Queue Manager.

🧩 Functions

checkout({ account, account_id, product_type, type, external_action, card, price, uid })

Handles both preview (type="preview") and purchase paths.

Preview Path

1. Upserts a single-item cart with proration time, metadata, and external_action payload.
2. Augments price data with phone-number quantity overrides when applicable.
3. Returns formatPrice DTO for UI display.

Purchase Path

1. Validates Stripe connectivity and resolves payment source (default source fallback).
2. Computes cost using OneBalance rebill values or price unit amount.
3. Executes Payment Intent (for pm_ IDs) or Charge (for legacy sources).
4. Creates parent subscription via createMainAccountSubscription.
5. Logs OneBalance debits for sub-account and parent contexts.
6. Enqueues subaccount-charge queue item with transaction metadata.
7. Returns formatted payload for receipt display.

Guards & Edge Cases

• Blocks duplicate listing purchases when Yext already active.
• Rejects Instasite/Site add-ons (unsupported via direct checkout).
• Requires payment source or default card; surfaces 3DS requirements for Payment Intents.

phoneNumQuantity({ account_id, parent_account, uid, external_action, price_id })

• Generates a scoped JWT to query Twilio inventory via Router.
• Matches returned pricing tiers to determine per-account costs.
• Returns { mainaccount, subaccount } integer amounts for rebill calculations.

formatPrice(item, product_type)

• Normalises cart or invoice data into { buyer, item } DTO consumed by frontend.
• Handles setup fee vs recurring fee extraction and discount adjustments.
• Provides human-readable product name and interval metadata.

createMainAccountSubscription({ account, parent_account, price, charge_id, external_action, quantity })

• Uses platform API key (STRIPE_SECRET_KEY) to create a subscription on the parent account.
• Upserts store-subscription record, enriches with latest invoice, and triggers newOrder utility.
• Annotates subscription metadata with sub-account identifiers for reporting.

additionalAction({ external_action, parent_account_id, account_id, subscription_id, uid })

• Derives follow-up queue payloads (phone provisioning, listings sync).
• Sets yext_status when listings purchased.
• Queues subscription-activate job targeting Queue Manager.

🧪 Testing Notes

• Fixtures: tests/fixtures/customer.js include sample checkout payloads; extend for new product types.
• Integration tests: tests/customer.test.js covers OneBalance entries and queue side-effects.

⚠️ Operational Considerations

• Ensure APP_SECRET, API_BASE_URL, SETUP_PRODUCT, and STRIPE_SECRET_KEY environment variables are configured.
• Rate limiting: Twilio search + Stripe calls can stack; controllers throttle repeated previews.
• Phone number pricing relies on Twilio response structure (pricing.price array).

🔗 Related Docs

• Billing Module Overview
• Customer
• Payment Intent
• Payment Link
• Webhook