shipping:set

Create or update one shipping rate for a workspace — the only writer of a shipping amount

Effect: ask; Awaits an outcome — the call returns the response below.
Caller: member; The class of authority the caller must already hold, decided from the attested context with no round trip.
Cost: free; What one call costs, so you can budget before acting.
Reversible: yes; The effect can be undone by a later call.
Idempotent: no; Not safe to blind-retry — dedupe on the envelope idempotencyKey.

Send it with your agent

One click hands your coding agent a prompt that registers the substrate, reads this contract, and makes the call. Launch opens the app; the others copy the prompt.

Claude Code

Codex

Cursor

Gemini CLI

Claude Desktop

ChatGPT

curl -X POST https://one.ie/api/ask/shipping:set \
  -H "Authorization: Bearer $ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": { "slug": "acme", "name": "Standard", "amountCents": 599, "freeOverCents": 5000 }}'

The key is never in a link. npx -y @oneie/cli login writes it to ~/.config/oneie/key on your machine.

Request

Validated before dispatch — an invalid payload is refused with the fix, never half-applied.

slug string required The workspace that OWNS the rate. Names the target only; the attested caller must control it or the call is refused `forbidden`.
srid string optional Update this rate. Absent mints a new one.
name string optional Displayed to the buyer in Checkout (Stripe caps display_name at 100 chars). Required when minting.
amountCents number optional The shipping charge in cents. Server truth — this is the number that reaches Stripe. Required when minting.
currency string optional Three-letter ISO code, lowercased. Defaults to 'usd'.
countries string[] optional ISO-3166-1 alpha-2 codes this rate serves. EMPTY = everywhere, and one everywhere-rate unconstrains the session's allowed_countries entirely.
freeOverCents number | null optional Subtotal in cents at or above which this rate costs 0. null = never free. This is also the threshold FreeShippingProgress renders against.
sort number optional Display order. Stripe shows at most 5 options per session, so the first five by sort are what a buyer sees.
active boolean optional false archives the rate without deleting the row an old order settled against.

Response

What comes back from the call.

srid string The rate written.
rates object[] Every active rate for the workspace after the write, in sort order.
error string `forbidden` (the caller does not control the workspace), `not_found` (no such srid in this workspace), or a named validation refusal.

Traffic

Every call to shipping:set, counted where it is dispatched — over HTTP or in-process alike. Aggregate only — no actor, no payload, no workspace.

Counting…

Wiring

Every place in the open source that names shipping:set, and the file that answers it. Read from the tree at build time — a receiver is reached by NAME through one door, so there is no import edge to follow and a grep is the honest shape of the question. Structure, not volume — the count is in Traffic above.

Called from

UI 1

one.ie/web/src/components/studio/ShippingRates.tsx:7

API route 1

one.ie/web/src/lib/puck/packs/shop/shipping-returns.ts:10

→

Answered by

shipping:set one.ie/web/src/lib/resolvers/storefront/shipping.ts:155 Dispatched through POST /api/ask/shipping:set, after the envelope validates the payload.

shipping family · 1 more

shipping:list

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The workspace that OWNS the rate. Names the target only; the attested caller must control it or the call is refused `forbidden`."
    },
    "srid": {
      "description": "Update this rate. Absent mints a new one.",
      "type": "string"
    },
    "name": {
      "description": "Displayed to the buyer in Checkout (Stripe caps display_name at 100 chars). Required when minting.",
      "type": "string"
    },
    "amountCents": {
      "description": "The shipping charge in cents. Server truth — this is the number that reaches Stripe. Required when minting.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "currency": {
      "description": "Three-letter ISO code, lowercased. Defaults to 'usd'.",
      "type": "string"
    },
    "countries": {
      "description": "ISO-3166-1 alpha-2 codes this rate serves. EMPTY = everywhere, and one everywhere-rate unconstrains the session's allowed_countries entirely.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "freeOverCents": {
      "description": "Subtotal in cents at or above which this rate costs 0. null = never free. This is also the threshold FreeShippingProgress renders against.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "sort": {
      "description": "Display order. Stripe shows at most 5 options per session, so the first five by sort are what a buyer sees.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "active": {
      "description": "false archives the rate without deleting the row an old order settled against.",
      "type": "boolean"
    }
  },
  "required": [
    "slug"
  ]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "srid": {
      "description": "The rate written.",
      "type": "string"
    },
    "rates": {
      "description": "Every active rate for the workspace after the write, in sort order.",
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "error": {
      "description": "`forbidden` (the caller does not control the workspace), `not_found` (no such srid in this workspace), or a named validation refusal.",
      "type": "string"
    }
  }
}