All articles

Platform

Salesforce Composite API: fewer calls, atomic writes, and which resource to use

Row-by-row integrations burn the daily API allowance and leave half-written records behind when a call fails. The Composite API collapses related work into one call with a transaction boundary. Here's what each composite resource does, the limits that shape it, and the one that won't save you a single call.

A nightly integration loads orders into Salesforce. For each order it inserts an account, then a contact, then an opportunity, then three line items. Six records, six REST calls, and the job runs twelve thousand orders a night. Seventy-two thousand API calls for twelve thousand units of work, and when call three fails, the first two records are already committed and orphaned. Someone spends Monday reconciling the orphans.

Both problems have the same fix. The Composite API lets you send related subrequests in one HTTP call, reference the result of one inside the next, and commit or roll back the whole set together.

My rule: if your integration writes related records, it should almost never make more than one call per unit of work, and the Composite API is how you get there. One caveat up front, because it trips people: one of the composite resources saves you nothing on the call meter, and I’ll get to which.

Four resources, four jobs

“Composite API” is really a family. Picking the right member is most of the work.

  • /composite runs up to 25 subrequests in order, lets later ones reference earlier results, and commits them as one optional transaction. The whole call counts as a single API request.
  • /composite/sobjects, the sObject Collections resource, performs one operation on up to 200 records of the same type in a single call. Create 200 accounts, update 200 contacts.
  • /composite/graph, the Composite Graph API, scales the idea up: up to 500 records arranged as a dependency graph, committed per graph, in one call.
  • /composite/batch runs up to 25 independent subrequests with no shared transaction. This is the one that does not save calls.

The first three collapse many round trips into one and spend one API request. Keep that distinction in hand and the rest is detail.

The /composite resource: dependent work in one call

The plain composite resource is the workhorse for a bounded unit of dependent work. You send an array of subrequests, each with a referenceId, and a later subrequest can read an earlier one’s output with the @{referenceId.field} syntax. Set allOrNone to true and the whole thing is one transaction.

POST /services/data/v68.0/composite
{
  "allOrNone": true,
  "compositeRequest": [
    {
      "method": "POST",
      "url": "/services/data/v68.0/sobjects/Account",
      "referenceId": "acct",
      "body": { "Name": "Northwind Traders" }
    },
    {
      "method": "POST",
      "url": "/services/data/v68.0/sobjects/Contact",
      "referenceId": "contact",
      "body": { "LastName": "Fuller", "AccountId": "@{acct.id}" }
    },
    {
      "method": "POST",
      "url": "/services/data/v68.0/sobjects/Opportunity",
      "referenceId": "opp",
      "body": { "Name": "Q4 renewal", "StageName": "Prospecting",
                "CloseDate": "2026-12-31", "AccountId": "@{acct.id}" }
    }
  ]
}

Three creates, one call charged, one transaction boundary. The reference syntax is case-sensitive: @{acct.id} matches the lowercase id field in the create response, not Id. You get up to 25 subrequests, of which at most 5 can be queries or sObject Collections operations, which comfortably covers a lookup-then-write unit of work.

The part worth internalising is the meter. The entire composite request counts as a single call toward your API limits, regardless of how many subrequests it carries. That lever is the point: the seventy-two-thousand-call job above, rebuilt as one composite call per order, becomes twelve thousand calls. The daily API allowance stops being the thing that breaks the nightly run.

sObject Collections: same operation, up to 200 records

When the work is homogeneous, 200 new leads, a status update across 200 cases, reach for sObject Collections at /composite/sobjects. One call, up to 200 records of one object, with an allOrNone flag of its own. A 40,000-row upsert becomes 200 calls instead of 40,000. For any integration still writing one record per request, this is the single highest-payoff change available, and less code than the loop it replaces.

When the unit of work is a larger web of related records, the Composite Graph API is the one to know. The graph form raises the subrequest ceiling from 25 to 500 and lets you express the dependencies as a graph of nodes, where a child node references its parent. Salesforce commits each graph as an independent all-or-nothing unit.

The limits are specific and worth writing down, because they shape the payload:

  • Up to 500 nodes in a single payload, across all graphs. One graph of 500 nodes, or fifty graphs of ten, or any split that totals 500.
  • Up to 75 graphs per payload.
  • A maximum graph depth of 15.
  • Processing halts after 14 graph failures, so the rest of a large payload is not attempted.

