> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.tiankii.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tiankii.com/_mcp/server. # List coupons GET https://api.md.tiankii.com/v1/payment-requests/{id}/coupons ## List coupons for a payment request Returns the coupons associated with the payment request identified by `:id`. Internally the payment request's id is injected as `forPaymentLinkId` into the coupon query, so only coupons that apply to this request are returned. The request must belong to the store resolved from the API key (a 404/validation error is raised otherwise). ### Authentication Send the merchant API key in `x-api-key` (alias `x-account-api-key`). Requires scope `Merchant.payment_link.read`. Optionally scope to a store with `x-application-account-id`. ### Path parameters - `id` — the payment request id. ### Query parameters (coupon filter) - `page`, `per_page` — pagination (defaults 1 / 10). - `discountType` — `ONE_TIME`, `REPEATING`, `UNLIMITED`. - `discountKind` — `FIXED`, `PERCENTAGE`. - `status` — `ACTIVE`, `INACTIVE`, `EXPIRED`, `MAXED_OUT`. - `paymentRequestApplicability` — `ALL`, `SPECIFIC`, `NONE`. - `filter` — free-text search across coupon `code`, `name`, `description`. - `sort` / `sorter` — order by allowed fields `code`, `createdAt`, `name`. There is **no request body**. --- **Notas:** Handler: paymentLinksService.getCoupons -> couponService.findMany with forPaymentLinkId injected from the path id. Accepts deprecated alias paths GET /v1/payment-links/:id/coupons and GET /v1/payment-link/:id/coupons. Coupon record shape is inferred from the Coupons model. Reference: https://docs.tiankii.com/api-reference/tiankii-api-api-key/payment-requests/general-operations/list-coupons ## Authentication - `x-api-key` header (required) ## Request ### Path parameters - `id` (string, required) — Id of the payment request whose coupons are listed. ### Query parameters - `page` (integer, optional, default: 1) — Page number to return. - `per_page` (integer, optional, default: 10) — Number of records per page. - `discountType` (enum, optional) — Filter by how often the coupon can be redeemed. - Allowed values: `ONE_TIME`, `REPEATING`, `UNLIMITED` - `discountKind` (enum, optional) — Filter by how the discount is calculated. - Allowed values: `FIXED`, `PERCENTAGE` - `status` (enum, optional) — Filter by coupon status. - Allowed values: `ACTIVE`, `INACTIVE`, `EXPIRED`, `MAXED_OUT` - `paymentRequestApplicability` (enum, optional) — Filter by which payment requests the coupon applies to. - Allowed values: `ALL`, `SPECIFIC`, `NONE` - `filter` (string, optional) — Filter with the query language. Accepts a string expression or a URL-encoded JSON object following Prisma's `where` clause. **Allowed fields:** `code`, `name`, `description` **Allowed operators:** `equals`, `not`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `contains`, `startsWith`, `endsWith`, `like` **String format:** `field:operator:value`, comma-separated. The operator defaults to `equals` (`field:value`), and `|` works as a separator. Group with `AND(...)` or `OR(...)` — `AND` is the default. **JSON format:** `{"OR":[{"name":{"contains":"Jane"}}]}` - `sort` (string, optional) — Sort by one or more fields, comma-separated. **Allowed fields:** `code`, `createdAt`, `name` **Formats:** `field` (ascending by default), `+field`, `-field`, `field:asc`, `field:desc` (`|` also works as the separator). - `sorter` (string, optional) — Alternative to `sort`: a JSON string mapping a field to a direction (`asc` / `desc`). **Allowed fields:** `createdAt`, `name`, `code` ### Headers - `x-application-account-id` (string, optional) — Scope the request to a specific store / account instead of the one resolved from the API key. Aliases: the `x-account-id` header, or the `application_account_id` / `account_id` query parameter. ## Examples **SDK Code** ```python import requests url = "https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons" querystring = {"filter":"AND(code:startsWith:SUMMER,name:contains:launch)","sort":"-createdAt","sorter":"{\"createdAt\":\"desc\"}"} headers = { "x-application-account-id": "acct_3f9a21c7", "x-api-key": "" } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons?filter=AND%28code%3AstartsWith%3ASUMMER%2Cname%3Acontains%3Alaunch%29&sort=-createdAt&sorter=%7B%22createdAt%22%3A%22desc%22%7D'; const options = { method: 'GET', headers: {'x-application-account-id': 'acct_3f9a21c7', 'x-api-key': ''} }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons?filter=AND%28code%3AstartsWith%3ASUMMER%2Cname%3Acontains%3Alaunch%29&sort=-createdAt&sorter=%7B%22createdAt%22%3A%22desc%22%7D" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-application-account-id", "acct_3f9a21c7") req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons?filter=AND%28code%3AstartsWith%3ASUMMER%2Cname%3Acontains%3Alaunch%29&sort=-createdAt&sorter=%7B%22createdAt%22%3A%22desc%22%7D") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-application-account-id"] = 'acct_3f9a21c7' request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons?filter=AND%28code%3AstartsWith%3ASUMMER%2Cname%3Acontains%3Alaunch%29&sort=-createdAt&sorter=%7B%22createdAt%22%3A%22desc%22%7D") .header("x-application-account-id", "acct_3f9a21c7") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons?filter=AND%28code%3AstartsWith%3ASUMMER%2Cname%3Acontains%3Alaunch%29&sort=-createdAt&sorter=%7B%22createdAt%22%3A%22desc%22%7D', [ 'headers' => [ 'x-api-key' => '', 'x-application-account-id' => 'acct_3f9a21c7', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons?filter=AND%28code%3AstartsWith%3ASUMMER%2Cname%3Acontains%3Alaunch%29&sort=-createdAt&sorter=%7B%22createdAt%22%3A%22desc%22%7D"); var request = new RestRequest(Method.GET); request.AddHeader("x-application-account-id", "acct_3f9a21c7"); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "x-application-account-id": "acct_3f9a21c7", "x-api-key": "" ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.md.tiankii.com/v1/payment-requests/A1B2C3D4E5F6A1B2/coupons?filter=AND%28code%3AstartsWith%3ASUMMER%2Cname%3Acontains%3Alaunch%29&sort=-createdAt&sorter=%7B%22createdAt%22%3A%22desc%22%7D")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```