---
title: "Ask buyers questions"
description: "Add registration questions to any product, including standard details and answers checked against a pattern, answered in checkout before payment, and read each buyer's answers."
---

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

# Ask buyers questions

Any product can ask each buyer questions when they buy it: their phone number, a painting level, which days they're coming, or a box to tick for your terms. Checkout asks them before payment, a free product when it's claimed and a subscription once when it starts, never at its renewals. This guide sets up the questions and reads the answers. It uses the `sherpo` helper from [your first call](/merchant-api/first-call) and a token with `product:read`, `product:write`, `product:delete` (to remove a question), `customer:read` (for the answers) and `customer:write` (to answer for a customer).

## Add a question

<a href="/merchant-api/reference/create-product-question/">`POST /products/{product}/questions`</a> adds a question to a product:

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: question-level' \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "select",
  "label": "Your painting level",
  "required": true,
  "options": [
    "Beginner",
    "Some practice",
    "Confident"
  ]
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions', {
  body: {
    "kind": "select",
    "label": "Your painting level",
    "required": true,
    "options": [
      "Beginner",
      "Some practice",
      "Confident"
    ]
  },
  key: 'question-level',
});
```

Answers `201`, abridged:

```json
{
  "id": "4b3c2d1e-0f9a-4b8c-9d7e-6f5a4b3c2d1e",
  "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
  "position": 1,
  "kind": "select",
  "preset": null,
  "label": "Your painting level",
  "required": true,
  "options": [
    "Beginner",
    "Some practice",
    "Confident"
  ],
  "pattern": null,
  "example": null,
  "created_at": "2026-09-20T10:00:00.000Z",
  "updated_at": "2026-09-20T10:00:00.000Z"
}
```

- **`kind`** is what the buyer answers with: `text` (one line, up to 300 characters), `long_text` (up to 3,000, line breaks kept), `select` (one of its `options`), `multi_select` (any of them) or `checkbox` (ticked or not). A question's kind stays what it was created with.
- **`label`** is what the buyer is asked, one line of up to 200 characters.
- **`options`** are a select's choices, in order: 2 to 20, each distinct and up to 100 characters. Any other kind takes none.
- **`required`** makes checkout wait for an answer. A required checkbox must be ticked, so it suits terms the buyer accepts.
- **`position`** places it among the product's questions, from zero; left out, it goes last.

A product asks up to 20 questions. None is asked unless you add it, whatever the product's category.

## Ask for a standard detail

A **`preset`** asks for a standard detail: `name`, `phone`, `company` or `address`, each once per product. It sets the kind (`address` is a `long_text`, the others a `text`), and the label and pattern unless you give your own. A preset asked twice on one product answers `invalid` on `preset`.

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: question-phone' \
  -H 'Content-Type: application/json' \
  -d '{
  "preset": "phone",
  "required": true
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions', {
  body: {
    "preset": "phone",
    "required": true
  },
  key: 'question-phone',
});
```

Answers `201`, abridged:

```json
{
  "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
  "position": 0,
  "kind": "text",
  "preset": "phone",
  "label": "Phone number",
  "required": true,
  "options": null,
  "pattern": "\\+?[0-9 ()./-]{6,20}",
  "example": null,
  "created_at": "2026-09-20T09:58:00.000Z",
  "updated_at": "2026-09-20T09:58:00.000Z"
}
```

## Check a text answer's format

A text question's **`pattern`** is a regular expression the whole answer must match, so a buyer can't continue until, say, an email looks like one. Checkout checks it as the buyer types, and the answers are checked again when they are saved, with the same matcher, so both always agree.

```bash
curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: question-email' \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "text",
  "label": "Work email",
  "pattern": "[^@\\s]+@[^@\\s]+\\.[^@\\s]+",
  "example": "name@company.com"
}'
```

```js
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions', {
  body: {
    "kind": "text",
    "label": "Work email",
    "pattern": "[^@\\s]+@[^@\\s]+\\.[^@\\s]+",
    "example": "name@company.com"
  },
  key: 'question-email',
});
```

