Skip to content

Ask buyers questions

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.

Updated

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

POST /products/{product}/questions adds a question to a product:

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"
  ]
}'
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:

{
  "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.

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
}'
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:

{
  "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.

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"
}'
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:

{
  "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

GET /products/{product}/questions lists them in the order checkout asks them:

curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/questions');

Answers 200, abridged:

{
  "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
}

PATCH /products/{product}/questions/{question} 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. DELETE /products/{product}/questions/{question} stops asking it and drops every answer to it.

The questions are on the product’s product read 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 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. 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

PUT /products/{product}/customers/{customer}/answers 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:

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"
    }
  ]
}'
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:

{
  "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 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

GET /customers/{customer}/answers 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:

curl 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/customers/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/answers' \
  -H "Authorization: Bearer $SHERPO_TOKEN"
const answer = await sherpo('GET', '/v1/stores/STORE_ID/customers/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/answers');

Answers 200, abridged:

{
  "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 GET /products/{product}/customers carries its customer’s answers too, an event’s guest list carries each attendee’s (a guest with none of their own carries their buyer’s, marked answered_by: buyer), and a product’s requests 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.

Type to search…

↑↓ navigate↵ selectEsc close