A coupon object lets Hellotext reference a code, its description, and the destination where the customer can redeem it. A coupon event records that a customer actually redeemed that code.
Creating a coupon in Hellotext does not create the discount in your eCommerce platform and does not enforce its eligibility, expiration, usage limit, or single-use rules. Create and validate the promotion in the system that owns checkout first.
Use the Coupons API reference for the complete contract.
Before you start
Prepare:
- A private API authorization token, stored in your backend. Do not put it in forms, public JavaScript, or messages.
- An active subscription to create or update coupons and track events.
- A coupon code that already works in the eCommerce platform.
- A public destination URL where the customer can redeem it.
- A short description that can be used in a message.
- A stable external reference when the source system has one.
- The customer profile and purchase data needed to confirm redemption.
1. Create the discount in the commerce system
Before creating the Hellotext coupon object, confirm in the system that owns checkout:
- Which products or customers are eligible.
- The discount amount or percentage.
- Start and expiration dates.
- Whether the code is single-use or reusable.
- Whether it can be combined with another promotion.
- The final destination URL.
Hellotext can deliver and track the coupon context, but the commerce system decides whether checkout accepts it.
2. Create the coupon object in Hellotext
The examples use fictional data. Replace COUPON_ID and PROFILE_ID with the corresponding Hellotext IDs, and load your token into the HELLOTEXT_API_TOKEN environment variable on your server. Create the matching coupon:
curl --request POST \
--url https://api.hellotext.com/v1/coupons \
--header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"code": "GUIA-QR-10",
"description": "Get 10% off your first order",
"destination_url": "https://shop.example.com/discount/GUIA-QR-10",
"reference": "promotion-2026-guide"
}'
The code is case-sensitive and must be unique within your business. Descriptions support up to 140 characters. Use a public URL with https:// or http://, and check that it opens the correct offer.
Save the returned coupon id. It is different from the customer-facing code and the reference that identifies the promotion in your system. Use the Hellotext ID to retrieve, update, or track events for the object.
Check the saved object with Retrieve a coupon:
curl --request GET \
--url https://api.hellotext.com/v1/coupons/COUPON_ID \
--header "Authorization: Bearer $HELLOTEXT_API_TOKEN"
If creation returns a duplicate-code error or you do not know whether a request completed, use List all coupons and review the result pages to identify the existing code and reference before creating the object again. See Create a coupon for every supported field.
3. Update the same coupon when its presentation changes
Use PATCH /v1/coupons/:id when the description or destination URL changes. Keep the same Hellotext coupon ID while it still represents the same promotion. Send the fields you need to change:
curl --request PATCH \
--url https://api.hellotext.com/v1/coupons/COUPON_ID \
--header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"description": "Get 10% off your first order with GUIA-QR-10",
"destination_url": "https://shop.example.com/discount/GUIA-QR-10"
}'
Retrieve the object again and check its new presentation. See Update a coupon.
Do not rotate an expired code into an unrelated promotion just to reuse its record. Create a new coupon when the offer has a different commercial identity, eligibility, or code.
Because checkout rules live in the commerce system, updating the Hellotext object does not change those rules.
4. Use the coupon in a compatible message or playbook
After the coupon exists, it can be selected where Hellotext exposes coupon support, such as compatible captures, messages, routes, or playbooks. In this demo example, a Shareable Link selects GUIA-QR-10 and an optional draft welcome journey.
Before launch, test the complete customer experience:
- The message shows the intended code and description.
- The destination opens the correct store and offer.
- Checkout accepts the code for an eligible customer.
- Expiration and reuse behavior match the commerce configuration.
Do not promise free shipping, bundles, or another benefit unless that exact offer exists in the commerce system.
5. Record a confirmed redemption
Send coupon.redeemed only after the commerce system confirms that the customer used the coupon:
curl --request POST \
--url https://api.hellotext.com/v1/attribution/events \
--header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"action": "coupon.redeemed",
"profile": "PROFILE_ID",
"object": "COUPON_ID",
"amount": 89.90,
"currency": "USD",
"tracked_at": 1786104000
}'
object is the Hellotext coupon ID, and profile is the ID of the customer who redeemed it. amount represents the revenue associated with that purchase: in the example, USD 89.90 is the purchase value you record, not the value of the 10% discount. Always send the actual ISO 4217 currency together with the amount, and preserve the original redemption time in tracked_at as a Unix timestamp in seconds.
A {"status":"received"} response means the request was accepted for processing; check afterward that the event appears on the correct profile. If your integration has a real attribution session for the same customer, you can include its ID in session. Do not invent a session or attribute a redemption to a campaign solely because its coupon was used.
Do not send coupon.redeemed when the coupon is displayed, delivered, clicked, or copied. Those actions do not prove that checkout accepted it.
See Track coupon events.
6. Prevent duplicate redemption events
The coupon object can be reused across many customers, but each confirmed redemption is a separate event.
- Give each commerce redemption a stable internal ID and store its submission state in your integration.
- Process the same checkout notification only once, even if it reaches two processes at the same time.
- Mark it as accepted after Hellotext responds with
status: received; verify processing afterward. - Do not send the same redemption from browser and backend code.
- After a timeout, check the outcome before retrying: the request may have been accepted even if you did not receive the response.
Preserving the same profile, coupon, and time does not guarantee that a retry will be deduplicated. Your integration must prevent repeated submission of the same redemption.
The commerce platform remains responsible for preventing a code from being redeemed more times than its rules allow. Hellotext should receive the final confirmed outcome.
7. Verify the complete flow
Use one test coupon and one recognizable customer:
- The code works in the store before it is added to Hellotext.
- Retrieving the object confirms that its ID, code, reference, and destination match the promotion.
- The Hellotext coupon opens the correct destination.
- A compatible message displays the expected offer.
- An unsuccessful checkout does not create
coupon.redeemed. - A successful checkout creates one redemption event on the correct customer profile.
- Amount, currency, and timestamp reflect the real transaction.
If the coupon request fails or a redemption event does not appear, use Troubleshoot a custom integration.