API

Base URL and authorization

The default base URL is https://thanklyclub.com. Every request to /v1 sends the site key from your ThanklyClub dashboard and a few service headers.

• Authorization: Bearer <site_key>: the site key.
• X-ThanklyClub-Site: the store URL, for example https://shop.example/.
• X-ThanklyClub-Plugin: the plugin version, for example 0.1.0.
• Content-Type: application/json.

Errors

Any response with a non-2xx status is an error, and the body is {"error": "text"}. The plugin shows this text to the store owner. An invalid key returns 401, a blocked account 403, and an unknown method 404.

If the server is unavailable, the plugin shows the thank-you page without the gift block.

GET /v1/site: key check

Returns {"ok": true, "site_id": "...", "merchant": "..."}. The plugin calls it from the Test connection button.

POST /v1/analyze: AI store analysis

The body is {"store": {...}}, a catalog snapshot with the fields site (name, description, URL, locale), store (currency, country, ship-to countries, product count, minimum, median, and maximum price), categories (name and product count), and products (name, price, categories). The plugin waits up to 60 seconds for the response.

The response has store_profile (a short description, primary and secondary vertical, price segment, country), recommendations as a list of {category, decision, score, reason}, plus brand_safety, model, and analyzed_at.

category uses only ThanklyClub taxonomy keys; the plugin drops unknown ones. decision is allow, block, or review. The plugin also enforces its own rules: prohibited categories are always block, and sensitive ones are never allow.

POST /v1/offers: gifts for an order

Called once per order. The response is stored in the order, and the email shows the same gifts. The plugin-side timeout is 4 seconds.

Request body: context with the placement (thankyou or email), product categories and titles, the number of line items, an order total range (<25, 25-75, 75-200, 200+), currency, country, language, and a returning-customer flag; rules with allowed (enabled categories) and blocked_domains; and max, from 1 to 3. The request contains no personal data.

The response has request_id and an offers array. Each offer has id, category, brand, title, description, cta, image, domain, click_url, terms. Text is in the language from context.language. The plugin drops offers that are not in allowed and offers from domains in blocked_domains.

POST /v1/events: impressions

The body is {"events": [...]}, up to 50 events with type, offer_id, request_id, placement, ts. The plugin sends events without waiting for a response.

The server counts impressions (impression), once per request, offer, and placement. Clicks are counted by the server itself when a visitor goes through /c/, so click events are not used for statistics.

GET /v1/stats?days=30: statistics

Returns impressions, clicks, conversions, the store's earnings, and the amount pending for the given period (1 to 365 days). The currency is EUR. The plugin caches the response for 15 minutes.

Click: GET /c/<offer_id>?r=<request_id>

This is the click_url from the /v1/offers response. The server checks that the offer was part of that request and is active, records the click, and redirects the customer to the advertiser. A sub parameter with the click ID is added to the advertiser's URL. The p=email parameter marks a click from an email.

No more than three clicks are counted per offer from one order, as protection against click inflation. The redirect is sent with the Referrer-Policy: no-referrer header.

Postback: GET /postback

An advertiser or affiliate network reports a conversion with the request /postback?sub=<click id>&payout=<amount>&status=<status>&secret=<secret>.

sub is the value received in the redirect link. payout is the payout in euros; if omitted, the offer's rate is used. status is pending, approved, or rejected; the default is pending. secret is the postback secret that ThanklyClub issues at onboarding.

A repeat postback with the same sub updates the status and amount of the existing conversion. The store's share is calculated from payout at 60%. The response is {"ok": true, "conversion_id": "...", "status": "..."}.

FAQ