Engineering Update: Billing Identity and Deployment Fixes

TL;DR

We have introduced a new Billing Identity API to allow organizations to manage legal names, addresses, and VAT IDs for compliant invoicing. Additionally, we resolved several critical bugs regarding Stripe webhook synchronization and production deployment configuration.

Engineering Log: Solving Data Consistency and Compliance

In our latest development cycle, we focused on three core areas: improving B2B compliance through structured billing identity, fixing race conditions in our webhook orchestration, and hardening our deployment infrastructure.

1. Implementing Legal Billing Identity

Previously, AlterLab lacked a formal way to capture organizational billing metadata. While Stripe handles payments, the legal information required for tax-compliant invoices (such as VAT IDs and registered addresses) needed to be managed manually by our operations team. This was a significant friction point for our international B2B customers, particularly in the EU.

We have implemented a new resource to manage this identity at the organization level. You can now programmatically manage your organization's legal details via the API.

New API Endpoints

The following endpoints are now available for managing organization-scoped billing data:

• GET /api/v1/organizations/{org_id}/billing-identity
• PUT /api/v1/organizations/{org_id}/billing-identity

This implementation mirrors the Stripe Customer object schema, ensuring that any data passed to our API is seamlessly synchronized with our Stripe integration.

import requests

ORG_ID = "org_12345"
API_URL = f"https://api.alterlab.io/api/v1/organizations/{ORG_ID}/billing-identity"

payload = {
    "legal_name": "Example SRL",
    "billing_address": {
        "line1": "123 Tech Street",
        "city": "Bucharest",
        "postal_code": "010011",
        "country": "RO"
    },
    "tax_id": "RO12345678"
}

response = requests.put(API_URL, json=payload)
print(response.json())

2. Resolving Webhook Ordering and Data Integrity

Reliable data synchronization between Stripe and our internal database is critical for maintaining accurate account states. We identified and resolved two distinct issues in our billing synchronization logic.

The Webhook Ordering Gap

We discovered a race condition (Issue #29520) where an outbound PUT /organizations/{org_id}/billing-identity request could be overwritten by a delayed customer.updated webhook.

Because our outbound write operation did not carry its own ordering signal, a delayed webhook from an unrelated, earlier edit could arrive after a successful API update, effectively reverting the user's changes. We have implemented ordering signals to ensure that the most recent state always takes precedence.

Fixing Silent Data Loss

We also identified a bug in our handle_customer_updated function. Previously, when a customer updated their billing address or tax ID via the Stripe Customer Portal, our system would only sync the default_payment_method and email, silently discarding the new address and tax information.

We have updated the logic to perform a full state synchronization. Instead of using a COALESCE approach that could miss new fields, we now explicitly set all provided fields from the Stripe event, ensuring our internal billing_customers table remains a true reflection of the Stripe source of truth.

3. Hardening Production Deployments

Our infrastructure team identified a critical issue in our deploy- workflow. When a developer dispatched a deployment using the --ref flag (e.g., workflow_dispatch --ref feature-branch), the deployment script was silently reverting the environment to the main branch.

The issue was located in our deployment runners for both cloud providers and Netcup workers. The scripts were unconditionally executing git checkout main and git reset --hard origin/main, regardless of the branch specified in the workflow dispatch. This resulted in a "successful" deployment that actually deployed the wrong configuration.

We have corrected the runner logic to respect the dispatched reference, ensuring that the intended branch's configuration (such as infra/netcup/env.production) is correctly applied.

Summary of Changes

For more information on how to integrate our updated billing features, please refer to our API reference. If you are looking to scale your data collection, check out our pricing plans to see how our pay-as-you-go model fits your needs.

Takeaway

This update ensures AlterLab is a more robust platform for enterprise and B2B users by providing formal billing identity management and resolving critical synchronization and deployment bugs.

Hit reply if you have questions.

AlterLab // Web Data, Simplified.