Salesforce’s own guidance, and mine, is to keep graphs small: fifty graphs of ten nodes beats one graph of five hundred. The reason is the atomicity boundary. Each graph commits or rolls back on its own, so a single bad record fails its graph and leaves the other forty-nine committed. One giant graph means one bad record rolls back all five hundred.

Sizing graphs around the unit you want to be atomic, usually one order or one customer, is the whole design decision. The entire request still counts as a single API call.

The resource that saves you nothing: /composite/batch

/composite/batch looks like the others and behaves differently where it counts. The resource runs up to 25 independent subrequests, with no referencing between them and no shared transaction. Each subrequest executes on its own, and each one counts against your rate limits as a separate request. A separate Connect API limit also applies, capping composite batch calls at 2,000 per user per hour.

So if your goal is to cut the call count or get atomicity, /composite/batch gives you neither. Its legitimate use is narrow: a set of unrelated operations you want to send together for convenience, where you have accepted that they are metered individually and can partially fail. Reach for /composite or /composite/graph by default, and treat batch as the exception it is.

Atomicity has a cost you should design for

Bundling work into one transaction is the feature, and it has a consequence people meet in production: governor limits apply cumulatively across all subrequests in a composite call. Twenty-five subrequests share one transaction’s worth of SOQL queries, DML rows, and CPU time. A composite request that each subrequest would pass in isolation can still hit a limit when they run together, especially if the target objects carry heavy triggers or flows.

The practical effect is that the real ceiling on a composite call is often well below 25 subrequests or 500 nodes. The ceiling is whatever your automation budget allows per transaction. Test a representative payload against an org that has your triggers and flows installed, not an empty scratch org, and size the batch to what commits. If your triggers are the thing eating the budget, that is a signal worth acting on in its own right, and the trigger framework patterns are where I’d start.

When it’s the wrong tool

Composite is for synchronous, related, bounded writes. Two neighbours do other jobs better.

Above a few thousand records, stop batching composite calls and move the load to Bulk API 2.0, where the meter is records rather than calls and Salesforce chunks the data for you. Composite is the wrong shape for a million-row migration.

For reads, especially a screen that needs an object and its related records, the GraphQL API returns exactly the fields you ask for in one call and caches them in Lightning components. Composite can bundle queries, but a read-shaped request has a read-shaped tool.

The full budgeting picture, which channel spends which meter and how to find where your calls are going, is in Salesforce API limits, and the wider menu of integration options is in our integration patterns guide.

What I’d do

Audit the integration for any code that writes one record per call, and there usually is some. Move homogeneous writes to sObject Collections and dependent writes to a composite request with allOrNone. That one change typically cuts an integration’s call count by a factor of a hundred and removes the orphaned-record class of bug at the same time, because the transaction boundary does the cleanup you were doing by hand.

Then size for atomicity, not for the maximum. Pick the unit that must succeed or fail together, build one graph or one composite call around it, and test it against an org that has your automation. The limit that stops you will not be 25 or 500. That limit will be your own triggers, and better learned in a sandbox than at 2 a.m.

Understanding the basics

What is the Salesforce Composite API?

It is a family of REST resources that bundle multiple operations into one HTTP call. The /composite resource runs up to 25 dependent subrequests in one transaction, sObject Collections operate on up to 200 records of one type, and the Composite Graph API handles up to 500 related records as dependency graphs. Each of these counts as a single call against your daily API limit.

Does a composite request count as one API call?

For /composite, /composite/sobjects, and /composite/graph, yes: the entire request counts as one call toward your daily API allowance regardless of how many subrequests it contains. The exception is /composite/batch, where each subrequest is metered separately and a Connect API limit of 2,000 calls per user per hour also applies.

What’s the difference between Composite and Composite Graph?

The plain composite resource runs up to 25 subrequests in order with optional all-or-none rollback across the whole request. The Composite Graph API raises the limit to 500 records expressed as dependency graphs, where each graph commits or rolls back independently. Use composite for a small dependent unit and graph for larger related trees where you want per-graph atomicity.

How do I reference one subrequest’s result in another?

In a /composite request, give each subrequest a referenceId and refer to an earlier result with the @{referenceId.field} syntax, for example @{acct.id} to use a newly created account’s id as a lookup on a child record. The syntax is case-sensitive and matches the field names in the subrequest’s response body.


Looking at an integration that writes a record at a time and wondering what it should be? Talk to us. Rebuilding integrations so they hold up at volume is what we do.

Keep reading

All articles