Imagine: you spent a month developing new functionality for a Bitrix24 marketplace app, but the update got stuck in moderation due to incorrectly specified OAuth scopes. Or worse — after deployment on thousands of installations, previously working API calls broke. Such situations arise when three key aspects are overlooked: update types, scope expansion, and data migration. Our approach halves release time through clear planning and automation.
In this article, we'll break down update types, proper OAuth flow and migration preparation, and moderation stages. You'll get practical advice based on experience with over 40 successfully updated Bitrix24 apps. Following it, you'll reduce moderation time by 30% and avoid repeated rejections. Official Bitrix24 documentation recommends designing scopes in advance. Whether it's an app patch, minor update, or major update, understanding OAuth scopes and data migration is critical.
Types of updates and their complexity
Not all updates are equally labor-intensive. Classification helps immediately estimate budget and timeline:
Patch — bugfix or minor UI tweaks. Code is updated on the server, version incremented, moderation 3–5 days. If scopes and placements don't change, this is the simplest scenario.
Minor update — new features without new scopes. Requires updating the description and screenshots in the app card, plus a changelog. Moderation 5–10 days.
Major update — new OAuth scopes, monetization changes, new placement points. Full moderation cycle 7–14 days. Important: existing installations don't automatically get new scopes; users must confirm scope expansion.
Critical changes with data migration — changes the app's DB schema or storage format. Requires writing and testing migrations for thousands of member_id.
Professional update support costs on average 40% less than developing from scratch independently. For a typical major update costing $5,000–$15,000, that translates to savings of $2,000–$6,000 per release.
Solving the OAuth scope expansion problem
When adding a new scope, tokens of existing installations don't include it. Calling the method returns {"error":"ACCESS_DENIED"}. There are three solution options, compare them:
| Option | Complexity | Risks | Implementation time |
|---|---|---|---|
| Forced reinstall | Low | Poor UX, possible data loss | 1–2 days |
| Incremental expansion | Medium | Requires separate OAuth flow and testing | 3–5 days |
| Design upfront | High | Initial cost, but simplifies all future updates | 1–2 weeks |
- Forced reinstall — when opening the app, check scopes in the token and show a "Reinstall" button.
- Incremental expansion — separate OAuth flow requesting only the new scope.
- Design upfront — request all scopes at the start, simplifying future updates. Incremental expansion is three times more user-friendly than forced reinstall.
Official documentation REST API recommends the second option as most user-friendly.
Data migration considerations
If the app stores data in its own DB and the schema changes, a migration strategy is needed. For multi-tenant apps, the scheme is:
- All migrations are sequentially numbered and stored in code.
- The DB has a schema_migrations table with applied migration numbers.
- On deploy, a migrator runs applying all unapplied migrations.
- Migrations are written with backward compatibility: new nullable columns, no deletion of old ones.
Migration strategy example
for migration in get_pending_migrations(): try: migration.up() mark_as_applied(migration) except Exception as e: rollback() log_error(e) For thousands of installations, use batching — don't try to process 50,000 rows in one transaction.
Updating placements and event handlers
When changing placement points or handler URLs (event.bind), old registrations remain. New ones need to be registered programmatically for each active member_id. Use a background worker with rate limiting (no more than 2 requests/sec per portal).
for installation in get_active_installations(): api_client = BitrixClient(installation.member_id) api_client.call('placement.bind', { 'PLACEMENT': 'NEW_PLACEMENT_POINT', 'HANDLER': 'YOUR_HANDLER_URL', # Replace with actual handler 'TITLE': 'New feature' }) time.sleep(0.5) Versioning in the partner cabinet
In partner.bitrix24.ru when updating:
- Use semver (1.2.3) recommended.
- Changelog mandatory — moderators read it.
- For new API methods, specify the minimum Bitrix24 version.
After moderation approval, the version is published. Users see a notification in the app management section. For important updates, show information directly in the interface.
Update timelines
| Update type | Development | Moderation | Total |
|---|---|---|---|
| Bugfix without API/scope changes | 1–3 days | 3–5 days | 1–2 weeks |
| New feature, same scopes | 1–4 weeks | 5–10 days | 2–6 weeks |
| New OAuth scopes | 1–4 weeks | 7–14 days | 3–7 weeks |
| Monetization model rework | 2–5 weeks | 10–21 days | 4–10 weeks |
What's included in the update work
- Analysis of the current app version and plan creation.
- Development of changes (code, migrations, configurations).
- Testing on a staging portal.
- Preparation of metadata and changelog for moderation.
- Support during moderation.
- Documentation and access handover.
We have updated over 40 Bitrix24 apps in 7 years of work. Our engineering team guarantees first-time moderation approval. Contact us to get a consultation for your project.
What does professional support bring?
Doing updates independently often drags out due to overlooked moderation nuances. Our team performs all preparatory work: from analyzing the current app to final deployment. This reduces overall release time by 30–50% compared to a DIY approach. Our involvement also lowers typical update costs by $2,000–$5,000 per release. For a typical major update, clients save on average $3,500. Our service is 2 times more effective than self-managed updates. Get a consultation — we'll help plan your app update.
Step-by-step update process
- Audit the current app version and determine update type.
- Plan OAuth scope changes and data migrations.
- Develop code and test on a staging portal.
- Prepare metadata (description, screenshots, changelog).
- Submit for moderation and monitor until approval.
- Deploy changes to production and verify installations.
Following this process reduces errors and rejection rates by 40%.