Skip to content
Last updated

User activity

Reporting cardholder activity lets Percents measure engagement and activate offers when the observed action qualifies. Send actual clicks and views using your internal cardholder IDs or Percents IDs, including activity for PASSIVE offers. Use the policies, event examples and timing rules below to record those interactions consistently.

The branded SDK session flow identifies the active cardholder so the SDK can report activity within its screens on your behalf. Send activity through the API for experiences you build yourself. Do not submit the same SDK activity again.

Activation policies

Every offer exposes activationType. Cashback uses VIEW, CLICK or PASSIVE. Branded rewards support these policies and ONE_TIME merchant activation.

Use the returned offer ID, rate and terms. Activity alone does not earn a reward. A qualifying purchase is also required.

Offer policyWhat to record
PASSIVENo activation is required. Report observed views and clicks for engagement measurement. Earning depends on the offer dates and purchase requirements, not activity.
CLICKAn observed CLICK event through a cardholder user-activity route.
VIEWAn observed click, or matched ENTER_VIEWPORT and EXIT_VIEWPORT events with at least 50% continuous visibility for at least 1.3 seconds.

Branded Merchant Activation

At participating merchants, branded ONE_TIME offers use merchant activation. Read the activation state or record merchant activation for the cardholder group.

Merchant activation does not satisfy VIEW or CLICK activation and does not activate cashback offers. Those policies use observed cardholder activity through the routes below.

When Offers Need to Be Activated Again

An offer may require activation again after a set number of rewarded purchases. If that number is three, one activation covers three qualifying settled purchases. The cardholder must then activate the offer again before another purchase can earn a reward.

For CLICK and VIEW offers, activationScope sets how many qualifying settled purchases one activation covers for the cardholder group:

activationScopeWhen to activate again
1After each redemption, activate again before the next qualifying purchase.
A positive integerActivate again after that many redemptions.
nullActivation lasts for the offer's lifetime.

Qualifying settled purchases count as redemptions. Clicks, views and authorization estimates do not. PASSIVE offers need no activation.

The separate total redemption limit does not reset when the offer is activated again. That limit is maxRedemptionsPerGroup. activationScope only controls when activation is needed again.

Percents may preserve activation across related offers. Use the offer’s current activation status from the eligibility response to determine whether the cardholder needs to activate again.

Offer start and end dates still apply. Activation cannot qualify a purchase that occurred before it.

PolicyEffective activation time
CLICKThe recorded click's occurrence time.
VIEWThe click's occurrence time, or the matched exit's occurrence time for a qualifying view.
PASSIVEAlways on within the offer dates and purchase requirements. Report observed interactions for engagement measurement.

Branded merchant activation has its own merchant/cardholder group lifetime and does not activate cashback. See branded activation.

Activity batches

Send 1 to 100 activity events for one cardholder per request. Use your server-side issuer credential in the Authorization: token <tok_id>:<api_secret> header. No SDK or card is required.

RouteIdentity handling
POST /api/v2/cardholder/{cardholderId}/user-activityRequires an existing accessible public ch_ cardholder and resolves its group.
POST /api/v2/cardholder/external/{externalCardholderId}/user-activityResolves your internal cardholder ID and can create a missing cardholder or group.

Percent-encode each path component once. Both routes are issuer-scoped and share the same event-ID namespace. Choosing another route does not create a new activity identity.

Send Activity Before Accounts Exist

The external-ID activity endpoint accepts cardholder activity even before an account is provisioned. It follows the lazy account provisioning strategy, creating only the missing cardholder and cardholder group. Activity requests have no card context, so they do not create cards.

Include the optional externalCardholderGroupId in the request body to assign a new or unassigned cardholder to the specified group. Use your internal group ID. Percents creates the group if needed. For example:

{
  "externalCardholderGroupId": "issuer-group-001",
  "events": [
    {
      "eventId": "issuer-activity-001",
      "offerId": "mpo_66666666-6666-4666-8666-666666666666",
      "type": "CLICK",
      "occurredAt": "2026-07-01T18:41:00.000Z"
    }
  ]
}

Omitting the group ID follows the same lazy provisioning rules. Supplying it does not move an already assigned cardholder to a different group. See Cardholders & Cardholder Groups for assignment rules and the configured IDs to use.

Use an Existing Percents Cardholder ID

If you already have the cardholder's Percents ch_ ID, send the activity payload to POST /api/v2/cardholder/{cardholderId}/user-activity. This route uses the existing cardholder and their group. Use the external-ID route when accounts need to be created lazily.

{
  "externalCardholderGroupId": "issuer-group-001",
  "events": [
    {
      "eventId": "issuer-activity-001",
      "offerId": "mpo_66666666-6666-4666-8666-666666666666",
      "type": "CLICK",
      "occurredAt": "2026-07-01T18:41:00.000Z"
    }
  ]
}

Replaying the same event through either route is a duplicate when both resolve to the same cardholder and the event details match. Keep the original event ID when retrying.

Event fields and timestamps

