Sign in

Create

POST https://{organization}.myguper.com/api/loyalty/campaign

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:

  1. Basics — name; what fires it (trigger); and the reward: rewardType (monetary/point) with the rate (aliquot + aliquotType; amounts in cents).
  2. Window — initAt and finishAt (when the campaign evaluates orders).
  3. Redeemability — availabilityMode: consecutiveDays (delayTime/expiryTime, in SECONDS) or dateRange (dateRangeStart/dateRangeEnd).
  4. Reach — storeGroups (empty = all stores) and any segmentations.
  5. 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)


Authentication

Token

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.

Request body

Content-Type: application/json

{
    "name": "Aniversário — 10% cashback",
    "displayName": "Feliz aniversário!",                        // optional
    "beneficiaryType": "buyer",                                 // optional, referrer | buyer
    "trigger": "purchase",                                      // optional
    "eventType": "tier_achieved",                               // optional
    "type": "monetary",                                         // optional, monetary | point | coupon | notification
    "isActive": true,                                           // optional
    "isDraft": false,                                           // optional
    "rewardType": "monetary",                                   // optional, monetary | point
    "pointsDividend": 1,                                        // optional
    "pointsDivisor": 1,                                         // optional
    "aliquot": 1000,
    "aliquotType": 0,                                           // optional
    "coupon": 0,                                                // optional
    "recurrentByOrder": false,                                  // optional
    "availabilityMode": "consecutiveDays",                      // optional, consecutiveDays | dateRange
    "delayTime": 86400,                                         // optional
    "expiryTime": 1296000,                                      // optional
    "expiryPeriod": "<expiryPeriod>",                           // optional, week | month | year
    "dateRangeStart": "2026-03-01T00:00:00-03:00",              // optional
    "dateRangeEnd": "2026-12-31T23:59:59-03:00",                // optional
    "initAt": "2026-03-01T00:00:00-03:00",
    "finishAt": "2026-03-31T23:59:59-03:00",
    "storeGroups": "",
    "segmentations": "[]",
    "redemptionPolicy": 0,                                      // optional
    "messageSequence": "<messageSequence>",                     // optional
    "campaignTag": 0,                                           // optional
    "rewardSegmentAdd": "<rewardSegmentAdd>",                   // optional
    "rewardSegmentDel": "<rewardSegmentDel>",                   // optional
    "list": 0,                                                  // optional
    "reactivateWithActiveCards": false,                         // optional
    "skipWithActiveCards": true,                                // optional
    "reactivationDateStart": "<reactivationDateStart>",         // optional
    "reactivationDateEnd": "<reactivationDateEnd>"              // optional
}

Responses

Copied to clipboard