Mobile App Engagement (Custom Actions)

One shared, server-to-server endpoint for partner apps (for example Shopney). The partner reports that a customer completed an action in its app. Joy maps the action to the Mobile app action program the merchant turned on and rewards the customer once.

context.provider is a self-declared label used for audit only; there is no partner-specific behaviour.

Plan: the store must be on the Ultimate plan. Other paid plans get HTTP 200 with status: "not_eligible" and reason: "plan_not_eligible"; the Free plan gets 402.

Key points

• Server only. Call it from the partner's server with the store's App ID and Secret Key. Never ship the Secret Key inside a mobile app or put it in a WebView URL.
• Business results are HTTP 200. Read status (awarded, already_awarded, not_eligible). Only infrastructure problems return 5xx.
• Safe to retry. Resend the same eventId and Joy never rewards twice (see Retry guidance).
• Once per customer. Sending the same action again on the next login returns already_awarded.
• Exempt from the daily quota, with its own burst limit (see Rate limits).

Authentication

POST https://api.joy.so/rest_api/v2/custom-actions
Content-Type: application/json
X-Joy-Loyalty-App-Key: <store App ID>
X-Joy-Loyalty-Secret-Key: <store Secret Key>
Idempotency-Key: shopney-evt-01JABC123

The keys are the pair the merchant copies from Settings → Developers. Read-only (ro_) keys are rejected with 403 because this is a POST. Use https://dev-api.joy.so only when you were told to use staging.

Request

eventId, actionName, occurredAt, customer and context are required (so are customer.shopifyCustomerId, context.provider and context.platform). Fields that are not listed are ignored. Joy returns the first validation problem it finds, as 400 VALIDATION_ERROR with the field name in details.field.

{
  "eventId": "shopney-evt-01JABC123",
  "actionName": "mobile_push_permission_granted",
  "occurredAt": "2026-10-26T12:05:00Z",
  "shop": {"myshopifyDomain": "example.myshopify.com"},
  "customer": {"shopifyCustomerId": "gid://shopify/Customer/123456789"},
  "context": {
    "provider": "shopney",
    "platform": "ios",
    "appVersion": "5.2.0",
    "permissionStatus": "authorized"
  }
}

Actions

Response

Every business result is HTTP 200, with status at the top level (there is no data envelope):

{
  "success": true,
  "status": "awarded",
  "reason": null,
  "eventId": "shopney-evt-01JABC123",
  "actionName": "mobile_push_permission_granted",
  "reward": {"type": "points", "amount": 100},
  "replayed": false
}

Treat the event as done only when success is true and status is present.

replayed: true (and the response header Idempotent-Replayed: true) means the eventId was already processed and this is the original result.

reason when not_eligible

Errors

There are two error shapes. Branch on the HTTP status and on success.

• Errors from Joy's API gateway (401, 402, 429, and 403 for a read-only key) return {"success": false, "error": "<string>"}, and an uninstalled store is HTTP 200 with {"error": "shop uninstalled", "code": "SHOP_UNINSTALLED"}.
• Every other error uses the standard envelope {"success": false, "error": {"message", "code", "statusCode", "details?"}, "timestamp"}.

Note the difference from /transactions/points/award: a reused idempotency key is 409 IDEMPOTENCY_KEY_REUSED here, but 422 there.

Requests rejected before the event is recorded (400, 403, 404 ACTION_NOT_FOUND, 503, and the gateway errors) leave no trace, so they can be resent freely once fixed.

Retry guidance

Always resend with the same eventId (and Idempotency-Key), so a retry can never reward twice. If a 5xx is returned, a reward may or may not have been issued; the same eventId is the way to find out, because the retry answers awarded, already_awarded or the stored result.

Idempotency

1. eventId is required, and Idempotency-Key must equal it.
2. A first request records the event and processes it.
3. The same eventId with the same content returns the stored result with replayed: true and never rewards again. The content that counts is actionName, the customer and permissionStatus; occurredAt and appVersion are not compared.
4. The same eventId with different content returns 409 IDEMPOTENCY_KEY_REUSED.
5. A request that is still running returns 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 2. Resend the same eventId after it, at most 5 attempts, then stop and contact Joy.
6. Joy remembers an eventId for 24 hours. Retry within that window; after it, a resend of an already rewarded event answers already_awarded (no second reward).

