Add practical API integration guides

_config.yml

@@ -218,6 +218,10 @@ collections:
       - developers-overview.md
       - custom-store-integration.md
       - api.md
+      - products-and-inventory-with-api.md
+      - orders-with-api.md
+      - coupons-with-api.md
+      - troubleshoot-custom-integration.md
       - send-sms-with-api.md
       - tracking-events.md
       - custom-actions.md

_developers/coupons-with-api.md

@@ -0,0 +1,19 @@
+---
+languages: ["en", "es"]
+
+en:
+  title: Create and track coupons with the API
+  description: Represent an existing store coupon in Hellotext and record confirmed redemptions without duplicating them.
+es:
+  title: Crea y registra cupones con la API
+  description: Representa en Hellotext un cupón existente de la tienda y registra canjes confirmados sin duplicarlos.
+
+permalink: coupons-with-api
+permalink_es: cupones-con-api
+
+layout: guide
+topic: developers
+popular: true
+---
+
+{% translate_file developers/coupons-with-api.md %}

_developers/orders-with-api.md

@@ -0,0 +1,19 @@
+---
+languages: ["en", "es"]
+
+en:
+  title: Create and track orders with the API
+  description: Synchronize an order once, connect it to the customer profile, and record each real lifecycle milestone.
+es:
+  title: Crea y registra pedidos con la API
+  description: Sincroniza un pedido una sola vez, conéctalo con el perfil del cliente y registra cada hito real de su ciclo.
+
+permalink: orders-with-api
+permalink_es: pedidos-con-api
+
+layout: guide
+topic: developers
+popular: true
+---
+
+{% translate_file developers/orders-with-api.md %}

_developers/products-and-inventory-with-api.md

@@ -0,0 +1,19 @@
+---
+languages: ["en", "es"]
+
+en:
+  title: Sync products and understand inventory availability
+  description: Keep products and variants synchronized through the API and understand how Hellotext obtains live availability.
+es:
+  title: Sincroniza productos y entiende la disponibilidad de inventario
+  description: Mantén productos y variantes sincronizados mediante la API y entiende cómo obtiene Hellotext la disponibilidad en tiempo real.
+
+permalink: products-and-inventory-with-api
+permalink_es: productos-inventario-con-api
+
+layout: guide
+topic: developers
+popular: true
+---
+
+{% translate_file developers/products-and-inventory-with-api.md %}

_developers/troubleshoot-custom-integration.md

@@ -0,0 +1,19 @@
+---
+languages: ["en", "es"]
+
+en:
+  title: Troubleshoot a custom integration
+  description: Diagnose authentication, validation, identity, duplicate data, delayed events, and safe retry problems.
+es:
+  title: Soluciona una integración propia
+  description: Diagnostica problemas de autenticación, validación, identidad, datos duplicados, eventos demorados y reintentos seguros.
+
+permalink: troubleshoot-custom-integration
+permalink_es: solucionar-integracion-personalizada
+
+layout: guide
+topic: developers
+popular: true
+---
+
+{% translate_file developers/troubleshoot-custom-integration.md %}

_i18n/en/developers/coupons-with-api.md

