fix(revenuecat): align tools and block with REST v1 API spec

Author: waleedlatif1

apps/docs/content/docs/en/tools/revenuecat.mdx

@@ -119,8 +119,10 @@ Record a purchase (receipt) for a subscriber via the REST API
 | `productId` | string | Yes | The product identifier for the purchase |
 | `price` | number | No | The price of the product in the currency specified |
 | `currency` | string | No | ISO 4217 currency code \(e.g., USD, EUR\) |
-| `isRestore` | boolean | No | Whether this is a restore of a previous purchase |
-| `platform` | string | No | Platform of the purchase \(ios, android, amazon, macos, stripe\). Required for Stripe and Paddle purchases. |
+| `isRestore` | boolean | No | Whether this is a restore of a previous purchase \(deprecated by RevenueCat\) |
+| `presentedOfferingIdentifier` | string | No | Identifier of the offering that was presented to the user when they made this purchase. Used by RevenueCat for offering-level analytics. |
+| `paymentMode` | string | No | Payment mode for the purchase. One of: pay_as_you_go, pay_up_front, free_trial. Only applies to introductory pricing periods. |
+| `platform` | string | Yes | Platform of the purchase. One of: ios, android, amazon, macos, uikitformac, stripe, roku, paddle. Sent as the X-Platform header \(required by RevenueCat\). |
 
 #### Output
 
@@ -170,7 +172,8 @@ Grant a promotional entitlement to a subscriber
 | `apiKey` | string | Yes | RevenueCat secret API key \(sk_...\) |
 | `appUserId` | string | Yes | The app user ID of the subscriber |
 | `entitlementIdentifier` | string | Yes | The entitlement identifier to grant |
-| `duration` | string | Yes | Duration of the entitlement \(daily, three_day, weekly, monthly, two_month, three_month, six_month, yearly, lifetime\) |
+| `duration` | string | No | Duration of the entitlement. Provide either duration or endTimeMs. One of: daily, three_day, weekly, two_week, monthly, two_month, three_month, six_month, yearly, lifetime |
+| `endTimeMs` | number | No | Absolute end time in milliseconds since Unix epoch. Use instead of duration to grant the entitlement until a specific timestamp. |
 | `startTimeMs` | number | No | Optional start time in milliseconds since Unix epoch. Set to a past time to achieve custom durations shorter than daily. |
 
 #### Output
