Questions

These endpoints are called from a shopper's browser, so they take your publishable key rather than a secret one. Anything specific to one customer also takes a signed email and timestamp: see Identifying the customer for how to produce the signature.

GET `/widgets/questions`

List a product's published questions with their published answers, newest question first. Only what a moderator has approved appears here, and an asker's email never does.

Query Parameters

apiPublishableKeystringrequired

Your organization's publishable key, from Settings, API keys.

productSlugstringrequired

Slug of the product whose questions to list.

limitnumber

How many questions to return.

cursorstring

The nextCursor from the previous page.

Request

curl \
  "https://api.cascade.dev/widgets/questions?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&productSlug=string"

Request

import { client } from "@cascade-commerce/api/widget/client"
import { getWidgetsQuestions } from "@cascade-commerce/api/widget"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
})

const { data, error } = await getWidgetsQuestions({
  query: { apiPublishableKey: "pk_YOUR_PUBLISHABLE_KEY", productSlug: "string" },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/widgets/questions?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&productSlug=string")
req = Net::HTTP::Get.new(uri)

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/widgets/questions?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&productSlug=string",
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "enabled": true,
  "allowShopperAnswers": true,
  "totalQuestions": 0,
  "questions": [
    {
      "id": "string",
      "body": "string",
      "askerName": "string",
      "createdAt": "string",
      "answers": ["..."]
    }
  ],
  "nextCursor": "string"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "description": "Whether the store is collecting questions. False hides the ask box and the Q&A section."
    },
    "allowShopperAnswers": {
      "type": "boolean",
      "description": "Whether shoppers may answer each other's published questions."
    },
    "totalQuestions": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many published questions this product has."
    },
    "questions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "askerName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Who asked, or null if they asked anonymously."
          },
          "createdAt": {
            "type": "string"
          },
          "answers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "body": {
                  "type": "string"
                },
                "authorName": {
                  "type": "string",
                  "description": "Who the answer is from."
                },
                "authorType": {
                  "type": "string",
                  "enum": ["merchant", "shopper"],
                  "description": "Whether the store or another shopper wrote it."
                },
                "createdAt": {
                  "type": "string"
                }
              },
              "required": ["id", "body", "authorName", "authorType", "createdAt"],
              "additionalProperties": false
            },
            "description": "The published answers, the store's first and then the shoppers', oldest first."
          }
        },
        "required": ["id", "body", "askerName", "createdAt", "answers"],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": ["enabled", "allowShopperAnswers", "totalQuestions", "questions", "nextCursor"],
  "additionalProperties": false
}

POST `/widgets/questions`

Ask a question about a product. The question is recorded for the store to answer and published once a moderator approves it. The response also carries an instant answer generated from the product's published reviews, to read while the store writes a real one; it is null when the store has generated answers switched off or unavailable, which never stops the question being recorded.

Query Parameters

apiPublishableKeystringrequired

Your organization's publishable key, from Settings, API keys.

Body Parameters

productSlugstringrequired

Slug of the product the question is about.

questionstringrequired

The shopper's question, up to 500 characters.

visitorTokenstringrequired

Random id identifying the visitor's browser, used only for rate limiting. Only a hash of it is ever stored, and never with the question.

namestring

The name to show beside the question once it is published. Omit to ask anonymously.

emailstring (email)

Where to send the answer. Never published, and used for nothing else. Omit to ask without leaving one.

Request

curl \
  -X POST \
  "https://api.cascade.dev/widgets/questions?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "productSlug": "string",
  "question": "string",
  "visitorToken": "string",
  "name": "string",
  "email": "[email protected]"
}'

Request

import { client } from "@cascade-commerce/api/widget/client"
import { postWidgetsQuestions } from "@cascade-commerce/api/widget"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
})