@@ -0,0 +1,129 @@
+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](https://www.hellotext.com/api#coupons) for the complete contract.
+
+## Before you start
+
+Prepare:
+
+- A private API authorization token.
+- 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
+
+Create the matching coupon:
+
+```bash
+curl --request POST \
+  --url https://api.hellotext.com/v1/coupons \
+  --header "Authorization: Bearer $HELLOTEXT_API_TOKEN" \
+  --header "Content-Type: application/json" \
+  --data '{
+    "code": "WELCOME10",
+    "description": "Get 10% off your first order",
+    "destination_url": "https://shop.example.com/discount/WELCOME10",
+    "reference": "promotion-2026-welcome"
+  }'
+```
+
+The code is case-sensitive and must be unique. Keep the description under the supported limit and make the destination URL publicly reachable.
+
+Save the returned coupon `id`. See [Create a coupon](https://www.hellotext.com/api#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.
+
+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.
+
+Before launch, test the complete customer experience:
+
+1. The message shows the intended code and description.
+2. The destination opens the correct store and offer.
+3. Checkout accepts the code for an eligible customer.
+4. 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:
+
+```bash
+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
+  }'
+```
+
+Use the monetary value associated with the confirmed redemption according to your reporting implementation. Keep `amount` and `currency` together, and preserve the original event time.
+
+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](https://www.hellotext.com/api#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.
+- Process the same checkout notification only once.
+- Mark it as sent after Hellotext responds with `status: received`.
+- Do not send the same redemption from browser and backend code.
+- Preserve the same customer profile and coupon ID on retries.
+
+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.
+- 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]({% link _developers/troubleshoot-custom-integration.md %}).
+
+## Related guides
+
+- [Integrate a custom store with Hellotext]({% link _developers/custom-store-integration.md %})
+- [External tracking]({% link _developers/external-tracking.md %})
+- [Tracking events]({% link _developers/tracking-events.md %})
+- [Forms]({% link _captures/forms.md %})
+- [Website Popup]({% link _captures/website-popup.md %})

_i18n/en/developers/custom-store-integration.md

@@ -119,6 +119,8 @@ Keep `source`, `reference`, and SKU values stable. Update the existing product w
 
 See [Create a product in the API](https://www.hellotext.com/api#create_a_product) for all supported product and variant data.
 
+The public product endpoint does not currently expose stock quantity or live availability. Do not add inventory values to `metadata` and assume that inventory-aware playbooks will use them. Read [Sync products and understand inventory availability]({% link _developers/products-and-inventory-with-api.md %}) before enabling a workflow that depends on stock.
+
 ## 5. Import historical orders
 
 Historical orders give Hellotext purchase context before the first live event arrives. Each imported order needs:
@@ -178,7 +180,7 @@ Use the event that reflects what really happened, such as `order.placed`, `order
 
 Preserve original timestamps during the historical import. Otherwise, old purchases can look like current activity and distort segmentation, playbook eligibility, and reporting.
 
-See [Create an order](https://www.hellotext.com/api#create_an_order) and [track order events](https://www.hellotext.com/api#track_order_events) for all available options.
+See [Create and track orders with the API]({% link _developers/orders-with-api.md %}), [Create an order](https://www.hellotext.com/api#create_an_order), and [track order events](https://www.hellotext.com/api#track_order_events) for all available options.
 
 ## 6. Install Hellotext.js on the storefront
 
@@ -376,6 +378,10 @@ If data is missing, use [Troubleshoot missing signals or activity]({% link _trou
 ## Related guides
 
 - [Developers and API overview]({% link _developers/developers-overview.md %})
+- [Sync products and understand inventory availability]({% link _developers/products-and-inventory-with-api.md %})
+- [Create and track orders with the API]({% link _developers/orders-with-api.md %})
+- [Create and track coupons with the API]({% link _developers/coupons-with-api.md %})
+- [Troubleshoot a custom integration]({% link _developers/troubleshoot-custom-integration.md %})
 - [Tracking events]({% link _developers/tracking-events.md %})
 - [Custom properties and events]({% link _audience/custom-properties-and-events.md %})
 - [Verify your data and signals after setup]({% link _integrations/verify-data-and-signals.md %})

_i18n/en/developers/developers-overview.md

@@ -23,6 +23,15 @@ The API reference is the source of truth for available resources, attributes, pa
 
 Open the [Hellotext API reference](https://www.hellotext.com/api).
 
+## API implementation recipes
+
+Use the practical API guides when you need to move from the endpoint contract to a complete integration flow:
+
+- [Sync products and understand inventory availability]({% link _developers/products-and-inventory-with-api.md %})
+- [Create and track orders with the API]({% link _developers/orders-with-api.md %})
+- [Create and track coupons with the API]({% link _developers/coupons-with-api.md %})
+- [Troubleshoot a custom integration]({% link _developers/troubleshoot-custom-integration.md %})
+
 ## Authentication
 
 API requests use bearer tokens.

_i18n/en/developers/external-tracking.md

@@ -190,7 +190,9 @@ Record the status and error in your logs, but never log the token or complete cu
 
 ## 7. Prevent duplicate events
 
-Every accepted request can create a new event, even when the same product or order is reused. Finding the same object through `reference` and `source` does not remove repeated events.
+Most accepted tracking requests can create a new event, even when the same object is reused. Finding the same object through `reference` and `source` does not remove repeated events.
+
+Built-in order lifecycle actions are a narrow exception: Hellotext stores one event for each order and action pair, such as one `order.shipped` event for a given order. This does not provide general request idempotency. Other event types can still be duplicated, so prevent repeated submissions in your integration.
 
 - Store which source event has already been accepted by Hellotext in your own system.
 - Do not retry `200` responses.
@@ -203,6 +205,9 @@ See the complete [tracking API reference](https://www.hellotext.com/api#tracking
 ## Related guides
 
 - [Integrate a custom store with Hellotext]({% link _developers/custom-store-integration.md %})
+- [Create and track orders with the API]({% link _developers/orders-with-api.md %})
+- [Create and track coupons with the API]({% link _developers/coupons-with-api.md %})
+- [Troubleshoot a custom integration]({% link _developers/troubleshoot-custom-integration.md %})
 - [Tracking events]({% link _developers/tracking-events.md %})
 - [Tracking unidentified customers]({% link _developers/tracking-unidentified-customers.md %})
 - [Custom properties and events]({% link _audience/custom-properties-and-events.md %})