Create a Private Offer via API

Overview

Create an Oracle Cloud Marketplace private offer programmatically with the Fours CreateOffer endpoint. Fours creates the offer in OCI, attaches the contract document, and sends it to the buyer — the same flow the console runs, driven from your own system.

The call is asynchronous. Fours validates the request, persists a DRAFT offer, returns it immediately, and then works with OCI in the background. The offer’s real status arrives through the hourly marketplace sync; poll the offer to follow it.

Prerequisites

• An Oracle Marketplace integration connected at the organization level.
• The product synced into Fours from your OCI listing — Fours resolves the listing OCID from the product’s external ID, so a product created by hand will not work. See List a Product.
• The buyer’s tenancy OCID, or an existing Fours buyer record whose partner is ORACLE.
• A contract document (EULA) reachable over https, or already uploaded to Fours.
• An access token — see OAuth App.

Endpoint

POST https://api.suger.cloud/org/{orgId}/offer

Request fields

Top level

info

info.oracleOffer

Oracle-specific fields, an OracleMarketplaceOffer object.

Contact objects take firstName, lastName, and email.

Pricing

Oracle offers are sent to OCI with a single ONE_TIME billing cycle and one total amount. Fours computes that total from info.commits:

totalAmount = round( Σ (commit.rate × commit.quantity) )

• A commit with no quantity counts as 1.
• The sum is rounded to the nearest whole unit of currency, never truncated.
• Omit info.commits entirely and the offer is created with a total of 0 — which Oracle rejects at send time, because its minimum contract value is 10,000 USD.

Example

Always include info.commits. Oracle requires a minimum contract value of 10,000 USD, so an offer whose commits sum to less than that — including an offer with no info.commits at all, which Fours sends as a $0 total — is rejected by Oracle at send time and ends up as CREATE_FAILED. Usage reported on the resulting entitlement is billed in addition to this contract value, not instead of it; see Usage Metering.

curl -L -X POST 'https://api.suger.cloud/org/YOUR_ORG_ID/offer' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "partner": "ORACLE",
    "service": "MARKETPLACE",
    "offerType": "PRIVATE",
    "productID": "KVvfb0Vhv",
    "name": "Acme Corp - Annual Contract 2026",
    "info": {
      "currency": "USD",
      "eulaUrl": "https://acme.example.com/legal/eula-2026.pdf",
      "additionalEulaUrls": [
        "https://acme.example.com/legal/annex-a-2026.pdf"
      ],
      "commits": [
        { "name": "Platform subscription", "rate": 50000, "quantity": 1 }
      ],
      "oracleOffer": {
        "description": "Annual platform subscription for Acme Corp.",
        "duration": "P1Y",
        "buyerTenancyOCID": "ocid1.tenancy.oc1..aaaaaaaaexamplebuyertenancy",
        "buyerCompanyName": "Acme Corp",
        "buyerPrimaryContact": {
          "firstName": "Ada",
          "lastName": "Lovelace",
          "email": "[email protected]"
        },
        "sellerPrimaryContact": {
          "firstName": "Grace",
          "lastName": "Hopper",
          "email": "[email protected]"
        }
      }
    }
  }'

The response is the persisted offer. Note status — it is the Fours record, not yet the OCI state:

{
  "id": "FIwCbefqu",
  "organizationID": "YOUR_ORG_ID",
  "partner": "ORACLE",
  "service": "MARKETPLACE",
  "offerType": "PRIVATE",
  "productID": "KVvfb0Vhv",
  "buyerID": "gHYis9RKU",
  "name": "Acme Corp - Annual Contract 2026",
  "status": "DRAFT",
  "info": {
    "currency": "USD",
    "visibility": "PRIVATE",
    "deliveryMethod": "PRIVATE"
  }
}

Keep the returned id. It is the Fours offer ID used for every follow-up call, and it doubles as the idempotency token for the OCI create — a retried submission will not produce a duplicate buyer-visible offer.

Track the offer

curl -L -X GET 'https://api.suger.cloud/org/YOUR_ORG_ID/offer/FIwCbefqu' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Immediately after the 200, Fours moves the offer to PENDING_CREATE while it creates the offer in OCI, attaches the contract, and sends it — about five minutes. Once OCI has the offer, info.oracleOffer.offerID holds the private-offer OCID and info.oracleOffer.offerStatus holds Oracle’s raw status. Fours maps that raw status onto its own:

When Oracle rejects the send, info.oracleOffer.lifecycleDetails carries Oracle’s reason — for example DURATION_IS_INVALID or TIME_ACCEPT_BY_IS_INVALID — and the offer’s metaInfo.errorMessages records it as … send rejected (FAILED_SEND: <reason>).

The Fours-side lifecycle, from the synchronous response through the hourly sync:

As soon as the offer is ACCEPTED, Fours derives an entitlement for the buyer — ACTIVE straight away when the offer has no timeStartDate (billing starts on acceptance); otherwise PENDING_START until the offer’s start date, ACTIVE from then on. Buyers are deduped by tenancy OCID, so repeat deals with the same customer attach to the same buyer record.

Withdraw an offer

curl -L -X POST 'https://api.suger.cloud/org/YOUR_ORG_ID/offer/FIwCbefqu/cancel' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Oracle allows withdrawing any offer the buyer has not yet accepted, so this is valid while the offer is PENDING_ACCEPTANCE or PENDING_MARKETPLACE_APPROVAL. Once accepted, it can no longer be withdrawn.

Validation errors

These are returned as 400 before anything is created in OCI, so a rejected request never leaves an orphaned draft in your marketplace account.

Two further checks need OCI context and therefore surface after the API has returned, as a CREATE_FAILED offer rather than a 400:

• The product must resolve to an Oracle listing OCID.
• A linked buyerID must belong to partner ORACLE; a buyer imported from another marketplace is refused.