commerce_product_settings_apply

Edit supported fields of an existing X00004 product in one source REVISE dispatch. Read the shop product guide for the required COMMERCE_V2 configuration, exact installed-store/channel scope, current delegate policy and recovery. These prerequisites apply to reads as well as writes.

Require channelCode, observed productId, requestId, fresh expectedRevision from commerce_product_settings_get, a nonempty strict settings object and optional dryRun (default false). Omitted fields are preserved; unknown fields fail.

Price strings have no signs, separators, exponent or rounding, at most ten whole digits and at most two fraction digits. KRW allows 100 through 9999999990 in multiples of 10; KRW decimal notation is accepted only when its value satisfies the integer/step rule. The currency comes from the selected channel, not input. The resulting sale price cannot exceed a nonzero retained/requested original price; equality is allowed. Null originalPrice removes that comparison ceiling by clearing it to zero.

Requested category/label/badge and shipping links are checked against the same store and unavailable/purged targets fail. This does not expose a catalog or shipping-policy writer. The source requires existing option-group/value identity mappings in every REVISE body; unknown option fields that cannot be preserved cause COMMERCE_PRODUCT_OPTIONS_UNSUPPORTED. Variant/option-group restructuring is not allowed; the later single buyer-input field action below has a separate contract. Images, variants, omitted add-ons, stock and other omitted product-owned fields must remain unchanged; a parent-name change may update the variant's embedded parent name. insertedAt/updatedAt fields are excluded from business-state comparison.

Dry run returns COMMERCE_OPERATION_PLAN with the source request and observed product, not a saved product. Confirmed readback returns COMMERCE_OPERATION_COMPLETE; related descriptive catalog/shipping projections are outside preservation. Use taskType commerce-product-settings with the original input. Central status is historical and resume only observes sent effects; identical apply may continue prepared work. Uncertain dispatch is never resent and no rollback is promised. Completed replay has no current verification/link. See the guide for shared error and context boundaries.

Product creation/deletion, uploads, detailed-page editing, variant/option-group changes and scheduled status changes are outside this method. Price configuration is not a charge or verified checkout.

Example

{"channelCode":"selected-channel","productId":"observed-product","requestId":"product-settings-001","expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000","settings":{"name":"Community notebook","oneLiner":"Member edition","enableReviewFeature":true,"orderQuantityLimit":2},"dryRun":true}

Replace the selectors/revision with a current settings read and inspect the plan. This example performs no live save.

One buyer input field

It configures one buyer-entered field on an existing product, separate from variants and paid add-ons. It does not edit existing order answers or purchases. That evidence remains specific to standalone fields.

The business ID follows the existing 1–160-character rule. Multiple current fields, foreign parent/store identities or unknown field metadata fail closed. The source body uses sequentialRank:1. Equal edits are no-ops. Dry run sends nothing and creates no new journal. Required option-group mappings and association arrays remain in the REVISE body. Omitted images, variants, paid add-ons, stock, prices, schedules and other product-owned fields are preserved.

Child-field creation additionally requires success:true, action:REVISE and result:ProductDto from the source response. That response must identify the new field business ID, requested title/example/rank and preserved product state. Persist the identity before independent stable readback; the later record must contain the same ID. Only its newly generated numeric row ID and ordinary timestamps are excluded from creation comparison; existing field row IDs and unrequested metadata remain strict. Missing response/durable identity stays pending; matching title is not adopted and no sent request is repeated. Earlier settings journals without this action retain their original receipt requirements.

The exact existing product detail remains the destination. Removal establishes configuration-array removal, not physical erasure, deletion of old order answers or old-ID restoration. Initial buyer options are separately covered by the later whole-product creation extension.

Illustrative create plan for an existing product whose observed field array is empty:

{"channelCode":"selected-channel","productId":"observed-product","requestId":"product-input-create-001","expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000","settings":{"inputOption":{"kind":"create","title":"Gift message","placeholder":"Enter your message"}},"dryRun":true}

Illustrative edit plan for the exact sole field returned by the product reader:

{"channelCode":"selected-channel","productId":"observed-product","requestId":"product-input-edit-001","expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000","settings":{"inputOption":{"kind":"edit","productInputOptionFieldId":"observed-input-field","title":"Gift message","placeholder":"Write a short message"}},"dryRun":true}

Illustrative explicit removal plan; replace all IDs and the settings revision:

{"channelCode":"selected-channel","productId":"observed-product","requestId":"product-input-remove-001","expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000","settings":{"inputOption":{"kind":"remove","productInputOptionFieldId":"observed-input-field","confirmation":"REMOVE_PRODUCT_INPUT_OPTION"}},"dryRun":true}

Existing paid add-on options

Read the exact existing product and settings revision first. The bounded rewrite requires one existing productAddonGroups entry with one to three ordered items, exact group/item business IDs and matching product/store/currency. the later create/addItem extension supplies those operations.

Use business IDs under the shared 1–160-character rule, not numeric row IDs, display names or guessed IDs. The existing isRequired flag is preserved and cannot be edited here. Multiple groups, unknown group/item/price metadata, foreign identities and noncanonical item order fail closed. Every retained title/name must satisfy the source text bound before rewriting.

Add-on additionalPrice has its own source rules, distinct from the product price and variant adjustment above. Supply an exact nonnegative decimal string without a sign, separators, exponent or rounding. The component permits zero through 9,999,999,990 inclusive in both KRW and USD. KRW input has no decimal part and uses steps of 100; USD permits up to two decimals in steps of 0.01. Currency comes from the verified channel. Omitted stored prices must also satisfy the known bounds; unchanged stored representations remain preserved without rounding.

