{"openapi":"3.1.0","info":{"title":"Tulus Partner API","version":"1.0.0","description":"Manage coupons, report confirmed redemptions, read usage and analytics, and receive webhooks. Base URL: https://tulus.ee/api/v1 (live keys: tls_live_…)"},"servers":[{"url":"https://tulus.ee/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Partner dashboard → API & Integrations: tls_{test|live}_{key_id}_{secret}. Never send it in the URL."}},"schemas":{"Meta":{"type":"object","properties":{"request_id":{"type":"string"},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"},"total":{"type":"integer"}}}}},"Error":{"type":"object","properties":{"success":{"const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"CouponCreate":{"type":"object","required":["shop_id","title","code_type","discount_type"],"properties":{"shop_id":{"type":"string"},"status":{"type":"string","enum":["active","draft"]},"title":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":5000},"code_type":{"type":"string","enum":["public_code","exclusive_code","unique_codes","no_code"]},"code":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$","description":"Required for public_code/exclusive_code; must be null otherwise. Upper-cased."},"discount_type":{"type":"string","enum":["percentage","fixed_amount","free_shipping","other"]},"discount_value":{"type":["number","null"],"description":"percentage: 0 < v ≤ 100; fixed_amount: > 0; otherwise null. Decimals allowed."},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$","default":"EUR"},"min_purchase_amount":{"type":["number","null"]},"max_discount_amount":{"type":["number","null"],"description":"percentage discounts only"},"applies_to":{"type":"string","enum":["all","products","categories"],"default":"all"},"applicable_products":{"type":"array","items":{"type":"string"}},"applicable_categories":{"type":"array","items":{"type":"string"}},"excluded_products":{"type":"array","items":{"type":"string"}},"customer_eligibility":{"type":"string","enum":["all","new_customers","registered_customers","specific"],"default":"all"},"restrictions_note":{"type":["string","null"],"maxLength":500},"category_ids":{"type":"array","items":{"type":"string"},"description":"Tulus category slugs (max 5)"},"starts_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"ends_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"usage_limit_total":{"type":["integer","null"],"minimum":1},"usage_limit_per_customer":{"type":["integer","null"],"minimum":1},"visibility":{"type":"string","enum":["public","unlisted","private"],"default":"public"},"terms":{"type":["string","null"],"maxLength":5000},"landing_url":{"type":["string","null"],"format":"uri"},"external_reference":{"type":["string","null"],"maxLength":190,"description":"Your ID; unique per shop"},"external_ids":{"type":"object","additionalProperties":{"type":"string"},"description":"e.g. {\"external_coupon_id\":\"…\",\"external_product_id\":\"…\",\"external_campaign_id\":\"…\"}"},"offer_id":{"type":["string","null"]},"campaign_id":{"type":["string","null"]}}},"CouponUpdate":{"type":"object","properties":{"title":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":5000},"code_type":{"type":"string","enum":["public_code","exclusive_code","unique_codes","no_code"]},"code":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$","description":"Required for public_code/exclusive_code; must be null otherwise. Upper-cased."},"discount_type":{"type":"string","enum":["percentage","fixed_amount","free_shipping","other"]},"discount_value":{"type":["number","null"],"description":"percentage: 0 < v ≤ 100; fixed_amount: > 0; otherwise null. Decimals allowed."},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$","default":"EUR"},"min_purchase_amount":{"type":["number","null"]},"max_discount_amount":{"type":["number","null"],"description":"percentage discounts only"},"applies_to":{"type":"string","enum":["all","products","categories"],"default":"all"},"applicable_products":{"type":"array","items":{"type":"string"}},"applicable_categories":{"type":"array","items":{"type":"string"}},"excluded_products":{"type":"array","items":{"type":"string"}},"customer_eligibility":{"type":"string","enum":["all","new_customers","registered_customers","specific"],"default":"all"},"restrictions_note":{"type":["string","null"],"maxLength":500},"category_ids":{"type":"array","items":{"type":"string"},"description":"Tulus category slugs (max 5)"},"starts_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"ends_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"usage_limit_total":{"type":["integer","null"],"minimum":1},"usage_limit_per_customer":{"type":["integer","null"],"minimum":1},"visibility":{"type":"string","enum":["public","unlisted","private"],"default":"public"},"terms":{"type":["string","null"],"maxLength":5000},"landing_url":{"type":["string","null"],"format":"uri"},"external_reference":{"type":["string","null"],"maxLength":190,"description":"Your ID; unique per shop"},"external_ids":{"type":"object","additionalProperties":{"type":"string"},"description":"e.g. {\"external_coupon_id\":\"…\",\"external_product_id\":\"…\",\"external_campaign_id\":\"…\"}"},"offer_id":{"type":["string","null"]},"campaign_id":{"type":["string","null"]}}},"Coupon":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"coupon"},"shop":{"type":"object"},"status":{"type":"string","enum":["draft","pending_approval","scheduled","active","paused","expired","exhausted","rejected","archived"]},"is_verified":{"type":"boolean"},"public_url":{"type":["string","null"]},"rejection_reason":{"type":["string","null"]},"version":{"type":"integer"},"created_via":{"type":"string"},"usage":{"type":"object","properties":{"usage_limit_total":{"type":["integer","null"]},"usage_limit_per_customer":{"type":["integer","null"]},"confirmed_redemptions":{"type":"integer"},"remaining_uses":{"type":["integer","null"]}}},"unique_codes":{"type":"object","description":"Only for code_type=unique_codes"},"created_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"updated_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"last_synced_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"title":{"type":"string","maxLength":200},"description":{"type":["string","null"],"maxLength":5000},"code_type":{"type":"string","enum":["public_code","exclusive_code","unique_codes","no_code"]},"code":{"type":["string","null"],"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,63}$","description":"Required for public_code/exclusive_code; must be null otherwise. Upper-cased."},"discount_type":{"type":"string","enum":["percentage","fixed_amount","free_shipping","other"]},"discount_value":{"type":["number","null"],"description":"percentage: 0 < v ≤ 100; fixed_amount: > 0; otherwise null. Decimals allowed."},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$","default":"EUR"},"min_purchase_amount":{"type":["number","null"]},"max_discount_amount":{"type":["number","null"],"description":"percentage discounts only"},"applies_to":{"type":"string","enum":["all","products","categories"],"default":"all"},"applicable_products":{"type":"array","items":{"type":"string"}},"applicable_categories":{"type":"array","items":{"type":"string"}},"excluded_products":{"type":"array","items":{"type":"string"}},"customer_eligibility":{"type":"string","enum":["all","new_customers","registered_customers","specific"],"default":"all"},"restrictions_note":{"type":["string","null"],"maxLength":500},"category_ids":{"type":"array","items":{"type":"string"},"description":"Tulus category slugs (max 5)"},"starts_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"ends_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"usage_limit_total":{"type":["integer","null"],"minimum":1},"usage_limit_per_customer":{"type":["integer","null"],"minimum":1},"visibility":{"type":"string","enum":["public","unlisted","private"],"default":"public"},"terms":{"type":["string","null"],"maxLength":5000},"landing_url":{"type":["string","null"],"format":"uri"},"external_reference":{"type":["string","null"],"maxLength":190,"description":"Your ID; unique per shop"},"external_ids":{"type":"object","additionalProperties":{"type":"string"},"description":"e.g. {\"external_coupon_id\":\"…\",\"external_product_id\":\"…\",\"external_campaign_id\":\"…\"}"},"offer_id":{"type":["string","null"]},"campaign_id":{"type":["string","null"]}}},"RedemptionCreate":{"type":"object","required":["external_redemption_id"],"properties":{"external_redemption_id":{"type":"string","maxLength":190,"description":"Idempotency key per coupon — usually your order id"},"external_order_id":{"type":["string","null"]},"external_customer_reference":{"type":["string","null"],"description":"Stored only as a keyed hash; used for per-customer limits"},"coupon_code":{"type":["string","null"],"description":"Required for unique_codes; validated otherwise"},"redeemed_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"discount_amount":{"type":["number","null"]},"order_amount":{"type":["number","null"]},"currency":{"type":["string","null"]},"metadata":{"type":"object","maxProperties":20,"additionalProperties":{"type":["string","number","boolean","null"]}}}},"Redemption":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["confirmed","reversed"]},"external_redemption_id":{"type":"string"},"external_order_id":{"type":["string","null"]},"coupon_code":{"type":["string","null"]},"discount_amount":{"type":["number","null"]},"order_amount":{"type":["number","null"]},"currency":{"type":["string","null"]},"source":{"type":"string"},"has_customer_reference":{"type":"boolean"},"metadata":{"type":"object"},"redeemed_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"reversed_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"reversal_reason":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"}}},"Usage":{"type":"object","properties":{"confirmed_redemptions":{"type":"integer"},"remaining_uses":{"type":["integer","null"]},"lifetime":{"$ref":"#/components/schemas/Metrics"},"range":{"$ref":"#/components/schemas/Metrics"}}},"Metrics":{"type":"object","properties":{"views":{"type":"integer"},"unique_views":{"type":"integer"},"code_reveals":{"type":"integer"},"code_copies":{"type":"integer"},"outbound_clicks":{"type":"integer"},"unique_clicks":{"type":"integer"},"redemptions_confirmed":{"type":"integer"},"redemptions_rejected":{"type":"integer"},"redemptions_reversed":{"type":"integer"},"net_redemptions":{"type":"integer"},"discount_total":{"type":"number"},"order_total":{"type":"number"},"average_order_amount":{"type":["number","null"]},"ctr":{"type":["number","null"]},"redemption_rate":{"type":["number","null"]}}},"AnalyticsOverview":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"timezone":{"const":"UTC"},"metrics":{"$ref":"#/components/schemas/Metrics"},"series":{"type":"array"}}},"SyncRequest":{"type":"object","required":["shop_id","coupons"],"properties":{"shop_id":{"type":"string"},"mode":{"type":"string","enum":["upsert","full"],"default":"upsert"},"conflict_policy":{"type":"string","enum":["skip","overwrite"],"default":"skip"},"dry_run":{"type":"boolean","default":false},"coupons":{"type":"array","maxItems":500,"items":{"allOf":[{"$ref":"#/components/schemas/CouponCreate"},{"required":["external_reference"]}]}}}},"SyncResult":{"type":"object","properties":{"sync_id":{"type":"string"},"summary":{"type":"object"},"results":{"type":"array","items":{"type":"object","properties":{"external_reference":{"type":"string"},"action":{"type":"string","enum":["created","updated","unchanged","archived","conflict","error"]},"id":{"type":["string","null"]}}}}}},"BulkCreate":{"type":"object","required":["shop_id","coupons"],"properties":{"shop_id":{"type":"string"},"status":{"type":"string","enum":["active","draft"]},"coupons":{"type":"array","maxItems":5000,"items":{"$ref":"#/components/schemas/CouponUpdate"}}}},"CodeBatchCreate":{"type":"object","properties":{"count":{"type":"integer","maximum":100000},"prefix":{"type":"string","maxLength":16},"length":{"type":"integer","minimum":6,"maximum":32},"codes":{"type":"array","maxItems":5000,"items":{"type":"string"}}}},"CodeBatch":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"requested_count":{"type":"integer"},"generated_count":{"type":"integer"}}},"Code":{"type":"object","properties":{"code":{"type":"string"},"status":{"type":"string"},"assigned_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"},"redeemed_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"}}},"Operation":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"total":{"type":"integer"},"processed":{"type":"integer"},"result":{"type":["object","null"]},"download_url":{"type":["string","null"]}}},"OperationRef":{"type":"object","properties":{"operation_id":{"type":"string"},"status":{"type":"string"},"status_url":{"type":"string"}}},"Category":{"type":"object","properties":{"object":{"type":"string"},"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"icon":{"type":["string","null"]}}},"Shop":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"website_url":{"type":["string","null"]},"status":{"type":"string"},"is_verified":{"type":"boolean"},"active_coupon_count":{"type":"integer"}}},"Credential":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"environment":{"type":"string"},"scopes":{"type":"array"},"shop_ids":{"type":"array"},"rate_limit_per_minute":{"type":"integer"},"expires_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"}}},"WebhookCreate":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","description":"Public https URL, port 443/8443"},"events":{"type":"array","items":{"type":"string","enum":["*","coupon.created","coupon.updated","coupon.activated","coupon.paused","coupon.expired","coupon.archived","coupon.usage_limit_reached","coupon.redemption.created","coupon.redemption.reversed","campaign.updated"]}},"description":{"type":["string","null"]}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array"},"status":{"type":"string","enum":["pending_verification","active","disabled"]},"secret":{"type":"string","description":"Only in create/rotate responses"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"event_type":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"},"last_response_status":{"type":["integer","null"]},"next_attempt_at":{"type":["string","null"],"format":"date-time","description":"ISO-8601, UTC (Z)"}}}},"responses":{"BadRequest":{"description":"Malformed request (e.g. invalid JSON, credentials in URL)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, revoked, suspended or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks a required scope (INSUFFICIENT_SCOPE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found — also returned for resources of shops the key may not access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"VALIDATION_ERROR with per-field messages, or a business-rule rejection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limit exceeded; see Retry-After and X-RateLimit-* headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/me":{"get":{"summary":"Describe the current API key","description":"","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Credential"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shops":{"get":{"summary":"List shops this key may access","description":"\n\nRequired scope: `shops.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Shop"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/categories":{"get":{"summary":"List public coupon categories (ids for category_ids)","description":"\n\nRequired scope: `coupons.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shops/{id}":{"get":{"summary":"Get a shop","description":"\n\nRequired scope: `shops.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Shop"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}},"/coupons":{"get":{"summary":"List coupons","description":"\n\nRequired scope: `coupons.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Coupon"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.pagination.next_cursor from the previous page"},{"name":"shop_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"active","in":"query","schema":{"type":"string"}},{"name":"starts_after","in":"query","schema":{"type":"string"}},{"name":"ends_before","in":"query","schema":{"type":"string"}},{"name":"updated_after","in":"query","schema":{"type":"string"}},{"name":"external_reference","in":"query","schema":{"type":"string"}},{"name":"campaign_id","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string"}}]},"post":{"summary":"Create a coupon","description":"Send `\"status\":\"active\"` to publish immediately (untrusted partners: goes to review → pending_approval).\n\nRequired scope: `coupons.create`","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponCreate"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/{id}":{"get":{"summary":"Get a coupon","description":"\n\nRequired scope: `coupons.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]},"patch":{"summary":"Partially update a coupon","description":"\n\nRequired scope: `coupons.update`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"409":{"description":"Coupon archived"},"412":{"description":"If-Match version conflict"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponUpdate"}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."},{"name":"If-Match","in":"header","schema":{"type":"string"},"description":"Coupon `version` for optimistic concurrency"}]},"put":{"summary":"Replace a coupon (omitted optional fields reset to defaults)","description":"\n\nRequired scope: `coupons.update`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponCreate"}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/{id}/activate":{"post":{"summary":"Publish / resume (optionally schedule with starts_at/ends_at)","description":"\n\nRequired scope: `coupons.activate`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"}}}}}}}},"/coupons/{id}/pause":{"post":{"summary":"Pause a coupon","description":"\n\nRequired scope: `coupons.pause`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/{id}/archive":{"post":{"summary":"Archive a coupon (irreversible; duplicate to reuse)","description":"\n\nRequired scope: `coupons.archive`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/{id}/duplicate":{"post":{"summary":"Duplicate as a new draft","description":"\n\nRequired scope: `coupons.create`","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Coupon"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/bulk":{"post":{"summary":"Bulk create (≤50 inline, ≤5000 async)","description":"\n\nRequired scope: `coupons.create`","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"202":{"description":"Accepted (async)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/OperationRef"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreate"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/sync":{"post":{"summary":"Synchronise coupons by external_reference","description":"\n\nRequired scope: `coupons.sync`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/SyncResult"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRequest"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/export":{"get":{"summary":"Export coupons as CSV/JSON (≤1000 inline, larger async)","description":"\n\nRequired scope: `coupons.export`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"File download"},"202":{"description":"Accepted (async)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/OperationRef"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json"]}}]}},"/coupons/{id}/usage":{"get":{"summary":"Usage: limits, confirmed redemptions, measured engagement","description":"\n\nRequired scope: `coupon_usage.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Usage"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}]}},"/coupons/{id}/analytics":{"get":{"summary":"Time series for one coupon","description":"\n\nRequired scope: `analytics.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group","in":"query","schema":{"type":"string","enum":["day","week","month"]}}]}},"/coupons/{id}/redemptions":{"get":{"summary":"List confirmed/reversed redemptions","description":"\n\nRequired scope: `coupon_redemptions.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Redemption"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.pagination.next_cursor from the previous page"}]},"post":{"summary":"Report a confirmed redemption (idempotent on external_redemption_id)","description":"\n\nRequired scope: `coupon_redemptions.create`","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Redemption"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"200":{"description":"Already reported (meta.duplicate = true)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Redemption"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedemptionCreate"}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupons/{id}/redemptions/{redemption}/reverse":{"post":{"summary":"Reverse (cancel) a redemption","description":"\n\nRequired scope: `coupon_redemptions.create`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Redemption"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"redemption","in":"path","required":true,"schema":{"type":"string"},"description":"Redemption id or your external_redemption_id"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":255}}}}}}}},"/coupons/{id}/codes":{"get":{"summary":"List single-use codes","description":"\n\nRequired scope: `coupon_codes.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Code"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"status","in":"query","schema":{"type":"string","enum":["available","assigned","redeemed","void"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.pagination.next_cursor from the previous page"}]}},"/coupons/{id}/codes/bulk":{"post":{"summary":"Generate (async) or import single-use codes","description":"\n\nRequired scope: `coupon_codes.create`","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CodeBatch"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CodeBatch"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeBatchCreate"}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/coupon-code-batches/{id}":{"get":{"summary":"Code batch status","description":"\n\nRequired scope: `coupon_codes.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/CodeBatch"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}},"/operations/{id}":{"get":{"summary":"Async operation status","description":"","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/Operation"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}},"/operations/{id}/download":{"get":{"summary":"Download an export result","description":"","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"File"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}},"/analytics/overview":{"get":{"summary":"Totals for a period (optionally with series via group)","description":"\n\nRequired scope: `analytics.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/AnalyticsOverview"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group","in":"query","schema":{"type":"string","enum":["day","week","month"]}},{"name":"shop_id","in":"query","schema":{"type":"string"}},{"name":"coupon_id","in":"query","schema":{"type":"string"}},{"name":"campaign_id","in":"query","schema":{"type":"string"}}]}},"/analytics/coupons":{"get":{"summary":"Per-coupon breakdown","description":"\n\nRequired scope: `analytics.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group","in":"query","schema":{"type":"string","enum":["day","week","month"]}},{"name":"shop_id","in":"query","schema":{"type":"string"}},{"name":"coupon_id","in":"query","schema":{"type":"string"}},{"name":"campaign_id","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string"}},{"name":"offset","in":"query","schema":{"type":"integer"}}]}},"/analytics/shops":{"get":{"summary":"Per-shop breakdown","description":"\n\nRequired scope: `analytics.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group","in":"query","schema":{"type":"string","enum":["day","week","month"]}},{"name":"shop_id","in":"query","schema":{"type":"string"}},{"name":"coupon_id","in":"query","schema":{"type":"string"}},{"name":"campaign_id","in":"query","schema":{"type":"string"}}]}},"/analytics/redemptions":{"get":{"summary":"Redemption log across shops, or series with group=","description":"\n\nRequired scope: `analytics.read`, `coupon_redemptions.read`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Redemption"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group","in":"query","schema":{"type":"string","enum":["day","week","month"]}},{"name":"shop_id","in":"query","schema":{"type":"string"}},{"name":"coupon_id","in":"query","schema":{"type":"string"}},{"name":"campaign_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.pagination.next_cursor from the previous page"}]}},"/webhooks":{"get":{"summary":"List webhook endpoints","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"summary":"Create a webhook endpoint (signing secret returned once)","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreate"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}]}},"/webhooks/{id}":{"get":{"summary":"Get an endpoint","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]},"patch":{"summary":"Update URL, events or enabled","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Recommended on every write. Same key + same body replays the stored response for 24 h."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}}},"delete":{"summary":"Delete an endpoint","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}},"/webhooks/{id}/rotate-secret":{"post":{"summary":"Rotate the signing secret (old one valid 24 h)","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/WebhookEndpoint"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}},"/webhooks/{id}/ping":{"post":{"summary":"Send a test webhook.ping","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}},"/webhooks/{id}/deliveries":{"get":{"summary":"Delivery log","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"meta.pagination.next_cursor from the previous page"}]}},"/webhook-deliveries/{id}/retry":{"post":{"summary":"Retry a failed delivery (same event id)","description":"\n\nRequired scope: `webhooks.manage`","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":true},"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Z]{26}$"},"description":"Public ID (ULID)"}]}}}}