A new event, such as the next login, needs a new eventId. It does not reward again: the customer already has a reward claim for the program, so Joy answers already_awarded.

Rate limits

This path is exempt from the daily quota (so a login wave does not use up the quota shared with the other REST and MCP calls) and has its own burst limit:

Rewards need the Ultimate plan. On other paid plans the request is accepted (Pro 50, Advanced 100 requests per 10 seconds) but answers not_eligible / plan_not_eligible; the Free plan (Starter in the Shopify admin) gets 402.

An overall limit of 120 requests per 10 seconds still applies to every request on every plan, and is shared with the rest of the API. Successful responses carry no X-RateLimit-* headers. On 429 wait for Retry-After.

Which actions are on (GET /rest_api/v2/custom-actions)

Send POST /custom-actions only for actions this endpoint reports as enabled.

GET https://api.joy.so/rest_api/v2/custom-actions
X-Joy-Loyalty-App-Key: <store App ID>
X-Joy-Loyalty-Secret-Key: <store Secret Key or read-only key>

• Keys: the same pair as the POST. Read-only (ro_) keys are accepted.
• Quota: exempt from the daily quota, with its own burst limit (the same numbers as the POST, counted separately, so polling never limits your event POSTs). The overall 120 requests per 10 seconds still applies. Same 402 and 503 CUSTOM_ACTIONS_TEMPORARILY_DISABLED as the POST.
• When to call: when the store connects, about once a day, and after the webhooks below.

{
  "success": true,
  "data": {
    "version": "2026-10-30T08:00:00.000Z",
    "actions": [
      {
        "actionName": "mobile_push_permission_granted",
        "enabled": true,
        "programId": "9cN2xkq0",
        "reward": {"type": "points", "amount": 100},
        "startDate": null,
        "endDate": null
      },
      {"actionName": "mobile_app_first_authenticated_session", "enabled": false}
    ]
  },
  "meta": {},
  "timestamp": "2026-10-30T08:00:00.123Z"
}

Program webhooks (program/created, program/updated, program/deleted)

Subscribe to these topics through the Webhook API, like points/earned. They cover earning and spending programs, including Mobile app action programs.

{
  "webhookId": "0b9f3c1e-6a43-4c55-9d0e-2f5d1c7a8b10",
  "topic": "program/updated",
  "triggeredAt": "2026-10-30T08:00:00.000Z",
  "data": {
    "id": "9cN2xkq0",
    "type": "earning",
    "event": "custom_program",
    "typeCustom": "custom_action_9cN2xkq0",
    "actionName": "mobile_push_permission_granted",
    "title": "Turn on notifications",
    "status": false,
    "earnPoint": 100,
    "updatedAt": "2026-10-30T07:59:59.000Z"
  }
}