The REVISE body keeps the complete known group/item form, business identities, requiredness, unselected items, required option mappings and unrelated product state. Numeric row identities remain strict in preservation. A no-op/dry run dispatches nothing. Existing add-on edits need no new identity receipt; they may compose with inputOption.create, which still requires its independently persisted response-returned field ID. The returned input identity must survive transport and durable journaling with add-on IDs, requiredness, unselected items and unrelated product fields preserved. Missing/lost/foreign or contradictory input receipts cannot become complete merely because add-on values match. A durable receipt may recover the full change after read loss without another REVISE; drift in either part remains pending. This adds shared verification evidence without changing the domain contract, and does not approve every add-on operation/combination or actual checkout, orders or restoration. Unknown/partial saves or failed completion persistence remain pending; sent effects never repeat. Old journals and the exact product-detail destination keep their existing rules.

Configuration-array removal is not physical deletion, modification of historical order selections or restoration of removed IDs. New groups/items are described in the later extension below; initial add-ons at whole-product creation use a different parent-receipt contract.

Illustrative plans only; copy group/item/product IDs and the settings revision from the exact observed product. The removal example requires another item to survive.

{
  "channelCode": "selected-channel",
  "productId": "observed-product",
  "requestId": "product-addon-example-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "addons": {
      "kind": "edit",
      "productAddonGroupId": "observed-addon-group",
      "title": "Gift options",
      "items": [
        {
          "productAddonItemId": "observed-addon-item",
          "name": "Gift wrapping",
          "additionalPrice": "100",
          "saleStatus": "ACTIVE"
        }
      ]
    }
  },
  "dryRun": true
}

{
  "channelCode": "selected-channel",
  "productId": "observed-product",
  "requestId": "product-addon-example-002",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "addons": {
      "kind": "removeItems",
      "productAddonGroupId": "observed-addon-group",
      "productAddonItemIds": [
        "observed-addon-item"
      ],
      "confirmation": "REMOVE_PRODUCT_ADDON_ITEMS"
    }
  },
  "dryRun": true
}

{
  "channelCode": "selected-channel",
  "productId": "observed-product",
  "requestId": "product-addon-example-003",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "addons": {
      "kind": "disable",
      "productAddonGroupId": "observed-addon-group",
      "confirmation": "DISABLE_PRODUCT_ADDONS"
    }
  },
  "dryRun": true
}

Create an add-on group or append one item

Read the current product/settings revision first. New options use one REVISE dispatch and its successful complete ProductDto response; they do not introduce a child-create endpoint or a new method.

A complete new item requires name, additionalPrice and saleStatus:ACTIVE or DISCONTINUED. Title/name are trimmed 1–50 UTF-16 units. Prices use the add-on rules above: zero through9,999,999,990 in either channel currency, KRW integer strings in100-unit steps and USD in0.01 steps with at most two decimals. Caller-created group/item IDs, requiredness, row IDs or ranks are rejected. Append preserves existing group requiredness, title/rank and every old item identity, price and status; unsupported metadata, invalid retained names/prices, foreign identities or three existing items stop the change.

One task stores one durable new identity. settings.inputOption.kind:create cannot be combined with addons.create or addons.addItem; use separate requests and a fresh product revision for the second request. Existing input edits/removal can compose with these new add-on operations. Input creation combined with existing add-on edit/removeItems/disable keeps its earlier receipt rules. This does not guarantee that every combination has shared-host or actual-service verification.

The response must have success:true, action:REVISE and a complete result matching the requested change and preserved product. Creating a group requires its returned business productAddonGroupId. Appending requires exactly one new productAddonItemId relative to the complete prior item set. The workflow persists that receipt before independent stable readback. An appended item must keep that exact received business ID and all old identities remain strict. A new group's children must be valid and stable within the exact returned group; their business IDs are not independently compared to every original response child ID. Newly generated numeric row IDs and ordinary timestamps have the existing creation-comparison exclusions; full stable observations still retain identities.

Lost response or failed receipt persistence never permits matching by title, adopting a later item or repeating REVISE. Missing receipts, partial saves, changed reads, foreign/duplicate identities or unrelated drift remain pending. A persisted receipt allows readback recovery without another dispatch, but failed terminal persistence cannot confirm completion. Dry run sends nothing. Completion establishes product configuration only, not checkout charges, existing-order changes, physical cleanup or exact original-ID restoration. The existing exact product detail is the destination; no child-specific console path is introduced.

Completion still requires success:true, action:REVISE, the full matching result, one durably saved group/item identity and two stable reads of the exact product. Independent inputOption.create remains rejected in the same request. Missing receipts never permit resend or adoption by matching name; saved receipts permit read-only recovery after read loss. Completed historical results have no current verification or link, and only eligible fresh results identify the exact product. Fixture cleanup compared the resulting configuration, not physical deletion or restoration of original child IDs.

Illustrative dry runs for an observed product with, respectively, no group or a matching group below the three-item limit. Replace product/group IDs and the settings revision:

{
  "channelCode": "selected-channel",
  "productId": "observed-product",
  "requestId": "product-addon-create-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "addons": {
      "kind": "create",
      "title": "Gift options",
      "items": [ { "name": "Gift wrapping", "additionalPrice": "100", "saleStatus": "ACTIVE" } ]
    }
  },
  "dryRun": true
}

{
  "channelCode": "selected-channel",
  "productId": "observed-product",
  "requestId": "product-addon-append-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "addons": {
      "kind": "addItem",
      "productAddonGroupId": "observed-addon-group",
      "item": { "name": "Greeting card", "additionalPrice": "0", "saleStatus": "ACTIVE" }
    }
  },
  "dryRun": true
}

Inputs