Subscribers

GET /subscribers/check

Check if a customer email has an active subscription.

Base URL

https://cadence-api.pleasurebyplease.com

Request

GET https://cadence-api.pleasurebyplease.com/subscribers/check

Headers

X-Api-Key: {your-api-key}
X-Api-Secret: {your-api-secret}

Query Parameters

Name	Type	Required	Description	Example
`email`	`string`	Yes	Customer email address to check for an active subscription	`john@example.com`

Response

Field	Type	Description
`status`	`string`	"success"
`exists`	`boolean`	Whether a customer with this email exists
`hasActiveSubscription`	`boolean`	Whether the customer has an active subscription (only when exists=true)
`data`	`object \| null`	Customer and subscription details (null when exists=false)
`data.customer`	`object`	Customer info (id, segnoId, email, name, surname)
`data.subscription`	`object \| null`	Subscription details if one exists (id, segnoId, iyzicoReference, planReference, status, createdAt, graceEndsAt, inGracePeriod)

Example Response

{
  "status": "success",
  "exists": true,
  "hasActiveSubscription": true,
  "data": {
    "customer": {
      "id": "c1d2e3f4-a5b6-7890-cdef-ab1234567890",
      "segnoId": "cust_id_3m7k9p2q",
      "email": "john@example.com",
      "name": "John",
      "surname": "Doe"
    },
    "subscription": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "segnoId": "sub_id_5x4n2v8k",
      "iyzicoReference": "SUB-12345",
      "planReference": "PLAN-abc123",
      "status": "ACTIVE",
      "createdAt": "2026-01-16T12:00:00.000Z",
      "graceEndsAt": null,
      "inGracePeriod": false
    }
  }
}

GET /subscribers

Retrieve a subscriber by iyzico reference code or internal ID.

Base URL

https://cadence-api.pleasurebyplease.com

Request

GET https://cadence-api.pleasurebyplease.com/subscribers

Headers

X-Api-Key: {your-api-key}
X-Api-Secret: {your-api-secret}

Query Parameters

Name	Type	Required	Description	Example
`iyzico-subscriber-code`	`string`	No	The iyzico subscription reference code (required if segno-id is not provided)	`SUB-12345`
`segno-id`	`string`	No	Optional internal Segno subscriber ID (or legacy UUID) to look up directly	`sub_id_5x4n2v8k`

TypeScript Interfaces

interface GetSubscriberQuery {
  "iyzico-subscriber-code": string; // The iyzico subscription reference code
  "segno-id"?: string;              // Optional internal Segno subscriber ID
}

interface GetSubscriberResponse {
  status: "success" | "failure";
  data: {
    id: string;
    segnoId: string;
    iyzicoReference: string;
    customerReference: string;
    planReference: string;
    subscriptionStatus: string;
    createdAt: string;
    customer: {
      id: string;
      name: string;
      surname: string;
      email: string;
      gsmNumber: string;
    } | null;
    latestInvoice: {
      id: string;
      segnoId: string;
      invoiceNumber: string;
      status: string;
      amount: string;
      currency: string;
      date: string;
      pdfUrl: string | null;
    } | null;
  };
}

Response

Field	Type	Description
`status`	`string`	"success" or "failure"
`data.id`	`string`	Internal subscription ID (UUID)
`data.segnoId`	`string`	Internal Cadence subscriber identifier
`data.iyzicoReference`	`string`	Iyzico subscription reference code
`data.customerReference`	`string`	Iyzico customer reference code
`data.planReference`	`string`	Current plan reference code
`data.subscriptionStatus`	`string`	Subscription status (ACTIVE, CANCELLED, etc.)
`data.createdAt`	`string`	Creation timestamp
`data.customer`	`object`	Associated customer data (name, surname, email, gsmNumber)
`data.latestInvoice`	`object \| null`	Most recent invoice for this subscriber
`data.latestInvoice.id`	`string`	Latest invoice UUID
`data.latestInvoice.segnoId`	`string`	Latest invoice Segno ID
`data.latestInvoice.invoiceNumber`	`string`	Latest invoice number
`data.latestInvoice.status`	`string`	Latest invoice status (PAID, PENDING, etc.)
`data.latestInvoice.amount`	`string`	Latest invoice amount
`data.latestInvoice.currency`	`string`	Latest invoice currency
`data.latestInvoice.date`	`string`	Latest invoice date timestamp
`data.latestInvoice.pdfUrl`	`string \| null`	Latest invoice PDF URL