Answers `201`, abridged:

```json
{
  "id": "5c4d3e2f-1a0b-4c9d-8e7f-6a5b4c3d2e1f",
  "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
  "position": 2,
  "kind": "text",
  "preset": null,
  "label": "Work email",
  "required": false,
  "options": null,
  "pattern": "[^@\\s]+@[^@\\s]+\\.[^@\\s]+",
  "example": "name@company.com",
  "created_at": "2026-09-20T10:02:00.000Z",
  "updated_at": "2026-09-20T10:02:00.000Z"
}
```

Patterns take a safe subset of JavaScript's syntax, up to 200 characters: characters and escapes, `.`, classes such as `[a-z]` or `[^@]`, `\d`, `\w` and `\s`, groups (plain or `(?:...)`), `|`, and the repeats `?`, `*`, `+` and `{n,m}` up to 100. The matching takes time in step with the answer's length whatever the pattern, so no pattern can stall checkout. A pattern outside the subset, such as one with a back reference, a lookaround or `\b`, or one too large to check against its question's longest answer (a `long_text` takes smaller patterns than a `text`), answers `invalid` on `pattern` with the reason it can't be checked safely. Only a `text` or `long_text` question takes one, trimmed as answers are, and `null` clears it. A blank answer clears a question that isn't required, whatever its pattern.

A patterned question can also take an **`example`**: an answer that fits the pattern, which checkout shows buyers as the format to follow, as a hint under the question and in the error when an answer doesn't fit ("Enter it like <name@company.com>"). It's one trimmed line of up to 100 characters, and the pattern must match it whole: sent to a question with no pattern, or one its pattern doesn't match, it answers `invalid` on `example`. `null` clears it. Clearing the pattern clears the example too, and so does a new pattern that no longer matches it, unless you send a new example with it.

## List, change and remove questions

<a href="/merchant-api/reference/list-product-questions/">`GET /products/{product}/questions`</a> lists them in the order checkout asks them:

```bash
curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions');
```

Answers `200`, abridged:

```json
{
  "items": [
    {
      "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
      "position": 0,
      "kind": "text",
      "preset": "phone",
      "label": "Phone number",
      "required": true,
      "options": null,
      "pattern": "\\+?[0-9 ()./-]{6,20}",
      "example": null,
      "created_at": "2026-09-20T09:58:00.000Z",
      "updated_at": "2026-09-20T09:58:00.000Z"
    },
    {
      "id": "4b3c2d1e-0f9a-4b8c-9d7e-6f5a4b3c2d1e",
      "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
      "position": 1,
      "kind": "select",
      "preset": null,
      "label": "Your painting level",
      "required": true,
      "options": [
        "Beginner",
        "Some practice",
        "Confident"
      ],
      "pattern": null,
      "example": null,
      "created_at": "2026-09-20T10:00:00.000Z",
      "updated_at": "2026-09-20T10:00:00.000Z"
    }
  ],
  "cursor": null
}
```

<a href="/merchant-api/reference/update-product-question/">`PATCH /products/{product}/questions/{question}`</a> rewords one, makes it required or not, changes a select's options or a text's pattern and example, or moves it with `position`; the others shift to make room. Send `from_position`, where you last read it, and a move is refused as `conflict` on `value` once someone else moved it, with `current` its place now, so two moves never add up. <a href="/merchant-api/reference/delete-product-question/">`DELETE /products/{product}/questions/{question}`</a> stops asking it and drops every answer to it.

The questions are on the product's [product read](/customer-api/storefront) too, as `questions`, for your own checkout page to show.

## How buyers answer