@@ -296,7 +299,7 @@ Update custom subscriber attributes (e.g., $email, $displayName, or custom key-v
 | --------- | ---- | -------- | ----------- |
 | `apiKey` | string | Yes | RevenueCat secret API key \(sk_...\) |
 | `appUserId` | string | Yes | The app user ID of the subscriber |
-| `attributes` | json | Yes | JSON object of attributes to set. Each key maps to an object with a "value" field. Example: \{"$email": \{"value": "user@example.com"\}, "$displayName": \{"value": "John"\}\} |
+| `attributes` | json | Yes | JSON object of attributes to set. Each key maps to an object with "value" \(string; null or empty deletes the attribute\) and "updated_at_ms" \(Unix epoch ms used for conflict resolution — required\). Example: \{"$email": \{"value": "user@example.com", "updated_at_ms": 1709195668093\}\} |
 
 #### Output
 
@@ -316,7 +319,8 @@ Defer a Google Play subscription by extending its billing date by a number of da
 | `apiKey` | string | Yes | RevenueCat secret API key \(sk_...\) |
 | `appUserId` | string | Yes | The app user ID of the subscriber |
 | `productId` | string | Yes | The Google Play product identifier of the subscription to defer \(use the part before the colon for products set up after Feb 2023\) |
-| `extendByDays` | number | Yes | Number of days to extend the subscription by \(1-365\) |
+| `extendByDays` | number | No | Number of days to extend the subscription by \(1-365\). Provide either extendByDays or expiryTimeMs. |
+| `expiryTimeMs` | number | No | Absolute new expiry time in milliseconds since Unix epoch. Use instead of extendByDays to set an exact expiry. |
 
 #### Output
 
@@ -357,15 +361,15 @@ Defer a Google Play subscription by extending its billing date by a number of da
 
 ### `revenuecat_refund_google_subscription`
 
-Refund and optionally revoke a Google Play subscription (Google Play only)
+Refund a specific store transaction by its store transaction identifier and revoke access (subscription or non-subscription, last 365 days)
 
 #### Input
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `apiKey` | string | Yes | RevenueCat secret API key \(sk_...\) |
 | `appUserId` | string | Yes | The app user ID of the subscriber |
-| `productId` | string | Yes | The Google Play product identifier of the subscription to refund |
+| `storeTransactionId` | string | Yes | The store transaction identifier of the purchase to refund \(e.g., GPA.3309-9122-6177-45730 for Google Play\) |
 
 #### Output
 

apps/sim/app/(landing)/integrations/data/integrations.json

@@ -10748,7 +10748,7 @@
       },
       {
         "name": "Refund Google Subscription",
-        "description": "Refund and optionally revoke a Google Play subscription (Google Play only)"
+        "description": "Refund a specific store transaction by its store transaction identifier and revoke access (subscription or non-subscription, last 365 days)"
       },
       {
         "name": "Revoke Google Subscription",

apps/sim/blocks/blocks/revenuecat.ts

@@ -72,6 +72,7 @@ export const RevenueCatBlock: BlockConfig<RevenueCatResponse> = {
         { label: 'Daily', id: 'daily' },
         { label: '3 Days', id: 'three_day' },
         { label: 'Weekly', id: 'weekly' },
+        { label: '2 Weeks', id: 'two_week' },
         { label: 'Monthly', id: 'monthly' },
         { label: '2 Months', id: 'two_month' },
         { label: '3 Months', id: 'three_month' },
@@ -85,6 +86,28 @@ export const RevenueCatBlock: BlockConfig<RevenueCatResponse> = {
         value: 'grant_entitlement',
       },
     },
+    {
+      id: 'endTimeMs',
+      title: 'End Time (ms)',
+      type: 'short-input',
+      placeholder: 'Optional absolute end time in ms since epoch',
+      condition: {
+        field: 'operation',
+        value: 'grant_entitlement',
+      },
+      mode: 'advanced',
+      wandConfig: {
+        enabled: true,
+        prompt: `Generate a Unix epoch timestamp in milliseconds based on the user's description.
+The timestamp should represent the absolute end time for the entitlement.
+Examples:
+- "in 7 days" -> current time plus 604800000 milliseconds
+- "next month" -> current time plus 2592000000 milliseconds
+- "end of 2026" -> 1798761600000
+
+Return ONLY the numeric timestamp, no text.`,
+      },
+    },
     {
       id: 'startTimeMs',
       title: 'Start Time (ms)',
@@ -129,21 +152,25 @@ Return ONLY the numeric timestamp, no text.`,
       placeholder: 'Product identifier',
       condition: {
         field: 'operation',
-        value: [
-          'create_purchase',
-          'defer_google_subscription',
-          'refund_google_subscription',
-          'revoke_google_subscription',
-        ],
+        value: ['create_purchase', 'defer_google_subscription', 'revoke_google_subscription'],
+      },
+      required: {
+        field: 'operation',
+        value: ['create_purchase', 'defer_google_subscription', 'revoke_google_subscription'],
+      },
+    },
+    {
+      id: 'storeTransactionId',
+      title: 'Store Transaction ID',
+      type: 'short-input',
+      placeholder: 'e.g., GPA.3309-9122-6177-45730',
+      condition: {
+        field: 'operation',
+        value: 'refund_google_subscription',
       },
       required: {
         field: 'operation',
-        value: [
-          'create_purchase',
-          'defer_google_subscription',
-          'refund_google_subscription',
-          'revoke_google_subscription',
-        ],
+        value: 'refund_google_subscription',
       },
     },
     {
@@ -168,6 +195,32 @@ Return ONLY the numeric timestamp, no text.`,
       },
       mode: 'advanced',
     },
