{"templateId":"markdown","versions":[{"version":"2.0","label":"v2.0","link":"/percents-api/user-activity","default":true,"active":true,"folderId":"27d36c3a"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"User activity"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"user-activity","__idx":0},"children":["User activity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSIVE"]}," offers. Use the policies, event examples and timing rules below to record those interactions consistently."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/auth-security/sdk-auth"},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"activation-policies","__idx":1},"children":["Activation policies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every offer exposes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activationType"]},". Cashback uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSIVE"]},". Branded rewards support these policies and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ONE_TIME"]}," merchant activation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the returned offer ID, rate and terms. Activity alone does not earn a reward. A qualifying purchase is also required."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Offer policy"},"children":["Offer policy"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to record"},"children":["What to record"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSIVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No activation is required. Report observed views and clicks for engagement measurement. Earning depends on the offer dates and purchase requirements, not activity."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An observed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," event through a cardholder user-activity route."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An observed click, or matched ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENTER_VIEWPORT"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXIT_VIEWPORT"]}," events with at least 50% continuous visibility for at least 1.3 seconds."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"branded-merchant-activation","__idx":2},"children":["Branded Merchant Activation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At participating merchants, branded ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ONE_TIME"]}," offers use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/merchant-activation-eligibility#branded-merchant-activation"},"children":["merchant activation"]},". ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/getMerchantActivation"},"children":["Read the activation state"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/activateMerchant"},"children":["record merchant activation"]}," for the cardholder group."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Merchant activation does not satisfy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," activation and does not activate cashback offers. Those policies use observed cardholder activity through the routes below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-offers-need-to-be-activated-again","__idx":3},"children":["When Offers Need to Be Activated Again"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}," offers, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activationScope"]}," sets how many qualifying settled purchases one activation covers for the cardholder group:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"activationScope"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activationScope"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When to activate again"},"children":["When to activate again"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["After each redemption, activate again before the next qualifying purchase."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A positive integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Activate again after that many redemptions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Activation lasts for the offer's lifetime."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Qualifying settled purchases count as redemptions. Clicks, views and authorization estimates do not. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSIVE"]}," offers need no activation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The separate total redemption limit does not reset when the offer is activated again. That limit is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["maxRedemptionsPerGroup"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activationScope"]}," only controls when activation is needed again."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Percents may preserve activation across related offers. Use the offer’s current activation status from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/offers#merchant-eligibility"},"children":["eligibility response"]}," to determine whether the cardholder needs to activate again."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Offer start and end dates still apply. Activation cannot qualify a purchase that occurred before it."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Policy"},"children":["Policy"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Effective activation time"},"children":["Effective activation time"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The recorded click's occurrence time."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The click's occurrence time, or the matched exit's occurrence time for a qualifying view."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSIVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always on within the offer dates and purchase requirements. Report observed interactions for engagement measurement."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Branded merchant activation has its own merchant/cardholder group lifetime and does not activate cashback. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/branded-rewards/merchant-activation-eligibility#branded-merchant-activation"},"children":["branded activation"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"activity-batches","__idx":4},"children":["Activity batches"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send 1 to 100 activity events for one cardholder per request. Use your server-side issuer credential in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: token <tok_id>:<api_secret>"]}," header. No SDK or card is required."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Route"},"children":["Route"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Identity handling"},"children":["Identity handling"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordCardholderUserActivity"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/cardholder/{cardholderId}/user-activity"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requires an existing accessible public ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ch_"]}," cardholder and resolves its group."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordExternalCardholderUserActivity"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v2/cardholder/external/{externalCardholderId}/user-activity"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resolves your internal cardholder ID and can create a missing cardholder or group."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"send-activity-before-accounts-exist","__idx":5},"children":["Send Activity Before Accounts Exist"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordExternalCardholderUserActivity"},"children":["external-ID activity endpoint"]}," accepts cardholder activity even before an account is provisioned. It follows the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cardholder-groups#lazy-provisioning"},"children":["lazy account provisioning strategy"]},", creating only the missing cardholder and cardholder group. Activity requests have no card context, so they do not create cards."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"events\": [\n    {\n      \"eventId\": \"issuer-activity-001\",\n      \"offerId\": \"mpo_66666666-6666-4666-8666-666666666666\",\n      \"type\": \"CLICK\",\n      \"occurredAt\": \"2026-07-01T18:41:00.000Z\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Omitting the group ID follows the same lazy provisioning rules. Supplying it does not move an already assigned cardholder to a different group. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cardholder-groups#lazy-provisioning"},"children":["Cardholders & Cardholder Groups"]}," for assignment rules and the configured IDs to use."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-an-existing-percents-cardholder-id","__idx":6},"children":["Use an Existing Percents Cardholder ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you already have the cardholder's Percents ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ch_"]}," ID, send the activity payload to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordCardholderUserActivity"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"externalCardholderGroupId\": \"issuer-group-001\",\n  \"events\": [\n    {\n      \"eventId\": \"issuer-activity-001\",\n      \"offerId\": \"mpo_66666666-6666-4666-8666-666666666666\",\n      \"type\": \"CLICK\",\n      \"occurredAt\": \"2026-07-01T18:41:00.000Z\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"event-fields-and-timestamps","__idx":7},"children":["Event fields and timestamps"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Requirement"},"children":["Requirement"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stable ID for this individual event, unique across your integration. Use a different ID for each distinct fact."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The returned public ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mpo_"]}," offer ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENTER_VIEWPORT"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXIT_VIEWPORT"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occurredAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Actual occurrence time as an ISO 8601 UTC timestamp ending in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Z"]},", for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2026-07-01T18:39:01.300Z"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENTER_VIEWPORT"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXIT_VIEWPORT"]},". Omit for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exposureId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENTER_VIEWPORT"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXIT_VIEWPORT"]},". Use the same value for the matching pair. Omit for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clickFlavor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional extensible ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," feedback, including ACTIVATE, OPEN, LIKE and DISLIKE."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Convert activity timestamps to UTC before sending them. Offset forms such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+01:00"]}," are not accepted for activity ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["occurredAt"]},". Authorization and settlement timestamps follow their own request schemas."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"click-events","__idx":8},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send an observed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," with a stable event ID and occurrence time. Do not include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exposureId"]}," for clicks. An optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clickFlavor"]},", such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVATE"]},", labels the action. A click can activate a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}," offer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/cashback/quickstart#2-record-the-cardholders-click"},"children":["cashback quickstart"]}," shows the minimal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLICK"]}," request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"view-events","__idx":9},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}," events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Record ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ENTER_VIEWPORT"]}," when at least 50% of the offer becomes visible."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Record ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EXIT_VIEWPORT"]}," when that exposure ends or falls below the threshold. Send the actual exit time."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pair facts for the same cardholder, offer, session and exposure. Visibility must remain at least 50% for at least 1.3 seconds."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The entry and exit events can be sent in the same request or in separate requests. Use the same cardholder, offer, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exposureId"]}," so Percents can match the exposure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example sends both events together for a view lasting exactly 1.3 seconds. Replace the sample offer ID with the ID of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW"]}," offer:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send this payload to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/openapi/percents-api#operation/recordExternalCardholderUserActivity"},"children":["external-ID activity endpoint"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"events\": [\n    {\n      \"eventId\": \"activity-entry-001\",\n      \"offerId\": \"mpo_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\n      \"type\": \"ENTER_VIEWPORT\",\n      \"occurredAt\": \"2026-07-01T18:39:00.000Z\",\n      \"sessionId\": \"session-001\",\n      \"exposureId\": \"exposure-view-001\"\n    },\n    {\n      \"eventId\": \"activity-exit-001\",\n      \"offerId\": \"mpo_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa\",\n      \"type\": \"EXIT_VIEWPORT\",\n      \"occurredAt\": \"2026-07-01T18:39:01.300Z\",\n      \"sessionId\": \"session-001\",\n      \"exposureId\": \"exposure-view-001\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A 1.299-second pair does not qualify."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["There is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VIEW_QUALIFIED"]}," event or manual activation bypass."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An unclosed entry does not qualify. Do not infer an exit or pair different cardholders, offers, sessions or exposures."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Qualification is effective at the matched exit's occurrence time once the pair is established, not at entry or request receipt."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A late exit does not automatically reprice an already processed purchase."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"activity-idempotency","__idx":10},"children":["Activity Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Reuse of an Event ID"},"children":["Reuse of an Event ID"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Outcome"},"children":["Outcome"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same resolved cardholder and identical normalized event facts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Successful retry with no repeated activation, including a replay through the other activity route or another batch."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Different cardholder, even within the same cardholder group"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conflict."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same cardholder but changed normalized facts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conflict."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A distinct activity fact"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Assign a new stable event ID."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retry the original facts, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"responses-and-errors","__idx":11},"children":["Responses and Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCardholderGroupId: \"issuer-group-001\""]},", creating both accounts returns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"lazilyProvisionedAccounts\": {\n    \"cardholderGroup\": {\n      \"externalId\": \"issuer-group-001\",\n      \"percentsId\": \"chg_22222222-2222-4222-8222-222222222222\"\n    },\n    \"cardholder\": {\n      \"externalId\": \"issuer-cardholder-001\",\n      \"percentsId\": \"ch_33333333-3333-4333-8333-333333333333\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store each returned mapping. Existing accounts are omitted. For example, a new cardholder in an existing group returns only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardholder"]},". If no accounts are created, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," is absent, including on a retry after creation succeeded."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP outcome"},"children":["HTTP outcome"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A cardholder was provisioned. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lazilyProvisionedAccounts"]}," contains its account mappings."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Activity recorded for an existing cardholder. No body. An identical retry is also successful."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid request fields, timestamps or batch size."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication or issuer-access failure."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A required public resource is inaccessible. The Percents-ID route does not create a missing cardholder."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conflicting identity assignment or reuse of an activity ID with different facts."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}," / network failure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry temporary failures using the same cardholder, event IDs and facts."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/percents-api/standards/errors"},"children":["public error fields"]}," for diagnosis and retain error instance IDs for support."]}]},"headings":[{"value":"User activity","id":"user-activity","depth":1},{"value":"Activation policies","id":"activation-policies","depth":2},{"value":"Branded Merchant Activation","id":"branded-merchant-activation","depth":3},{"value":"When Offers Need to Be Activated Again","id":"when-offers-need-to-be-activated-again","depth":2},{"value":"Activity batches","id":"activity-batches","depth":2},{"value":"Send Activity Before Accounts Exist","id":"send-activity-before-accounts-exist","depth":3},{"value":"Use an Existing Percents Cardholder ID","id":"use-an-existing-percents-cardholder-id","depth":3},{"value":"Event fields and timestamps","id":"event-fields-and-timestamps","depth":3},{"value":"CLICK events","id":"click-events","depth":3},{"value":"VIEW events","id":"view-events","depth":3},{"value":"Activity Idempotency","id":"activity-idempotency","depth":2},{"value":"Responses and Errors","id":"responses-and-errors","depth":2}],"frontmatter":{"title":"User activity","description":"Determine whether an offer qualifies for activation from clicks and visibility events.","seo":{"title":"User activity"}},"lastModified":"2026-11-10T20:25:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/percents-api/user-activity","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}