{"openapi":"3.1.0","info":{"title":"Gia's Giraffes API","version":"1.0.0","description":"Send gifts, keep contacts in sync and read the catalog from your own tools (Pro). Keys: Settings → Developers → API keys.\n\nScopes: `read` (Read only), `draft` (Read and draft), `send` (Read, draft and send). A request outside the key's scope gets 403 with code `insufficient_scope`.\nModes: `gg_live_…` keys act on live data; `gg_test_…` keys only ever see and create test data and never make real charges, orders or texts.\nRate limit: 120 requests a minute per key (429 with Retry-After). Rotating a key keeps the old one working for 24 hours.\nWebhooks are signed (GG-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">). An endpoint failing 10+ times in a row over 24+ hours is turned off.","contact":{"email":"hello@giasgiraffes.com"}},"servers":[{"url":"https://www.giasgiraffes.com"}],"externalDocs":{"url":"https://www.giasgiraffes.com/docs/api","description":"Guides, quickstart and examples"},"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key: gg_live_… (live) or gg_test_… (test)."}}},"paths":{"/api/v1/contacts":{"get":{"operationId":"listContacts","summary":"List contacts","description":"Your contacts (your team's shared contacts on a team), filtered by tag or email.","tags":["contacts"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000}},{"name":"tag","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"email","in":"query","required":false,"schema":{"type":"string","maxLength":254,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}],"responses":{"200":{"description":"A page of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"name":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"phones":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"type":{"type":"string"}},"required":["number","type"],"additionalProperties":false}},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"birthday":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"anniversary":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"work_anniversary":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"client_since":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"other_occasions":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"date":{"type":"string"}},"required":["label","date"],"additionalProperties":false}},"test":{"description":"Test data (made with a test key).","type":"boolean"}},"required":["id","name","emails","phones","company","title","tags","birthday","anniversary","work_anniversary","client_since","other_occasions","test"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["data","limit","offset"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"createContact","summary":"Add a contact","description":"Same validation as the app's contact form. A test key adds a test contact.","tags":["contacts"],"x-required-scope":"draft","security":[{"bearerAuth":["gifts.read","gifts.draft"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"emails":{"maxItems":5,"type":"array","items":{"type":"string"}},"email":{"type":"string"},"phones":{"maxItems":5,"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"number":{"type":"string"},"type":{"type":"string","enum":["mobile","work","home","other"]}},"required":["number"]}]}},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"birthday":{"anyOf":[{"description":"YYYY-MM-DD, or MM-DD when the year isn't known","type":"string","maxLength":10},{"type":"null"}]},"anniversary":{"anyOf":[{"description":"YYYY-MM-DD, or MM-DD when the year isn't known","type":"string","maxLength":10},{"type":"null"}]},"work_anniversary":{"anyOf":[{"description":"YYYY-MM-DD, or MM-DD when the year isn't known","type":"string","maxLength":10},{"type":"null"}]},"client_since":{"anyOf":[{"description":"YYYY-MM-DD, or MM-DD when the year isn't known","type":"string","maxLength":10},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"The new contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"name":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"phones":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"type":{"type":"string"}},"required":["number","type"],"additionalProperties":false}},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}},"birthday":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"anniversary":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"work_anniversary":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"client_since":{"description":"YYYY-MM-DD, or --MM-DD when the year isn't known","anyOf":[{"type":"string"},{"type":"null"}]},"other_occasions":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"date":{"type":"string"}},"required":["label","date"],"additionalProperties":false}},"test":{"description":"Test data (made with a test key).","type":"boolean"}},"required":["id","name","emails","phones","company","title","tags","birthday","anniversary","work_anniversary","client_since","other_occasions","test"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid JSON or field types","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"A contact with that email already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Valid JSON the form would refuse","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/gifts":{"get":{"operationId":"listGifts","summary":"List gifts","description":"Gifts you sent, newest first. Add email= for one recipient's gift history.","tags":["gifts"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["sent","opened","accepted","ordered","shipped","delivered","cancelled"]}},{"name":"email","in":"query","required":false,"schema":{"description":"Only gifts to this recipient email (case-insensitive): one contact's gift history.","type":"string","maxLength":254,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"description":"Only gifts to this recipient email (case-insensitive): one contact's gift history."}],"responses":{"200":{"description":"A page of gifts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"ref":{"type":"string"},"link":{"description":"The recipient's gift page","type":"string"},"status":{"type":"string"},"mode":{"type":"string","enum":["one","choice"]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email"],"additionalProperties":false},"occasion":{"anyOf":[{"type":"string"},{"type":"null"}]},"budget_cents":{"description":"The most it can cost (charged on acceptance, never above this)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"smart_link_id":{"description":"The GG Link it was claimed from","anyOf":[{"type":"string"},{"type":"null"}]},"automation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign":{"description":"The GG Link campaign tag the claim carried (null for a gift sent directly)","anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"accepted_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"test":{"description":"A test gift: never charged, ordered or texted.","type":"boolean"},"items":{"description":"What they accepted, one entry per gift (several when the recipient picked more than one); empty until accepted","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"title":{"type":"string"},"status":{"type":"string"},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","status","shipped_at","delivered_at"],"additionalProperties":false}}},"required":["id","ref","link","status","mode","recipient","occasion","budget_cents","charged_cents","smart_link_id","automation_id","contact_id","campaign","created_at","opened_at","accepted_at","shipped_at","delivered_at","cancelled_at","expires_at","test","items"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["data","limit","offset"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"createGift","summary":"Send a gift","description":"Sends now, from your saved card (charged only when they accept). Counts against the key's spending limits and your team's AI and API cap, reserved atomically, so parallel requests can't go over. Send an Idempotency-Key header so a retry never sends twice.","tags":["gifts"],"x-required-scope":"send","security":[{"bearerAuth":["gifts.read","gifts.draft","gifts.send"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Any unique string (a UUID is ideal). A retry with the same key within 24 hours returns the first response and sends nothing."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"additionalProperties":false},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"budget_cents":{"description":"Their choice of any gift up to this budget, in cents. One of: 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12500, 15000, 17500, 20000, 25000, 30000, 35000.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"item_id":{"description":"Or this one gift (they can swap it unless allow_swap is false).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"allow_swap":{"type":"boolean"},"note":{"default":"","type":"string","maxLength":600},"occasion":{"type":"string","maxLength":40},"delivery":{"description":"email: we email them the link. link: you share it yourself (returned as `link`).","type":"string","enum":["email","link"]},"sender_name":{"type":"string","minLength":1,"maxLength":80}},"additionalProperties":false}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"ref":{"type":"string"},"link":{"description":"The recipient's gift page","type":"string"},"status":{"type":"string"},"mode":{"type":"string","enum":["one","choice"]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email"],"additionalProperties":false},"occasion":{"anyOf":[{"type":"string"},{"type":"null"}]},"budget_cents":{"description":"The most it can cost (charged on acceptance, never above this)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"smart_link_id":{"description":"The GG Link it was claimed from","anyOf":[{"type":"string"},{"type":"null"}]},"automation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign":{"description":"The GG Link campaign tag the claim carried (null for a gift sent directly)","anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"accepted_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"test":{"description":"A test gift: never charged, ordered or texted.","type":"boolean"},"items":{"description":"What they accepted, one entry per gift (several when the recipient picked more than one); empty until accepted","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"title":{"type":"string"},"status":{"type":"string"},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","status","shipped_at","delivered_at"],"additionalProperties":false}}},"required":["id","ref","link","status","mode","recipient","occasion","budget_cents","charged_cents","smart_link_id","automation_id","contact_id","campaign","created_at","opened_at","accepted_at","shipped_at","delivered_at","cancelled_at","expires_at","test","items"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"202":{"description":"Over your monthly team budget: waiting for an owner's or admin's approval","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","const":"pending_approval"},"approval_id":{"type":"string"},"message":{"type":"string"}},"required":["status","approval_id","message"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid request (or Idempotency-Key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"No saved card (add one in the app; you're charged only when a gift is accepted)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Contact or draft not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"A request with this Idempotency-Key is still running, or a live key on a deployment running Stripe test keys (code live_mode_unavailable)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Can't be done (for example over a spending limit: code limit_exceeded), or the Idempotency-Key was used with a different request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/gifts/{id}":{"get":{"operationId":"getGift","summary":"Get a gift","description":"By its id or its ref (the code in the gift link).","tags":["gifts"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id (or, for gifts, the ref from the gift link)"}],"responses":{"200":{"description":"The gift","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"ref":{"type":"string"},"link":{"description":"The recipient's gift page","type":"string"},"status":{"type":"string"},"mode":{"type":"string","enum":["one","choice"]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email"],"additionalProperties":false},"occasion":{"anyOf":[{"type":"string"},{"type":"null"}]},"budget_cents":{"description":"The most it can cost (charged on acceptance, never above this)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"smart_link_id":{"description":"The GG Link it was claimed from","anyOf":[{"type":"string"},{"type":"null"}]},"automation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign":{"description":"The GG Link campaign tag the claim carried (null for a gift sent directly)","anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"accepted_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"test":{"description":"A test gift: never charged, ordered or texted.","type":"boolean"},"items":{"description":"What they accepted, one entry per gift (several when the recipient picked more than one); empty until accepted","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"title":{"type":"string"},"status":{"type":"string"},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","status","shipped_at","delivered_at"],"additionalProperties":false}}},"required":["id","ref","link","status","mode","recipient","occasion","budget_cents","charged_cents","smart_link_id","automation_id","contact_id","campaign","created_at","opened_at","accepted_at","shipped_at","delivered_at","cancelled_at","expires_at","test","items"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Not found (or not yours, or the other mode's)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/gift-drafts":{"post":{"operationId":"createGiftDraft","summary":"Draft a gift","description":"Nothing is sent. Returns a draft id and the full summary (recipient, gift, note, the most it can cost, the card, the key's remaining limits). Drafts last 24 hours; send one with POST /gift-drafts/{id}/send.","tags":["gift drafts"],"x-required-scope":"draft","security":[{"bearerAuth":["gifts.read","gifts.draft"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"recipient":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["name"]},"budget_cents":{"description":"The most it can cost, in cents. One of: 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12500, 15000, 17500, 20000, 25000, 30000, 35000.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"item_id":{"description":"One gift from search_catalog (they can swap it unless allow_swap is false).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"allow_swap":{"default":true,"type":"boolean"},"note":{"description":"Your message, shown on their gift page.","default":"","type":"string","maxLength":600},"occasion":{"type":"string","maxLength":40},"delivery":{"description":"email (default when there's an email): we email them. link: you get a link to share yourself.","type":"string","enum":["email","link"]},"from_name":{"description":"Your name as they'll see it (default: your From name in Settings).","type":"string","minLength":1,"maxLength":80}}}}}},"responses":{"201":{"description":"The draft and its summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"draft_id":{"type":"string"},"status":{"type":"string"},"expires_at":{"type":"string"},"recipient":{"type":"object","properties":{"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email","contact_id"],"additionalProperties":false},"delivery":{"description":"email: we email them the gift. link: you get a link to share yourself.","type":"string","enum":["email","link"]},"gift":{"type":"object","properties":{"type":{"type":"string","enum":["their_choice","one_gift"]},"budget_cents":{"anyOf":[{"type":"number"},{"type":"null"}]},"item_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_can_swap":{"type":"boolean"},"options_available":{"description":"Their choice: how many gifts they can pick from.","anyOf":[{"type":"number"},{"type":"null"}]}},"required":["type","budget_cents","item_id","title","recipient_can_swap","options_available"],"additionalProperties":false},"note":{"type":"string"},"occasion":{"anyOf":[{"type":"string"},{"type":"null"}]},"from_name":{"type":"string"},"max_cost_cents":{"description":"The most you can be charged. You're charged only if they accept, never more than this.","type":"number"},"payment":{"type":"object","properties":{"card":{"type":"string"},"when":{"type":"string"}},"required":["card","when"],"additionalProperties":false},"recipient_sees_price":{"type":"boolean","const":false},"limits":{"type":"object","properties":{"per_gift_cents":{"anyOf":[{"type":"number"},{"type":"null"}]},"remaining_today_cents":{"anyOf":[{"type":"number"},{"type":"null"}]},"remaining_this_month_cents":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["per_gift_cents","remaining_today_cents","remaining_this_month_cents"],"additionalProperties":false},"next_step":{"type":"string"}},"required":["draft_id","status","expires_at","recipient","delivery","gift","note","occasion","from_name","max_cost_cents","payment","recipient_sees_price","limits","next_step"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"No saved card","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Can't be drafted (with the reason)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/gift-drafts/{id}/send":{"post":{"operationId":"sendGiftDraft","summary":"Send a draft","description":"Send a draft made with this key. The body must be {\"confirm\": true}. Spending limits are reserved atomically; send an Idempotency-Key header so a retry never sends twice.","tags":["gift drafts"],"x-required-scope":"send","security":[{"bearerAuth":["gifts.read","gifts.draft","gifts.send"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id (or, for gifts, the ref from the gift link)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Any unique string (a UUID is ideal). A retry with the same key within 24 hours returns the first response and sends nothing."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"description":"Must be true: you (or your user) approved this exact draft.","type":"boolean","const":true}},"required":["confirm"],"additionalProperties":false}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"ref":{"type":"string"},"link":{"description":"The recipient's gift page","type":"string"},"status":{"type":"string"},"mode":{"type":"string","enum":["one","choice"]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"email":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","email"],"additionalProperties":false},"occasion":{"anyOf":[{"type":"string"},{"type":"null"}]},"budget_cents":{"description":"The most it can cost (charged on acceptance, never above this)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"smart_link_id":{"description":"The GG Link it was claimed from","anyOf":[{"type":"string"},{"type":"null"}]},"automation_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"campaign":{"description":"The GG Link campaign tag the claim carried (null for a gift sent directly)","anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"accepted_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"test":{"description":"A test gift: never charged, ordered or texted.","type":"boolean"},"items":{"description":"What they accepted, one entry per gift (several when the recipient picked more than one); empty until accepted","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"title":{"type":"string"},"status":{"type":"string"},"shipped_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title","status","shipped_at","delivered_at"],"additionalProperties":false}}},"required":["id","ref","link","status","mode","recipient","occasion","budget_cents","charged_cents","smart_link_id","automation_id","contact_id","campaign","created_at","opened_at","accepted_at","shipped_at","delivered_at","cancelled_at","expires_at","test","items"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"202":{"description":"Over your monthly team budget: waiting for an owner's or admin's approval","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","const":"pending_approval"},"approval_id":{"type":"string"},"message":{"type":"string"}},"required":["status","approval_id","message"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid request (or Idempotency-Key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"No saved card (add one in the app; you're charged only when a gift is accepted)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Contact or draft not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"A request with this Idempotency-Key is still running, or a live key on a deployment running Stripe test keys (code live_mode_unavailable)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Can't be done (for example over a spending limit: code limit_exceeded), or the Idempotency-Key was used with a different request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/gg-links":{"get":{"operationId":"listGgLinks","summary":"List GG Links","description":"Your GG Links, newest first (open ones, then the last 20 closed): status, claims used of the max, and spend so far.","tags":["gg links"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000}}],"responses":{"200":{"description":"A page of GG Links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"url":{"description":"The shareable link (/l/…). Anyone with it can claim one gift; they never see a price.","type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","expired","full","closed"]},"budget_cents":{"description":"The most each claim can cost (charged on acceptance, never above this)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_claims":{"description":"The cap that applies (Free plans: at most 5)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"claims_used":{"description":"Claims so far (skipped ones don't count)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"waiting_for_approval":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"accepted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spent_cents":{"description":"Charged so far, net of refunds","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"one_per":{"type":"string","enum":["person","company"]},"require_approval":{"type":"boolean"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"description":"Plain English, e.g. \"Up to 10 people can each choose one gift up to $50. Your card is charged only when someone accepts.\"","type":"string"},"created_at":{"type":"string"},"test":{"type":"boolean"}},"required":["id","url","name","status","budget_cents","max_claims","claims_used","waiting_for_approval","accepted","spent_cents","one_per","require_approval","expires_at","summary","created_at","test"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["data","limit","offset"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"createGgLink","summary":"Create a GG Link","description":"One shareable URL anyone can open to claim one gift within budget_cents. Guardrails: max_claims (default 10; Free plans up to 5), expires_at, one claim per person (email and shipping address), and require_approval. Each claim is charged only when it's accepted; the key's spending limits count max_claims × budget_cents, reserved atomically. Personal links (type \"single\") were retired: send a gift with POST /gifts. Send recipient_email, recipient_name, recipient_company and campaign to get personalized_url back for that prospect; creating a link counts toward the plan's active-link cap (Free: 1), personalizing never does.","tags":["gg links"],"x-required-scope":"send","security":[{"bearerAuth":["gifts.read","gifts.draft","gifts.send"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Any unique string (a UUID is ideal). A retry with the same key within 24 hours returns the first response and sends nothing."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"description":"Optional, kept for older clients: \"team\" (the default) is the only kind. \"single\" (one named person) was retired on 2026-10-19 and is refused: send a gift instead.","type":"string","enum":["single","team"]},"budget_cents":{"description":"The most it can cost, in cents. One of: 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12500, 15000, 17500, 20000, 25000, 30000, 35000.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"description":"Your note on the gift page.","default":"","type":"string","maxLength":600},"headline":{"description":"Shown at the top of the link's page (default: \"A gift for you\").","type":"string","minLength":1,"maxLength":140},"name":{"description":"Only you see this, in your links list.","type":"string","minLength":1,"maxLength":80},"recipient_name":{"description":"Their first name (or full name: the greeting uses the first word). Letters only survive; anything else is dropped.","type":"string","maxLength":80},"recipient_email":{"description":"The prospect's email. The claim page prefills it (the 6-digit code still verifies it).","type":"string","maxLength":254},"max_claims":{"description":"How many people can claim (default 10; Free plans up to 5). The link closes when they're used.","default":10,"type":"integer","minimum":1,"maximum":500},"one_per":{"description":"One claim per person (email and shipping address), or also one per company email domain.","default":"person","type":"string","enum":["person","company"]},"expires_at":{"description":"ISO time the link stops accepting claims.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"require_approval":{"description":"Each claim waits for your Approve or Skip (by email and in the app); nothing is sent, charged or ordered until you approve.","default":false,"type":"boolean"},"from_name":{"type":"string","minLength":1,"maxLength":80},"recipient_company":{"description":"Their company. Prefills Company on the claim page when the link asks for it (they can change it); letters, digits, spaces and & . , ' - ( ) + survive, up to 120.","type":"string","maxLength":160},"campaign":{"description":"A campaign tag stored on the claim and its gift (letters, digits, spaces, _ . and -; up to 64).","type":"string","maxLength":80}},"required":["budget_cents"]}}}},"responses":{"201":{"description":"The new link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"type":{"description":"Always \"team\" (kept for older clients).","type":"string","enum":["single","team"]},"budget_cents":{"type":"number"},"max_claims":{"type":"number"},"max_cost_cents":{"type":"number"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"require_approval":{"type":"boolean"},"summary":{"type":"string"},"message":{"type":"string"},"personalized_url":{"description":"url with ?e=&n=&c=&co= filled in from recipient_email, recipient_name, campaign and recipient_company (null when none were sent). For more prospects on the same link: POST /gg-links/{id}/personalize.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","type","budget_cents","max_claims","max_cost_cents","expires_at","require_approval","summary","message","personalized_url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid request (or Idempotency-Key)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"402":{"description":"No saved card (you're charged only when a claim is accepted)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"The key's mode doesn't match this deployment's payments (code live_mode_unavailable)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Can't be done: over a spending limit (code limit_exceeded), a plan limit (Free: 1 active link, 5 claims), a retired personal link, or no gifts at the budget","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/gg-links/{id}/personalize":{"post":{"operationId":"personalizeGgLink","summary":"Personalize a GG Link per prospect","description":"The link with ?e=<email>&n=<first name>&c=<campaign>&co=<company> filled in for one prospect ({\"recipient_email\", \"recipient_name\", \"recipient_company\", \"campaign\"}) or up to 500 ({\"recipients\": [...]}, with an optional \"campaign\" for all of them). Nothing is created, counted or stored: one link serves a whole list, so a Free plan's one active link works for every prospect. The claim page prefills their email (the 6-digit code still verifies it), greets them by first name, prefills Company when the link asks for it, and the campaign tag lands on the claim and its gift. Only an active link of this key's account (and mode) can be personalized.","tags":["gg links"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id (or, for gifts, the ref from the gift link)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"recipient_email":{"description":"The prospect's email. The claim page prefills it (the 6-digit code still verifies it).","type":"string","maxLength":254},"recipient_name":{"description":"Their first name (or full name: the greeting uses the first word). Letters only survive; anything else is dropped.","type":"string","maxLength":80},"recipient_company":{"description":"Their company. Prefills Company on the claim page when the link asks for it (they can change it); letters, digits, spaces and & . , ' - ( ) + survive, up to 120.","type":"string","maxLength":160},"campaign":{"description":"A campaign tag stored on the claim and its gift (letters, digits, spaces, _ . and -; up to 64).","type":"string","maxLength":80}},"required":["recipient_email"],"additionalProperties":false},{"type":"object","properties":{"recipients":{"description":"Up to 500 per call. A row without a valid email gets personalized_url null and a note; the others still come back.","minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"recipient_email":{"description":"The prospect's email. The claim page prefills it (the 6-digit code still verifies it).","type":"string","maxLength":254},"recipient_name":{"description":"Their first name (or full name: the greeting uses the first word). Letters only survive; anything else is dropped.","type":"string","maxLength":80},"recipient_company":{"description":"Their company. Prefills Company on the claim page when the link asks for it (they can change it); letters, digits, spaces and & . , ' - ( ) + survive, up to 120.","type":"string","maxLength":160},"campaign":{"description":"A campaign tag stored on the claim and its gift (letters, digits, spaces, _ . and -; up to 64).","type":"string","maxLength":80}},"required":["recipient_email"],"additionalProperties":false}},"campaign":{"description":"A campaign tag for every recipient (a recipient's own tag is used when this is absent).","type":"string","maxLength":80}},"required":["recipients"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"The personalized URL(s): an object for one recipient, an array for a batch","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"personalized_url":{"description":"The link with ?e=&n=&c=&co= filled in (null when the email isn't usable; see note). Share this with that prospect; they never see a price.","anyOf":[{"type":"string"},{"type":"null"}]},"recipient_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_name":{"description":"As the claim page will greet them","anyOf":[{"type":"string"},{"type":"null"}]},"campaign":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_company":{"description":"As the claim page will prefill it","anyOf":[{"type":"string"},{"type":"null"}]},"note":{"description":"\"No valid email\", or what was dropped","anyOf":[{"type":"string"},{"type":"null"}]},"link_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"url":{"description":"The bare link","type":"string"}},"required":["personalized_url","recipient_email","recipient_name","campaign","recipient_company","note","link_id","url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"personalized_url":{"description":"The link with ?e=&n=&c=&co= filled in (null when the email isn't usable; see note). Share this with that prospect; they never see a price.","anyOf":[{"type":"string"},{"type":"null"}]},"recipient_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_name":{"description":"As the claim page will greet them","anyOf":[{"type":"string"},{"type":"null"}]},"campaign":{"anyOf":[{"type":"string"},{"type":"null"}]},"recipient_company":{"description":"As the claim page will prefill it","anyOf":[{"type":"string"},{"type":"null"}]},"note":{"description":"\"No valid email\", or what was dropped","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["personalized_url","recipient_email","recipient_name","campaign","recipient_company","note"],"additionalProperties":false}},"link_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"url":{"type":"string"},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linked":{"description":"Rows with a personalized_url","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["data","link_id","url","total","linked"],"additionalProperties":false}]}}}},"400":{"description":"Invalid request (a bad recipient_email on the single form, more than the batch limit, unknown fields)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No such link on this account (or the other mode's)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"The link isn't active: paused, expired, full or closed (code link_not_active)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/catalog":{"get":{"operationId":"listCatalog","summary":"List the catalog","description":"Gifts you can send, with what each costs if accepted, and the budgets a their-choice gift can use.","tags":["catalog"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0,"maximum":100000}},{"name":"max_cents","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000000}},{"name":"min_cents","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":1000000}},{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":40}}],"responses":{"200":{"description":"A page of catalog items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"title":{"type":"string"},"brand":{"type":"string"},"description":{"type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_cents":{"description":"What you pay if it's accepted. Recipients never see prices.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"images":{"type":"array","items":{"type":"string"}},"occasions":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"ships_in_days":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","title","brand","description","category","price_cents","images","occasions","tags","ships_in_days"],"additionalProperties":false}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"budgets_cents":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["data","limit","offset","budgets_cents"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/me":{"get":{"operationId":"me","summary":"The key's account and scope","description":"The account email, the key's mode (live or test) and scope. Nothing changes; a good first call to check a key.","tags":["me"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"responses":{"200":{"description":"The key","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"email":{"description":"The account the key belongs to","type":"string"},"mode":{"type":"string","enum":["live","test"]},"access":{"type":"string","enum":["read","draft","send"]},"test":{"description":"Everything this key sees or makes is test data","type":"boolean"},"key_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["email","mode","access","test","key_name"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhook endpoints","description":"The endpoints this key's mode delivers to, newest first (the same list as Developers → Webhooks).","tags":["webhooks"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"responses":{"200":{"description":"The endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["gift.sent","gift.opened","gift.claimed","gift.accepted","gift.shipped","gift.delivered","gift.thank_you","gift.expired","gift.payment_failed","video.reply_received","meeting.booked","meeting.canceled"]}},"active":{"type":"boolean"},"mode":{"description":"Follows the key: a test key's endpoints get test data only.","type":"string","enum":["live","test"]},"created_at":{"type":"string"},"disabled_at":{"description":"Set when the endpoint was turned off after failing repeatedly","anyOf":[{"type":"string"},{"type":"null"}]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","url","events","active","mode","created_at","disabled_at","disabled_reason"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}},"post":{"operationId":"createWebhook","summary":"Subscribe an endpoint","description":"Add an https endpoint for one or more events (Zapier's REST hook subscribe: one event per hook). The endpoint takes the key's mode, so a test key only ever sends test data to it. The answer carries the signing secret once; every delivery is signed with it (GG-Signature). Up to 10 endpoints per account; private and local addresses are refused.","tags":["webhooks"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"description":"An https URL on the public internet (Zapier's or Make's hook URL, or your own endpoint).","type":"string","minLength":1,"maxLength":500},"events":{"description":"The events this endpoint gets (a Zapier trigger subscribes to one).","minItems":1,"maxItems":12,"type":"array","items":{"type":"string","enum":["gift.sent","gift.opened","gift.claimed","gift.accepted","gift.shipped","gift.delivered","gift.thank_you","gift.expired","gift.payment_failed","video.reply_received","meeting.booked","meeting.canceled"]}}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"The endpoint, with its secret (shown once)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["gift.sent","gift.opened","gift.claimed","gift.accepted","gift.shipped","gift.delivered","gift.thank_you","gift.expired","gift.payment_failed","video.reply_received","meeting.booked","meeting.canceled"]}},"active":{"type":"boolean"},"mode":{"description":"Follows the key: a test key's endpoints get test data only.","type":"string","enum":["live","test"]},"created_at":{"type":"string"},"disabled_at":{"description":"Set when the endpoint was turned off after failing repeatedly","anyOf":[{"type":"string"},{"type":"null"}]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"secret":{"description":"The endpoint's signing secret (whsec_…), shown once. Verify GG-Signature with it.","type":"string"}},"required":["id","url","events","active","mode","created_at","disabled_at","disabled_reason","secret"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Invalid JSON, an unknown event, or no events","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"The URL can't be used (not https, private, credentials in it), or the account is at its endpoint limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Remove an endpoint","description":"Unsubscribe (Zapier's REST hook unsubscribe). Its signing secret is deleted; pending deliveries to it are dropped.","tags":["webhooks"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id (or, for gifts, the ref from the gift link)"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No such endpoint on this account (or the other mode's)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}},"/api/v1/events/sample":{"get":{"operationId":"eventSample","summary":"A sample delivery for an event","description":"One made-up delivery body for `type` (exactly the shape a real delivery has; `data.test` follows the key's mode). Nothing real is read or sent.","tags":["events"],"x-required-scope":"read","security":[{"bearerAuth":["gifts.read"]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"description":"The event to sample","type":"string","enum":["gift.sent","gift.opened","gift.claimed","gift.accepted","gift.shipped","gift.delivered","gift.thank_you","gift.expired","gift.payment_failed","video.reply_received","meeting.booked","meeting.canceled"]},"description":"The event to sample"}],"responses":{"200":{"description":"A list with one sample","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"description":"A delivery id (made up)","type":"string"},"type":{"type":"string","enum":["gift.sent","gift.opened","gift.claimed","gift.accepted","gift.shipped","gift.delivered","gift.thank_you","gift.expired","gift.payment_failed","video.reply_received","meeting.booked","meeting.canceled"]},"created":{"type":"string"},"data":{"description":"The event's flat payload, exactly as a delivery carries it","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","type","created","data"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Unknown or missing type","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Not on Pro, or the key's scope doesn't allow this (code insufficient_scope)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"message":{"description":"Safe to show a person","type":"string"}},"required":["status","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}}}}},"webhooks":{"gift.sent":{"post":{"summary":"gift.sent","description":"A gift link was created (sent, or ready to share).","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.sent"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.sent","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"sent","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":0,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":null,"accepted_at":null,"shipped_at":null,"delivered_at":null,"test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"sent","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":0,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":null,"accepted_at":null,"shipped_at":null,"delivered_at":null,"cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.opened":{"post":{"summary":"gift.opened","description":"The recipient opened their gift for the first time.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.opened"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.opened","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"opened","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":0,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":null,"shipped_at":null,"delivered_at":null,"test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"opened","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":0,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":null,"shipped_at":null,"delivered_at":null,"cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.claimed":{"post":{"summary":"gift.claimed","description":"Someone claimed a gift from one of your GG Links (their email verified). For a gift you sent to one person, the matching signal is gift.accepted.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.claimed"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.claimed","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"9d8c7b6a-5f4e-4d3c-b2a1-0f9e8d7c6b5a","gift_ref":"Lm3Np7Qr9St1Uv5Wx8Yz2A","gift_url":"https://www.giasgiraffes.com/g/Lm3Np7Qr9St1Uv5Wx8Yz2A","gift_status":"sent","recipient_name":"Pat Prospect","recipient_first_name":"Pat","recipient_email":"pat@acme.example","occasion":null,"campaign":"Q4 outbound","link_id":"7a3b9c1d-2e4f-4a5b-8c6d-0e1f2a3b4c5d","contact_id":null,"budget_cents":5000,"charged_cents":0,"sent_at":"2026-10-19T15:21:40.000Z","opened_at":null,"accepted_at":null,"shipped_at":null,"delivered_at":null,"test":false,"claim_id":"c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f","claim_state":"sent","claimed_at":"2026-10-19T15:21:40.000Z","link_name":"Q4 outbound","link_url":"https://www.giasgiraffes.com/l/q4-outbound-k7m3q9xw","recipient_company":"Acme","recipient_title":"VP Sales","gift":{"id":"9d8c7b6a-5f4e-4d3c-b2a1-0f9e8d7c6b5a","ref":"Lm3Np7Qr9St1Uv5Wx8Yz2A","link":"https://www.giasgiraffes.com/g/Lm3Np7Qr9St1Uv5Wx8Yz2A","status":"sent","mode":"choice","recipient":{"name":"Pat Prospect","email":"pat@acme.example"},"occasion":null,"budget_cents":5000,"charged_cents":0,"smart_link_id":"7a3b9c1d-2e4f-4a5b-8c6d-0e1f2a3b4c5d","automation_id":null,"contact_id":null,"campaign":"Q4 outbound","created_at":"2026-10-19T15:21:40.000Z","opened_at":null,"accepted_at":null,"shipped_at":null,"delivered_at":null,"cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.accepted":{"post":{"summary":"gift.accepted","description":"They picked a gift and accepted it.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.accepted"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.accepted","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"accepted","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":4500,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":null,"delivered_at":null,"test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"accepted","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":4500,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":null,"delivered_at":null,"cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.shipped":{"post":{"summary":"gift.shipped","description":"The brand shipped it.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.shipped"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.shipped","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"shipped","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":4500,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":null,"test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"shipped","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":4500,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":null,"cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.delivered":{"post":{"summary":"gift.delivered","description":"It was delivered.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.delivered"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.delivered","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"delivered","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":4500,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":"2026-10-19T20:31:00.000Z","test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"delivered","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":4500,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":"2026-10-19T20:31:00.000Z","cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.thank_you":{"post":{"summary":"gift.thank_you","description":"The recipient sent you a thank-you note.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.thank_you"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.thank_you","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"delivered","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":4500,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":"2026-10-19T20:31:00.000Z","test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"delivered","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":4500,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":"2026-10-19T20:31:00.000Z","cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]},"message":"This made my week. Thank you!","thanked_at":"2026-10-20T13:02:45.000Z"}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.expired":{"post":{"summary":"gift.expired","description":"The link expired unredeemed (nothing was charged).","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.expired"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.expired","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"cancelled","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":0,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":null,"accepted_at":null,"shipped_at":null,"delivered_at":null,"test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"cancelled","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":0,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":null,"accepted_at":null,"shipped_at":null,"delivered_at":null,"cancelled_at":"2026-11-14T17:02:11.000Z","expires_at":"2026-11-14T17:02:11.000Z","test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"gift.payment_failed":{"post":{"summary":"gift.payment_failed","description":"Your card was declined when they accepted (data.final: true once the gift is cancelled for it).","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"gift.payment_failed"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"gift.payment_failed","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"accepted","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":0,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":null,"delivered_at":null,"test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"accepted","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":0,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":null,"delivered_at":null,"cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]},"final":false}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"video.reply_received":{"post":{"summary":"video.reply_received","description":"The recipient's thank-you video is ready to watch.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"video.reply_received"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"video.reply_received","created":"2026-10-15T18:44:58.000Z","data":{"gift_id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","gift_ref":"q8Zr2mT4VxK1nP0aBcDeFg","gift_url":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","gift_status":"delivered","recipient_name":"Avery Chen","recipient_first_name":"Avery","recipient_email":"avery@northwind.example","occasion":"Thank you","campaign":null,"link_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","budget_cents":5000,"charged_cents":4500,"sent_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":"2026-10-19T20:31:00.000Z","test":false,"gift":{"id":"5f0c2a1e-8b7d-4c9a-a1f3-2d6e9b8c7a10","ref":"q8Zr2mT4VxK1nP0aBcDeFg","link":"https://www.giasgiraffes.com/g/q8Zr2mT4VxK1nP0aBcDeFg","status":"delivered","mode":"choice","recipient":{"name":"Avery Chen","email":"avery@northwind.example"},"occasion":"Thank you","budget_cents":5000,"charged_cents":4500,"smart_link_id":null,"automation_id":null,"contact_id":"0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d","campaign":null,"created_at":"2026-10-15T17:02:11.000Z","opened_at":"2026-10-15T18:40:03.000Z","accepted_at":"2026-10-15T18:44:57.000Z","shipped_at":"2026-10-17T15:10:00.000Z","delivered_at":"2026-10-19T20:31:00.000Z","cancelled_at":null,"expires_at":null,"test":false,"items":[{"id":"8a1f6c2e-3b4d-4e5f-9a6b-7c8d9e0f1a2b","title":"Explorer Coffee Box","status":"ordered","shipped_at":null,"delivered_at":null}]},"video_id":"2b7e1c9a-4d3f-4e5a-9b8c-7d6e5f4a3b2c","duration_seconds":23,"ready_at":"2026-10-20T13:10:02.000Z","watch_url":"https://www.giasgiraffes.com/app/gifts?gift=q8Zr2mT4VxK1nP0aBcDeFg"}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"meeting.booked":{"post":{"summary":"meeting.booked","description":"A prospect booked a meeting with you (Meetings).","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"meeting.booked"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"meeting.booked","created":"2026-10-15T18:44:58.000Z","data":{"meeting_id":"mtg_3f2a9c8e7d6b5a4f","provider":"google","title":"Intro call: Acme × Northwind","starts_at":"2026-10-27T17:00:00.000Z","ends_at":"2026-10-27T17:30:00.000Z","timezone":"America/New_York","join_url":"https://meet.google.com/abc-defg-hij","attendee_name":"Pat Prospect","attendee_email":"pat@acme.example","attendee_company":"Acme","contact_id":null,"gift_id":"9d8c7b6a-5f4e-4d3c-b2a1-0f9e8d7c6b5a","link_id":"7a3b9c1d-2e4f-4a5b-8c6d-0e1f2a3b4c5d","campaign":"Q4 outbound","booked_at":"2026-10-20T14:05:12.000Z","canceled_at":null,"test":false,"attendee_first_name":"Pat"}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}},"meeting.canceled":{"post":{"summary":"meeting.canceled","description":"A booked meeting was canceled.","parameters":[{"name":"GG-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with the endpoint's signing secret"},{"name":"GG-Event","in":"header","required":true,"schema":{"type":"string","const":"meeting.canceled"}},{"name":"GG-Delivery","in":"header","required":true,"schema":{"type":"string"},"description":"The delivery id (the same across retries)"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"id":"8c1d0b0e-4a5f-4b1e-9e6a-0f3c2b1a9d87","type":"meeting.canceled","created":"2026-10-15T18:44:58.000Z","data":{"meeting_id":"mtg_3f2a9c8e7d6b5a4f","provider":"google","title":"Intro call: Acme × Northwind","starts_at":"2026-10-27T17:00:00.000Z","ends_at":"2026-10-27T17:30:00.000Z","timezone":"America/New_York","join_url":"https://meet.google.com/abc-defg-hij","attendee_name":"Pat Prospect","attendee_email":"pat@acme.example","attendee_company":"Acme","contact_id":null,"gift_id":"9d8c7b6a-5f4e-4d3c-b2a1-0f9e8d7c6b5a","link_id":"7a3b9c1d-2e4f-4a5b-8c6d-0e1f2a3b4c5d","campaign":"Q4 outbound","booked_at":"2026-10-20T14:05:12.000Z","canceled_at":"2026-10-26T09:14:00.000Z","test":false,"attendee_first_name":"Pat"}}}}},"responses":{"200":{"description":"Any 2xx acknowledges it; anything else (or no answer in 10 seconds) is retried"}}}}}}