> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Assess a return request

> Evaluate a return request with an existing Function. The example returns a policy assessment; it does not authorize a return, create a shipping label or issue a refund.

Evaluate a return request with an existing Function. The example returns a policy assessment; it does not authorize a return, create a shipping label or issue a refund.

Connect the permitted order through [WooCommerce](/docs/guides/integrations/woocommerce/overview#looking-up-orders), [Wix Stores](/docs/guides/integrations/wix-stores/overview#looking-up-orders) or [Squarespace Commerce](/docs/guides/integrations/squarespace-commerce/overview#looking-up-orders). Each still needs a trusted actual delivery timestamp and merchant policy; an order creation/completion field is not a substitute.

## Before you begin

- A merchant-approved return policy. The fictional example allows unused, non-final-sale items in their original packaging within 30 elapsed days of delivery; damaged items require support review. Replace these rules before use.
- An application-owned order access check and a trusted source of the delivery timestamp and final-sale flag. A fulfillment administrator or your backend must supply them. Shopify Get order's creation time is not a delivery time.
- A request timestamp recorded by your application and the customer's confirmed item condition and original-packaging status.

#### Studio

Open the test project in [Agent studio](https://creator.voiceflow.com).

#### Developer

Use a [Voiceflow bearer credential](/docs/api-reference/authentication) with access to your test project and Environment. Keep it on your backend or development machine. Set:

```sh
export VF_TOKEN='YOUR_VOICEFLOW_BEARER_TOKEN'
export PROJECT_ID='YOUR_TEST_PROJECT_ID'
export ENVIRONMENT='main'
```

The API examples use the Environment’s saved Draft. Standalone execution does not attach a tool, compile an agent or publish a release.

## Prepare the policy function

Download [assess-return.mjs](/examples/ecommerce/assess-return.mjs), or copy the source below. Replace the illustrative policy with your approved rules. Declare these string inputs:

| Input | Trusted source | Test value |
| --- | --- | --- |
| `delivered_at` | Fulfillment record/backend | `2026-11-01T12:00:00Z` |
| `requested_at` | Application-recorded request time | `2026-11-16T12:00:00Z` |
| `condition` | Customer’s confirmed condition | `unused` |
| `final_sale` | Merchant record/backend | `false` |
| `original_packaging` | Customer’s confirmation | `true` |

Declare outputs `decision` and `reason`. Times must be UTC ISO instants; the window uses elapsed time rather than local calendar dates. Unknown or invalid inputs produce `needs_review`.

#### Studio

1. Open **Tools** and create a Function named **Assess return request**.
2. Paste the source and declare the five **Input variables** and two **Output variables** above.
3. Save and test with the fixed example values before using it in a conversation.

#### Developer

Use Node 22+ on your development machine. Save [create-function.mjs](/examples/ecommerce/create-function.mjs) and [assess-return.mjs](/examples/ecommerce/assess-return.mjs) in the same directory. Inspect the downloaded source and apply your approved merchant settings before creating it.

The helper needs Function create/update permissions and uses the stable Function API:

- Creates the Function, then adds its input/output declarations through `function-variable/batch` in the selected Environment’s Draft.
- Leaves agent attachment and publication as separate steps.
- Is not idempotent: inspect the project before rerunning after a failed request.

```sh
node create-function.mjs assess-return > created-function.json
export FUNCTION_ID="$(node -p "JSON.parse(require('fs').readFileSync('created-function.json','utf8')).functionID")"
```

The saved `functionID` is the ID produced by creation, not a name or a guessed identifier.

### Return-assessment Function source

Copy the complete example and adapt its rules to the merchant’s approved policy.

```javascript title="assess-return.mjs — illustrative merchant policy"
// Illustrative merchant policy: unused items in original packaging, not final sale,
// within 30 elapsed days of delivery. Damaged items need merchant review.
// Populate dates and final_sale from trusted merchant records, not model guesses.
export default async function main(args) {
  const { delivered_at, requested_at, condition, final_sale, original_packaging } = args.inputVars;
  const result = (decision, reason) => ({ outputVars: { decision, reason } });
  const instant = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
  const validDate = (value) => {
    if (typeof value !== 'string' || !instant.test(value)) return false;
    const ms = Date.parse(value);
    const canonical = value.includes('.') ? value : value.replace('Z', '.000Z');
    return Number.isFinite(ms) && new Date(ms).toISOString() === canonical;
  };
  if (!validDate(delivered_at) || !validDate(requested_at)) {
    return result('needs_review', 'A verified UTC delivery and request time are required.');
  }
  const elapsed = Date.parse(requested_at) - Date.parse(delivered_at);
  if (elapsed < 0 || !['true', 'false'].includes(final_sale) || !['true', 'false'].includes(original_packaging) || !['unused', 'used', 'damaged'].includes(condition)) {
    return result('needs_review', 'The request needs a support review.');
  }
  if (condition === 'damaged') return result('needs_review', 'Route damage claims to the support team.');
  if (final_sale === 'true') return result('outside_policy', 'This item is marked final sale.');
  if (elapsed > 30 * 24 * 60 * 60 * 1000) return result('outside_policy', 'The example 30-day window has elapsed.');
  if (condition !== 'unused') return result('outside_policy', 'The example policy requires an unused item.');
  if (original_packaging !== 'true') return result('outside_policy', 'The example policy requires the original packaging.');
  return result('eligible_for_review', 'The request meets the example policy; the merchant must authorize the return.');
}
```

## Run the assessment

### 1. Populate trusted inputs

Have your backend supply the permitted order’s delivery time and final-sale status, and record the request time. Use the table’s fixed values for this controlled test.

Define and populate conversation variables before mapping them. An empty variable definition is not a verified value.

### 2. Execute the saved function

#### Studio

1. Add the saved Function to a Workflow’s [Function step](/docs/documentation/build/steps/function) and map the five verified inputs.
2. Create conversation variables `return_decision` and `return_reason`. Map Function outputs `decision` and `reason` to them.
3. Route `return_decision` explicitly using the decisions below.

A Playbook can also call the Function; agent-generated values do not replace trusted fulfillment data.

Map trusted return inputs in the saved Function step. — Map verified return inputs through a Workflow.

#### Developer

```sh
curl --fail-with-body --silent --show-error \
  --request POST "https://realtime-api.voiceflow.com/v1/stable/function/$FUNCTION_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" --header 'Content-Type: application/json' \
  --data '{
  "inputs": {
    "delivered_at": "2026-11-01T12:00:00Z",
    "requested_at": "2026-11-16T12:00:00Z",
    "condition": "unused",
    "final_sale": "false",
    "original_packaging": "true"
  }
}'
```

Require `success: true`, `error: null` and `truncated: false`, then inspect `output.outputVars`. Every declared input must be present as a string. This is standalone execution of the saved Draft; [agent attachment](/docs/cli/commands/tool/create) and compilation are separate if your application needs the agent to invoke it.

### 3. Explain and route the decision

For the sample, expect `eligible_for_review`. Route the actual output:

| `decision` | Customer response and next action |
| --- | --- |
| `eligible_for_review` | Explain that the request meets the policy and still needs merchant authorization. |
| `outside_policy` | Explain the returned reason; offer review for disputed outcomes. |
| `needs_review` | Send missing-data or damage claims for support review. |

Pass only the permitted order and assessment to [support](/docs/guides/integrations/help-desks/create-and-route-support-requests). That workflow owns creating and confirming the case.

## Verify the policy boundary

#### Studio

Illustrative test: the policy assessment still requires merchant authorization. — Illustrative test: the policy assessment still requires merchant authorization.

Verify the actual Function outputs for each boundary:

- **Exactly 30 elapsed days:** an otherwise qualifying request returns `eligible_for_review`.
- **Beyond 30 days, final-sale, used or missing original packaging:** returns `outside_policy` under the example rules.
- **Damaged, malformed dates, request before delivery or missing data:** returns `needs_review`.

Check that the conversation follows the actual output. No path should promise a refund or return authorization from this assessment alone.
