> ## 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.

# Create a shopping link

> Use a Function to turn a confirmed selection into a Shopify cart link. This recipe needs no Shopify connector credentials.

Use a Function to turn a confirmed selection into a Shopify cart link. This recipe needs no Shopify connector credentials. Generating the link does not create an order or charge the shopper.

For WooCommerce, use its [approved product/variation add-to-cart Function](/docs/guides/integrations/woocommerce/overview#create-shopping-links); opening that link changes the browser cart. For [Wix Stores](/docs/guides/integrations/wix-stores/overview#finding-products) and [Squarespace Commerce](/docs/guides/integrations/squarespace-commerce/overview#finding-products), continue through the verified returned product page. The Shopify permalink implementation below is specific to its contract.

## Before you begin

- A store supporting [Shopify’s Cart and Checkout Permalinks](https://shopify.dev/docs/agents/carts-and-checkout/permalinks) for one-time products. Selling-plan items need another workflow.
- A merchant administrator who can supply the advertised endpoint/version and approved variant map below.
- An editable test project and a test store where you can inspect the resulting cart.

#### 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.

## Configure the merchant selection

Have the merchant administrator supply these values before creating the Function:

| Setting | Source |
| --- | --- |
| Endpoint and supported version | The store’s public `/.well-known/ucp` profile, under `dev.ucp.shopping.permalink`. Use the advertised endpoint rather than guessing a domain. |
| Approved variant key → numeric variant ID | **Shopify admin → Products → product → variant**. Read the numeric ID after `/variants/` in the URL and verify the exact options. See [Find product and variant IDs](https://help.shopify.com/en/manual/products/variants/find-variant-id) for other product-page layouts. |
| Quantity rule | The example allows 1–5 as an illustrative merchant rule. Replace it with your approved policy. |

Get products returns product IDs, not variant IDs. Keep this map administrator-owned.

Download [build-shopping-link.mjs](/examples/ecommerce/build-shopping-link.mjs) and replace its fictional settings, or copy the source below. The Function takes string inputs `variant_key` and `quantity` and returns `shopping_url` and `result`.

#### Studio

1. In **Tools**, create a Function named **Build shopping link**.
2. Paste the edited source. Declare **Input variables** `variant_key` and `quantity`, and **Output variables** `shopping_url` and `result`.
3. Save and test a permitted key and quantity.

#### Developer

Use Node 22+ on your development machine. Save [create-function.mjs](/examples/ecommerce/create-function.mjs) and [build-shopping-link.mjs](/examples/ecommerce/build-shopping-link.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 build-shopping-link > 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.

### Shopping-link Function source

Copy the complete implementation after replacing the merchant settings.

```javascript title="build-shopping-link.mjs — replace the fictional merchant settings"
// Replace these fictional merchant settings before saving the function.
// Obtain endpoint/version from the store's UCP permalink capability.
const PERMALINK_ENDPOINT = 'https://northstar.example/buy';
const UCP_VERSION = '2026-08-25';
const VARIANTS = {
  'trail-blue-small': '70881412',
  'trail-blue-medium': '70881382',
};

export default async function main(args) {
  const { variant_key, quantity } = args.inputVars;
  const id = Object.prototype.hasOwnProperty.call(VARIANTS, variant_key) ? VARIANTS[variant_key] : null;
  // A maximum of five is an illustrative merchant rule, not a Shopify limit.
  if (!id || !/^[1-5]$/.test(quantity)) {
    return { outputVars: { shopping_url: '', result: 'needs_selection' } };
  }
  const shopping_url = `${PERMALINK_ENDPOINT}/${id}:${quantity}?ucp/version=${UCP_VERSION}&continue_to=%2Fcart`;
  return { outputVars: { shopping_url, result: 'link_ready' } };
}
```

## Produce and verify the shopping link

### 1. Confirm the variant and quantity

Present the product and its exact options from the merchant-approved map. Ask the buyer to confirm the selection and quantity. If the desired option is absent, send them to the verified product page rather than inventing a variant ID.

### 2. Build the link

#### Studio

Attach **Build shopping link** through **Agent → Global tools → + → Function** or call it from a Workflow. Set its Trigger to run only after selection confirmation. Supply the approved key and quantity. Share `shopping_url` only when `result` is `link_ready`; `needs_selection` requires another selection, not an empty link.

Call the saved Function after confirming an approved variant and quantity. — Use the approved variant key and confirmed quantity.

#### 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": {
    "variant_key": "trail-blue-small",
    "quantity": "2"
  }
}'
```

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. Check the buyer's result

For the fictional settings, the expected link is:

```text
https://northstar.example/buy/70881412:2?ucp/version=2026-08-25&continue_to=%2Fcart
```

Open your actual test link after replacing those settings. Verify the variant, quantity and cart destination; a homepage or empty cart is not success.

Shopify can reduce or omit unavailable items. The shopper reviews the actual cart and finishes the purchase in the store.

## Test invalid selections

| Function result | Expected behavior |
| --- | --- |
| `link_ready` with a nonempty `shopping_url` | Open the link and check the intended variant, quantity and cart. |
| `needs_selection` with an empty `shopping_url` | Ask for a supported selection; do not share an empty link. |

Test an unknown key, `__proto__`, an empty quantity, zero, a decimal and a quantity above the example’s limit. Each must return `needs_selection` and an empty link.

Also test an unavailable variant in the store. The Function does not return cart totals or reserve stock; the buyer must inspect the actual cart.