A buyer answers in checkout, while their cart holds the product, and a cart can't be frozen for payment until every required question has an answer and every text answer fits its pattern. The answers are kept per buyer per product, so a buyer coming back finds theirs filled in and is asked only what's new. See [Checkout](/customer-api/checkout#registration-questions) for the calls a checkout page makes.

A customer you add yourself, through a grant, an automation or a sale you record, skipped checkout, so they have no answers until you [give them](#answer-for-a-customer). Changing a select's options keeps the answers given, but a choice you take off no longer reads as an answer, and checkout asks it again. An answer given before you change a pattern stays as given, and checkout asks the buyer to correct it before their next payment.

## Answer for a customer

<a href="/merchant-api/reference/set-customer-answers/">`PUT /products/{product}/customers/{customer}/answers`</a> answers for a customer who holds the product, such as answers they gave on another platform before you moved them, with a token holding `customer:write`:

```bash
curl -X PUT 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/customers/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/answers' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: answers-ada-watercolor' \
  -H 'Content-Type: application/json' \
  -d '{
  "answers": [
    {
      "question": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "value": "+39 333 123 4567"
    },
    {
      "question": "4b3c2d1e-0f9a-4b8c-9d7e-6f5a4b3c2d1e",
      "value": "Beginner"
    }
  ]
}'
```

```js
const answer = await sherpo('PUT', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/customers/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/answers', {
  body: {
    "answers": [
      {
        "question": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
        "value": "+39 333 123 4567"
      },
      {
        "question": "4b3c2d1e-0f9a-4b8c-9d7e-6f5a4b3c2d1e",
        "value": "Beginner"
      }
    ]
  },
  key: 'answers-ada-watercolor',
});
```

Answers `200`, abridged:

```json
{
  "product_id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
  "customer_id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
  "answers": [
    {
      "question_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "value": "+39 333 123 4567"
    },
    {
      "question_id": "4b3c2d1e-0f9a-4b8c-9d7e-6f5a4b3c2d1e",
      "value": "Beginner"
    }
  ]
}
```

Each answer is checked as checkout checks it, against its question's kind, options and pattern, and a question you leave out keeps what it holds. `null` clears an optional answer, as a blank text does; a required question can be left unanswered but never cleared. A customer who holds no access to the product answers `409` [`conflict`](/merchant-api/errors#conflict) on `customer`, so give the access first. A customer you invited by email keeps the answers once they sign in. The answer reads the customer's answers back only for a token holding `customer:read`, and none otherwise.

## Read the answers

<a href="/merchant-api/reference/list-customer-answers/">`GET /customers/{customer}/answers`</a> reads one customer's answers to each product they answered, latest first, each with the question's label. It covers the 100 latest products, with `total` counting them all; `product` reads any one of them:

```bash
curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/customers/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/answers' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
```

```js
const answer = await sherpo('GET', '/v1/stores/STORE_ID/customers/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/answers');
```

Answers `200`, abridged:

```json
{
  "total": 1,
  "items": [
    {
      "product": {
        "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
        "title": "Watercolor basics"
      },
      "answers": [
        {
          "question_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
          "label": "Phone number",
          "kind": "text",
          "preset": "phone",
          "value": "+39 333 123 4567"
        },
        {
          "question_id": "4b3c2d1e-0f9a-4b8c-9d7e-6f5a4b3c2d1e",
          "label": "Your painting level",
          "kind": "select",
          "preset": null,
          "value": "Beginner"
        }
      ]
    }
  ]
}
```

Each row of <a href="/merchant-api/reference/list-product-customers/">`GET /products/{product}/customers`</a> carries its customer's `answers` too, an event's [guest list](/merchant-api/guides/event-guest-lists) carries each attendee's (a guest with none of their own carries their buyer's, marked `answered_by: buyer`), and a product's [requests](/merchant-api/guides/approvals-and-waitlists) carry each requester's, all in the questions' order, each with the `question_id` it answers and its `value`: a string for a text or a select, a list for a multi select, `true` or `false` for a checkbox. A question left unanswered isn't in the list. A customer whose details are erased loses their answers too.

Source: https://docs.sherpo.io/merchant-api/guides/registration-questions/index.mdx