Example Response

{
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "segnoId": "sub_id_5x4n2v8k",
    "iyzicoReference": "SUB-12345",
    "customerReference": "CUST-67890",
    "planReference": "PLAN-abc123",
    "subscriptionStatus": "ACTIVE",
    "createdAt": "2026-01-16T12:00:00.000Z",
    "customer": {
      "id": "c1d2e3f4-a5b6-7890-cdef-ab1234567890",
      "name": "John",
      "surname": "Doe",
      "email": "john@example.com",
      "gsmNumber": "+905551234567"
    },
    "latestInvoice": {
      "id": "4f7414f8-a7ee-4f56-b40f-a458ef8ea7d4",
      "segnoId": "inv_id_2hn4k90s",
      "invoiceNumber": "FAT-2026-00192",
      "status": "PAID",
      "amount": "999.90",
      "currency": "TRY",
      "date": "2026-03-20T09:10:11.000Z",
      "pdfUrl": "https://api.parasut.com/e_archives/123/pdf?signature=..."
    }
  }
}

GET /subscribers/invoices

List invoices for a subscriber with cursor pagination and signed Parasut PDF data.

Base URL

https://cadence-api.pleasurebyplease.com

Request

GET https://cadence-api.pleasurebyplease.com/subscribers/invoices

Headers

X-Api-Key: {your-api-key}
X-Api-Secret: {your-api-secret}

Query Parameters

Name	Type	Required	Description	Example
`subscriber-id`	`string`	No	Subscriber reference ID (required when segno-id is not provided)	`SUB-12345`
`segno-id`	`string`	No	Internal Cadence subscriber ID (required when subscriber-id is not provided)	`sub_id_5x4n2v8k`
`limit`	`number`	No	Number of invoices to return (default: 10, max: 100)	`10`
`starting_after`	`string`	No	Return results after this invoice ID cursor	`4f7414f8-a7ee-4f56-b40f-a458ef8ea7d4`
`ending_before`	`string`	No	Return results before this invoice ID cursor	`8c535fb0-4d66-4489-a5e6-bb47dfd19e3d`

TypeScript Interfaces

interface ListSubscriberInvoicesQuery {
  "subscriber-id"?: string;
  "segno-id"?: string;
  limit?: number; // default: 10, max: 100
  starting_after?: string; // invoice UUID cursor
  ending_before?: string; // invoice UUID cursor
}

interface SubscriberInvoiceListItem {
  id: string;
  segnoId: string;
  invoiceNumber: string;
  status: string;
  amount: string;
  currency: string;
  date: string;
  pdfUrl: string | null;
  signedPdf: {
    provider: 'parasut';
    eArchiveId: string;
    url: string;
    expiresAt: string | null;
    signedAt: string;
  } | null;
  pdfStatus: 'ready' | 'processing' | 'unavailable' | 'error';
  pdfMessage: string | null;
}

interface ListSubscriberInvoicesResponse {
  status: 'success';
  object: 'list';
  url: '/subscribers/invoices';
  has_more: boolean;
  limit: number;
  starting_after: string | null;
  ending_before: string | null;
  subscriber: {
    id: string;
    segnoId: string;
    subscriberId: string;
  };
  data: SubscriberInvoiceListItem[];
}

Response

