How to ensure a coupon is applied to a customer's first invoice

If a coupon isn't applied to a customer's first invoice, the most likely cause is that the subscription was created before the coupon API call finished, for example because both requests were fired in parallel. Applying a coupon and then creating a subscription is a reliable flow, but only when the two calls are made sequentially.

How it works

POST /api/v1/applied_coupons is synchronous. Once Lago returns a 200 response, the coupon is already written to the database with status: active, with no background processing or activation delay. Invoice generation, by contrast, is asynchronous: it runs as a background job after the subscription is created. So as long as the coupon call finishes first, it's already active by the time the first invoice bills. The same logic applies when creating and applying a coupon in the UI before creating the subscription there.

How to confirm the cause

Check your application logs to confirm the coupon API call completed successfully before the subscription creation call was made.

How to resolve the issue

Sequence the calls strictly: call POST /api/v1/applied_coupons and wait for a successful 200 response, then call POST /api/v1/subscriptions. No polling or artificial delay is needed beyond waiting for that response.

If the coupon is still missed despite sequential calls, contact Lago support with the relevant customer and organization IDs so the activity log can be reviewed.

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