promotions

Specifies one or more promotional offers applicable to the offer. Enables detailed representation of discounts, special deals or incentives to improve sales and engagement.

benefit

Description

Specifies the advantage or reward granted by the promotion. Enables clear communication of what the customer gains.

Guideline

Clear description of the reward.

Correct Example

"benefit": "10% discount on your total order"

Incorrect Example

"benefit": "huge discount on your total order"

countries

Description

List of country codes where the promotion is valid. Enables geo-targeting for accurate promotion eligibility.

Guideline

Use the ISO 3166 short name.

Correct Example

"countries": ["Italy"]

Incorrect Example

"countries": ["IT"]

minimum_age

Description

Minimum age required to be eligible for the promotion. Helps enforce age-appropriate targeting.

Guideline

Use a positive integer.

Correct Example

"minimum_age": 18

Incorrect Example

"minimum_age": "adult"

subscribed_email_required

Description

Indicates whether users must be subscribed to email marketing to qualify. Enables promotions tied to communication opt-in.

user_type

Description

Specifies the customer type the promotion applies to. Enables segmentation by user journey stage.

Guideline

Use the enumerated values.

Enumerated Values

• new_customer — First-time buyer or newly registered user
• existing_customer — User with past purchases or activity
• all — Promotion available to all users

minimum_purchase_amount

Description

Minimum spend required to activate the promotion. Supports conditional promotions based on order value.

Guideline

Currency symbol followed by the amount.

Correct Example

"minimum_purchase_amount": "€5"

Incorrect Example

"minimum_purchase_amount": "EUR 5"

note

Description

Optional disclaimer or notice related to eligibility. Helps communicate important conditions or limitations that users should be aware of.

Guideline

Concise text with clear message.

Correct Example

"note": "Offer not valid during public holidays"

Incorrect Example

"note": "Public holidays excluded"

custom_rules

Description

Additional eligibility notes or clarifications. Enables inclusion of custom rules that don't fit structured fields.

Guideline

Each rule must be a clear, actionable condition, not vague.

Correct Example

"custom_rules": ["Must complete onboarding tutorial"]

Incorrect Example

"custom_rules": ["Onboarding tutorial"]

linked_offer

Description

Provides a direct URL to the related offer. Enables easy access and reference to the specific offer from the promotion.

Guideline

Use a direct, public URL to the offer. Avoid redirects, query strings, or tracking codes.

Correct Example

"linked_offer": "https://acmecorp.com/products/vinyl-turntable"

Incorrect Example

"linked_offer": "/products/vinyl-turntable"