Field	Type	Description
`status`	`string`	"success"
`object`	`string`	Always "list"
`url`	`string`	Endpoint path: /subscribers/invoices
`has_more`	`boolean`	Whether there are more records for pagination
`limit`	`number`	Applied page size limit
`starting_after`	`string \| null`	Echoed starting_after cursor
`ending_before`	`string \| null`	Echoed ending_before cursor
`subscriber`	`object`	Resolved subscriber context (id, segnoId, subscriberId)
`data`	`array`	List of invoice objects
`data[].id`	`string`	Invoice UUID
`data[].segnoId`	`string`	Invoice Segno ID
`data[].invoiceNumber`	`string`	Human-readable invoice number
`data[].status`	`string`	Invoice status (PAID, PENDING, etc.)
`data[].amount`	`string`	Invoice amount
`data[].currency`	`string`	Currency code
`data[].date`	`string`	Invoice date timestamp
`data[].pdfUrl`	`string \| null`	PDF download URL when available
`data[].signedPdf`	`object \| null`	Signed PDF details from Parasut (url, expiresAt)
`data[].pdfStatus`	`string`	PDF readiness: ready \| processing \| unavailable \| error
`data[].pdfMessage`	`string \| null`	Optional status/error details for PDF resolution

Example Response

{
  "status": "success",
  "object": "list",
  "url": "/subscribers/invoices",
  "has_more": true,
  "limit": 2,
  "starting_after": null,
  "ending_before": null,
  "subscriber": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "segnoId": "sub_id_5x4n2v8k",
    "subscriberId": "SUB-12345"
  },
  "data": [
    {
      "id": "4f7414f8-a7ee-4f56-b40f-a458ef8ea7d4",
      "segnoId": "inv_id_2hn4k90s",
      "invoiceNumber": "FAT-2026-00192",
      "status": "PAID",
      "amount": "999.90",
      "currency": "TRY",
      "date": "2026-03-20T09:10:11.000Z",
      "pdfUrl": "https://api.parasut.com/e_archives/123/pdf?signature=...",
      "signedPdf": {
        "provider": "parasut",
        "eArchiveId": "123",
        "url": "https://api.parasut.com/e_archives/123/pdf?signature=...",
        "expiresAt": "2026-03-20T10:10:11.000Z",
        "signedAt": "2026-03-20T09:11:02.000Z"
      },
      "pdfStatus": "ready",
      "pdfMessage": null
    },
    {
      "id": "8c535fb0-4d66-4489-a5e6-bb47dfd19e3d",
      "segnoId": "inv_id_70k3n5xz",
      "invoiceNumber": "FAT-2026-00191",
      "status": "PAID",
      "amount": "999.90",
      "currency": "TRY",
      "date": "2026-02-20T09:10:11.000Z",
      "pdfUrl": null,
      "signedPdf": null,
      "pdfStatus": "processing",
      "pdfMessage": "E-archive PDF is still processing."
    }
  ]
}

PUT /subscribers

Update a subscriber's plan. If both segno IDs are provided, only updates database without iyzico sync.

Base URL

https://cadence-api.pleasurebyplease.com

Request

PUT https://cadence-api.pleasurebyplease.com/subscribers

Headers

X-Api-Key: {your-api-key}
X-Api-Secret: {your-api-secret}

Request Body

Name	Type	Required	Description	Example
`iyzico-subscriber-reference-code`	`string`	No	The iyzico subscription reference code. Required if segno-subscriber-id is not provided; use with iyzico-plan-reference-code (mutually exclusive with segno pair)	`SUB-12345`
`iyzico-plan-reference-code`	`string`	No	The new plan reference code to upgrade to. Required if segno-plan-id is not provided; use with iyzico-subscriber-reference-code (mutually exclusive with segno pair)	`PLAN-67890`
`segno-subscriber-id`	`string`	No	Internal Cadence subscriber ID. Required if iyzico pair not provided; use with segno-plan-id. If both segno IDs provided, updates database only (no iyzico sync)	`sub_id_5x4n2v8k`
`segno-plan-id`	`string`	No	Internal Cadence plan ID. Required if iyzico pair not provided; use with segno-subscriber-id. If both segno IDs provided, updates database only (no iyzico sync)	`plan_id_8r2n3k1p`
`resetRecurrenceCount`	`boolean`	No	Reset recurrence count on upgrade (default: true)	`true`
`useTrial`	`boolean`	No	Use trial period on new plan	`false`
`upgradePeriod`	`string ("NOW" \| "NEXT_PERIOD")`	No	When to apply upgrade	`NOW`

