--- id: ACTORS-COM title: Commerce Actors product_area: commerce revision: 1 status: draft product_intent: proposed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f actors: - id: ACT-COM-001 name: Selling configuration administrator who: >- A staff administrator maintains selling configuration and authorizes campaign launch and overrides. goals: - >- Keep sale processing aligned with the customer’s billing and payment choices - Prepare appropriate catalog offerings and prices - Control campaign launch and deliberate usage restoration can_broadly: - Maintain Commerce configuration while respecting retained dependencies - Activate or resume campaigns and release usage with a reason - Configure supported recommendation and application-flow registrations represented_by: - >- commerce.ordering-profiles.*, commerce.stores.*, commerce.tax-zones.* (admin tier writes) - >- commerce.product-categories.*, commerce.product-listings.*, commerce.merchandise.* (admin tier writes) - >- commerce.pricing-audiences.*, commerce.pricing-schedules.*, commerce.product-purchasing-settings.*, commerce.product-extensions.* (admin tier writes) - 'commerce.promotions.activate, commerce.promotions.override (admin tier)' - >- commerce.recommendation-rules.*, commerce.recommendation-journeys.* (admin tier writes) surfaces: - console - api - id: ACT-COM-002 name: Campaign coordinator who: >- A staff coordinator prepares marketing offers and codes and manages stopping actions without launch authority. goals: - Prepare campaigns for authorized activation - Distribute claims with appropriate access and capacity can_broadly: - 'Draft, maintain, duplicate, pause, end and archive offers' - Maintain individual codes and request generated batches represented_by: - commerce.promotions.manage (user tier) - commerce.promotions.read surfaces: - console - id: ACT-COM-003 name: Order-taking staff who: >- A console staff member prepares quotes and sales for contacts or represented organizations. goals: - Explain likely payment before order placement - Prepare staff sales beyond the public catalog can_broadly: - 'Preview permitted buyer, audience and date context' - Use staff order authority for products excluded by public-sale guards represented_by: - commerce.price-quotes.read - commerce.orders.create surfaces: - console - id: ACT-COM-004 name: Configuration and campaign reader who: >- A read-only staff member reviews selling configuration and campaign outcomes. goals: - Inspect selling arrangements and results without changing configuration can_broadly: - 'Read permitted configuration, claims, redemptions and performance' - Assess sample promotion carts without persisting a sale represented_by: - commerce.*.read keys of the catalog resources - commerce.promotions.read - commerce.recommendation-placements.read surfaces: - console - id: ACT-COM-005 name: Authenticated purchaser who: >- A signed-in portal contact requests their applicable offering, files and contextual suggestions. goals: - Understand the amount applicable to their qualification - Retrieve digital purchases through grants - Respond to permitted contextual offers can_broadly: - Browse and quote for self or a permitted organization - Use authorized file grants within available capacity - Accept or dismiss permitted presentations represented_by: - commerce.storefront.read - commerce.price-quotes.read - commerce.downloads.read - 'commerce.offers.read, commerce.offers.respond' surfaces: - portal - id: ACT-COM-006 name: Public shopper who: >- A visitor without authentication inspects the public offering and price estimates. goals: - Discover available items and public prices before authentication can_broadly: - Browse active-store public listings and price presentations - >- Request public quotes and estimated suggestions without accepting estimates represented_by: - 'the public storefront, quote and offer routes (no permission key)' surfaces: - portal - id: ACT-COM-007 name: Product-selling application who: >- A participating application supplies product-specific selling context, promotion assessment and recommendation registrations. goals: - Use the shared pricing and benefit assessment - Identify the application’s qualifying promotion lines can_broadly: - Supply item availability and application adjustments - Assess selling-area part criteria - Declare supported placements and registered response flows represented_by: - >- the participant registry and its manifest (service-to-service, no person) surfaces: - api - job - id: ACT-COM-008 name: Order Operations Staff who: >- Staff who investigate placed-order problems and carry out authorized delivery and financial interventions. goals: - Explain outstanding order work. - Recover or close failures with an accountable result. can_broadly: - >- Inspect delivery, findings, financial adjustments and reversal enforcement. - >- Use authorized approval, holding, recovery, override, resolution and manual-completion operations. - >- Acknowledge or close findings and handle failed financial or enforcement work. represented_by: - >- commerce.obligations.read, .approve, .override, .reauthorize, .resolve, .hold, .complete-manually - commerce.exceptions.* - commerce.adjustments.* - commerce.enforcements.* - >- console orders.operations.*, orders.obligations.*, orders.adjustments.*, orders.enforcements.* surfaces: - console - api - id: ACT-COM-009 name: Commerce Administrator who: >- Customer or Rhythm implementation staff who configure delivery and warehouse behavior and administer historical loading. goals: - Maintain deliberate delivery and shipping configuration. - Reconcile imported Commerce history. can_broadly: - Configure and apply delivery policies. - >- Manage shipping coverage, charging strategies, carrier references and stock places. - 'Validate, apply and reconcile collection imports.' represented_by: - commerce.fulfillment-policies.* - >- commerce.shipping-zones.*, commerce.shipping-strategies.*, commerce.carrier-accounts.* - commerce.inventory.* (administrator tier) - the bulk key of each loaded collection surfaces: - api - id: ACT-COM-010 name: Warehouse Staff who: >- Staff who prepare and hand over goods, process physical returns and account for shelf quantities. goals: - Dispatch the units belonging to the buyer. - Retain accurate physical-stock records. can_broadly: - >- Create and progress shipment and picking work through physical departure. - 'Record authorized receipt, inspection and return disposition.' - 'Enter permitted stock movements, transfers and counts.' represented_by: - >- commerce.shipments.read, .create, .update, .handoff (.handover and .cancel are administrator tier) - commerce.pick-lists.* - commerce.return-receipts.* - 'commerce.inventory.create, .update (administrator tier today)' surfaces: - api - console - id: ACT-COM-011 name: Delivering Application who: >- A registered application service responsible for producing the result owed by a sold line. goals: - Recognize repeated delivery instructions safely. - Retain progress and final delivery outcomes. can_broadly: - Handle delivery and post-sale change instructions. - 'Report authorized completion, failure and prerequisite readiness.' represented_by: - >- commerce.obligations.callback (staff-only, held at platform scope by the application’s service identity) surfaces: - api - job - id: ACT-COM-012 name: Accounting who: >- The financial application that supplies receivable changes and executes Commerce-requested financial steps. goals: - Publish financial changes affecting order eligibility. - Preserve command identity during financial execution. can_broadly: - Send affected-line financial facts. - 'Execute invoicing, memo, credit, application and refund commands.' represented_by: - IAM invocation of commerce_financial_facts - Accounting’s service functions called by Commerce surfaces: - job - id: ACT-COM-013 name: Commerce Scheduler who: >- Background execution that dispatches delivery and data jobs and checks Commerce records for stalled or inconsistent work. goals: - Progress eligible work automatically. - Report conditions requiring staff investigation. can_broadly: - Run due dispatch and reconciliation work. - Resume work through its owning process and retain detected findings. - Expire eligible stock holds. represented_by: - system context with the sweep policies surfaces: - job - id: ACT-COM-014 name: Sales Clerk who: Staff who assemble customer purchases and coordinate their payment through the console. goals: - Prepare a correctly priced customer purchase - Complete payment or terms acceptance can_broadly: - Build carts for contacts and organizations - Place sales and record a staff purchasing-role override - 'Take card, check, cash, store-credit or terms tender' - 'Submit customer cancellations, amendments and returns' represented_by: - commerce.checkouts.create - commerce.checkouts.update - commerce.orders.create - commerce.orders.tender - commerce.orders.read - commerce.cancellations.create - commerce.amendments.create - commerce.returns.create surfaces: - console - id: ACT-COM-015 name: Commerce Reviewer who: Staff who inspect purchasing and benefit records using read permissions. goals: - Explain a customer purchase - Review sales activity and outstanding balances can_broadly: - 'Inspect carts, sales, after-sale documents and benefits' - Inspect vendor purchasing and inventory value represented_by: - commerce.checkouts.read - commerce.orders.read - commerce.cancellations.read - commerce.amendments.read - commerce.returns.read - commerce.entitlements.read - commerce.purchasing.read - commerce.inventory-costing.read surfaces: - console - api - id: ACT-COM-016 name: Commerce Manager who: >- Staff who administer order interventions, benefit grants and return policies; support attribution uses the recorded support model. goals: - Resolve purchases that cannot complete - Record justified exceptions can_broadly: - Void purchases before acceptance - 'Approve, refuse or override after-sale requests' - Apply promotions after placement - 'Grant, restore or revoke benefit rights' - Maintain return policies represented_by: - commerce.orders.void - commerce.cancellations.approve - commerce.cancellations.override - commerce.amendments.approve - commerce.amendments.override - commerce.amendments.apply-promotion - commerce.returns.approve - commerce.returns.override - commerce.return-policies.create - commerce.return-policies.delete - commerce.entitlements.restore - commerce.entitlements.grant - commerce.entitlements.revoke - Rhythm support identity (rhythm-admin) under Platform's standing Administrator grant (COMM-M2 M2-S2) surfaces: - console - id: ACT-COM-017 name: Member Buyer who: >- A proposed portal purchaser acting for themselves or an organization where they hold the purchasing role; the storefront remains deferred. goals: - Complete their purchase and payment - Use the benefits they acquire can_broadly: - Prepare and place carts for their purchasing party - 'Tender their purchases by card, store credit or terms' - Request allowed after-sale changes - Inspect and consume their own grants represented_by: - commerce.checkouts.create - commerce.checkouts.update - commerce.orders.create - commerce.orders.tender - commerce.orders.read - commerce.entitlements.read - 'portal access, own records only' surfaces: - portal - id: ACT-COM-018 name: Product-Owning Application who: >- An application participating in Commerce sales for its product types, including Membership and Commerce’s built-in participants. goals: - Use the shared purchasing contract - Fulfill the accepted purchase can_broadly: - Declare its supported product types - Evaluate and prepare items and secure limited availability - Perform delivery and product-specific reversal or amendment represented_by: - the commerce-participant-registration-invoke policy on its deploy role - commerce.obligations.callback (platform scope) surfaces: - api - job - id: ACT-COM-019 name: Stock Buyer who: 'Staff who acquire vendor stock, record incoming deliveries and maintain acquisition cost.' goals: - Acquire the stock required for sales - Explain inventory value can_broadly: - Maintain supplier and purchase-order records - Record incoming stock with landed cost - Correct cost layers and select the costing method represented_by: - commerce.purchasing.create - commerce.purchasing.update - commerce.purchasing.delete - commerce.inventory-costing.update surfaces: - api evidence: - >- services-commerce at c8b66a98: aws/commerce.service.ts (permission groups and tiers), the route declarations of the catalog, merchandise, pricing, promotions, configuration and recommendations modules - >- react-console at baf6dae3: lib/authz/permissions.ts and lib/authz/backend-aliases.ts (the console keys and their Commerce keys) --- # Commerce Actors Commerce separates configuration administration, campaign preparation, staff sales and read-only review. Buyers receive public or authenticated calculations according to their context. Participating applications provide the domain-specific answers the shared selling machinery needs. These actors describe broad working roles; each operation still evaluates its own permission and subject constraints.