Pinflower — flowers in Prague

Use this when the buyer explicitly asks to cancel an order placed here. The website's rules apply: free while the florist has not confirmed, and for a later-day order until the cut-off before its time window; a paid amount is refunded in full. Two steps: order_ref with confirm=true sends a 6-digit code to the e-mail the order was placed with; order_ref with that code then cancels. It does not modify orders.

{
  "type": "object",
  "properties": {
    "order_ref": {
      "type": "string"
    },
    "confirm": {
      "type": "boolean",
      "description": "true = the buyer confirmed they want to cancel."
    },
    "code": {
      "type": "string",
      "description": "The 6-digit code from the e-mail (second call)."
    }
  },
  "required": [
    "order_ref",
    "confirm"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "order_ref": {
      "type": "string"
    },
    "cancelled": {
      "type": "boolean"
    },
    "code_sent_to": {
      "type": "string"
    },
    "refunded_czk": {
      "type": [
        "number",
        "null"
      ]
    }
  },
  "required": [
    "order_ref",
    "cancelled"
  ]
}

Use this when the buyer asks whether Pinflower delivers to a place in Prague, how much delivery costs, how soon it can arrive, or whether flowers can come tonight — before choosing a bouquet. Takes the place as the buyer said it. Bouquet search results already include this for their place.

{
  "type": "object",
  "properties": {
    "where": {
      "type": "string",
      "description": "Where the flowers go, as the buyer said it: a Prague district ('Praha 5'), a quarter ('Vinohrady', 'Smíchov') or a street address. Omit when unknown."
    },
    "date": {
      "type": "string",
      "description": "Delivery/pickup day: 'today', 'tomorrow' or YYYY-MM-DD (Prague). Omit for as soon as possible."
    },
    "locale": {
      "type": "string",
      "enum": [
        "cs",
        "en",
        "ru",
        "uk"
      ],
      "description": "The buyer's language for names, texts and links: cs, en, ru or uk (default cs)."
    }
  },
  "required": [
    "where"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "can_deliver": {
      "type": "boolean"
    },
    "place": {
      "type": "string"
    },
    "florists": {
      "type": "integer"
    },
    "delivery_fee_from_czk": {
      "type": [
        "number",
        "null"
      ]
    },
    "earliest": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "date": {
          "type": "string"
        },
        "time": {
          "type": "string"
        },
        "day": {
          "type": "string",
          "enum": [
            "today",
            "tonight",
            "tomorrow",
            "later"
          ]
        },
        "asap": {
          "type": "boolean"
        }
      }
    },
    "night_delivery": {
      "type": "boolean"
    }
  },
  "required": [
    "can_deliver"
  ]
}

