revenue-cloud-txn-management-apis

Revenue Cloud Transaction Management Business APIs

Salesforce Revenue Cloud (Agentforce Revenue Management / Revenue Lifecycle Management) exposes Connect REST resources for Quote & Order Capture ("Transaction Management"). Use them to create and price quotes and orders, run asset actions, manage ramp deals, and handle promotions. This skill lists every resource and bundles a curl script that authenticates through the Salesforce CLI and calls each one.

• Base URL pattern: https://<instance>/services/data/v<version><resource>
• Auth: OAuth bearer token (Authorization: Bearer <accessToken>), obtained from an

authorized org via sf org display --json.

• Source of truth: docs/TXN Management APIs.md. For

the full resource catalog, request bodies, and response representations, read references/resources.md first; consult the source doc for complete nested schemas.

When to use which resource

• Create or update a quote/order (the default entry point): place-sales-transaction

(POST /connect/rev/sales-transaction/actions/place). It runs pricing, configuration, and tax in one call. The older place-order and place-quote are deprecated as of v63.0 - prefer this resource.

• Price a line data grid without committing a full transaction: instant-pricing

(POST .../get-instant-price) - creates or updates a context and can group lines.

• Asset actions: asset-amend, asset-cancel, asset-renew (add/reduce, cancel,

renew) and initiate-swap / initiate-upgrade / initiate-downgrade (product moves).

• Ramp deals (line ramps): ramp-deal-create / -update / -delete / -view. These

return a context id you then pass to place-sales-transaction to persist. For group ramps, use place-sales-transaction with groupRampAction instead.

• Copy or inspect a transaction: clone-sales-transaction, read-sales-transaction.
• After submission: place-supplemental-transaction (change orders during fulfillment).
• Debug an async place: sales-transaction-errors

(GET .../place/{trackerId}/errors).

• Promotions: create-promotions (GET/POST/PUT), get-eligible-promotions.

See references/resources.md for the full 20-resource catalog with methods, versions, path/query parameters, payloads, and response bodies.

API version rule

Always call with the latest API version the org supports, and never below v67.0. The bundled script auto-discovers the newest version from GET /services/data/ and uses max(latestOrgVersion, 67.0), then bumps to a resource's own minimum where higher. Any explicit --api-version below 67.0 is rejected.

Gotchas

• Most POST bodies are an object graph: graph.records[], each with

attributes.type (sObject), attributes.method (POST/PATCH/DELETE), and field values. Reference an as-yet-uncreated record's id with @{referenceId.id} and a group with {@GroupId}. PATCH/DELETE records need attributes.id. This is the most common source of "record not found"/reconciliation errors.

• Place Sales Transaction runs asynchronously. A 2xx from the place call only means it

was accepted. Take the returned tracker id and call sales-transaction-errors with --param trackerId=... (add --query 'includeRetryablePayload=true') to see blocking errors and the retryable payload. It does not return non-blocking config/tax warnings.

• place-sales-transaction needs either graph or contextDetails, not neither.

It does not create amendment/renewal/cancellation records - use the asset actions. The quote header commits first, so a later component failure won't roll it back.

• Ramp-deal create/update/delete only stage changes and return a context id; nothing

persists until you call place-sales-transaction with that context id.

• Asset actions need permission sets: InitiateAmend, InitiateCancellation,

InitiateRenewal. For usage products, amend with outputRecordType: "Quote" and a two-step quote-then-order flow; direct-to-Order is unsupported and can fail activation.

• swap / upgrade / downgrade share the same swapGroups body shape (an outGroup

of assets swapped out and an inGroup object graph swapped in).

• clone-sales-transaction takes a single record id in recordIds plus the parent

salesTransactionId.

• These resources mix GET/POST/PUT and several use path parameters ({resourceId},

{trackerId}), so call one resource at a time with --resource (and --param/--query /--method), not a bulk "call everything" run.

• Sample ids in payloads/*.json are placeholders - replace them with real org ids

before calling a live org.

Authentication

Authorize an org once with the Salesforce CLI, then reuse it:

sf org login web --alias myorg
sf org display --json --target-org myorg

sf org display --json returns result.instanceUrl and result.accessToken, which the script uses to build the URL and bearer header.

Quick start

Prerequisites: Salesforce CLI (sf) with an authorized org, curl, jq, and a Bash shell (Git Bash or WSL on Windows). --list and --dry-run work offline.

# List every resource with its methods, min version, and path (no org needed)
bash scripts/call-txn-management-apis.sh --list

# Preview the resolved URL and curl command without calling the org
bash scripts/call-txn-management-apis.sh --resource place-sales-transaction --dry-run

# Create a quote/order (edit payloads/place-sales-transaction.json with real ids first)
bash scripts/call-txn-management-apis.sh --resource place-sales-transaction --target-org myorg

# Debug an async place by its tracker id
bash scripts/call-txn-management-apis.sh --resource sales-transaction-errors \
  --param trackerId=16PRM0000004DBq --query 'includeRetryablePayload=true' --target-org myorg

# Path + query resource (view a ramp deal)
bash scripts/call-txn-management-apis.sh --resource ramp-deal-view \
  --param resourceId=0QLxx0000004CSOGA2 \
  --query 'transactionId=0Q0xx0000004CDxCAM&transactionLineId=0QLxx0000004CSOGA2' --target-org myorg

# Multi-method resource
bash scripts/call-txn-management-apis.sh --resource create-promotions --method GET --target-org myorg

Run bash scripts/call-txn-management-apis.sh --help for all flags and exit codes.

Workflow for calling a live org

1. Pick the resource for the goal (see "When to use which resource").
2. For POST/PUT resources, edit the matching payloads/*.json with real ids and build the

object graph (correct type/method, @{...} references, group actions).

1. For path/query resources, gather the ids and pass --param key=value / --query.
2. --dry-run first to confirm the URL, effective version (>= v67.0), method, and payload.
3. Run without --dry-run. Inspect the JSON result line on stdout.
4. For place-sales-transaction, don't stop at the 2xx: capture the tracker id and call

sales-transaction-errors to confirm the records actually persisted (it is async). On any failure, read the response body and cross-check against references/resources.md and the source doc.

Available scripts

• `scripts/call-txn-management-apis.sh` - Auth via sf, auto-select latest API version

(floored at v67.0, bumped per resource), and call one resource by name. Supports --list, --dry-run, --resource, --method, --param, --query, --payload, --target-org, --api-version, --payload-dir, --output. Emits one JSON result line to stdout.

Related skills

• revenue-cloud-pricing-apis - the Pricing Business APIs (/connect/core-pricing).
• revenue-cloud-config-apis - the Product Configurator Business APIs.
• salesforce-revenue-cloud-pricing - design/build/debug pricing procedures and recipes.
• revenue-cloud-pricing-diagnostics - trace how a specific pricing field is calculated.