FieldRequirement
eventIdStable ID for this individual event, unique across your integration. Use a different ID for each distinct fact.
offerIdThe returned public mpo_ offer ID.
typeCLICK, ENTER_VIEWPORT or EXIT_VIEWPORT.
occurredAtActual occurrence time as an ISO 8601 UTC timestamp ending in Z, for example 2026-07-01T18:39:01.300Z.
sessionIdRequired for ENTER_VIEWPORT and EXIT_VIEWPORT. Omit for CLICK.
exposureIdRequired for ENTER_VIEWPORT and EXIT_VIEWPORT. Use the same value for the matching pair. Omit for CLICK.
clickFlavorOptional extensible CLICK feedback, including ACTIVATE, OPEN, LIKE and DISLIKE.

Convert activity timestamps to UTC before sending them. Offset forms such as +01:00 are not accepted for activity occurredAt. Authorization and settlement timestamps follow their own request schemas.

CLICK events

Send an observed CLICK with a stable event ID and occurrence time. Do not include sessionId or exposureId for clicks. An optional clickFlavor, such as ACTIVATE, labels the action. A click can activate a CLICK or VIEW offer.

The cashback quickstart shows the minimal CLICK request.

VIEW events

A VIEW offer can be activated by an observed click, even if it was visible for less than 1.3 seconds. To report a view without a click, send the viewport events below.

  1. Record ENTER_VIEWPORT when at least 50% of the offer becomes visible.
  2. Record EXIT_VIEWPORT when that exposure ends or falls below the threshold. Send the actual exit time.
  3. Pair facts for the same cardholder, offer, session and exposure. Visibility must remain at least 50% for at least 1.3 seconds.

The entry and exit events can be sent in the same request or in separate requests. Use the same cardholder, offer, sessionId and exposureId so Percents can match the exposure.

This example sends both events together for a view lasting exactly 1.3 seconds. Replace the sample offer ID with the ID of a VIEW offer:

Send this payload to the external-ID activity endpoint:

{
  "events": [
    {
      "eventId": "activity-entry-001",
      "offerId": "mpo_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
      "type": "ENTER_VIEWPORT",
      "occurredAt": "2026-07-01T18:39:00.000Z",
      "sessionId": "session-001",
      "exposureId": "exposure-view-001"
    },
    {
      "eventId": "activity-exit-001",
      "offerId": "mpo_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
      "type": "EXIT_VIEWPORT",
      "occurredAt": "2026-07-01T18:39:01.300Z",
      "sessionId": "session-001",
      "exposureId": "exposure-view-001"
    }
  ]
}
  • A 1.299-second pair does not qualify.
  • There is no VIEW_QUALIFIED event or manual activation bypass.
  • An unclosed entry does not qualify. Do not infer an exit or pair different cardholders, offers, sessions or exposures.
  • Qualification is effective at the matched exit's occurrence time once the pair is established, not at entry or request receipt.
  • A late exit does not automatically reprice an already processed purchase.

Activity Idempotency

Use a unique eventId for each distinct activity event across all your cardholders, batches and both activity routes. A different cardholder, route or session does not make a reused event ID new.

Reuse of an Event IDOutcome
Same resolved cardholder and identical normalized event factsSuccessful retry with no repeated activation, including a replay through the other activity route or another batch.
Different cardholder, even within the same cardholder groupConflict.
Same cardholder but changed normalized factsConflict.
A distinct activity factAssign a new stable event ID.

Retry the original facts, including VIEW correlation and the action label when supplied. Changing the HTTP route or JSON property order does not make a new fact. The Percents-ID and external-ID routes must resolve to the same cardholder for a replay. Do not create a replacement ID merely to conceal an ownership or conflicting-facts error.

Responses and Errors

An existing cardholder returns 204 No Content. If the external-ID route creates a new cardholder, it returns 201 Created with only the accounts created by that operation. For the earlier request with externalCardholderGroupId: "issuer-group-001", creating both accounts returns:

{
  "lazilyProvisionedAccounts": {
    "cardholderGroup": {
      "externalId": "issuer-group-001",
      "percentsId": "chg_22222222-2222-4222-8222-222222222222"
    },
    "cardholder": {
      "externalId": "issuer-cardholder-001",
      "percentsId": "ch_33333333-3333-4333-8333-333333333333"
    }
  }
}

Store each returned mapping. Existing accounts are omitted. For example, a new cardholder in an existing group returns only cardholder. If no accounts are created, lazilyProvisionedAccounts is absent, including on a retry after creation succeeded.

HTTP outcomeMeaning
201A cardholder was provisioned. lazilyProvisionedAccounts contains its account mappings.
204Activity recorded for an existing cardholder. No body. An identical retry is also successful.
400Invalid request fields, timestamps or batch size.
401 / 403Authentication or issuer-access failure.
404A required public resource is inaccessible. The Percents-ID route does not create a missing cardholder.
409Conflicting identity assignment or reuse of an activity ID with different facts.
503 / network failureRetry temporary failures using the same cardholder, event IDs and facts.

Use the public error fields for diagnosis and retain error instance IDs for support.