Did gifts lift my AOV?
The question the app exists to answer, and one figure answers it.
Ask: "Did my free gift offers lift average order value last month?"
Step 1 — Get the window right before the numbers
Call get_analytics with the window the question implies:
| The question says | Use |
|---|---|
| "last 7 days", "last month" | days: 7, days: 30 |
| "today", "this week so far" | add includeToday: true |
| nothing in particular | the default, 30 days |
Leave ianaTimezone alone. The store's own timezone is used by default, it is echoed back in the
result, and it is almost always what the question meant.
Step 2 — Compare the two AOV figures
The result carries five metrics. Two of them answer the question:
aovByFG— average order value of orders that involved a giftaovStore— average order value across the whole store
If aovByFG is higher than aovStore, the offers are lifting order value. If it is not, they
are not, however good the other numbers look. An offer can drive plenty of orders and still pull the
average down, which is exactly the case worth catching.
The other three — orders, revenue, conversionRate — say how much of the store the offers are
touching. They size the effect; they do not establish it.
Step 3 — Read the comparison that came with it
Every metric arrives with previous and changePercent, comparing against the immediately preceding
window of the same length. A 30-day call is already a month-over-month answer; there is no need for a
second call to get one.
changePercent comes back empty when the previous window was zero. That is not a failure — there is
no meaningful percentage change from nothing. Report the raw figures instead of a percentage.
Step 4 — Say so if the period is unfinished
With includeToday: true the result is marked partial and is not cached, because the store's current
day is still running. Present it as a period in progress. A partial day reported as a finished one
looks like a collapse in performance.
What you finish holding
Two AOV figures with their comparison, in the store's own currency and timezone, over a window you can name.