Meisei

    Surveys

    GET /surveys

    List review requests, newest first by default. Supports search, filtering and cursor pagination. To find requests nobody has answered, filter on {"reviews": 0} beside requestCount and lastRequestedAt.

    Requires the surveys:read permission.

    Query parameters

    limitnumber

    The number of records to return.

    cursorstring

    A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

    sortcreatedAt | -createdAt | nextActionAt | -nextActionAt | lastRequestedAt | -lastRequestedAt

    The sort order. Prefix a field with - to sort descending. Defaults to -createdAt.

    searchstring

    A free-text search term. Every word has to match, from the start of a word, in any order and ignoring case and accents, against the record's most identifying fields. Combined with filter using AND.

    filterstring

    A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, token, orderId, requestCount, lastRequestedAt, nextActionAt, createdAt, customer.id, customer.email, customer.firstName, customer.lastName, customer.metadata, customer.emailOptOut, customer.emailOptOutSource, customer.createdAt, product.id, product.slug, product.title, product.metadata, product.averageRating, product.ratingCount, product.createdAt, reviews.rating, reviews.createdAt. See Filtering for the syntax.

    includestring

    A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: order, customer.

    Request
    curl \
  "https://your-store.meisei.app/api/surveys" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "data": [
    {
      "id": "A4Ws1igz",
      "orderId": "A4Ws1igz",
      "token": "string",
      "includedProducts": ["..."],
      "reviewUrl": "string",
      "nextActionAt": "2025-01-15T09:30:00Z",
      "requestCount": 0,
      "lastRequestedAt": "2025-01-15T09:30:00Z",
      "reviewCount": 0,
      "error": "string",
      "status": "scheduled",
      "metadata": "...",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "order": {
        "id": "...",
        "siteId": "...",
        "customerId": "...",
        "remoteId": "...",
        "number": "...",
        "totalCents": "...",
        "subtotalCents": "...",
        "shippingCents": "...",
        "taxCents": "...",
        "currencyCode": "...",
        "shippedAt": "...",
        "deliveredAt": "...",
        "cancelledAt": "...",
        "metadata": "...",
        "notes": "...",
        "createdAt": "...",
        "updatedAt": "..."
      },
      "customer": {
        "id": "...",
        "email": "...",
        "phone": "...",
        "firstName": "...",
        "lastName": "...",
        "country": "...",
        "metadata": "...",
        "notes": "...",
        "emailOptOut": "...",
        "emailOptOutAt": "...",
        "emailOptOutSource": "...",
        "createdAt": "...",
        "updatedAt": "..."
      }
    }
  ],
  "nextCursor": "string"
}

    POST /surveys

    Open a review request for an order, which gives the order a review link. This is how an organization whose review request trigger is custom asks for reviews. An order has at most one review request, so a second one answers with a 409. Pass send: true to send it straight away.

    Requires the surveys:write permission.

    Body parameters

    orderIdstringrequired

    The order to ask about. An order has at most one review request.

    sendboolean

    Whether to send the request straight away, through the organization's review request channel. Defaults to false, which leaves it unsent so you can render it or send it later.

    metadataobject

    Free-form string key/value pairs for your own data.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/surveys" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "string",
  "send": true,
  "metadata": "..."
}'
    Response
    {
  "id": "A4Ws1igz",
  "orderId": "A4Ws1igz",
  "token": "string",
  "includedProducts": [
    {
      "id": "A4Ws1igz",
      "title": "string",
      "reviewUrl": "string",
      "ratingUrls": ["..."]
    }
  ],
  "reviewUrl": "string",
  "nextActionAt": "2025-01-15T09:30:00Z",
  "requestCount": 0,
  "lastRequestedAt": "2025-01-15T09:30:00Z",
  "reviewCount": 0,
  "error": "string",
  "status": "scheduled",
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

    GET /surveys/{id}

    Get a single review request by ID.

    Requires the surveys:read permission.

    Path parameters

    idstringrequired

    The ID of the review request.

    Query parameters

    includestring

    A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: order, customer.

    Request
    curl \
  "https://your-store.meisei.app/api/surveys/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "A4Ws1igz",
  "orderId": "A4Ws1igz",
  "token": "string",
  "includedProducts": [
    {
      "id": "A4Ws1igz",
      "title": "string",
      "reviewUrl": "string",
      "ratingUrls": ["..."]
    }
  ],
  "reviewUrl": "string",
  "nextActionAt": "2025-01-15T09:30:00Z",
  "requestCount": 0,
  "lastRequestedAt": "2025-01-15T09:30:00Z",
  "reviewCount": 0,
  "error": "string",
  "status": "scheduled",
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "order": {
    "id": "A4Ws1igz",
    "siteId": "A4Ws1igz",
    "customerId": "A4Ws1igz",
    "remoteId": "string",
    "number": "string",
    "totalCents": 0,
    "subtotalCents": 0,
    "shippingCents": 0,
    "taxCents": 0,
    "currencyCode": "string",
    "shippedAt": "2025-01-15T09:30:00Z",
    "deliveredAt": "2025-01-15T09:30:00Z",
    "cancelledAt": "2025-01-15T09:30:00Z",
    "metadata": "...",
    "notes": "string",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  },
  "customer": {
    "id": "A4Ws1igz",
    "email": "user@example.com",
    "phone": "string",
    "firstName": "string",
    "lastName": "string",
    "country": "string",
    "metadata": "...",
    "notes": "string",
    "emailOptOut": true,
    "emailOptOutAt": "2025-01-15T09:30:00Z",
    "emailOptOutSource": "customer",
    "createdAt": "2025-01-15T09:30:00Z",
    "updatedAt": "2025-01-15T09:30:00Z"
  }
}

    DELETE /surveys/{id}

    Delete a review request before it goes out, so it is never sent. A request that has already been sent, or that has collected a review, is part of the audit trail and can't be deleted: those requests answer with a 409. Triggers the survey.deleted webhook.

    Requires the surveys:write permission.

    Path parameters

    idstringrequired

    The ID of the review request to delete.

    Request
    curl \
  -X DELETE \
  "https://your-store.meisei.app/api/surveys/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "id": "A4Ws1igz",
  "orderId": "A4Ws1igz",
  "token": "string",
  "includedProducts": [
    {
      "id": "A4Ws1igz",
      "title": "string",
      "reviewUrl": "string",
      "ratingUrls": ["..."]
    }
  ],
  "reviewUrl": "string",
  "nextActionAt": "2025-01-15T09:30:00Z",
  "requestCount": 0,
  "lastRequestedAt": "2025-01-15T09:30:00Z",
  "reviewCount": 0,
  "error": "string",
  "status": "scheduled",
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

    POST /surveys/{id}/send

    Send a review request now, through the organization's review request channel: an email from the default review request template (or the one you choose), or the reviewRequest.eligible event when Klaviyo sends it. Call it again on a request nobody has answered to send a follow-up, passing a reminder template if you wrote one. The body is optional. A customer who has opted out of marketing email, an imported customer who has never been emailed, and an organization whose sending is paused each answer with a 409 saying so, and nothing is sent.

    Requires the surveys:write permission.

    Path parameters

    idstringrequired

    The ID of the review request to send.

    Body parameters

    templateIdstring

    A review request email template to send instead of the default, such as a reminder you wrote for follow-ups. Leave it out to send the default. Can't be used when Klaviyo sends the organization's review requests.

    Request
    curl \
  -X POST \
  "https://your-store.meisei.app/api/surveys/A4Ws1igz/send" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "templateId": "string"
}'
    Response
    {
  "id": "A4Ws1igz",
  "orderId": "A4Ws1igz",
  "token": "string",
  "includedProducts": [
    {
      "id": "A4Ws1igz",
      "title": "string",
      "reviewUrl": "string",
      "ratingUrls": ["..."]
    }
  ],
  "reviewUrl": "string",
  "nextActionAt": "2025-01-15T09:30:00Z",
  "requestCount": 0,
  "lastRequestedAt": "2025-01-15T09:30:00Z",
  "reviewCount": 0,
  "error": "string",
  "status": "scheduled",
  "metadata": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}