TypeScript Interfaces

interface UpdateSubscriberBody {
  "iyzico-subscriber-reference-code"?: string; // Iyzico subscription reference (use with iyzico-plan-reference-code)
  "iyzico-plan-reference-code"?: string;      // New plan reference (use with iyzico-subscriber-reference-code)
  "segno-subscriber-id"?: string;             // Segno subscriber ID (use with segno-plan-id, mutually exclusive with iyzico pair)
  "segno-plan-id"?: string;                   // Cadence plan ID (use with segno-subscriber-id)
  resetRecurrenceCount?: boolean;              // Default: true
  useTrial?: boolean;                         // Default: false
  upgradePeriod?: "NOW" | "NEXT_PERIOD";      // Default: NOW
}

interface UpdateSubscriberResponse {
  status: "success" | "failure";
  message: string;
  data: {
    id: string;
    segnoId: string;
    iyzicoReference: string;
    newPlanReference: string;
    newPlanSegnoId?: string;  // When using segno IDs
    syncedWithIyzico: boolean;
    iyzicoResponse?: unknown;
  };
}

Response

Field	Type	Description
`status`	`string`	"success" or "failure"
`message`	`string`	Success/error message
`data.id`	`string`	Internal subscription ID
`data.segnoId`	`string`	Internal Cadence subscriber identifier
`data.iyzicoReference`	`string`	Iyzico subscription reference code
`data.newPlanReference`	`string`	New plan reference code
`data.newPlanSegnoId`	`string`	Internal Cadence plan identifier for new plan (when using segno IDs)
`data.syncedWithIyzico`	`boolean`	Whether the update was synced with iyzico
`data.iyzicoResponse`	`object`	Raw iyzico response (only when synced)

Example Response

{
  "status": "success",
  "message": "Subscriber plan upgraded successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "segnoId": "sub_id_5x4n2v8k",
    "iyzicoReference": "SUB-12345",
    "newPlanReference": "PLAN-67890",
    "newPlanSegnoId": "plan_id_8r2n3k1p",
    "syncedWithIyzico": true,
    "iyzicoResponse": {
      "referenceCode": "SUB-12345",
      "status": "ACTIVE"
    }
  }
}

DELETE /subscribers

Cancel a subscription at period end. If segno-id is provided, only schedules cancellation in the database.

Base URL

https://cadence-api.pleasurebyplease.com

Request

DELETE https://cadence-api.pleasurebyplease.com/subscribers

Headers

X-Api-Key: {your-api-key}
X-Api-Secret: {your-api-secret}

Request Body

Name	Type	Required	Description	Example
`iyzico-subscriber-reference-code`	`string`	No	The iyzico subscription reference code. Required if segno-id is not provided (mutually exclusive)	`SUB-12345`
`segno-id`	`string`	No	Internal Cadence subscriber ID. Required if iyzico-subscriber-reference-code is not provided (mutually exclusive). If provided, schedules cancellation in the database only	`sub_id_5x4n2v8k`

TypeScript Interfaces

interface CancelSubscriberBody {
  "iyzico-subscriber-reference-code"?: string; // Iyzico subscription reference (mutually exclusive with segno-id)
  "segno-id"?: string;                        // Segno subscriber ID (mutually exclusive with iyzico code)
}