Use this when the buyer has agreed to the quoted total: it creates the order exactly like the website's checkout and returns the secure payment link on pinflower.cz. Takes the quote's details plus terms_accepted, confirmed_total_czk (the agreed total) and order_intent; if the total has changed meanwhile, nothing is created and it returns the new breakdown instead. Takes: the bouquet(s) (bouquet_id from search; several bouquets of ONE florist with quantities in items); delivery or pickup; for delivery the street address with house number in Prague; the recipient's name and phone when someone else receives the flowers; the date and a time (one of the bouquet's offered times, or 'asap'); the buyer's name, e-mail and phone (+420…); an optional card message and note for the florist; the buyer's promo code if they have one. Above 10 000 Kč the buyer's billing address is required. Also on offer: address_mode 'ask_recipient' when the florist should agree the address with the recipient by phone — a surprise (the recipient's name and phone are then required); time 'agree_with_recipient' when the florist should agree the time with the recipient by phone (the recipient's name and phone are then required); company details (IČO) for a purchase by a company. Nothing is charged here and the florist is not told until the buyer pays.

{
  "type": "object",
  "properties": {
    "address_mode": {
      "type": "string",
      "enum": [
        "known",
        "ask_recipient"
      ],
      "description": "ask_recipient = the courier/florist agrees the address with the recipient by phone (a surprise); no address needed, delivery priced at the whole-city rate."
    },
    "florist_id": {
      "type": "string",
      "description": "The florist — required when the order is a custom bouquet alone."
    },
    "company": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "ico": {
          "type": "string",
          "description": "Czech company ID (IČO, 8 digits)."
        },
        "dic": {
          "type": "string"
        },
        "address": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "ico"
      ],
      "description": "Buying for a company — the invoice is issued to it."
    },
    "bouquet_id": {
      "type": "string",
      "description": "One bouquet (shortcut for items with a single line)."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "bouquet_id": {
            "type": "string",
            "description": "A bouquet_id as search results and bouquet details show it."
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "How many of this bouquet (default 1)."
          },
          "addons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Add-on keys the bouquet offers (its details list them as addons)."
          },
          "custom_budget_czk": {
            "type": "integer",
            "minimum": 390,
            "maximum": 2400,
            "description": "A bouquet composed by the florist to a budget (390–2400 Kč) instead of bouquet_id; the wishes go in florist_note."
          }
        }
      },
      "description": "Several bouquets from the SAME florist, with quantities."
    },
    "fulfilment": {
      "type": "string",
      "enum": [
        "delivery",
        "pickup"
      ]
    },
    "address": {
      "type": "string",
      "description": "Delivery to a known address: street and house number in Prague."
    },
    "unit": {
      "type": "string",
      "maxLength": 80,
      "description": "Apartment, floor, company at the door."
    },
    "courier_note": {
      "type": "string",
      "maxLength": 200,
      "description": "Bell name, entrance, gate code."
    },
    "date": {
      "type": "string",
      "description": "'today', 'tomorrow' or YYYY-MM-DD."
    },
    "time": {
      "type": "string",
      "description": "HH:MM from the offered times, or 'asap', or 'agree_with_recipient' (the florist agrees the time with the recipient by phone; delivery only)."
    },
    "buyer": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "First name (or the full name)."
        },
        "last_name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone": {
          "type": "string",
          "description": "+420…"
        }
      },
      "required": [
        "name",
        "email",
        "phone"
      ]
    },
    "recipient": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "string",
          "description": "+420…"
        },
        "sms_opt_out": {
          "type": "boolean",
          "description": "true = no SMS to the recipient (keeps a surprise)."
        }
      },
      "required": [
        "name",
        "phone"
      ],
      "description": "Who receives the flowers, when it is someone else than the buyer — the courier calls them."
    },
    "billing_address": {
      "type": "string",
      "maxLength": 200,
      "description": "The buyer's billing address — required by Czech tax rules when the order is over 10 000 Kč (unless buying for a company)."
    },
    "card_message": {
      "type": "string",
      "maxLength": 240
    },
    "florist_note": {
      "type": "string",
      "maxLength": 500
    },
    "promo_code": {
      "type": "string",
      "maxLength": 64,
      "description": "The buyer's promo code, if they have one — works for guests and signed-in buyers alike; the checkout checks it."
    },
    "marketing_opt_in": {
      "type": "boolean",
      "description": "true = the buyer asked for news and offers."
    },
    "locale": {
      "type": "string",
      "enum": [
        "cs",
        "en",
        "ru",
        "uk"
      ]
    },
    "terms_accepted": {
      "type": "boolean",
      "description": "true = the buyer agreed to the terms."
    },
    "confirmed_total_czk": {
      "type": "integer",
      "minimum": 0,
      "description": "The quoted total_czk the buyer agreed to — a different total refuses the order."
    },
    "order_intent": {
      "type": "string",
      "description": "The quote's order_intent. The same order_intent always returns the same order (a lost answer is safe to retry); each quote issues a new one."
    }
  },
  "required": [
    "date",
    "time",
    "buyer",
    "terms_accepted",
    "confirmed_total_czk",
    "order_intent"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "order_ref": {
      "type": "string"
    },
    "order_number": {
      "type": [
        "integer",
        "null"
      ]
    },
    "total_czk": {
      "type": "number"
    },
    "pay_url": {
      "type": "string"
    }
  },
  "required": [
    "order_ref",
    "total_czk",
    "pay_url"
  ]
}

