{
  "name": "terns-stamped-api-proxy",
  "description": "Authenticated passthrough to the Stamped.io Reviews and Loyalty API for a single shop. Send an Authorization: Bearer <token> header; Stamped credentials and the shop identifier are added by this proxy.",
  "usage": {
    "shopIdentifier": "Omit it. Paths below already exclude the shop segment; it is injected server-side. `/shops/_/` and `/shops/{shopId}/` are also accepted, as is dropping the leading /api.",
    "methods": "Use the method listed for each endpoint. GET endpoints are read-only and safe to explore.",
    "pagination": "List endpoints accept `page` (1-based). Page size is fixed and not adjustable: 25 on /api/v3/merchant/*, 20 on /api/v2/dashboard/*, 50 on /api/v2/survey/*. Only /api/v3/loyalty/* honours `limit`; elsewhere it is silently ignored.",
    "rateLimits": "Stamped throttles bursts. Issue requests sequentially rather than in parallel, and on a timeout wait a moment and retry once before treating it as an error.",
    "coverage": "Both API versions are required and do not overlap: /api/v3/* serves customer, product and order records plus loyalty; /api/v2/* is the only source of reviews, NPS, questions and review requests, as Stamped has not yet shipped a v3 reviews API.",
    "response": "JSON is returned exactly as Stamped sends it, with the upstream status code."
  },
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/v3/merchant/customers",
      "description": "Search/filter customer records. Text filters are begins-with matches; date and numeric filters are ranges.",
      "query": [
        "email",
        "firstName",
        "lastName",
        "lastFirst",
        "shopifyId",
        "bigcommerceId",
        "customCustomerId",
        "datePlatformCreated",
        "datePlatformCreatedEnd",
        "reviewsMin",
        "reviewsMax",
        "pointsMin",
        "pointsMax",
        "vipTier",
        "tags",
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/customers/{customerId}",
      "description": "Fetch one customer record by Stamped customer id, including loyalty activity summary.",
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/customers/lookup",
      "description": "Resolve a customer by an exact external identifier (email or platform id) rather than by Stamped id.",
      "query": [
        "email",
        "customCustomerId",
        "shopifyId",
        "bigcommerceId"
      ],
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/v3/merchant/customers",
      "description": "Create a customer record. On Shopify/BigCommerce the platform is the source of truth, so prefer syncing there. Creating a customer can trigger loyalty earning rules.",
      "body": [
        "email",
        "customCustomerId",
        "firstName",
        "lastName",
        "dateOfBirth",
        "datePlatformUpdated",
        "tags",
        "addresses"
      ],
      "access": "write"
    },
    {
      "method": "PATCH",
      "path": "/api/v3/merchant/customers/{customerId}",
      "description": "Patch fields on an existing customer record. Only supplied fields change.",
      "body": [
        "email",
        "customCustomerId",
        "firstName",
        "lastName",
        "dateOfBirth",
        "datePlatformUpdated",
        "tags",
        "addresses"
      ],
      "access": "write"
    },
    {
      "method": "DELETE",
      "path": "/api/v3/merchant/customers/{customerId}",
      "description": "Permanently delete a customer record and its associated Stamped data. Not reversible.",
      "access": "destructive"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/products",
      "description": "Search/filter the product catalog.",
      "query": [
        "title",
        "vendor",
        "type",
        "handle",
        "status",
        "publishedScope",
        "shopifyId",
        "bigcommerceId",
        "customProductId",
        "tags",
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/products/{productId}",
      "description": "Fetch one product record by Stamped product id.",
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/products/lookup",
      "description": "Resolve a product by an exact external platform identifier.",
      "query": [
        "customProductId",
        "shopifyId",
        "bigcommerceId"
      ],
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/v3/merchant/products",
      "description": "Create a product record. On Shopify/BigCommerce the platform is the source of truth.",
      "body": [
        "customProductId",
        "publishedScope",
        "status",
        "title",
        "htmlProductDescription",
        "vendor",
        "type",
        "handle",
        "datePublished",
        "datePlatformUpdated",
        "tags",
        "variants",
        "images"
      ],
      "access": "write"
    },
    {
      "method": "PATCH",
      "path": "/api/v3/merchant/products/{productId}",
      "description": "Patch fields on an existing product record.",
      "body": [
        "customProductId",
        "publishedScope",
        "status",
        "title",
        "htmlProductDescription",
        "vendor",
        "type",
        "handle",
        "datePublished",
        "datePlatformUpdated",
        "tags",
        "variants",
        "images"
      ],
      "access": "write"
    },
    {
      "method": "DELETE",
      "path": "/api/v3/merchant/products/{productId}",
      "description": "Permanently delete a product record. Reviews attached to it may become unreachable. Not reversible.",
      "access": "destructive"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/orders",
      "description": "List order records.",
      "query": [
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/orders/{orderId}",
      "description": "Fetch one order record by Stamped order id.",
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v3/merchant/orders/lookup",
      "description": "Resolve an order by an exact external platform identifier.",
      "query": [
        "customOrderId",
        "shopifyId",
        "bigcommerceId"
      ],
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/v3/merchant/orders",
      "description": "Create an order record. This starts the review-request schedule and is evaluated by the loyalty engine, so it can send customer email and award points.",
      "body": [
        "customOrderId",
        "customCustomerId",
        "customerId",
        "cart",
        "tags"
      ],
      "access": "write"
    },
    {
      "method": "PATCH",
      "path": "/api/v3/merchant/orders/{orderId}",
      "description": "Patch an order's cart, statuses, or totals.",
      "body": [
        "lineItems",
        "financialStatus",
        "fulfillmentStatus",
        "discountsApplied",
        "shopCurrency",
        "shopPriceDiscountTotal",
        "shopPriceItemsTotal",
        "shopPriceSubTotal",
        "shopPriceTotal",
        "shopPriceShipping",
        "shopPriceTax"
      ],
      "access": "write"
    },
    {
      "method": "DELETE",
      "path": "/api/v3/merchant/orders/{orderId}",
      "description": "Permanently delete an order record. Not reversible.",
      "access": "destructive"
    },
    {
      "method": "GET",
      "path": "/api/v3/loyalty/activities",
      "description": "Program-wide report of loyalty activity records (points earned, actions completed).",
      "query": [
        "page",
        "limit"
      ],
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v3/loyalty/rewards",
      "description": "Program-wide report of loyalty rewards and redemptions.",
      "query": [
        "page",
        "limit"
      ],
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/v3/loyalty/customers/{customerId}/adjust-points",
      "description": "Add or subtract loyalty points on a customer's balance. Points are real spendable value; a positive number grants them.",
      "body": [
        "points",
        "reason"
      ],
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/v3/loyalty/customers/{customerId}/adjust-vip-tier",
      "description": "Move a customer to a named VIP tier, overriding the tier the program rules would assign.",
      "body": [
        "tierName"
      ],
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/v3/loyalty/customers/{customerId}/redeem-reward/{rewardId}",
      "description": "Redeem a reward for a customer, spending their points and issuing a real coupon/discount.",
      "query": [
        "points"
      ],
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/v3/loyalty/customers/{customerId}/void-coupon/{couponCode}",
      "description": "Void a coupon previously issued to a customer. The customer loses access to that discount.",
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/v3/loyalty/customers/{customerId}/trigger-activity",
      "description": "Fire a configured earning rule for a customer, awarding whatever points that rule grants.",
      "query": [
        "ruleId",
        "title"
      ],
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/v3/loyalty/activities",
      "description": "Record a custom loyalty activity against a customer's email, optionally tied to a campaign.",
      "query": [
        "email",
        "campaignId"
      ],
      "body": "json",
      "access": "write"
    },
    {
      "method": "GET",
      "path": "/api/v2/dashboard/reviews",
      "description": "Dashboard review listing with search, rating, state and date filters.",
      "query": [
        "search",
        "rating",
        "state",
        "email",
        "dateFrom",
        "dateTo",
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v2/dashboard/nps/",
      "description": "Dashboard NPS responses with search, state, rating and date filters.",
      "query": [
        "search",
        "state",
        "rating",
        "dateFrom",
        "dateTo",
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/v2/dashboard/reviews/{reviewId}/publish",
      "description": "Publish a review so it appears publicly on the storefront.",
      "access": "write"
    },
    {
      "method": "POST",
      "path": "/api/v2/dashboard/reviews/{reviewId}/unpublish",
      "description": "Remove a review from public display without deleting it.",
      "access": "write"
    },
    {
      "method": "GET",
      "path": "/api/v2/dashboard/questions/",
      "description": "Dashboard listing of customer questions.",
      "query": [
        "search",
        "state",
        "dateFrom",
        "dateTo",
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/v2/dashboard/questions/{questionId}/reply",
      "description": "Post a merchant reply to a customer question. Replies are publicly visible and may email the asker.",
      "body": "json",
      "access": "write"
    },
    {
      "method": "GET",
      "path": "/api/v2/survey/reviews",
      "description": "List scheduled and sent review requests.",
      "query": [
        "filter",
        "state",
        "search",
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/v2/survey/reviews/{id}",
      "description": "Fetch one review request by id.",
      "access": "read-only"
    },
    {
      "method": "PUT",
      "path": "/api/v2/survey/reviews/{id}",
      "description": "Update a scheduled review request.",
      "body": "json",
      "access": "write"
    },
    {
      "method": "DELETE",
      "path": "/api/v2/survey/reviews/{id}",
      "description": "Permanently delete a review request. Not reversible.",
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/v2/survey/reviews/{id}/send",
      "description": "Immediately send a review request. This delivers real email to the customer.",
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/v2/survey/reviews/bulk",
      "description": "Create survey/review requests in bulk. Can queue email to many customers at once.",
      "body": "json",
      "access": "destructive"
    },
    {
      "method": "GET",
      "path": "/api/v2/account/groups",
      "description": "List product groups, which share reviews across grouped products.",
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/v2/account/groups",
      "description": "Create or update product groups.",
      "body": "json",
      "access": "write"
    },
    {
      "method": "POST",
      "path": "/api/v2/account/groups/{groupId}/delete",
      "description": "Delete a product group. Grouped products stop sharing reviews. Not reversible.",
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/widget/badges",
      "description": "Public rating badge data (average rating and counts) for products.",
      "query": [
        "productIds",
        "isIncludeBreakdown",
        "isincludehtml"
      ],
      "body": "json",
      "access": "read-only"
    },
    {
      "method": "GET",
      "path": "/api/widget/reviews",
      "description": "Public storefront review feed for a product, as the review widget sees it.",
      "query": [
        "productId",
        "productType",
        "productTitle",
        "email",
        "dateFrom",
        "dateTo",
        "sortReviews",
        "tags",
        "storeUrl",
        "page"
      ],
      "access": "read-only"
    },
    {
      "method": "POST",
      "path": "/api/reviews3",
      "description": "Submit a review as a customer would through the public endpoint. This creates real review content attributed to the email supplied.",
      "query": [
        "storeUrl"
      ],
      "body": "json",
      "access": "destructive"
    },
    {
      "method": "POST",
      "path": "/api/reviews/vote",
      "description": "Cast a helpful/unhelpful vote on a review.",
      "body": "json",
      "access": "write"
    },
    {
      "method": "POST",
      "path": "/api/questions",
      "description": "Submit a customer question through the public endpoint.",
      "body": "json",
      "access": "write"
    },
    {
      "method": "POST",
      "path": "/api/questions/vote",
      "description": "Cast a vote on a customer question.",
      "body": "json",
      "access": "write"
    }
  ],
  "mcp": "An MCP Streamable-HTTP endpoint with the same operations as tools is also served at POST /mcp."
}