REST coupons object – Personyze Developer Docs

For information about how REST API works, see rest main page.

Tells Personyze that coupon codes were used at a checkout it did not see: your own order system, a point of sale, a coupon engine's callback. Each code is matched to its coupon (Promotions → Coupons) and to the person it was given to, and counts as a redemption of that coupon - in its numbers, its redemption cap, and the promotions or chat offers that showed it.

A code the Personyze tag already saw used on your site, or that a connected store (Shopify, Magento, WooCommerce, BigCommerce) reports with its orders, is recorded already: send only what neither of them sees.

The URL is:

app.personyze.com/rest/coupons/redeemed

POST

One redemption:

{"code": "SPRING-K7Q2MX", "time": 1790000000, "email": "ann@example.com", "order": "#1001"}

or up to 500 at once:

{"redemptions": [{"code": "SPRING-K7Q2MX", "order": "#1001"}, {"code": "SPRING-P3DW8N", "email": "bob@example.com"}]}

Field	Notes
`code`	Required. The code as the shopper typed it; letter case does not matter.
`time`	When it was used, in Unix seconds. Now when omitted.
`email`	The shopper's email. For a code everyone shares, this is what tells one shopper from another.
`order`	Your order number, kept with the redemption. The same order is counted once, however often it is sent.

The answer:

{"recorded": 1, "already": 0, "unknown": 1, "unknown_codes": ["NOT-A-CODE"]}

recorded - counted now.
already - counted before: a personal code counts once ever, a shared code once per order and once per shopper (their email) per day. Sending the same redemption twice is safe - except a shared code sent with neither email nor order, which counts every time.
unknown - no coupon of yours has the code; unknown_codes names up to 20 of them.

Without an API key: signed calls

A checkout that should not hold your API key can send the same body to the address on its connection in Personyze (Promotions → Coupons → Stores & engines → Your webhook), signed with the connection's signing secret:

POST https://counter2.personyze.com/api/coupons/hook?p=webhook&a=<your account id>
X-Personyze-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<body>" with the signing secret>

A call with no valid signature, or signed more than 5 minutes away from now, is refused with 401.

Codes from your own system: the issue call

A coupon from Your webhook gets each visitor's code from your endpoint. Personyze sends, signed the same way:

{"event": "coupon.issue", "account": 1234, "coupon": {"id": 12, "name": "Spring", "discount": "15%", "ref": ""}, "visitor": {"id": 4242, "email": "ann@example.com"}, "time": 1790000000}

and hands out the code you answer, {"code": "SPRING-K7Q2MX"} (or the code alone as plain text) - at most 64 printable characters, no spaces. Answer within 2.5 seconds: a slower or failed answer gives that visitor no code on that page. The visitor keeps the code you gave them on every page after; you are not asked again.

Coupon engines

Voucherify: in Voucherify, Project settings → Webhooks, add the address the Voucherify connection shows (.../api/coupons/hook?p=voucherify&a=<account>) with the event redemption.succeeded, and enter that webhook's secret on the connection. Without it, Personyze reads the campaign's redemptions every 10 minutes.
Talon.One: Personyze reads the used coupons it made every 10 minutes. For them at once, create a webhook in Talon.One that posts {"code": ...} to POST /rest/coupons/redeemed with the header Authorization: Bearer <your API key> (or Basic with the user name api and your key as the password - see API key; the key alone is refused), and trigger it from the campaign's rules.
Klaviyo: Klaviyo does not report when a code is used. The codes you send it are codes of your coupon's list, so their use reaches Personyze from your store, like any other.