interface CancelSubscriberResponse {
  status: "success" | "failure";
  message: string;
  data: {
    id: string;
    segnoId: string;
    iyzicoReference: string;
    status: "ACTIVE";
    cancelAtPeriodEnd: boolean;
    cancelledAt: string;
    accessUntil: string | null;
    syncedWithIyzico: boolean;
  };
}

Response

Field	Type	Description
`status`	`string`	"success" or "failure"
`message`	`string`	Success/error message
`data.id`	`string`	Internal subscription ID
`data.segnoId`	`string`	Internal Cadence subscriber identifier
`data.iyzicoReference`	`string`	Iyzico subscription reference code
`data.status`	`string`	Current status (remains ACTIVE until period end)
`data.cancelAtPeriodEnd`	`boolean`	Whether cancellation is scheduled for period end
`data.cancelledAt`	`string`	When cancellation was requested (ISO timestamp)
`data.accessUntil`	`string`	Access end time (period end, ISO timestamp)
`data.syncedWithIyzico`	`boolean`	Whether the cancellation was synced with iyzico

Example Response

{
  "status": "success",
  "message": "Subscription will be cancelled at period end",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "segnoId": "sub_id_5x4n2v8k",
    "iyzicoReference": "SUB-12345",
    "status": "ACTIVE",
    "cancelAtPeriodEnd": true,
    "cancelledAt": "2026-02-03T12:00:00.000Z",
    "accessUntil": "2026-02-04T12:00:00.000Z",
    "syncedWithIyzico": false
  }
}

POST /subscribers/undo-cancel

Undo a pending cancellation before the buffer window. If segno-id is provided, only updates the database.

Base URL

https://cadence-api.pleasurebyplease.com

Request

POST https://cadence-api.pleasurebyplease.com/subscribers/undo-cancel

Headers

X-Api-Key: {your-api-key}
X-Api-Secret: {your-api-secret}

Request Body

Name	Type	Required	Description	Example
`iyzico-subscriber-reference-code`	`string`	No	The iyzico subscription reference code. Required if segno-id is not provided (mutually exclusive)	`SUB-12345`
`segno-id`	`string`	No	Internal Cadence subscriber ID. Required if iyzico-subscriber-reference-code is not provided (mutually exclusive). If provided, undo cancellation in the database only	`sub_id_5x4n2v8k`

TypeScript Interfaces

interface UndoCancelSubscriberBody {
  "iyzico-subscriber-reference-code"?: string; // Iyzico subscription reference (mutually exclusive with segno-id)
  "segno-id"?: string;                        // Segno subscriber ID (mutually exclusive with iyzico code)
}

interface UndoCancelSubscriberResponse {
  status: "success" | "failure";
  message: string;
  data: {
    id: string;
    segnoId: string;
    iyzicoReference: string;
    status: "ACTIVE";
    cancelAtPeriodEnd: boolean;
    cancelledAt: string | null;
    accessUntil: string | null;
    syncedWithIyzico: boolean;
  };
}

Response

Field	Type	Description
`status`	`string`	"success" or "failure"
`message`	`string`	Success/error message
`data.id`	`string`	Internal subscription ID
`data.segnoId`	`string`	Internal Cadence subscriber identifier
`data.iyzicoReference`	`string`	Iyzico subscription reference code
`data.status`	`string`	Current status (ACTIVE)
`data.cancelAtPeriodEnd`	`boolean`	Whether cancellation is scheduled for period end
`data.cancelledAt`	`string`	When cancellation was requested (null if not cancelled)
`data.accessUntil`	`string`	Access end time (period end, ISO timestamp)
`data.syncedWithIyzico`	`boolean`	Whether the undo was synced with iyzico

Example Response

{
  "status": "success",
  "message": "Subscription cancellation undone",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "segnoId": "sub_id_5x4n2v8k",
    "iyzicoReference": "SUB-12345",
    "status": "ACTIVE",
    "cancelAtPeriodEnd": false,
    "cancelledAt": null,
    "accessUntil": "2026-02-04T12:00:00.000Z",
    "syncedWithIyzico": false
  }
}

On this page