Updating the application in the Bitrix24 marketplace

Updating Application in Bitrix24 Marketplace

Updating a published application is not just deploying a new code version. It's a process with several dependent stages: updating code on the server, updating metadata in the partner account, passing repeat moderation, and sometimes — migrating data of all installed instances. Underestimating this process leads to situations where new functionality is ready, but reaches users a month later.

Types of Updates and Their Complexity

Not all updates are equally labor-intensive. It's important to classify immediately what exactly changes:

Patch (bugfix, minor UI fixes) — code is updated on the server, in the partner account version number is incremented, moderation passes in 3–5 days. If scopes, placement points, and monetization don't change — this is the simplest scenario.

Minor update (new features, no new scopes needed) — code + description in marketplace card + screenshots. Moderation 5–10 days. Need to update version changelog in the app card — the reviewer reads it during review.

Major update — adding new OAuth scopes, changing monetization model, new placement points. Requires full moderation cycle (7–14 days). When adding new scopes existing installations don't get them automatically — users must reinstall the application or explicitly confirm extended permissions.

Critical changes with data migration — database schema change, change in data storage format. Requires writing and testing migrations that work correctly for thousands of member_id.

Problem of Expanding OAuth Scopes

This is a technical feature important to know in advance. When you add a new scope to the app settings, existing tokens from users who installed it don't include this scope. Calling a method requiring the new scope returns {"error":"ACCESS_DENIED"}.

Solution options:

1. Forced reinstallation. When the app opens, check the list of scopes in the current token (scope field in app.info response). If needed scope is missing — show UI with explanation and "Reinstall application" button.

2. Incremental expansion. Additional OAuth flow requesting only the new scope. User clicks button in app → redirect to Bitrix24 OAuth page → confirm → new token is saved.

3. Design ahead. On initial development request all scopes that might be needed in future versions. Extra scopes — risk at moderation stage, but better to discuss their purpose in description.

Data Migrations on Update

If the application stores data in its own database and the schema changes — you need a migration strategy.

Schema that works for multi-tenant application:

1. All migrations are numbered sequentially and stored in code
2. Database has schema_migrations table with numbers of applied migrations
3. On deploy a migrator runs: applies all unapplied migrations
4. Migrations are written with backward compatibility — new nullable columns, don't delete old ones

Multi-tenant specific: if migration changes specific installation data structure (e.g., converts storage format), you need staged migration with batching — don't try to process 50,000 rows in one transaction at once.

Updating Placements and Event Handlers

When changing the list of placement points or event handler URLs (event.bind) for already installed portals, old registrations remain valid. New placements and handlers need to be registered programmatically for each active member_id.

Approach: on version update, a job runs that for each active member_id calls corresponding registration methods. This is done in a background worker with rate limiting (no more than 2 requests/sec per portal).

# Pseudocode for updating placements for all installations
for installation in get_active_installations():
    api_client = BitrixClient(installation.member_id)
    api_client.call('placement.bind', {
        'PLACEMENT': 'NEW_PLACEMENT_POINT',
        'HANDLER': 'https://app.example.com/iframe/new-feature',
        'TITLE': 'New Feature'
    })
    time.sleep(0.5)  # Rate limit

Versioning in Partner Account

In partner.bitrix24.ru when updating the application:

• Version number: semver is recommended (1.2.3), but technically it's just a string
• Description of version changes (changelog): fill obligatory — moderator reads this
• Minimum Bitrix24 version: if new feature requires API methods that appeared in specific B24 version, specify this limit

After moderation approval new version is published. Users who already have the application installed don't get update notification automatically — notification of new version appears only in Bitrix24 interface in the applications management section. Important update information should be shown directly in the app interface when opened.

Update Timeline