• data is the REST v2 Program shape (the same as GET /rest_api/v2/programs/{id}). actionName is present only on Mobile app action programs (typeCustom starting with custom_action_).
• Headers: X-Joy-Loyalty-Topic, X-Joy-Loyalty-Shop-Source-Id, and X-Joy-Loyalty-Hmac-Sha256: the base64 HMAC-SHA256 of the raw request body, keyed with the store's Secret Key. Verify it against the raw bytes before parsing.
• Delivery is at least once. Answer 2xx within 10 seconds. Any other answer, or none, is retried after 1 min, 10 min, 1 h, 6 h and 16 h (6 attempts over about 23 hours), then dropped. The same event can arrive more than once: dedupe on webhookId. A retry of program/created or program/updated is dropped when the program was deleted or changed again in the meantime, because a newer event carries the newer state.
• Order is not guaranteed. Keep the latest triggeredAt you processed for each data.id, and ignore an event whose triggeredAt is older.
• Re-fetch the read model. On any program/* event whose data.typeCustom starts with custom_action_, call GET /rest_api/v2/custom-actions instead of deriving enabled from the payload. enabled also changes without any event: when a startDate or endDate passes, when the store's plan changes, or when app rewards are turned off for the store. Keep the daily resync for those cases.

Examples

Reward for turning on notifications:

curl -X POST "https://api.joy.so/rest_api/v2/custom-actions" \
  -H "X-Joy-Loyalty-App-Key: $JOY_APP_KEY" \
  -H "X-Joy-Loyalty-Secret-Key: $JOY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shopney-evt-01JABC123" \
  -d '{
    "eventId": "shopney-evt-01JABC123",
    "actionName": "mobile_push_permission_granted",
    "occurredAt": "2026-10-26T12:05:00Z",
    "shop": {"myshopifyDomain": "example.myshopify.com"},
    "customer": {"shopifyCustomerId": "gid://shopify/Customer/123456789"},
    "context": {"provider": "shopney", "platform": "ios", "permissionStatus": "authorized"}
  }'

Already rewarded (the next login, with a new eventId):

{
  "success": true,
  "status": "already_awarded",
  "reason": null,
  "eventId": "shopney-evt-01JABC124",
  "actionName": "mobile_app_first_authenticated_session",
  "replayed": false
}

Not eligible:

{
  "success": true,
  "status": "not_eligible",
  "reason": "permission_not_granted",
  "eventId": "shopney-evt-01JABC125",
  "actionName": "mobile_push_permission_granted",
  "replayed": false
}

Customer not in Joy yet (retry with the same eventId):

{
  "success": false,
  "error": {
    "message": "Customer not found",
    "code": "CUSTOMER_NOT_FOUND",
    "statusCode": 404,
    "details": {"retryable": true}
  },
  "timestamp": "2026-10-26T12:05:00.123Z"
}

Same eventId, different content:

{
  "success": false,
  "error": {
    "message": "This eventId was already used with different content",
    "code": "IDEMPOTENCY_KEY_REUSED",
    "statusCode": 409
  },
  "timestamp": "2026-10-26T12:05:00.123Z"
}

How merchants turn it on

The merchant creates a Mobile app action program in the Joy admin (Custom program → Trigger action → Mobile app action), picks the action and the reward, and turns it on. The program can only be created in the admin: REST v2 program creation rejects the custom_action type, and the storefront triggerActivity rejects it too.

• First login in the app shows on the website's Ways to earn as an invitation to download the app (App Store / Google Play links). A click only opens the link and never earns.
• Turn on notifications is hidden on the website. Points are not taken back if the customer later turns notifications off.
• The once-per-customer record belongs to the program: if the merchant deletes the program and creates a new one, customers can be rewarded again by the new program.
• Each reward goes through the same emails, tier progress and points/earned webhook as any other earning.

API reference

List custom actions

GET /rest_api/v2/custom-actions HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "version": "2026-10-30T08:00:00.000Z",
    "actions": [
      {
        "actionName": "mobile_push_permission_granted",
        "enabled": true,
        "programId": "9cN2xkq0",
        "reward": {
          "type": "points",
          "amount": 100
        },
        "startDate": null,
        "endDate": null
      },
      {
        "actionName": "mobile_app_first_authenticated_session",
        "enabled": false
      }
    ]
  },
  "meta": {},
  "timestamp": "2026-10-30T08:00:00.123Z"
}

Report a customer action

POST /rest_api/v2/custom-actions HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 409

{
  "eventId": "shopney-evt-01JABC123",
  "actionName": "mobile_push_permission_granted",
  "occurredAt": "2026-10-26T12:05:00Z",
  "shop": {
    "myshopifyDomain": "example.myshopify.com"
  },
  "customer": {
    "shopifyCustomerId": "gid://shopify/Customer/123456789"
  },
  "context": {
    "provider": "shopney",
    "platform": "ios",
    "appVersion": "5.2.0",
    "permissionStatus": "authorized"
  }
}

{
  "success": true,
  "status": "awarded",
  "reason": null,
  "eventId": "shopney-evt-01JABC123",
  "actionName": "mobile_push_permission_granted",
  "reward": {
    "type": "points",
    "amount": 100
  },
  "replayed": false
}