+    {
+      id: 'presentedOfferingIdentifier',
+      title: 'Presented Offering ID',
+      type: 'short-input',
+      placeholder: 'Offering identifier shown to the user',
+      condition: {
+        field: 'operation',
+        value: 'create_purchase',
+      },
+      mode: 'advanced',
+    },
+    {
+      id: 'paymentMode',
+      title: 'Payment Mode',
+      type: 'dropdown',
+      options: [
+        { label: 'Pay As You Go', id: 'pay_as_you_go' },
+        { label: 'Pay Up Front', id: 'pay_up_front' },
+        { label: 'Free Trial', id: 'free_trial' },
+      ],
+      condition: {
+        field: 'operation',
+        value: 'create_purchase',
+      },
+      mode: 'advanced',
+    },
     {
       id: 'isRestore',
       title: 'Is Restore',
@@ -192,13 +245,19 @@ Return ONLY the numeric timestamp, no text.`,
         { label: 'Android', id: 'android' },
         { label: 'Amazon', id: 'amazon' },
         { label: 'macOS', id: 'macos' },
+        { label: 'UIKit for Mac', id: 'uikitformac' },
         { label: 'Stripe', id: 'stripe' },
+        { label: 'Roku', id: 'roku' },
+        { label: 'Paddle', id: 'paddle' },
       ],
       condition: {
         field: 'operation',
         value: 'create_purchase',
       },
-      mode: 'advanced',
+      required: {
+        field: 'operation',
+        value: 'create_purchase',
+      },
     },
     {
       id: 'attributes',
@@ -238,10 +297,24 @@ Return ONLY valid JSON.`,
         field: 'operation',
         value: 'defer_google_subscription',
       },
