KFC API endpoint
Returns one promotion by its redemption code (the code a customer types in at checkout) or its serialized code (a unique per-print QR/serial code, e.g. from a printed coupon, that resolves to a shared redemption code and its promotion). Exactly one of code or serialized_code is required. A serialized-code lookup additionally returns that code's own usage metadata (redemption_code, times_used, code_status, group_status, effective_date, expiration_date) alongside the promotion. An unknown or expired code returns a 404 rather than a null success payload.
/kfc/promotionQuery parameters:
code (optional) — the redemption code, preferably one returned by kfc-promotions, e.g. WALMART5DOLLARSOFF. Exactly one of code or serialized_code is required.serialized_code (optional) — a unique per-print serialized/QR code, e.g. deadbeef1234. Exactly one of code or serialized_code is required.Response is the promotion object directly plus source_url and fetched_at: promotion_id, name (KFC's internal campaign label), display_name (the customer-facing name), description, and automatic (whether it applies automatically or requires this code to be entered). A serialized_code lookup additionally returns that code's own usage metadata: redemption_code (the shared code this serialized code resolves to), times_used, code_status, group_status, effective_date, and expiration_date. These fields are omitted for a code lookup.
Example response (code lookup):
{"code":200,"msg":"OK","data":{"promotion_id":"d8da51c0-3497-485a-b68d-a8aa464da799","name":"Digital - 2026_Q4_1101_Partnership_Buy Two $25 gift cards and get $5 off your next digital purchase","display_name":"$5 off","description":"$5 off","automatic":false,"source_url":"https://www.kfc.com/api/kfc_us/storefront/graphql","fetched_at":"2026-09-21T03:37:59Z"}}
Example response (serialized_code lookup):
{"code":200,"msg":"OK","data":{"promotion_id":"6815f409-5b1e-44dc-9f99-26b1c1a2699a","name":"Digital-Q324 - 50% off Chicken Sandwich","display_name":"50% off Chicken Sandwich","description":"Digital - .Q324 - Get 50% off the purchase of a Chicken Sandwich. ","automatic":false,"redemption_code":"WELCOME10","times_used":0,"code_status":"ACTIVE","group_status":"ACTIVE","effective_date":"2026-01-01","expiration_date":"2026-12-31","source_url":"https://www.kfc.com/api/kfc_us/storefront/graphql","fetched_at":"2026-09-03T00:00:00Z"}}
| Field | In the sample | Value in the sample |
|---|---|---|
| promotion_id | Has a value | |
| name | Has a value | “Digital - 2026_Q4_1101_Partnership_Buy Two $25 gift cards a…” |
| display_name | Has a value | |
| description | Has a value | “$5 off” |
| automatic | Has a value | false |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| code | string | No | The redemption code as a customer would type it in at checkout. Use a value returned by kfc-promotions when available. Exactly one of code or serialized_code is required | WALMART5DOLLARSOFF | |
| serialized_code | string | No | A unique per-print serialized/QR code that resolves to a shared redemption code. Exactly one of code or serialized_code is required | deadbeef1234 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/kfc/promotion" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"promotion_id": "d8da51c0-3497-485a-b68d-a8aa464da799",
"name": "Digital - 2026_Q4_1101_Partnership_Buy Two $25 gift cards and get $5 off your next digital purchase",
"display_name": "$5 off",
"description": "$5 off",
"automatic": false,
"source_url": "https://www.kfc.com/api/kfc_us/storefront/graphql",
"fetched_at": "2026-09-21T03:37:59Z"
}
}Request schema
No body schema
Response schema
#/definitions/kfc.promotionResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | Code is the HTTP status code or a custom code used to indicate the result of the request @example 200 | |||
| data | kfc.PromotionResponse | No | ||||
| data.automatic | boolean | No | true | |||
| data.code_status | string | No | ||||
| data.description | string | No | ||||
| data.display_name | string | No | 50% off Chicken Sandwich | |||
| data.effective_date | string | No | ||||
| data.expiration_date | string | No | ||||
| data.fetched_at | string | No | ||||
| data.group_status | string | No | ||||
| data.name | string | No | Digital-Q324 - 50% off Chicken Sandwich | |||
| data.promotion_id | string | No | 6815f409-5b1e-44dc-9f99-26b1c1a2699a | |||
| data.redemption_code | string | No | WELCOME10 | The fields below are populated only when looked up by serialized_code -- a serialized code carries its own usage metadata distinct from the promotion it resolves to. | ||
| data.redemption_codes | array | No | WALMART5DOLLARSOFF | RedemptionCodes is populated from the public promotion's active code connection. It gives callers a durable discovery path for PromotionByCode instead of requiring a guessed or stale code. | ||
| data.source_url | string | No | ||||
| data.times_used | integer | No | 0 | |||
| msg | unknown | No | Msg is the message that describes the result of the request @example "Request successful" |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 404 | Not Found | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/kfc/promotion" \
-H "x-api-key: $CRAWLORA_API_KEY"