External Calls

An external call is a durable request for an external system to do something: void an invoice, update a customer record, send an email. You submit it from an operation’s preparation, and it is persisted in the same transaction as your local changes, before anything is sent.

bijection/invoices.ts

import { defineOperation } from "bijection/server";
import { v } from "bijection/values";
import { invoices } from "./schema";
import { billing } from "./billing";

export const markDisputed = defineOperation({
  on: invoices,
  target: { argument: "invoice_id" },
  args: { invoice_id: v.id("billing_invoices"), reason: v.string() },
  returns: v.object({ call: v.string() }),
  prepare: async (ctx, args) => {
    await ctx.db.insert("invoice_disputes", {
      invoice_id: args.invoice_id,
      reason: args.reason,
    });
    const call = await ctx.externalCalls.submit(billing.commands.setStatus, {
      target: args.invoice_id,
      args: { status: "disputed" },
    });
    return { call };
  },
});

Here billing is an integration whose setStatus command describes how to send the request and how to tell whether it took effect. billing_invoices is the table that integration keeps in sync.

Submitting an external call

ctx.externalCalls.submit(command, options) takes a command from one of your integrations and these options:

Option	Meaning
`target`	The local ID of the synced record the command changes, or `{ sourceId }` for a command that creates a record
`args`	The command’s arguments, checked against the command’s declared validators
`approval`	Optional. The ID of an approval issued for exactly this request. See access rules

It returns the call’s ID, a string you can store and use to follow the call. Submission is part of the transaction:

The call is recorded only if the transaction commits. If preparation throws after submitting, the call disappears with the rest of the transaction.
The call can only be submitted from a mutation transaction, such as an operation’s prepare. Anywhere else it is refused with MutationRequired.
The command’s arguments are fixed when the request is accepted. Later retries send those same arguments; they are never recalculated by newer code.

Submitting records your intent. It does not update the synced table. The table changes only when the external system’s answer confirms the change and the confirmed record is published back.

The lifecycle of an external call

Persisted

The call commits with the operation, before any request is sent. From this point the engine owns delivering it, independently of the process that submitted it.

Held and sent

When the call’s turn comes, the engine holds it and sends the command’s request. A call can wait here for an earlier call it is ordered after, or for an approval.

Outcome recorded

The external system’s response is retained and interpreted under the command’s declared evidence contract. The resulting outcome is recorded in its own commit.

Published

Confirmed facts reach the synced table, where your queries see them: from the response itself when it proves the resulting record, otherwise from a later read of the source. Confirmation and publication are recorded separately.

External systems control their own transactions. No local transaction stays open while a request is in flight, and an operation that submits several calls does not make their effects atomic.

Delivery outcomes

Each external call has one of these delivery states, reported by an operation’s status:

State	Meaning
`pending`	Persisted and not yet delivered
`held`	Waiting on an earlier call it is ordered after, or on an approval
`unknown`	A request may have reached the destination, but its outcome could not be established
`delivered`	The destination’s answer settled it as applied
`refused`	The destination answered and refused it
`indeterminate`	Reconciliation could not establish what happened
`delivered_unacknowledged`	Reconciliation found it delivered, without an acknowledgement that proves it
`not_applied`	A completed search of the destination’s own records found no trace of it
`duplicated`	That search found it applied more than once. This needs an operator
`superseded`	Replaced by a later operation

A call’s status also reports its publication: null, pending, blocked, or published at a revision.

Delivery guarantees

What the engine may do after a lost response depends on the command’s declared delivery contract, which the integration states for each command:

idempotent
single_attempt

The destination deduplicates requests by the call’s identity for a stated period. Within that period, the engine can send again under the same identity, and the destination treats it as the same request. If the destination states no retention period, the engine never resends under the retained identity.

Neither contract promises that the external effect happens exactly once. The engine records what the destination’s evidence proves, and nothing more.

A successful HTTP status is not always proof. Commands declare which part of a response carries the verdict, and a response that proves only that a request was well formed does not settle the call as delivered.

Unknown outcomes and recovery

A timeout, a crashed worker, or a missing response does not prove that a call failed. The engine records such a call as unknown, and it stays unknown until it is reconciled under the command’s own contract, for example by reading the destination’s records for this call’s identity. When you meet an unknown outcome:

Do not submit a replacement. A new request is a new business change and could apply the effect twice. The original call keeps its identity.
Recover the same call. A deployment administrator can inspect and recover it from the CLI. Recovery reuses the accepted identity, interprets retained evidence or performs a bounded read, and never sends a new write.

bijection integration command-status <external-call-id>
bijection integration command-recover <external-call-id>

command-status reports the retained outcome, the stopping reason, the attempt and byte budgets, and the evidence still required. See also CLI and console.

Undoing a completed external effect is a new business change. Write a separate operation for it, such as refund for charge. Cancelling a request cannot undo an effect that already happened.

Reading a call’s status in your code

externalCallStatus is in beta.

externalCallStatus(ctx, id) returns the delivery state of a call your component submitted, as one of the states above. It is an ordinary tracked read, so a query that calls it re-runs when the call settles.

bijection/invoices.ts

import { externalCallStatus, type ExternalCallId } from "bijection/server";
import { query } from "./_generated/server";
import { v } from "bijection/values";

export const disputeStatus = query({
  args: { call: v.string() },
  handler: async (ctx, args) => {
    return await externalCallStatus(ctx, args.call as ExternalCallId);
  },
});

It answers only for calls submitted by the calling component. Any other ID, or a call another component submitted, is refused with ExternalCallNotFound. Nothing else about the call is disclosed: not its arguments, its attempts, nor the destination’s own words for a refusal.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Submitting an external call

The lifecycle of an external call

Delivery outcomes

Delivery guarantees

Unknown outcomes and recovery

Reading a call’s status in your code

​Submitting an external call

​The lifecycle of an external call

​Delivery outcomes

​Delivery guarantees

​Unknown outcomes and recovery

​Reading a call’s status in your code

Submitting an external call

The lifecycle of an external call

Delivery outcomes

Delivery guarantees

Unknown outcomes and recovery

Reading a call’s status in your code