Use this when the buyer is interested in one bouquet from the search results: what is inside, its size, photos, the florist's rating, the price with delivery (exact for a street address — delivery_fee_exact says so; otherwise the shop's typical fee) and every time it can arrive on a given day. Needs a bouquet_id as search results show it. Covers one bouquet at a time.

{
  "type": "object",
  "properties": {
    "bouquet_id": {
      "type": "string"
    },
    "fulfilment": {
      "type": "string",
      "enum": [
        "delivery",
        "pickup"
      ],
      "description": "delivery (default) or pickup at the florist's shop."
    },
    "where": {
      "type": "string",
      "description": "Where the flowers go, as the buyer said it: a Prague district ('Praha 5'), a quarter ('Vinohrady', 'Smíchov') or a street address. Omit when unknown."
    },
    "date": {
      "type": "string",
      "description": "Delivery/pickup day: 'today', 'tomorrow' or YYYY-MM-DD (Prague). Omit for as soon as possible."
    },
    "locale": {
      "type": "string",
      "enum": [
        "cs",
        "en",
        "ru",
        "uk"
      ],
      "description": "The buyer's language for names, texts and links: cs, en, ru or uk (default cs)."
    }
  },
  "required": [
    "bouquet_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "bouquet_id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "slots": {
      "type": "object"
    }
  },
  "required": [
    "bouquet_id",
    "name"
  ]
}

Use this when the buyer asks what is happening with an order placed here — whether it is paid, confirmed by the florist, on the way or delivered. Needs the order_ref returned when the order was created. Read-only: it changes nothing.

{
  "type": "object",
  "properties": {
    "order_ref": {
      "type": "string"
    },
    "locale": {
      "type": "string",
      "enum": [
        "cs",
        "en",
        "ru",
        "uk"
      ],
      "description": "The buyer's language for names, texts and links: cs, en, ru or uk (default cs)."
    }
  },
  "required": [
    "order_ref"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "order_ref": {
      "type": "string"
    },
    "step": {
      "type": "string"
    },
    "paid": {
      "type": "boolean"
    }
  },
  "required": [
    "order_ref",
    "step",
    "paid"
  ]
}

Use this when the buyer has not paid yet and the order's payment link expired or got lost: it returns the order's payable link on pinflower.cz — the same one while it is still open (one order, one payable link). Needs the order_ref. Not for paid or cancelled orders.

{
  "type": "object",
  "properties": {
    "order_ref": {
      "type": "string"
    }
  },
  "required": [
    "order_ref"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "order_ref": {
      "type": "string"
    },
    "pay_url": {
      "type": "string"
    }
  },
  "required": [
    "order_ref",
    "pay_url"
  ]
}

