Promotion validation

Check whether a code passes the configured resource/date/usage validation. Use a Pricing calculation to see whether that code actually discounts the chosen item.

Task	Operation
Validate code context	Validate promotion

Validate a promotion code

POST /api/v1/promo-validation

This validates the code against the selected resource, its configured dates and activation limit. It does not select a Pricing/content item, calculate an amount, reserve discount availability or record a promotion activation. HTTP 200/result:true means this validation passed; it does not establish item eligibility or a discount.

Before you call

Requires existing active member context, user-role/inherited permission and a valid resource public key. Use the code supplied by the integration. Validation checks code/resource and configured date bounds plus global activation count; it does not guarantee that an item is included in the promotion. Member payment later can record activation before provider success.

Request

POST JSON object or form fields. Nonempty form input takes precedence over JSON. The examples use JSON. Missing/empty promo fails the presence validator; no default code.

Name	Location	Type	Requirement	Meaning
`resource`	header	string	required	Resource public key against which the code is looked up.
`token`	header	string	member context	Existing member token.
`firebase-token`	header	string	Firebase-enabled context	Provider ID token alongside Wallkit token; see credentials.
`promo`	JSON/form	string	required, nonempty	Existing resource promotion code.

Result

HTTP 200 JSON result boolean true. Common optional debug fields follow response conventions. No amount, promotion ID, item eligibility or purchase fields are returned.

Example: accept the code's context

Assume EXAMPLE10 is an existing code in this resource, within configured date bounds and below its global activation limit. Use sample runtimes.

cURL

curl "${WALLKIT_API_BASE}/api/v1/promo-validation" \
  -X POST \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"promo":"EXAMPLE10"}'

JavaScript

// Node.js 18+; built-in fetch.
async function main() {
  const url = new URL("/api/v1/promo-validation", process.env.WALLKIT_API_BASE);
  const headers = {
    resource: process.env.RESOURCE_KEY,
    token: process.env.USER_TOKEN,
    "Content-Type": "application/json"
  };
  const response = await fetch(url, {
    method: "POST", headers, body: JSON.stringify({"promo":"EXAMPLE10"})
  });
  console.log(response.status, await response.json());
}
main().catch(console.error);

Python

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urljoin
from urllib.request import Request, urlopen

url = urljoin(os.environ["WALLKIT_API_BASE"], "/api/v1/promo-validation")
headers = {
    "resource": os.environ["RESOURCE_KEY"],
    "token": os.environ["USER_TOKEN"],
    "Content-Type": "application/json"
}
body = {'promo': 'EXAMPLE10'}
request = Request(url, data=json.dumps(body).encode("utf-8"), headers=headers, method="POST")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

HTTP 200:

{"result":true}

The code passed validation. Submit it with the selected Pricing to calculation and inspect the returned discount/promo fields; an accepted code can leave an unrelated item's discount at zero.

Consequential alternate: code unavailable

HTTP 409:

{"error":"invalid_promo","error_description":"Incorrect promo code","req_guid":"example-request"}

This occurs when the validator cannot find a valid code in the supplied context. Correct/remove it; do not invent a discount from a remembered code.

Recovery

HTTP	Code / response	Cause	Next action
401	`auth_failed` / `auth_access_fail`	Identity/account/resource restrictions.	Check existing member context or administrator restrictions.
404	`resource_not_exists`	Invalid header resource.	Correct the public resource key.
409	`invalid_promo`	Missing code, wrong resource/code, outside dates or exhausted global activation limit.	Inspect description; correct/remove the code and recalculate the chosen item.
406	`incorrect_data`	Source's unreadable-body branch.	Supply the JSON/form promo field; missing promo is normally handled by validation.

Provider payment errors are not part of this validation call. Validation does not reserve remaining activations, so later calculation/payment can differ.

Next task

Include the code in the member price calculation for the selected Pricing. Display only its returned discount, then follow the appropriate User subscriptions and Pricing selection.