Automated Coupon Mapping — Export Requirements
This document describes the file format and update logic for feeding coupon-to-UTM mappings into Kickbite for automated coupon attribution. Kickbite uses this mapping to make a virtual touchpoint when users buy but do not click on ads.
General requirements
Destination | Google Cloud Storage bucket, Google Drive, BigQuery, or AWS S3 bucket. Other options can be discussed. |
Format | CSV or JSON file. |
File name | coupons_mapping |
Update logic | The same file is maintained over time: add new coupons, remove inactive ones. Each day, Kickbite deletes all records in the database where record_type = automated and re-imports from the file. |
Frequency | File should be refreshed before 2am website timezone whenever changes are made. |
File fields
Each row in the file represents one active coupon mapping. Mandatory fields are marked with an asterisk (*).
Field | Example | Type | Description |
coupon_code * | WELCOME10 | string | Coupon code as used by the customer at checkout. |
market * | DE | string | Market identifier. Country abbreviation or country name. |
rule * | is | enum | Matching rule. Accepted values: is, contains, starts_with. |
utm_campaign * | summer_sale_2026 | string | UTM campaign value this coupon should be mapped to for attribution. |
channel * | Influencers | string | Kickbite channel name. Must exactly match an existing channel definition in the account. |
start_date | 2026-01-01 | date | First day the coupon is active (YYYY-MM-DD, website timezone). Leave empty for coupons with no start boundary. |
end_date | 2026-03-31 | date | Last day the coupon is active (YYYY-MM-DD). Leave empty for open-ended coupons. |
Notes
rule defines how Kickbite matches the coupon_code against the code on an order. Use
isfor exact match,containswhen the code appears as a substring (e.g. an influencer suffix), andstarts_withwhen all variants share a prefix.channel must exactly match a channel name already defined in the Kickbite account settings. Unknown channel names will cause the row to be skipped.
Orders are only attributed to a coupon mapping if the order date falls between start_date and end_date (inclusive). If either date is empty, that side is treated as unbounded.
The file should always contain the full current list of active coupons. Kickbite does not track deltas — each day the file is re-imported in full, replacing all records where record_type = automated.
Mandatory fields: coupon_code, market, rule, utm_campaign, channel.