Florist One Flowers

Overview

Search flower products by category or product code, get full pricing with delivery fees and tax, and place flower delivery orders across the US. Prices shown in search results are product prices only — a $19.99 delivery fee and applicable sales tax are added at checkout.

Actions

list_categories

Returns all available product categories grouped by type.

Required fields: none

Example:

{"action": "list_categories"}

Returns categories grouped as: Occasions (Best Sellers, Every Day, Birthday, Anniversary, Love & Romance, Get Well, New Baby, Thank You, Funeral and Sympathy), Product Types (Centerpieces, One Sided Arrangements, Vased Arrangements, Roses, Fruit Baskets, Plants, Balloons), Funeral Product Types (Funeral Best Sellers, Funeral Table Arrangements, Funeral Baskets, Funeral Sprays, Funeral Plants, Funeral Inside Casket, Funeral Wreaths, Funeral Hearts, Funeral Crosses, Funeral Casket Sprays, Funeral Urn Arrangements), Price Ranges (Under $60, $60–$80, $80–$100, Above $100, plus funeral equivalents), Seasonal Holidays (Christmas, Easter, Valentine's Day, Mother's Day), and Other (All Products).

---

search_products

Search for flower products by category name or by a specific product code. Provide exactly one of category or product_code — not both.

Required fields (one of):

• category (string) — category name or alias from list_categories (e.g., "Birthday", "roses", "funeral sprays")
• product_code (string) — specific Florist One product code (e.g., "F1-509", "E2-4305")

Optional fields:

• limit (integer, 1–50, default 12) — max results to return
• page (integer, min 1, default 1) — page number for pagination
• sort (string) — sort order: popularity (default), price_asc, price_desc, az, za

Example — search by category:

{"action": "search_products", "category": "Birthday", "limit": 6, "sort": "price_asc"}

Example — search by product code:

{"action": "search_products", "product_code": "E2-4305"}

Each product in results includes: code, name, price, dimension, description, thumbnail_url, image_url. The response also includes total_available for the total number of matching products.

---

get_order_total

Get the full price breakdown (product price, delivery fee, sales tax, order total) and resolved delivery date for a specific product and recipient ZIP code. You MUST call this before placing an order and confirm the total and delivery date with the user.

Required fields:

• product_code (string) — the product code from search results
• recipient_zipcode (string) — recipient's ZIP/postal code

Optional fields:

• delivery_date (string, MM-DD-YYYY) — desired delivery date. If omitted, the soonest available date is returned.

Example:

{"action": "get_order_total", "product_code": "E2-4305", "recipient_zipcode": "30303"}

Example with specific date:

{"action": "get_order_total", "product_code": "E2-4305", "recipient_zipcode": "30303", "delivery_date": "04-15-2026"}

Returns: product_code, product_name, product_price, delivery_fee, tax, order_total, delivery_date, recipient_zipcode. If the requested date is unavailable, the response includes delivery_date_unavailable: true and a list of available_dates — ask the user to choose one, then call get_order_total again with that date.

---

place_order

Place a flower delivery order. You MUST call get_order_total first and confirm the total and delivery date with the user before calling this action. The order will be rejected if confirmed_total is missing or does not match the current order total.

After calling place_order, a credit card request is sent to the user's mobile app. The order completes automatically once the user approves and enters their card details.

Required fields:

• product_code (string) — the product to order
• confirmed_total (number) — the order_total value returned by get_order_total, confirmed by the user
• delivery_date (string, MM-DD-YYYY) — the delivery date from get_order_total
• recipient (object) — delivery recipient with these fields:
  • name (string, required) — recipient's full name
  • phone (string, required) — 10-digit phone number
  • address1 (string, required) — street address
  • address2 (string, optional) — apt/suite/unit
  • city (string, required) — city
  • state (string, required) — 2-letter state code
  • zipcode (string, required) — ZIP/postal code
  • institution (string, optional) — hospital, funeral home, etc.
• card_message (string, required, max 200 characters) — message on the card

Optional fields:

• special_instructions (string, max 100 characters) — delivery instructions
• idempotency_key (string) — prevents duplicate orders when retrying

Example:

{
  "action": "place_order",
  "product_code": "E2-4305",
  "confirmed_total": 84.97,
  "delivery_date": "04-15-2026",
  "recipient": {
    "name": "Jane Smith",
    "phone": "4045551234",
    "address1": "200 Peachtree St NW",
    "city": "Atlanta",
    "state": "GA",
    "zipcode": "30303"
  },
  "card_message": "Happy Birthday! Thinking of you."
}

---

get_order

Look up a completed order by its confirmation number.

Required fields:

• orderno (string) — the Florist One confirmation number returned by place_order

Example:

{"action": "get_order", "orderno": "FO-123456"}

---

list_orders

List past orders with pagination.

Optional fields:

• limit (integer, 1–50, default 12) — max results to return
• offset (integer, min 0, default 0) — skip first N results

Example:

{"action": "list_orders", "limit": 10, "offset": 0}

---

Common Workflows

1. Browse and Order Flowers for a Birthday

1. list_categories — see available categories
2. search_products with category: "Birthday" — browse birthday arrangements
3. get_order_total with the chosen product_code and recipient_zipcode — get full pricing and delivery date
4. Confirm the total and delivery date with the user
5. place_order with the confirmed details — sends payment request to user's mobile app

2. Send Sympathy Flowers to a Funeral Home

1. search_products with category: "Funeral and Sympathy" — browse funeral arrangements
2. get_order_total with chosen product_code, recipient_zipcode, and optionally a specific delivery_date
3. Confirm pricing with user
4. place_order including institution in the recipient object (e.g., the funeral home name)

3. Check Order Status

1. get_order with the orderno from a previous order — view order details
2. Or list_orders to see all past orders

Important Notes

• Pricing: Search result prices are product-only. The $19.99 delivery fee and sales tax are only shown via get_order_total.
• Order flow is mandatory: Always call get_order_total before place_order. Always confirm the total and delivery date with the user. The order is rejected if confirmed_total does not match (tolerance: $0.01).
• Payment: place_order does not complete the order immediately. It sends a credit card request to the user's mobile app. The order is fulfilled automatically after the user approves.
• Same-day delivery cutoff: Same-day deliveries can only be processed if payment is approved by 12:00 PM in the recipient's time zone. If approved later, delivery is automatically moved to the next available date.
• Date format: Always use MM-DD-YYYY format for delivery_date.
• Idempotency: Use idempotency_key when retrying to prevent duplicate orders. If a matching pending or completed order exists, the existing order is returned instead of creating a new one.
• Category matching: Categories accept names, aliases, and codes (e.g., "Birthday", "bday", "bd" all work). Use list_categories if unsure.
• Card message limit: Maximum 200 characters for the card message, 100 characters for special instructions.
• Phone numbers: Must include at least 10 digits. Country codes are stripped automatically.
• US delivery only: ZIP codes must be valid US 5-digit codes (9-digit codes are truncated to 5). Canadian postal codes are also accepted.