This guide shows how to build a reusable Fin procedure that looks up a product catalog via your API, matches a customer’s requested item, checks stock and routes the flow based on stock availability. You can use this procedure to create new orders or update existing ones using your backend order APIs.

Keep your own API endpoints and parameter names — replace the example URLs, request bodies and field names with the ones your backend exposes. If you haven't built a procedure before, read Building Fin Procedures first.

Note:

Data Connectors: You need three specific connectors:
- One to return a product catalog (GET).
- One to create an order item (POST).
- One to update an existing order (PUT).
Canonical response shape: Your APIs must return a consistent data structure.
Error Handling: For a robust procedure, your Condition steps must use the status_code and error response attributes returned by Data Connectors. This allows Fin to branch on specific HTTP error codes (e.g. 400, 500) rather than relying on a generic pass/fail path.

Tip: Connect with Community Experts and Intercom Solutions Architects at our Procedures Meetup Office Hours. Held every two weeks, these sessions offer practical, real-time support, including live Q&A to help you set up and optimize your Fin Procedures and Data connectors.

Setting up data connectors

Create three connectors with clear names (for example, Get Product Catalog, Create Order Item, Update Order Item) to help Fin identify the correct action.

Collect any inputs the connector needs. Temporary Attributes can now be passed directly as inputs to a Data Connector — if the data already exists in a temporary variable, Fin maps it automatically without prompting the customer. Only configure an input as customer-collected if the value is not already stored. Replace https://api.example.com and field names with your own endpoints and JSON keys. For common questions on connector setup, authentication, and execution, see Fin and Data connectors FAQs.

1. Get Product Catalog (GET)

Purpose: Returns a list of products including id, name, price, and stock.
Method: GET.
URL: https://api.example.com/items (or your catalog endpoint)
Headers: Content-Type: application/json (+ auth as required)

Response: An array of product objects.

Example response:

[
  { "id": "sku-100", "name": "Classic T-Shirt", "price": 19.99, "stock": 120 },
  { "id": "sku-101", "name": "Running Shoes",  "price": 89.50, "stock": 45 },
  { "id": "sku-104", "name": "Nintendo Switch", "price": 119.00, "stock": 0 }
]

2. Create Order Item (POST)

Purpose: Creates a new order or a specific order item.
Method: POST.
URL: https://api.example.com/orders (or your create-order endpoint)
Headers: Content-Type: application/json (+ auth)
Request body: Must include product_id and quantity.
```
{
  "product_id": "<product id>",
  "quantity": <integer>
}
```
Configure connector inputs if you want Fin to collect product_id and quantity.

3. Update Order Item (PUT)

Purpose: Adds items to or updates an existing order.
Method: PUT.
URL: https://api.example.com/orders/{{order_id}} (or PUT /orders/{order_id}/items)
Headers: Content-Type: application/json (+ auth)

Request body: Must include product_id and quantity.

{
  "product_id": "<product id>",
  "quantity": <integer>
}

Required inputs: order_id, product_id, quantity

API connection showing path variable order_id and request body.
Collect data inputs listing order_id, product_id, quantity.

Building the procedure flow

Use temporary variables to store intermediate data throughout the conversation. Recommended variables include Temporary.SelectedProductID, Temporary.StockLevel, and Temporary.OrderAction.

Step 1: Product inquiry and lookup

Prompt the customer: Ask, "Which product would you like?".
Call Data Connector: Use Get Product Catalog.
Logic: Search the returned list for a product whose name (or SKU) best matches Temporary.SelectedProductName.
On match, set:
- Temporary.SelectedProductID = product id
- Temporary.SelectedProductName = canonical product name from catalog
- Temporary.StockLevel = product stock (cast to integer)
Validation: If no match is found, prompt the customer to clarify or suggest top similar products from the catalog and loop back to Step 1 if they pick another product.

Implementation notes

Matching logic can be a simple substring match or more sophisticated fuzzy matching. Keep matching deterministic so Fin’s condition steps work reliably.

Step 2: Stock check and branching

Use a standard IF/ELSE logic block in the procedure UI to check Temporary.StockLevel. This is a straightforward value comparison — you do not need a code condition here. Use the visual condition builder and select Temporary.StockLevel as the attribute.

IF Temporary.StockLevel > 0: Continue to Step 3.
ELSE: Route to the "Out of Stock" section (Step 8).

Step 3: Ask new or existing order

Prompt: “Would you like to create a new order for this item, or add it to an existing order?”
Accept answers:
- New → Temporary.OrderAction = "new" → Step 4
- Existing → Temporary.OrderAction = "existing" → Step 4
- If unclear, ask a clarifying question and repeat.

Step 4 — Ask quantity and validate (minor update)

Prompt: “How many units would you like?” → parse integer → store in Temporary.Quantity.
Validation:
- If Temporary.Quantity <= 0 → ask again.
- If Temporary.Quantity > Temporary.StockLevel → inform the customer of available stock and either:
  - Offer the maximum available and ask to confirm a smaller quantity (loop within Step 4), or
  - Offer backorder/notify options (Step 8).
After quantity is validated, proceed to Step 5 (Order action decision).
Quantity prompt and validation action blocks.

Step 5: Order action decision (IF / ELSE IF)