const { data, error } = await postWidgetsQuestions({
  query: { apiPublishableKey: "pk_YOUR_PUBLISHABLE_KEY" },
  body: {
    productSlug: "string",
    question: "string",
    visitorToken: "string",
    name: "string",
    email: "[email protected]",
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/widgets/questions?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY")
req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "productSlug": "string",
    "question": "string",
    "visitorToken": "string",
    "name": "string",
    "email": "[email protected]"
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "productSlug": "string",
  "question": "string",
  "visitorToken": "string",
  "name": "string",
  "email": "[email protected]"
}"""

req = Request(
    "https://api.cascade.dev/widgets/questions?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY",
    data=body.encode(),
    headers={"Content-Type": "application/json"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "questionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "notifyByEmail": true,
  "instantAnswer": {
    "answered": true,
    "answer": "string",
    "reviewCount": 0,
    "generatedAt": "string",
    "citedReviews": [
      {
        "id": "...",
        "rating": "...",
        "title": "...",
        "excerpt": "...",
        "createdAt": "..."
      }
    ]
  }
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "questionId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The question that is now waiting for the store to answer it."
    },
    "status": {
      "type": "string",
      "enum": ["pending"],
      "description": "Always `pending`: a question is published once someone at the store has read it, which never happens inside this request."
    },
    "notifyByEmail": {
      "type": "boolean",
      "description": "Whether the asker will be emailed when the first answer is published."
    },
    "instantAnswer": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "answered": {
              "type": "boolean",
              "description": "True when the reviews address the question. False means the reviews do not say, which is an expected outcome rather than an error."
            },
            "answer": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "A short generated paragraph answering the question from the product's published reviews, in the language the question was asked in. Null when `answered` is false."
            },
            "reviewCount": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "How many published reviews the product had when the answer was generated."
            },
            "generatedAt": {
              "type": "string",
              "description": "When the answer was generated. Repeated questions are cached."
            },
            "citedReviews": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The review's id."
                  },
                  "rating": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991,
                    "description": "The review's star rating."
                  },
                  "title": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The review's headline, if it has one."
                  },
                  "excerpt": {
                    "type": "string",
                    "description": "The start of the review's body, cut at 300 characters."
                  },
                  "createdAt": {
                    "type": "string",
                    "description": "When the review was written."
                  }
                },
                "required": ["id", "rating", "title", "excerpt", "createdAt"],
                "additionalProperties": false
              },
              "description": "The published reviews the answer draws on. A review unpublished since the answer was generated is dropped from this list."
            }
          },
          "required": ["answered", "answer", "reviewCount", "generatedAt", "citedReviews"],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "An answer generated from the product's published reviews, to read while the store writes a real one. Null when the store does not have generated answers, the product has too few reviews, or the monthly allowance is used up. Its absence never stops the question being recorded."
    }
  },
  "required": ["questionId", "status", "notifyByEmail", "instantAnswer"],
  "additionalProperties": false
}

POST `/widgets/questions/{id}/answers`

Answer another shopper's published question. The answer waits for the store to approve it before it appears. Only available when the store allows shoppers to answer, which GET /widgets/questions reports as allowShopperAnswers.

Path Parameters

idstring (uuid)required

The ID of the published question being answered.

Query Parameters

apiPublishableKeystringrequired

Your organization's publishable key, from Settings, API keys.

Body Parameters

answerstringrequired

What this shopper wants to tell the person who asked.

visitorTokenstringrequired

Random id identifying the visitor's browser, used only for rate limiting.

namestring

The name to show above the answer. Omit to answer anonymously.

Request

curl \
  -X POST \
  "https://api.cascade.dev/widgets/questions/550e8400-e29b-41d4-a716-446655440000/answers?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "answer": "string",
  "visitorToken": "string",
  "name": "string"
}'

Request

import { client } from "@cascade-commerce/api/widget/client"
import { postWidgetsQuestionsByIdAnswers } from "@cascade-commerce/api/widget"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
})

const { data, error } = await postWidgetsQuestionsByIdAnswers({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
  query: { apiPublishableKey: "pk_YOUR_PUBLISHABLE_KEY" },
  body: {
    answer: "string",
    visitorToken: "string",
    name: "string",
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/widgets/questions/550e8400-e29b-41d4-a716-446655440000/answers?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY")
req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "answer": "string",
    "visitorToken": "string",
    "name": "string"
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "answer": "string",
  "visitorToken": "string",
  "name": "string"
}"""

req = Request(
    "https://api.cascade.dev/widgets/questions/550e8400-e29b-41d4-a716-446655440000/answers?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY",
    data=body.encode(),
    headers={"Content-Type": "application/json"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "answerId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "answerId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "The answer that is now waiting for moderation."
    },
    "status": {
      "type": "string",
      "enum": ["pending"],
      "description": "Always `pending`: an answer a shopper wrote is published by the store, not by them."
    }
  },
  "required": ["answerId", "status"],
  "additionalProperties": false
}

#Questions

GET /widgets/questions

Query Parameters

POST /widgets/questions

Query Parameters

Body Parameters

POST /widgets/questions/{id}/answers

Path Parameters

Query Parameters

Body Parameters

Questions

GET `/widgets/questions`

POST `/widgets/questions`

POST `/widgets/questions/{id}/answers`