fulfillment_order
Place a manufacturing order from an existing quote and charge the orchestration fee before ordering, with an automatic refund if order placement fails.
Instructions
Place a manufacturing order based on a previous quote.
Charges the orchestration fee BEFORE placing the order to prevent
unpaid orders. If order placement fails after payment, the
charge is automatically refunded. On an install that orders
through Kiln's servers, the servers charge the fee when they
place the order and the reply says what they charged.
Args:
quote_id: Quote ID from ``fulfillment_quote``.
quote_token: The ``quote_token`` a quote through Kiln's
servers returned. Optional: Kiln keeps it beside the
quote, so ``quote_id`` alone works; when passed it must
be that token. An order is placed only from a quote
taken on this computer.
shipping_option_id: Shipping option ID from the quote's
``shipping_options`` list.
shipping_address: Optional shipping contact/address dict for
provider checkout. Keys: ``first_name``, ``last_name``,
``email``, ``phone``, ``street``, ``city``,
``postal_code``, ``country``; include ``state`` for US.
shipping_profile_name: Saved shipping profile name to use
instead of passing ``shipping_address``.
preview_token: Token from ``issue_preview_token`` after the
rendered model preview was shown to and approved by the user.
preview_file_path: Exact model file path that was previewed.
The preview token is validated against this file's bytes.
shipping_confirmation_token: Token from
``issue_shipping_confirmation_token`` after the contact and
shipping address were shown to and approved by the user.
payment_hold_id: PaymentIntent ID from the quote's
``payment_hold`` field. If provided, the previously
authorized hold is captured before placing the order.
This is the preferred payment flow.
quoted_price: Total price returned by ``fulfillment_quote``
(used to calculate the fee when no ``payment_hold_id``
is provided). Required when ``payment_hold_id`` is
empty and a payment rail is configured.
quoted_currency: Currency of ``quoted_price`` (default USD).
jurisdiction: Buyer's region (e.g. ``"US-CA"``, ``"DE"``, ``"AU"``).
When provided, the response includes an accurate total with
tax so the user sees exactly what they'll pay — no hidden
fees. Use ``tax_jurisdictions`` to see all supported codes.
On an install that orders through Kiln's servers, pass it
to ``fulfillment_quote`` instead: the servers pin it to the
quote and the order is taxed as the quote said.
business_tax_id: If the buyer is a registered business, their
tax ID (EU VAT number, AU ABN, etc.). Businesses in the
EU, UK, Australia, and Japan are tax-exempt via reverse
charge — the tax line shows $0.00.
Use ``fulfillment_order_status`` to track progress after placing.
Nothing is made until the person pays on the print service's
checkout, so the reply opens with ``tell_the_person``: the link to
pay first, then the checkout total with any tax, the print
service's order terms and a link to them. Pass every line on to
the person word for word.
If the person asks whether they can pay with a particular method,
answer from ``provider_pay_methods`` in the reply: yes for one it
lists; for any other, say Kiln doesn't know and that the checkout
page shows every option for their country. Never claim a method
that isn't listed.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"quote_id": "<quote_id>"
},
"name": "fulfillment_order"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| quote_id | Yes | Quote ID from ``fulfillment_quote``. | |
| quote_token | No | The ``quote_token`` a quote through Kiln's servers returned. Optional: Kiln keeps it beside the quote, so ``quote_id`` alone works; when passed it must be that token. An order is placed only from a quote taken on this computer. Default: "". | |
| jurisdiction | No | Buyer's region (e.g. ``"US-CA"``, ``"DE"``, ``"AU"``). When provided, the response includes an accurate total with tax so the user sees exactly what they'll pay — no hidden fees. Use ``tax_jurisdictions`` to see all supported codes. On an install that orders through Kiln's servers, pass it to ``fulfillment_quote`` instead: the servers pin it to the quote and the order is taxed as the quote said. Default: "". | |
| quoted_price | No | Total price returned by ``fulfillment_quote`` (used to calculate the fee when no ``payment_hold_id`` is provided). Required when ``payment_hold_id`` is empty and a payment rail is configured. Default: 0.0. | |
| preview_token | No | Token from ``issue_preview_token`` after the rendered model preview was shown to and approved by the user. Default: "". | |
| business_tax_id | No | If the buyer is a registered business, their tax ID (EU VAT number, AU ABN, etc.). Businesses in the EU, UK, Australia, and Japan are tax-exempt via reverse charge — the tax line shows $0.00. Default: "". | |
| payment_hold_id | No | PaymentIntent ID from the quote's ``payment_hold`` field. If provided, the previously authorized hold is captured before placing the order. This is the preferred payment flow. Default: "". | |
| quoted_currency | No | Currency of ``quoted_price`` (default USD). Default: "USD". | |
| shipping_address | No | Optional shipping contact/address dict for provider checkout. Keys: ``first_name``, ``last_name``, ``email``, ``phone``, ``street``, ``city``, ``postal_code``, ``country``; include ``state`` for US. | |
| preview_file_path | No | Exact model file path that was previewed. The preview token is validated against this file's bytes. Default: "". | |
| shipping_option_id | No | Shipping option ID from the quote's ``shipping_options`` list. Default: "". | |
| shipping_profile_name | No | Saved shipping profile name to use instead of passing ``shipping_address``. Default: "". | |
| shipping_confirmation_token | No | Token from ``issue_shipping_confirmation_token`` after the contact and shipping address were shown to and approved by the user. Default: "". |