Reading points campaigns from GET

This guide is aimed at the integrations team interpreting already-created points and wallet campaigns when listing them via GetAListOfScoreCampaigns (internal equivalent: GET /points) and aligning them with the ticket sent to the Streaming API.

Scope: points/wallet campaigns for the configured when event: cart (after_create_activity), triggers (configured trigger slug for the Company), custom events (after_create_custom_entity), or direct assignment (manual). Challenges are out of scope here (documented separately). The rule_* JSON grammar matches discounts except for when restrictions and balance lifecycle.

On this page

• Guide contents
• Canonical model
• Accrual modalities (points vs wallet)
• Audience in points (select_customers)
• Reference by event (when)
• How to read a campaign step by step
• Direct assignment (manual)
• Integration checklist
• Related pages

---

Guide contents

Page	What it covers
GET response	Query params, metadata, activation/expiration, JSON parsing
Conditions	rule_conditions: AND/OR, customer/cart/line/store catalogs
Application	rule_application: accrual scope on lines
Effects	rule_effects: types, distribution, limits, bundle, scores[] on ticket

Canonical model

Field	What it represents
rule_conditions	Victory conditions: when can the campaign accrue?
rule_application	Application: which lines is accrual calculated on?
rule_effects	Effect: how many points/balance and how it is distributed

Always use rule_conditions, rule_application, rule_effects (not rules_* or legacy aliases). rule_application is not distribution; distribution goes in rule_effects.distribution.

---

Accrual modalities (points vs wallet)

A loyalty program can present accrual to the customer in two ways:

Modality	What the customer sees	Example copy
Points	Units (points, miles, likes, …); default label in the platform: points	“Earn points”
Wallet (money)	Monetary balance in a wallet, without a points concept	“Add balance to your wallet”

Internally the engine treats both the same: the customer accrues a value with monetary potential. The Company chooses how to present and operate it in Owner App and integrations via accrual_mode (Company configuration):

accrual_mode	Behavior
points	Points-oriented copy and flows; the Streaming API converts and displays in point units using the currency’s score_exchange.
money	Wallet/money-oriented copy and flows; accrual is expressed and redeemed as a monetary amount.

The engine logic is uniform; presentation and parts of Streaming API behavior (accrue, display, redeem) differ. When reading campaigns from GET, check currency and accrual_mode (if present) on each data[] item — see GET response.

How to interpret rule_effects.value (always stored in money) is in Effects — Monetary value.

---

Audience in points (select_customers)

Points/wallet campaigns do not support all_customers (mass campaigns without a specific customer). Accrual requires an identified customer; the engine cannot grant balance “in the air” like a mass discount leaflet.

Value in GET / Owner App	Use in points
loyalty	Enrolled club customers (typical for cart, triggers, and direct assignment).
targeted	Targeted delivery (specific audience / voucher).
all_customers	Not applicable in points — discounts only.

If you see select_customers: "all_customers" in a points list, treat it as inconsistent or legacy data; valid configuration is loyalty or targeted.

---

Reference by event (when)

Each points campaign has a single when. That drives which effects, distributions, and rule_* blocks are valid.

Event	when (API)	Effects	Distributions	rule_conditions	rule_application	select_customers
Cart	after_create_activity	All 6 types	All 3 + per-type rules	Full catalog (same as discounts)	Lines, additional costs, payments	loyalty, targeted
Trigger	Company-configured slug	direct_value only	total only	No ticket conditions	No block	loyalty
Custom event	after_create_custom_entity	percentage, ratio, direct_value	total only	Event attributes	Numeric event field	loyalty, targeted
Direct assignment	manual	direct_value only	total only	Empty required	No block	loyalty

See Effects for each effect type and distribution in detail.

---

How to read a campaign step by step

1. Metadata and validity — id, name, active, available_from / available_to, category, currency, accrual_mode (if applicable). See GET /points response.
2. Event (when) and audience — Identify the event (cart, trigger, custom event, direct assignment). Review select_customers: only loyalty or targeted (see Audience). See Points Campaigns.
3. Victory conditions — Parse rule_conditions (JSON string). For manual, it may be empty: {"conditions":{"and":[]}}. See Conditions.
4. Application — rule_application limits lines; if missing, scope depends on when and effect type. See Application.
5. Effect — rule_effects: type, value, unit (ratio), distribution, limits, rule_group. See Effects.
6. Activation and expiration — activation_period_type, activation_delay, expiration_period_type, availability_duration explain pending vs available balance.
7. Victory limits — once, once_limit, budget — see Limits (distinct from rule_effects.limits).

---

Direct assignment (manual)

Points/wallet campaigns an operator triggers without a purchase ticket. In GET they have when: "manual"; lists support GET /points?when=manual.

When reading a direct-assignment campaign, expect this profile (creation: Campaigns API):

Aspect	Typical value for manual
rule_conditions	Empty: {"conditions":{"and":[]}}
rule_effects	direct_value only; distribution: "total"; rule_group: false
select_customers	"loyalty" (enrolled customers)
rule_application	Usually omitted (no cart lines)
Ticket accrual	No cart flow; balance is assigned via operational/admin flow, not via scores[] on POST /activities

---

Integration checklist

• GET /points with correct filters (when, customer_id, countries, …); ?when=manual for direct assignment.
• Pagination: next_token_starts_after → starting_after until data[] is exhausted.
• Map GetAListOfScoreCampaigns to rule_conditions, rule_application, rule_effects.
• Parse JSON when rule_* fields are serialized strings.
• Validate restrictions per when using the matrix by event (effects, distributions, rule_conditions, rule_application).
• Confirm select_customers is not all_customers.
• With accrual_mode: points, convert rule_effects.value (money) to points using the campaign currency’s score_exchange.
• Review activation/expiration before reporting “did not accrue”.
• On ticket: validate scores[] (accrual) against GET rule_effects; effects[] is for discounts.

Related pages

• Points Campaigns — triggers and Owner App configuration
• Limits — victory frequency and budget
• Campaigns API — creation with flat format