crm.deal.update — Update Bitrix24 Deals via REST API

What crm.deal.update does

Updates deal fields and stages. The backbone of status sync-back: payment received → stage moved; order shipped → fields updated; contract signed → deal won.

Business use cases

Payment gateway webhooks moving deals to 'Paid'
ERP/fulfillment status written back to the deal
Marking deals won/lost from external contract or billing systems
Bulk repricing or reassignment operations
Escalation systems changing responsible users

Typical fields and parameters

id — Deal ID to update
STAGE_ID — Move stages with the C{cat}:{code} format; WON/LOSE stage codes close the deal
OPPORTUNITY — Amount updates; respect IS_MANUAL_OPPORTUNITY interplay with product rows
ASSIGNED_BY_ID — Reassignment — fires notification automations if configured
UF_CRM_* — Status fields, external references, sync timestamps

Example workflow

Payment gateway sends 'payment.succeeded' to your receiver
Deal located by UF_CRM_ORDER_ID via crm.deal.list
crm.deal.update moves STAGE_ID to C2:PAID and stamps UF_CRM_PAID_AT
crm.timeline.comment.add records amount, method, and transaction ID
Stage automation sends the receipt template on WhatsApp

Example request

POST .../crm.deal.update.json

{
  "id": 3120,
  "fields": {
    "STAGE_ID": "C2:PAID",
    "UF_CRM_PAID_AT": "2026-07-07T15:12:00+04:00",
    "UF_CRM_TXN_ID": "pay_9f3k2"
  }
}

Example response

{ "result": true, "time": { ... } }

Field mapping notes

Won/lost are stages, not booleans — find the right terminal STAGE_ID per pipeline; moving to a lost stage should also require your lost-reason field
Stage regression (moving backwards) may be blocked by settings or make metrics lie — decide policy explicitly
As with leads: invalid field names fail silently with result: true

Security notes

Verify payment-webhook signatures before moving any deal to a paid stage — an unverified webhook allows forged payment confirmations
Restrict which stages the integration may set; 'anything can move anything to WON' is fraud surface

Common errors

Stage didn't change, no error — Stage ID belongs to another pipeline, or a workflow blocked the transition — check both
Deal not found by external ID — Creation race: the payment arrived before deal sync. Queue with retry-later instead of dropping
Automation double-fired — Your retry re-sent an identical update; make handlers idempotent (check current stage before moving)

Production implementation tips

Check current stage before setting it — no-op writes still fire some robots
Keep a UF sync-timestamp so two-way syncs can detect and skip echo updates (loop prevention)
For bulk updates, batch in 50s with backoff and run off-hours

Webhook or OAuth app?

Payment and ERP sync-backs are long-lived production flows — OAuth apps are usually worth it here; webhooks acceptable with strict secret management.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Essential: payment webhooks must be acknowledged instantly and processed asynchronously with retries — the gateway will not wait for Bitrix24.

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around crm.deal.update and its siblings — with authentication, field mapping, queue workers, retry logic, duplicate handling, and structured logs as standard. If this method is on your critical path, bring the requirement to a free audit call and leave with an architecture sketch.

Book Free CRM Audit or Demo API Development service

Frequently asked questions

How do I update a deal from a webhook in Bitrix24?

Receive the external event, locate the deal (external-ID custom field), and call crm.deal.update with the changed fields — from a queue, with idempotency.

How do I mark a deal as won via API?

Move STAGE_ID to the pipeline's won stage (e.g. C2:WON). Configure mandatory fields (final amount) on that transition so API closes meet the same bar as manual ones.