Use this when the buyer has chosen what to order and you have the details: it prices the order exactly as the checkout will charge it — the bouquet(s), add-ons, the shop's launch discount or the buyer's promo code, the delivery fee — and checks the time, without creating anything. Takes: the bouquet(s) (bouquet_id from search; several bouquets of ONE florist with quantities in items); delivery or pickup; for delivery the street address with house number in Prague; the recipient's name and phone when someone else receives the flowers; the date and a time (one of the bouquet's offered times, or 'asap'); the buyer's name, e-mail and phone (+420…); an optional card message and note for the florist; the buyer's promo code if they have one. Above 10 000 Kč the buyer's billing address is required. Also on offer: address_mode 'ask_recipient' when the florist should agree the address with the recipient by phone — a surprise (the recipient's name and phone are then required); time 'agree_with_recipient' when the florist should agree the time with the recipient by phone (the recipient's name and phone are then required); company details (IČO) for a purchase by a company. Returns the breakdown, the total, the terms link and an order_intent; it creates nothing. The total is valid for exactly these details.

{
  "type": "object",
  "properties": {
    "address_mode": {
      "type": "string",
      "enum": [
        "known",
        "ask_recipient"
      ],
      "description": "ask_recipient = the courier/florist agrees the address with the recipient by phone (a surprise); no address needed, delivery priced at the whole-city rate."
    },
    "company": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "ico": {
          "type": "string",
          "description": "Czech company ID (IČO, 8 digits)."
        },
        "dic": {
          "type": "string"
        },
        "address": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "ico"
      ],
      "description": "Buying for a company — the invoice is issued to it."
    },
    "bouquet_id": {
      "type": "string",
      "description": "One bouquet (shortcut for items with a single line)."
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "bouquet_id": {
            "type": "string",
            "description": "A bouquet_id as search results and bouquet details show it."
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "How many of this bouquet (default 1)."
          }
        }
      },
      "description": "Several bouquets from the SAME florist, with quantities."
    },
    "fulfilment": {
      "type": "string",
      "enum": [
        "delivery",
        "pickup"
      ]
    },
    "address": {
      "type": "string",
      "description": "Delivery to a known address: street and house number in Prague."
    },
    "unit": {
      "type": "string",
      "maxLength": 80,
      "description": "Apartment, floor, company at the door."
    },
    "courier_note": {
      "type": "string",
      "maxLength": 200,
      "description": "Bell name, entrance, gate code."
    },
    "date": {
      "type": "string",
      "description": "'today', 'tomorrow' or YYYY-MM-DD."
    },
    "time": {
      "type": "string",
      "description": "HH:MM from the offered times, or 'asap', or 'agree_with_recipient' (the florist agrees the time with the recipient by phone; delivery only)."
    },
    "buyer": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "First name (or the full name)."
        },
        "last_name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone": {
          "type": "string",
          "description": "+420…"
        }
      },
      "required": [
        "name",
        "email",
        "phone"
      ]
    },
    "recipient": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "phone": {
          "type": "string",
          "description": "+420…"
        }
      },
      "required": [
        "name",
        "phone"
      ],
      "description": "Who receives the flowers, when it is someone else than the buyer — the courier calls them."
    },
    "billing_address": {
      "type": "string",
      "maxLength": 200,
      "description": "The buyer's billing address — required by Czech tax rules when the order is over 10 000 Kč (unless buying for a company)."
    },
    "card_message": {
      "type": "string",
      "maxLength": 240
    },
    "florist_note": {
      "type": "string",
      "maxLength": 500
    },
    "promo_code": {
      "type": "string",
      "maxLength": 64,
      "description": "The buyer's promo code, if they have one — works for guests and signed-in buyers alike; the checkout checks it."
    },
    "marketing_opt_in": {
      "type": "boolean",
      "description": "true = the buyer asked for news and offers."
    },
    "locale": {
      "type": "string",
      "enum": [
        "cs",
        "en",
        "ru",
        "uk"
      ]
    }
  },
  "required": [
    "date",
    "time",
    "buyer"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "goods_czk": {
      "type": "number"
    },
    "discount": {
      "type": "object"
    },
    "delivery_fee_czk": {
      "type": "number"
    },
    "total_czk": {
      "type": "number"
    },
    "terms_url": {
      "type": "string"
    },
    "next_step": {
      "type": "string"
    }
  },
  "required": [
    "goods_czk",
    "delivery_fee_czk",
    "total_czk",
    "terms_url",
    "next_step"
  ]
}

