Plugin Actions

Defining Actions

Actions are defined in provider.actions:

{
  "provider": {
    "actions": {
      "shipping.get_rates": {
        "method": "POST",
        "path": "/actions/shipping/get-rates",
        "timeout_ms": 10000
      },
      "shipping.create_shipment": {
        "method": "POST",
        "path": "/actions/shipping/create-shipment",
        "timeout_ms": 15000
      }
    }
  }
}

Implementing Actions

Your service must implement HTTP endpoints matching the manifest paths. Every action endpoint should:

1. Verify the request signature
2. Parse the request body
3. Execute the business logic
4. Return JSON with a success boolean

How an Action is Triggered & Gated

An action fires one of two ways, set by the manifest's trigger_mode:

• manual — invoked on demand through the authenticated gateway: POST /api/plugins/{idOrSlug}/gateway/{action}.
• automatic — fired by a platform event the plugin subscribes to (subscribed_actions), fanned out to your service.

Before any action reaches your service, ThreeU checks exactly four gates (the plugin.access middleware): (1) the plugin resolves, (2) a brand context resolves, (3) the brand has the plugin installed and active, and (4) the caller's token scope and the brand's `allowed_actions` permit that action. That is the complete gate set — there is no other precondition on an action call.

Customer Validation & Prerequisites (Reality)

If your integration needs a customer to be validated/verified before an action (e.g. OTP, KYC, eligibility), know the current state so you build it correctly:

• Not a plugin-action feature. Nothing in the plugin manifest or the action gate consults customer/verification state. If your action requires it, enforce it inside your own service (return a success:false / structured error the theme can act on) — do not assume the platform blocks the call.
• The verification primitive that DOES exist is VerificationWorkflow — a prerequisites engine (prerequisites: ["otp", "documents.complete", "status.active"]) that supports subjects including customer and can link to a plugin. Today it gates merchant onboarding to a plugin (e.g. a payment gateway's KYC), not end-customer action triggers.
• Roadmap: wiring VerificationWorkflow (subject customer) into the action path so a manifest could declare a customer-validation prerequisite is a known gap, not a shipped feature. Document/relied-upon behavior should reflect that it is enforced by your service today.