Retention offers

curl "https://app.nautilus.co/api/v1/retention-offers?start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/retention-offers?start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "organizationId": "<string>",
  "dateRange": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "totals": {
    "viewed": 123,
    "accepted": 123,
    "declined": 123,
    "acceptanceRatePct": 123
  },
  "offers": [
    {
      "offerId": "<string>",
      "offerName": "<string>",
      "targetPlanName": "<string>",
      "targetPlanPrice": 123,
      "viewed": 123,
      "accepted": 123,
      "declined": 123,
      "acceptanceRatePct": 123
    }
  ],
  "ltv": {
    "acceptedMembers": {
      "count": 123,
      "avgRevenuePostOffer": 123,
      "avgLifetimeRevenue": 123
    },
    "declinedMembers": {
      "count": 123,
      "avgRevenuePostOffer": 123,
      "avgLifetimeRevenue": 123
    },
    "windowMonths": null,
    "definition": "<string>",
    "coverage": {
      "acceptedDecisionEvents": 123,
      "acceptedJoinableDecisionEvents": 123,
      "acceptedMembersWithRevenueLookup": 123,
      "declinedDecisionEvents": 123,
      "declinedJoinableDecisionEvents": 123,
      "declinedMembersWithRevenueLookup": 123
    }
  }
}

{
  "error": "Retention offer analytics are not available for this organization"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

GET

api

retention-offers

curl "https://app.nautilus.co/api/v1/retention-offers?start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/retention-offers?start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "organizationId": "<string>",
  "dateRange": {
    "start": "2023-11-07T05:31:56Z",
    "end": "2023-11-07T05:31:56Z"
  },
  "totals": {
    "viewed": 123,
    "accepted": 123,
    "declined": 123,
    "acceptanceRatePct": 123
  },
  "offers": [
    {
      "offerId": "<string>",
      "offerName": "<string>",
      "targetPlanName": "<string>",
      "targetPlanPrice": 123,
      "viewed": 123,
      "accepted": 123,
      "declined": 123,
      "acceptanceRatePct": 123
    }
  ],
  "ltv": {
    "acceptedMembers": {
      "count": 123,
      "avgRevenuePostOffer": 123,
      "avgLifetimeRevenue": 123
    },
    "declinedMembers": {
      "count": 123,
      "avgRevenuePostOffer": 123,
      "avgLifetimeRevenue": 123
    },
    "windowMonths": null,
    "definition": "<string>",
    "coverage": {
      "acceptedDecisionEvents": 123,
      "acceptedJoinableDecisionEvents": 123,
      "acceptedMembersWithRevenueLookup": 123,
      "declinedDecisionEvents": 123,
      "declinedJoinableDecisionEvents": 123,
      "declinedMembersWithRevenueLookup": 123
    }
  }
}

{
  "error": "Retention offer analytics are not available for this organization"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Returns retention save-offer views, accepts, declines, acceptance rates, and accepted-versus-declined revenue LTV where supported.

This endpoint requires a tenant-scoped API key and the retention-offer analytics capability for the tenant.

curl "https://app.nautilus.co/api/v1/retention-offers?start=2026-01-01&end=2026-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://app.nautilus.co/api/v1/retention-offers?start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "organizationId": "org_example_123",
  "dateRange": {
    "start": "2026-01-01T00:00:00.000Z",
    "end": "2026-06-30T23:59:59.999Z"
  },
  "totals": {
    "viewed": 512,
    "accepted": 146,
    "declined": 366,
    "acceptanceRatePct": 28.5
  },
  "offers": [
    {
      "offerId": "offer_example_001",
      "offerName": "Stay and Save",
      "targetPlanName": "Unlimited Plus",
      "targetPlanPrice": 2999,
      "viewed": 310,
      "accepted": 96,
      "declined": 214,
      "acceptanceRatePct": 31.0
    }
  ],
  "ltv": {
    "acceptedMembers": {
      "count": 84,
      "avgRevenuePostOffer": 73.42,
      "avgLifetimeRevenue": 412.18
    },
    "declinedMembers": {
      "count": 190,
      "avgRevenuePostOffer": 18.65,
      "avgLifetimeRevenue": 263.91
    },
    "windowMonths": null,
    "definition": "LTV uses unique members whose accepted or declined offer event carried a customer_id. Lifetime revenue is all transaction total for that customer in sonnys.transactions_shared; post-offer revenue is transaction total where completeDate is after the member's earliest decision event in the requested offer-event window. Amounts are returned in dollars.",
    "coverage": {
      "acceptedDecisionEvents": 146,
      "acceptedJoinableDecisionEvents": 91,
      "acceptedMembersWithRevenueLookup": 84,
      "declinedDecisionEvents": 366,
      "declinedJoinableDecisionEvents": 205,
      "declinedMembersWithRevenueLookup": 190
    }
  }
}

LTV availability

Revenue LTV is currently available only for sonnys-shared tenants. Other providers return an explained null LTV block:

{
  "ltv": {
    "acceptedMembers": null,
    "declinedMembers": null,
    "windowMonths": null,
    "definition": "LTV uses unique members whose accepted or declined offer event carried a customer_id. Lifetime revenue is all transaction total for that customer in sonnys.transactions_shared; post-offer revenue is transaction total where completeDate is after the member's earliest decision event in the requested offer-event window. Amounts are returned in dollars.",
    "coverage": null,
    "unavailableReason": "Revenue LTV is currently available only for the sonnys-shared provider because it depends on sonnys.transactions_shared."
  }
}

Use ltv.coverage to compare LTV sample size against totals.accepted and totals.declined. LTV is computed only for decision events that include a joinable customer id.

Dates

start and end accept date-only values or explicit timestamps. Date-only lower bounds start at 00:00:00.000Z; date-only upper bounds include the full UTC day. If you omit start, Nautilus queries all time. If you omit end, Nautilus uses the current time internally. Omitted bounds are returned as null in dateRange.

Errors

400 - Retention offer analytics are not available for this organization.
401 - Missing, invalid, or non-tenant-scoped API key.
500 - Internal server error.

Authorizations

Authorization

string

header

required

Clerk tenant API key. The organizationId encoded by the key is the exact and only tenant scope.

Query Parameters

start

string

Inclusive lower bound on offer events. Date-only values start at 00:00:00.000Z.

end

string

Inclusive upper bound on offer events. Date-only values include the full UTC day.

Response

Retention offer analytics response

organizationId

string

required

dateRange

Date range · object

required

Show child attributes

totals

object

required

Show child attributes

offers

object[]

required

Show child attributes

ltv

object

required

Option 1
Option 2

Show child attributes

API documentation

Sites

Products

Checkout links

Purchases

Contacts

Marketing

Forms

Vouchers

Links

Automations

Surveys

Cases

Cancellations

Sonny's POS

Message

Email

Analytics

Integration

Response

LTV availability

Dates

Errors

Authorizations

Query Parameters

Response

​Response

​LTV availability

​Dates

​Errors

Authorizations

Query Parameters

Response

Response

LTV availability

Dates

Errors