Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Resources
  3. Schemas
  4. Common types

Common types

These primitive types appear throughout other schemas — Amount for any money value, Fee for a labeled merchant-imposed charge, Address for any shipping or billing address, TimeSlot for scheduled-delivery and pickup windows.

​​ Amount

Monetary value with currency information.

  • value (number, required) — Decimal value (e.g., 99.99).

  • currency (string, required) — ISO 4217 currency code, exactly three characters (e.g., “USD”).

  • number (integer) — Value in smallest currency unit (e.g., 9999 for $99.99).

  • symbol (string) — Currency symbol (e.g., “$”).


{
  "value": 99.99,
  "currency": "USD",
  "number": 9999,
  "symbol": "$"

}

​​ Fee

A merchant-imposed fee. Same fields as Amount, plus a description that labels the fee for the shopper.

  • description (string, required) — Human-readable label for the fee (e.g., “Recycle fee”).

  • value (number, required) — Decimal value (e.g., 16.00).

  • currency (string, required) — ISO 4217 currency code, exactly three characters (e.g., “USD”).

  • number (integer) — Value in smallest currency unit (e.g., 1600 for $16.00).

  • symbol (string) — Currency symbol (e.g., “$”).


{
  "description": "Recycle fee",
  "value": 16.00,
  "currency": "USD",
  "number": 1600,
  "symbol": "$"

}

​​ Address

There are two address shapes. ShippingInfo is used for the buyer’s shipping address and requires contact details; the looser AddressInfo is used for billing addresses and for store (pickup-location) addresses, where the contact fields are optional.

​​ ShippingInfo

Buyer shipping address. This is the wire shape used by Set Shipping Info and returned on the cart as shipping_info.

  • first_name (string, required) — Buyer first name.

  • last_name (string, required) — Buyer last name.

  • address1 (string, required) — Primary address line.

  • city (string, required) — City name.

  • state_or_province (string, required) — State or province.

  • postal_code (string, required) — Postal code.

  • country (string, required) — Country.

  • phone (string, required) — Contact phone number.

  • email (string, required) — Contact email.

  • address2 (string) — Secondary address line (apt, suite, etc.).

  • company (string) — Company name.

  • state_name (string) — Full state or province name, when the merchant provides it in addition to state_or_province.


{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "address1": "123 Main St",
  "address2": "Apt 4",
  "city": "San Francisco",
  "state_or_province": "CA",
  "postal_code": "94105",
  "country": "US",
  "phone": "(415) 555-0123",
  "email": "ada@example.com"

}

​​ AddressInfo (billing and location addresses)

Used for the cart’s billing_info and for store address fields on a PickupLocation. Same fields as ShippingInfo, but first_name, last_name, phone, and email are optional.

  • address1 (string, required) — Primary address line.

  • city (string, required) — City name.

  • state_or_province (string, required) — State or province.

  • postal_code (string, required) — Postal code.

  • country (string, required) — Country.

  • first_name (string) — First name.

  • last_name (string) — Last name.

  • company (string) — Company name.

  • address2 (string) — Secondary address line.

  • state_name (string) — Full state or province name.

  • phone (string) — Contact phone number.

  • email (string) — Contact email.

​​ TimeSlot

Available time window for scheduled delivery or in-store pickup.

  • start_time (Time, required) — Window start time.

  • end_time (Time, required) — Window end time.

  • slot_id (string) — Unique slot identifier.

  • description (string) — Human-readable time range.

  • price (Amount) — Additional cost for this time slot.

​​ Time object

  • utc (string, required) — UTC timestamp (ISO 8601).

  • local (string, required) — Local time representation.

  • local_timezone (string, required) — IANA timezone identifier.

  • display (string) — Display-ready time string.


{
  "slot_id": "morning_9_12",
  "start_time": {
    "utc": "2024-02-15T17:00:00Z",
    "local": "2024-02-15T09:00:00",
    "local_timezone": "America/Los_Angeles"
  },
  "end_time": {
    "utc": "2024-02-15T20:00:00Z",
    "local": "2024-02-15T12:00:00",
    "local_timezone": "America/Los_Angeles"
  },
  "description": "9:00 AM - 12:00 PM",
  "price": {
    "value": 0,
    "currency": "USD"
  }

}