Rather than handling order creation and updates inline, route each path to a dedicated sub-procedure. This keeps the main flow clean and makes each path independently testable. Add an IF / ELSE IF conditional block, then use @Run sub-procedure in each branch: For complex or date-based comparisons, see How to write code conditions for Fin Procedures.
1. IF Temporary.OrderAction == 'new': use @Run sub-procedure to invoke the Create New Order sub-procedure.
2. ELSE IF Temporary.OrderAction == 'existing': use @Run sub-procedure to invoke the Update Existing Order sub-procedure.
3. ELSE (fallback): escalate to team

Step 6: CREATE NEW ORDER (sub-procedure)

Move this step into a dedicated sub-procedure (e.g. "Create New Order") to keep the main flow readable. Within that sub-procedure, call the Create Order Item connector. Temporary attributes such as Temporary.SelectedProductID and Temporary.Quantity can be mapped directly to connector inputs — no manual prompting needed:
- product_id = Temporary.SelectedProductID
- quantity = Temporary.Quantity
Capture the response into Temporary.NewOrderID (if returned) and store the connector's status_code into Temporary.CreateOrderStatus.
On success: reply:
“Created new order with [Temporary.Quantity] × [Temporary.SelectedProductName]. Order ID: [Temporary.NewOrderID]. Anything else I can do?”
Offer post-action choices (add more items, change quantity, checkout, finish). Persist Temporary.NewOrderID if continuing the session.
Add a Condition step immediately after the connector call and branch on Temporary.CreateOrderStatus. The status_code and error attributes may appear at the bottom of the attribute selector — scroll down if you don't see them. Use the following branches: IF status_code == 200 or 201: proceed to the success confirmation. ELSE IF status_code == 400: inform the customer their request was invalid (e.g. bad product ID or quantity), prompt them to correct the input, and offer a retry. ELSE IF status_code >= 500: apologise for a server error, capture the error attribute into an internal note for debugging, and escalate to the E-Comm Support Team. ELSE (unexpected status): log Temporary.CreateOrderStatus and escalate to the E-Comm Support Team. For a deeper guide on debugging connector failures and interpreting status codes, see Troubleshooting Fin Procedures and Data connectors.
Connector call with mapped inputs and response mapping (order_id → Temporary.NewOrderID).
Post-action confirmation message and options.

Step 7: UPDATE EXISTING ORDER (sub-procedure)

Prompt: “Please provide the existing order ID you want to add this item to.” → save to Temporary.ExistingOrderID.
Call: Update Order Item connector with:
- order_id = Temporary.ExistingOrderID
- product_id = Temporary.SelectedProductID
- quantity = Temporary.Quantity
Capture the connector's status_code into Temporary.UpdateOrderStatus and the error field (if present) into Temporary.UpdateOrderError.
On success: reply:
“Added [Temporary.Quantity] × [Temporary.SelectedProductName] to order [Temporary.ExistingOrderID]. Anything else?”
Offer post-action choices (add more items, change quantity, checkout, finish).
Add a Condition step immediately after the connector call and branch on Temporary.UpdateOrderStatus. As with Step 6, the status_code and error attributes may appear at the bottom of the attribute selector. Use the following branches: IF status_code == 200: proceed to the success confirmation. ELSE IF status_code == 400: inform the customer the order ID may be invalid, ask them to verify and re-enter it, and offer a retry. ELSE IF status_code >= 500: apologise for a server error, surface Temporary.UpdateOrderError in an internal note, and escalate to the E-Comm Support Team. ELSE (unexpected status): log the status and escalate to the E-Comm Support Team. See Troubleshooting Fin Procedures and Data connectors for full guidance on diagnosing connector failures in live conversations.
Tip: The status_code and error attributes returned by a Data Connector may appear at the bottom of the attribute selector. Scroll down if you don't see them immediately — they are essential for building robust error-handling branches.
Collection of ExistingOrderID and the Update connector call that uses it.
Post-action confirmation message and options.

Step 8: OUT OF STOCK

Trigger when Temporary.StockLevel ≤ 0 or when the requested quantity > available and customer declines reduced quantity.
Actions:
1. Apologize and present clear options:
  - Show similar products (top matches from the catalog).
  - Offer backorder/notify when available — record contact preference.
  - Offer partial quantity if available.
2. If the customer chooses notify/backorder → record preference and confirm.
3. If the customer chooses an alternative → return to Step 1 (Product inquiry and lookup) with the new selection.
4. End or loop per customer response.

Next steps

Once your core order flow is working, consider these advanced patterns to handle more complex outcomes.

Hand off to a Workflow after order creation

After a successful new order, hand off to a Workflow (e.g. "Send Order Confirmation") to handle downstream automation such as email receipts or CRM updates. Use a Handoff to workflow step at the end of your Create New Order sub-procedure. The procedure ends at the handoff and won't resume after the Workflow finishes, so make this the last step.

Switch procedures based on order outcome

If the order results in a specific state — for example a backorder or a failed payment — switch to a dedicated procedure (e.g. "Backorder Management" or "Payment Failure Recovery") rather than handling every outcome in one procedure. This keeps individual procedures focused and easier to maintain.

Escalate with context on repeated API failures

If the same connector fails on retry (e.g. two consecutive 500 errors), escalate to a human team and include an internal note summarising Temporary.CreateOrderStatus or Temporary.UpdateOrderError so the teammate has full context without needing to re-ask the customer.

Chain sub-procedures for multi-item carts

To support customers ordering multiple products in one session, loop back to the Product Inquiry sub-procedure after a successful order action and increment an item counter. End the loop when the customer confirms they are done.

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

Create a complex Fin procedure