How to Update an AWS Co-Sell Referral | Suger

Updating an AWS co-sell referral in Suger used to mean resending the whole opportunity, because a PATCH replaced the stored content field-for-field. As of this week you can pass merge=true and patch only the fields you send — omitted fields keep their stored value, and nothing else on the referral moves.

---

You need to nudge one date. The AWS account team asked to push the target close date out a quarter, and that is the only thing that changed. But your integration loads the whole opportunity, re-serializes it, and PATCHes all of it back — because that is what a replace-semantics update demands. One of those trips drops a contact whose email got blanked upstream, and now the referral AWS sees is subtly wrong for a reason nobody can trace to a one-field edit.

That is the failure the merge=true contract removes. This post is the merge semantics for AWS (ACE) referrals on Suger’s API: what happens to a field you omit, a field you send, and a field you set to null — and the handful of cases where the update is refused instead.

The buyer question underneath it: I only need to change one field on an ACE referral — how, without resending the whole thing and wiping the rest?

---

How do you update one field on an AWS ACE referral?

A partial update is a PATCH to Suger’s referral endpoint with merge=true, which patches only the fields present in your request body and leaves every other stored field untouched. Send the one field you are changing; omit the rest. Nothing you leave out is cleared.

The endpoint is the same one a full update uses:

PATCH /org/{orgId}/cosell/referral/{referralId}

Without merge=true, that PATCH replaces the referral’s stored content — so every field has to be in the body, and any field you leave out is effectively erased. That is the behaviour that turns a one-field change into a full re-serialization of the opportunity, and it is why a stray upstream edit can ride along on an unrelated update.

With merge=true — passed as a query parameter or in the body — the same endpoint patches in place. It is supported for AWS only, and the body must always carry "partner": "AWS" so Suger knows which cloud’s opportunity slot (info.aceOpportunityV2) it is patching.

PATCH /org/{orgId}/cosell/referral/{referralId}?merge=true

{
  "partner": "AWS",
  "info": {
    "aceOpportunityV2": {
      "LifeCycle": { "TargetCloseDate": "2027-09-30" }
    }
  }
}

That request changes the target close date and nothing else. The company name, the contacts, the solutions, the primary needs from AWS — all of it keeps its stored value, because none of it appears in the body.

---

What does merge do with each field?

Under merge=true, an omitted field keeps its stored value, a sent field replaces it, and an explicit null clears it — with two fields that refuse to be cleared. The rule is per field, so you compose an update out of exactly the changes you mean to make.

The two exceptions are info.aceOpportunityV2.lifeCycle.reviewStatus and lifeCycle.stage. They cannot be cleared: send either as null and it keeps its stored value rather than emptying. These describe where the opportunity is in its lifecycle, and an empty review status or stage is not a state an ACE opportunity is allowed to be in — so a null there is treated as “leave it”, not “wipe it”.

Here is the full contract in one place.

You send…	…and merge does this
Nothing (field omitted from the body)	Keeps the stored value. This is the whole point — an omitted field is never mistaken for one you wanted to clear.
A value for the field	Replaces the stored value with what you sent.
An explicit null	Clears the field — except lifeCycle.reviewStatus and lifeCycle.stage, which keep their stored value.
A nested object (e.g. Customer.Account)	Merges key by key — the keys you include are updated, the keys you omit inside that object are kept.
A list (e.g. Contacts, Solutions)	Replaces the whole list. Lists are not merged element-by-element — to change one entry, send the complete list.

The object-versus-list distinction is the one that bites. Nested objects merge, so patching Customer.Account.Industry alone leaves the rest of the account intact. Lists do not merge — if you send a Contacts array with one entry to fix that contact’s title, you have just replaced every other contact on the referral. When you touch a list, send it whole.

---

What is preserved, and what is not?

A merge update preserves the referral’s top-level fields and the info.aceOpportunityV2 opportunity — the AWS opportunity content. It does not preserve other info sub-documents. So the thing you are actually editing survives a partial update untouched where you didn’t touch it; adjacent structures under info do not.

The clearest example is info.aceEngagementInvitation. An engagement invitation is not part of the opportunity body, and a merge update does not carry it forward. If your workflow has to act on an engagement invitation, that is not a merge-update operation — see the rejected cases below.

This is why merge=true is scoped to info.aceOpportunityV2 plus the top-level fields and nothing wider: it is a partial-update tool for the opportunity, not a general-purpose patch over the entire referral record.

---

When is a merge update rejected?

Suger rejects a merge=true request with 400 in three cases: a non-AWS partner, combining it with isLinkageUpdate=true, and an engagement-invitation accept or reject. For any of those, send the full referral body on the appropriate path instead — merge is not the right tool for them.

