Creates a new loyalty campaign — how cashback (or points) is generated for orders: the
rate (aliquot/aliquotType), the trigger, the validity window and the reward type.
This is a financial, hard-to-reverse write. Get the enum values EXACTLY right. This
database has no STRICT mode: an invalid ENUM value is stored as an empty string in
silence (no error), and the campaign then behaves in ways nobody asked for. Every field
below whose type says enum(...) lists its only accepted values — do not invent others
(client, points, delay are NOT valid).
Required for a successful insert (NOT NULL in the schema — the controller only checks
name, but the database rejects the row without these): name, aliquot, initAt,
finishAt, storeGroups, segmentations. Sending only name returns a 500.
A campaign created with trigger: audience-list is automatically paired with a
CampaignAudience record that drives audience-based scheduling.
HOW TO CREATE ONE — guided flow. Do NOT dump the whole form, and do NOT guess.
Walk the user through it one group at a time. For anything they already told you, restate
your understanding and ask them to confirm — do not ask again. Ask only for what is still
missing, in this order:
Basics — name; what fires it (trigger); and the reward: rewardType
(monetary/point) with the rate (aliquot + aliquotType; amounts in cents).
Window — initAt and finishAt (when the campaign evaluates orders).
Redeemability — availabilityMode: consecutiveDays (delayTime/expiryTime,
in SECONDS) or dateRange (dateRangeStart/dateRangeEnd).
Reach — storeGroups (empty = all stores) and any segmentations.
Narrowing rules (optional) — ask whether to limit by minimum/maximum value,
category, brand, tier, etc. Each is a SEPARATE call to the campaign-rule endpoint
after the campaign exists; see its docs for the per-rule params format.
Then show a FULL preview — every field, in plain language, amounts formatted back from
cents — and execute ONLY after the user explicitly confirms. This operation is financial
and requires confirmar=true, so it will not run without that confirmation regardless.
Try-it values populated from environment ACME (Demo)
Send your user token in the x-guper-authorization header. Endpoints that
support a Public mode (e.g. acúmulo and resgate previews) accept the same
request without the header — Private mode adds customer data and a
confirmation token to the response.
Headers
Name
Type
Description
x-guper-authorization
*
string
User token issued by Guper. Omit only on endpoints that explicitly support a Public mode.
Content-Type
*
string
Always `application/json` for endpoints that accept a JSON body.
Event that fires the campaign. When audience-list, a paired
CampaignAudience record is created automatically and you set list to the
audience-list id. When member-event, eventType must also be provided.
eventType
string | null
Required when trigger is member-event; leave null otherwise. Which
lifecycle event fires the campaign — e.g. membership_joined (customer joins
the program) or tier_achieved (customer reaches a higher tier).
type
string
Campaign category. Constrained enum — not free-form.
monetary | point | coupon | notification
isActive
boolean | int
Whether the campaign is active (BIT, default 1). Inactive campaigns are skipped during evaluation.
isDraft
boolean | int
Draft: saved but not published (BIT, default 0). While isDraft is true the campaign never runs and isActive is forced to 0 server-side. Publish by sending isDraft: false; a published campaign cannot go back to draft (400).
rewardType
string
Reward the campaign generates. monetary (default) or point — singular, NOT points.
monetary | point
pointsDividend
integer | null
Numerator of the points conversion ratio, used when rewardType is point.
These divisors are a SNAPSHOT of the campaign at creation — the card
copies them and clients (e.g. diageo) depend on that snapshot. Set them
deliberately; do not derive them from a wallet. See the point-vs-monetary
card notes before touching these.
pointsDivisor
integer | null
Denominator of the points conversion ratio (with pointsDividend). Same snapshot caveat.
aliquot
*
integer
Reward rate. Interpretation depends on aliquotType:
aliquotType=0 (fixed) → amount in cents per matching order/item
(1000 = R$10,00; 10000 = R$100,00);
aliquotType=1 (percentage) → the percentage value (5 = 5%).
aliquotType
bit (0|1)
0 (default) = aliquot is a fixed amount in cents; 1 = aliquot is a percentage.
coupon
integer | null
ID of an associated coupon batch (Coupon model). Only for type: coupon.
recurrentByOrder
boolean | int
BIT, default 0. When 1, the campaign can fire on every order; when 0, only the first matching order.
availabilityMode
string
How the generated card's validity is decided (there is NO delay value):
consecutiveDays → uses delayTime (when it becomes redeemable) and
expiryTime (how long it lasts), both counted from the purchase;
consecutiveDays mode. Delay, in SECONDS (not days), from the purchase
until the card becomes redeemable. 86400 = 24h = the card is only usable the
next day. 0 = usable immediately.
expiryTime
integer (seconds) | null
consecutiveDays mode. Card lifetime in SECONDS (not days) from when it
becomes redeemable. 1296000 = 15 days; 86400 = 1 day. Sending 15 means
15 SECONDS.
expiryPeriod
string
Optional calendar-based expiry unit, when expiry is expressed as whole weeks/months/years instead of a raw expiryTime in seconds.
week | month | year
dateRangeStart
string (date-time) | null
dateRange mode: the date the cards become redeemable.
dateRangeEnd
string (date-time) | null
dateRange mode: the date the cards expire.
initAt
*
string (date-time)
Date the campaign STARTS evaluating orders. Required (NOT NULL). This is the campaign window, distinct from card validity.
finishAt
*
string (date-time)
Date the campaign STOPS evaluating orders. Required (NOT NULL).
storeGroups
*
string (JSON) — required
Which store groups the campaign applies to. Stored as text and required
(NOT NULL). An empty string "" means ALL stores — that is the common
value. Otherwise a JSON array of store-group ids (e.g. "[12,15]").
segmentations
*
string (JSON) — required
Audience segmentation rules. Stored as text and required (NOT NULL). The
common value is an empty array "[]" (no segmentation). Otherwise a JSON
array of segmentation rules.
redemptionPolicy
integer | null
ID of the redemption policy for the cards this campaign generates (min/max order total, wallet, etc.). See the policy endpoints.
messageSequence
string | null
ID/key of the message sequence triggered for the customer.
campaignTag
integer | null
Register tag id used to mark customers reached by the campaign.
rewardSegmentAdd
array | string | null
Segments ADDED to the customer when the reward fires. JSON-stored.
rewardSegmentDel
array | string | null
Segments REMOVED from the customer when the reward fires. JSON-stored.
list
integer | null
Audience-list id this campaign targets. Set together with trigger: audience-list.
reactivateWithActiveCards
boolean | int
reactivate-reward flows: reactivate even when the customer still has active cards (default 0).
skipWithActiveCards
boolean | int
reactivate-reward flows: skip the customer when they already have active cards from this campaign (default 1).
reactivationDateStart
string (date-time) | null
Start of the reactivation window (reactivate-reward flows).
reactivationDateEnd
string (date-time) | null
End of the reactivation window (reactivate-reward flows).