Why metadata can't be attached to applied coupons

Lago doesn't currently support attaching custom metadata to an applied_coupon object. There's no metadata field when applying a coupon via the API, so external identifiers such as Salesforce Opportunity IDs or contract references can't be stored directly on the coupon application and have to be tracked outside Lago.

Workarounds

Customer metadata. Store the identifier on the customer object itself using Lago's customer metadata field. This works if the mapping between coupons and external identifiers is one-to-one per customer, but breaks down if a customer can have multiple concurrent coupon applications each needing distinct metadata.

Coupon code encoding. Encode identifiers into the coupon code at creation time, for example DEAL-SF-OPP-12345. This avoids needing metadata fields but makes aggregation harder and is brittle if identifier formats change.

External tracking table (recommended). Maintain a separate table mapping applied_coupon IDs, retrievable via the API, to your external identifiers, and use the coupon.applied and coupon.terminated webhooks to keep it in sync. This is the most robust approach for teams tracking redemptions in a data warehouse.

Metadata on applied coupons is a tracked feature request. Contact Lago support to register interest if this capability matters for your use case.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.