> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order placement skill

The `order-placement` skill handles order submission and status updates. It covers the skill definition, the validation script that runs before any order is placed, and the order policy reference the agent consults for limits, approval rules, and shipping terms.

Allowed tools: `create_order`, `update_order_status`

For the tool source code, see [Tools](/agent_skills/multi/tools). For the agent YAML that loads this skill, see [Operations assistant](/agent_skills/multi/agent). To see the other skill in action end-to-end, see the [Sample query walkthrough](/agent_skills/multi/sample_query).

***

## Skill definition `SKILL.md`

```yaml YAML theme={null}
---
name: order-placement
description: Place and track customer orders. Use when a user wants to submit a new order or check the status of an existing order.
allowed-tools:
  - create_order
  - update_order_status
---

# Order Placement

You are an order management specialist. You help customers place orders accurately and in compliance with company policy.

## Instructions

### Step 1 — Collect Order Details
Ask the user for:
- **product_id**: The product identifier (e.g. SKU-12345)
- **quantity**: How many units they want to order
- **unit_price**: Price per unit in USD

### Step 2 — Validate the Order
Before placing any order, run the validation script validate_order.py with:
args={"product_id": "<product_id>", "quantity": <quantity>, "unit_price": <unit_price>}

The script returns:
- `valid` (boolean): whether the order passes all checks
- `errors` (list): list of validation error messages if invalid
- `total_value` (number): computed order total
- `requires_approval` (boolean): true if total > $10,000

If `valid` is false, report all errors to the user and ask for corrections. Do not call `create_order` until validation passes.

If `requires_approval` is true, inform the user that manager approval is required before proceeding.

For detailed order limits and shipping rules, read the policy reference: ORDER_POLICY.md

### Step 3 — Place the Order
Once validation passes (and approval is acknowledged if required), call:
create_order(product_id="<product_id>", quantity=<quantity>, unit_price=<unit_price>)

### Step 4 — Confirm
Return the `order_id` and `status` from the tool response to the user.
```

***

## Script `scripts/validate_order.py`

The validation script runs before `create_order` is called. It enforces quantity and price limits and computes the order total.

```python theme={null}
def run(product_id: str, quantity: int, unit_price: float) -> dict:
    errors = []

    if not product_id or not product_id.strip():
        errors.append("product_id cannot be empty")

    if quantity < 1:
        errors.append(f"quantity must be at least 1, got {quantity}")
    if quantity > 10000:
        errors.append(f"quantity {quantity} exceeds single-order limit of 10,000")

    if unit_price <= 0:
        errors.append(f"unit_price must be positive, got {unit_price}")
    if unit_price > 50000:
        errors.append(f"unit_price {unit_price} exceeds maximum of $50,000")

    total = quantity * unit_price
    requires_approval = total > 10000

    return {
        "valid":              len(errors) == 0,
        "errors":             errors,
        "total_value":        round(total, 2),
        "requires_approval":  requires_approval,
    }
```

**Return values**

| Field               | Type    | Description                                             |
| ------------------- | ------- | ------------------------------------------------------- |
| `valid`             | Boolean | `true` if the order passes all checks                   |
| `errors`            | List    | Validation error messages. Empty when `valid` is `true` |
| `total_value`       | Number  | Computed order total (`quantity × unit_price`)          |
| `requires_approval` | Boolean | `true` when `total_value` exceeds \$10,000              |

***

## Reference `references/ORDER_POLICY.md`

```markdown theme={null}
# Order Policy

## Order Limits
- **Minimum order**: 1 unit
- **Maximum single order**: 10,000 units
- **Maximum unit price**: $50,000
- **Approval threshold**: Orders with total value > $10,000 require manager approval before `create_order` is called

## Approval Process
1. Inform the user the order requires approval (total > $10,000).
2. Ask them to confirm they have obtained manager sign-off.
3. Proceed with `create_order` only after explicit confirmation.

## Shipping Rules
| Order Total       | Shipping Method |
|-------------------|----------------|
| Under $500        | Standard (5–7 business days) |
| $500–$5,000       | Expedited available (+$25 flat fee) |
| Over $5,000       | Dedicated logistics team assigns carrier |

## Payment Terms
- **Approved business accounts**: Net 30
- **New accounts**: Prepayment required
- **Orders above $25,000**: Prepayment required regardless of account status

## Cancellation Policy
- Orders may be cancelled within 1 hour of placement at no charge.
- After 1 hour: 10% restocking fee applies.
- Shipped orders cannot be cancelled; initiate a return instead.
```

***

## Next steps

* See [Inventory check skill](/agent_skills/multi/inventory_check) for the companion skill that handles stock analysis.
* See [Agent configuration](/agent_skills/multi/agent) for how both skills are attached to the agent.