Rejected case	Why, and what to do instead
A non-AWS partner (AZURE, GCP, SUGER)	Partial merge is AWS-only. For Azure or GCP, send the complete opportunity body on a normal PATCH.
Combined with isLinkageUpdate=true	A linkage update only persists CRM-link fields and skips the partner opportunity entirely, so merging opportunity fields on the same call is contradictory. Do the CRM link/unlink on its own isLinkageUpdate call; do the field change on a separate merge call.
An engagement-invitation accept or reject	Accepting or rejecting an aceEngagementInvitation is a distinct operation, not a field patch — and that sub-document is not preserved by an update anyway. Send the full referral body for it.

Two adjacent behaviours are worth knowing so you don’t reach for merge in the wrong place. A referral in CREATE_FAILED cannot be edited by PATCH at all — AWS never accepted it, so there is nothing to patch; you resubmit it by POSTing it back to the create endpoint with the same id. And isLinkageUpdate=true is itself the right tool for a pure CRM link or unlink (attaching a referral to a Salesforce opportunity), because it saves the linkage even when the opportunity’s own state would fail validation — but it is a separate call from a merge, never the same one.

---

Does the sync to AWS happen automatically?

Yes. After a merge update, Suger starts the outbound sync to AWS automatically — you do not call a sync afterwards. The same partner-specific update validator that runs on a full update runs on a merge update, and the outbound push follows it. This matches how the initial create behaves: submission is automatic, and so is the update.

Concretely, once your PATCH …?merge=true returns, the changed opportunity is already on its way to AWS Partner Central. Calling a sync endpoint yourself would be redundant. The only path that deliberately skips the validator and the outbound sync is a linkage-only update (isLinkageUpdate=true), because that one changes CRM links, not the opportunity AWS sees.

A note for anyone wiring this into an agent: AI agents and MCP clients should always send merge=true. An agent assembling a request from a natural-language instruction like “change the close date” will send only the field it was asked about — and under replace semantics, every field it didn’t mention would be cleared. With merge=true, an omitted field is never mistaken for a deliberate clear, which is exactly the safety property an agent needs.

---

How Suger handles ACE referral updates

Suger runs one referral API across AWS, Microsoft (Azure) and Google Cloud, with the cloud chosen by the top-level partner field. Co-selling with AWS itself runs through the APN Customer Engagements program (ACE), where partners create, share and receive opportunities with AWS — and Suger’s API is how an ISV drives that program from its own systems instead of from Partner Central by hand.

The full create-and-update reference documents the whole envelope — every AWS field, the validation tiers, and the partial-update contract in this post. If you are building the inbound side of the motion rather than the outbound, the acceptance clocks and triage differ by cloud; AWS vs Microsoft inbound co-sell referral triage covers that. And if you are still upstream of the API — turning conversations into referrals worth submitting at all — start with turning AWS event conversations into ACE referrals.

Because Suger also executes the marketplace transaction that a co-sold deal closes on, the referral you update here and the private offer it becomes live in the same system.

---

Frequently asked questions

How do I update one field on an AWS ACE referral without resending everything? Send a PATCH to /org/{orgId}/cosell/referral/{referralId} with merge=true — as a query parameter or in the body — and include only the field you are changing plus “partner”: “AWS”. Every omitted field keeps its stored value.

What does an explicit null do in a merge update? An explicit null clears the field, with two exceptions: lifeCycle.reviewStatus and lifeCycle.stage cannot be cleared, so sending either as null keeps its stored value instead of emptying it.

Are lists merged or replaced on a merge update? Lists are replaced whole, not merged element-by-element. Nested objects merge key by key, but a list such as Contacts or Solutions is overwritten — so send the complete list even when you are only changing one entry.

Does merge work for Azure or GCP referrals? No. Partial merge is AWS-only, and the body must carry “partner”: “AWS”. A non-AWS partner, combining merge with isLinkageUpdate=true, or an engagement-invitation accept or reject are each rejected with 400 — send the full body instead.

Do I need to trigger the sync to AWS after updating? No. The outbound sync to AWS starts automatically after a merge update, just as it does after a full update. The only path that skips the validator and outbound sync is a linkage-only update with isLinkageUpdate=true.

---

Takeaways

• To change one field on an AWS ACE referral, PATCH with merge=true and send only that field plus "partner": "AWS". Omitted fields keep their stored value; a plain PATCH would erase them.
• A sent field replaces, an explicit null clears — except lifeCycle.reviewStatus and lifeCycle.stage, which can’t be cleared and keep their stored value on null.
• Objects merge key by key; lists are replaced whole. When you touch a Contacts or Solutions list, send it complete or you’ll drop the entries you left out.
• Merge is AWS-only and preserves info.aceOpportunityV2 plus top-level fields; a non-AWS partner, isLinkageUpdate=true, or an engagement-invitation accept/reject each return 400. The outbound sync to AWS runs automatically afterward.

---

Suger runs one co-sell referral API across AWS, Azure and Google Cloud, on the same platform that closes the marketplace deal. See how it fits your motion on the Suger co-sell page, or read the referral API reference for the full merge contract.