Use this when the buyer wants flowers delivered in Prague (or picked up there) and you need concrete bouquets: it returns only bouquets that can really arrive at the given place and time, with price, delivery fee, total and the earliest delivery time, in the storefront's recommended order. Takes what the buyer said: free text, occasion, budget, where, date and a deliver-by time; without date and deliver_by every result carries its earliest time. Each call displays its results to the buyer as a carousel. Not for general flower advice or for orders outside Prague.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free text in any language: flower, colour or bouquet name, e.g. 'red roses', 'tulipány', 'пионы'."
    },
    "occasion": {
      "type": "string",
      "enum": [
        "birthday",
        "name_day",
        "romance",
        "anniversary",
        "apology",
        "sympathy",
        "thank_you",
        "new_baby"
      ],
      "description": "The occasion the buyer named."
    },
    "budget_min_czk": {
      "type": "number",
      "minimum": 0
    },
    "budget_max_czk": {
      "type": "number",
      "minimum": 0,
      "description": "Bouquet price limit in CZK (delivery not included)."
    },
    "fulfilment": {
      "type": "string",
      "enum": [
        "delivery",
        "pickup"
      ],
      "description": "delivery (default) or pickup at the florist's shop."
    },
    "where": {
      "type": "string",
      "description": "Where the flowers go, as the buyer said it: a Prague district ('Praha 5'), a quarter ('Vinohrady', 'Smíchov') or a street address. Omit when unknown."
    },
    "date": {
      "type": "string",
      "description": "Delivery/pickup day: 'today', 'tomorrow' or YYYY-MM-DD (Prague). Omit for as soon as possible."
    },
    "deliver_by": {
      "type": "string",
      "description": "HH:MM (24 h): must arrive by then. Without date it means today."
    },
    "free_delivery": {
      "type": "boolean",
      "description": "Only bouquets with free delivery."
    },
    "currency": {
      "type": "string",
      "enum": [
        "czk",
        "eur",
        "usd"
      ],
      "description": "Add an approximate EUR/USD preview for a buyer abroad (default czk). The charge is always in CZK."
    },
    "sort": {
      "type": "string",
      "enum": [
        "recommended",
        "price_asc",
        "price_desc",
        "fastest"
      ],
      "description": "recommended (default, the storefront's order), cheapest, most expensive, or soonest arrival."
    },
    "ready_now": {
      "type": "boolean",
      "description": "Only bouquets already made and waiting (fastest)."
    },
    "style": {
      "type": "string",
      "enum": [
        "as_pictured",
        "florists_style"
      ],
      "description": "as_pictured = looks like the photo; florists_style = composed fresh by the florist in that spirit."
    },
    "category": {
      "type": "string",
      "description": "A category slug as results show it (e.g. roses, tulips)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8,
      "description": "How many results (default 6)."
    },
    "detail": {
      "type": "string",
      "enum": [
        "short",
        "full"
      ],
      "description": "full adds composition and a short description (default short)."
    },
    "locale": {
      "type": "string",
      "enum": [
        "cs",
        "en",
        "ru",
        "uk"
      ],
      "description": "The buyer's language for names, texts and links: cs, en, ru or uk (default cs)."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "interpreted": {
      "type": "object"
    },
    "currency": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "bouquet_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "florist": {
            "type": "string"
          },
          "price_czk": {
            "type": "number"
          },
          "delivery_fee_czk": {
            "type": [
              "number",
              "null"
            ]
          },
          "total_czk": {
            "type": "number"
          },
          "earliest": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "date": {
                "type": "string"
              },
              "time": {
                "type": "string"
              },
              "day": {
                "type": "string",
                "enum": [
                  "today",
                  "tonight",
                  "tomorrow",
                  "later"
                ]
              },
              "asap": {
                "type": "boolean"
              }
            }
          },
          "url": {
            "type": "string"
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "bouquet_id",
          "name",
          "florist",
          "price_czk",
          "total_czk",
          "url"
        ]
      }
    },
    "total_found": {
      "type": "integer"
    },
    "empty": {
      "type": "object",
      "properties": {
        "reason": {
          "type": "string"
        },
        "next_step": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "interpreted",
    "results",
    "total_found"
  ]
}

Use this when the buyer asks how ordering works: payment and when the card is charged, delivery area and fees, anonymous delivery and the card message, what happens if nobody is home, returns and complaints, or how to contact Pinflower. Answers come from the shop's own pages, with links. Does not cover bouquet availability.

{
  "type": "object",
  "properties": {
    "locale": {
      "type": "string",
      "enum": [
        "cs",
        "en",
        "ru",
        "uk"
      ],
      "description": "The buyer's language for names, texts and links: cs, en, ru or uk (default cs)."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "faq": {
      "type": "array"
    },
    "facts": {
      "type": "object"
    },
    "links": {
      "type": "object"
    }
  },
  "required": [
    "faq",
    "links"
  ]
}