-      required: {
+    },
+    {
+      id: 'expiryTimeMs',
+      title: 'Expiry Time (ms)',
+      type: 'short-input',
+      placeholder: 'Absolute new expiry time in ms since epoch',
+      condition: {
         field: 'operation',
         value: 'defer_google_subscription',
       },
+      mode: 'advanced',
+      wandConfig: {
+        enabled: true,
+        prompt: `Generate a Unix epoch timestamp in milliseconds based on the user's description.
+The timestamp should represent the new absolute expiry time of the subscription.
+
+Return ONLY the numeric timestamp, no text.`,
+      },
     },
     {
       id: 'platform',
@@ -251,13 +324,15 @@ Return ONLY valid JSON.`,
         { label: 'iOS', id: 'ios' },
         { label: 'Android', id: 'android' },
         { label: 'Amazon', id: 'amazon' },
-        { label: 'macOS', id: 'macos' },
         { label: 'Stripe', id: 'stripe' },
+        { label: 'Roku', id: 'roku' },
+        { label: 'Paddle', id: 'paddle' },
       ],
       condition: {
         field: 'operation',
         value: 'list_offerings',
       },
+      mode: 'advanced',
     },
   ],
   tools: {
@@ -274,23 +349,32 @@ Return ONLY valid JSON.`,
       'revenuecat_revoke_google_subscription',
     ],
     config: {
-      tool: (params) => {
+      tool: (params) => `revenuecat_${params.operation}`,
+      params: (params) => {
+        const next: Record<string, unknown> = { ...params }
         if (params.purchasePlatform && params.operation === 'create_purchase') {
-          params.platform = params.purchasePlatform
+          next.platform = params.purchasePlatform
         }
-        if (params.isRestore !== undefined) {
-          params.isRestore = params.isRestore === 'true'
+        next.purchasePlatform = undefined
+        if (params.isRestore !== undefined && params.isRestore !== '') {
+          next.isRestore = params.isRestore === true || params.isRestore === 'true'
         }
         if (params.price !== undefined && params.price !== '') {
-          params.price = Number(params.price)
+          next.price = Number(params.price)
         }
         if (params.extendByDays !== undefined && params.extendByDays !== '') {
-          params.extendByDays = Number(params.extendByDays)
+          next.extendByDays = Number(params.extendByDays)
         }
         if (params.startTimeMs !== undefined && params.startTimeMs !== '') {
-          params.startTimeMs = Number(params.startTimeMs)
+          next.startTimeMs = Number(params.startTimeMs)
+        }
+        if (params.endTimeMs !== undefined && params.endTimeMs !== '') {
+          next.endTimeMs = Number(params.endTimeMs)
         }
-        return `revenuecat_${params.operation}`
+        if (params.expiryTimeMs !== undefined && params.expiryTimeMs !== '') {
+          next.expiryTimeMs = Number(params.expiryTimeMs)
+        }
+        return next
       },
     },
   },
@@ -303,25 +387,43 @@ Return ONLY valid JSON.`,
     startTimeMs: { type: 'number', description: 'Custom start time in ms since epoch' },
     fetchToken: { type: 'string', description: 'Store receipt or purchase token' },
     productId: { type: 'string', description: 'Product identifier' },
+    storeTransactionId: { type: 'string', description: 'Store transaction identifier' },
     price: { type: 'number', description: 'Product price' },
     currency: { type: 'string', description: 'ISO 4217 currency code' },
     isRestore: { type: 'boolean', description: 'Whether this is a restore purchase' },
-    purchasePlatform: { type: 'string', description: 'Platform for the purchase' },
+    presentedOfferingIdentifier: {
+      type: 'string',
+      description: 'Identifier of the offering presented to the user',
+    },
+    paymentMode: {
+      type: 'string',
+      description: 'Payment mode (pay_as_you_go, pay_up_front, free_trial)',
+    },
     attributes: { type: 'string', description: 'JSON object of subscriber attributes' },
     extendByDays: { type: 'number', description: 'Number of days to extend (1-365)' },
-    platform: { type: 'string', description: 'Platform filter for offerings' },
+    expiryTimeMs: { type: 'number', description: 'Absolute new expiry time in ms since epoch' },
+    endTimeMs: {
+      type: 'number',
+      description: 'Absolute end time for entitlement in ms since epoch',
+    },
+    platform: { type: 'string', description: 'Platform (X-Platform header)' },
   },
   outputs: {
     subscriber: {
       type: 'json',
-      description: 'Subscriber object with subscriptions and entitlements',
+      description:
+        'Subscriber object (first_seen, original_app_user_id, original_purchase_date, management_url, subscriptions, entitlements, non_subscriptions)',
     },
     offerings: {
       type: 'json',
-      description: 'Array of offerings with packages',
+      description: 'Array of offerings, each with identifier, description, and packages[]',
     },
     current_offering_id: { type: 'string', description: 'Current offering identifier' },
-    metadata: { type: 'json', description: 'Operation metadata' },
+    metadata: {
+      type: 'json',
+      description:
+        'Operation metadata. For get_customer: app_user_id, first_seen, active_entitlements, active_subscriptions. For list_offerings: count, current_offering_id.',
+    },
     deleted: { type: 'boolean', description: 'Whether the subscriber was deleted' },
     app_user_id: { type: 'string', description: 'The app user ID' },
     updated: { type: 'boolean', description: 'Whether the attributes were updated' },

apps/sim/tools/revenuecat/create_purchase.ts

@@ -1,5 +1,5 @@
 import type { CreatePurchaseParams, CreatePurchaseResponse } from '@/tools/revenuecat/types'
-import { SUBSCRIBER_OUTPUT } from '@/tools/revenuecat/types'
+import { SUBSCRIBER_OUTPUT, throwIfRevenueCatError } from '@/tools/revenuecat/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const revenuecatCreatePurchaseTool: ToolConfig<
@@ -53,14 +53,28 @@ export const revenuecatCreatePurchaseTool: ToolConfig<
       type: 'boolean',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Whether this is a restore of a previous purchase',
+      description: 'Whether this is a restore of a previous purchase (deprecated by RevenueCat)',
     },
-    platform: {
+    presentedOfferingIdentifier: {
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
       description:
-        'Platform of the purchase (ios, android, amazon, macos, stripe). Required for Stripe and Paddle purchases.',
+        'Identifier of the offering that was presented to the user when they made this purchase. Used by RevenueCat for offering-level analytics.',
+    },
+    paymentMode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Payment mode for the purchase. One of: pay_as_you_go, pay_up_front, free_trial. Only applies to introductory pricing periods.',
+    },
+    platform: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description:
+        'Platform of the purchase. One of: ios, android, amazon, macos, uikitformac, stripe, roku, paddle. Sent as the X-Platform header (required by RevenueCat).',
     },
   },
 
@@ -86,11 +100,16 @@ export const revenuecatCreatePurchaseTool: ToolConfig<
       if (params.price !== undefined) body.price = params.price
       if (params.currency) body.currency = params.currency
       if (params.isRestore !== undefined) body.is_restore = params.isRestore
+      if (params.presentedOfferingIdentifier) {
+        body.presented_offering_identifier = params.presentedOfferingIdentifier
+      }
+      if (params.paymentMode) body.payment_mode = params.paymentMode
       return body
     },
   },
 
   transformResponse: async (response) => {
+    await throwIfRevenueCatError(response)
     const data = await response.json()
     const subscriber = data.subscriber ?? {}