Payment Plan

The subscription system operates by default according to the specified plan. The payment plan is the step where all the necessary features for recurring payments are specified.

Plans have unique names, and one plan can only be associated with one product. If a plan is actively linked to a subscription, it cannot be deleted.

There are five different methods that can be used on plans.

1. Create Payment Plan

2. Update Payment Plan

3. List Pricing Plans

4. Get Payment Plan Detail

5. Delete Payment Plan

Create Payment Plan

To create a plan, the following details must be provided: product reference number, name, price, currency, payment interval, and other parameters as detailed below.

If a trial period is desired for a subscription, the trialPeriodDays parameter can be used. If this parameter is sent, no subscription will be initiated and no payment will be collected from the card during the specified period.

The Payment Interval parameter specified in the request indicates the payment period. When sending the "WEEKLY" parameter when creating a plan, iyzico will deduct the specified amount from the card every week. Customizing this period is also possible. For example, if you want payments to be collected every 2 weeks, you should send the PaymentInterval value as "WEEKLY" and the paymentIntervalCount value as 2.

The planPaymentType parameter is mandatory and can currently only take the value RECURRING.

Create Pricing Plan

post

Creates a new pricing plan for a specific product.

Path parameters

productReferenceCodestringRequired

Reference code of the product the plan will be attached to.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

Format of the request payload.

Example: application/json

Body

application/json

namestringRequired

Pricing plan name.

pricedecimalRequired

Amount to charge on each billing period.

currencyCodestring · enumRequired

Currency. (For foreign currency, only non-TRY cards are allowed.)

Possible values:

paymentIntervalstring · enumRequired

Recurrence interval for the subscription charge.

Possible values:

planPaymentTypestring · enumRequired

Subscription type.

Possible values:

paymentIntervalCountintegerOptional

Frequency multiplier for the interval. For example, if you set a weekly plan and send 2, the charge occurs every 2 weeks.

Example: 2

recurrenceCountintegerOptional

Total number of repeats (e.g., 12 → 12 months). If omitted, it continues until the subscription is canceled.

Example: 12

trialPeriodDaysintegerOptional

Free trial length in days. If provided, the first charge happens after this period.

Example: 10

localestring · enumOptional

Language of the response and error messages.

Possible values:

conversationIdstringOptional

Custom identifier for request tracking.

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/products/{productReferenceCode}/pricing-plans

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/products/8d562f84-f8d5-441a-b086-9483fc5133a0/pricing-plans
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "conv-001",
  "name": "Monthly Plan",
  "recurrenceCount": 12,
  "planPaymentType": "RECURRING",
  "trialPeriodDays": 0,
  "paymentIntervalCount": 1,
  "paymentInterval": "MONTHLY",
  "currencyCode": "TRY",
  "price": 99.99
}

{
  "status": "success",
  "systemTime": 1755561449951,
  "data": {
    "referenceCode": "08159c1d-6fe9-4934-8a55-e191bd4119e0",
    "createdDate": 1755552252531,
    "name": "Monthly Plan",
    "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
    "price": 99.99,
    "currencyCode": "TRY",
    "paymentInterval": "MONTHLY",
    "paymentIntervalCount": 1,
    "planPaymentType": "RECURRING",
    "recurrenceCount": 12,
    "trialPeriodDays": 0,
    "status": "ACTIVE"
  }
}

Sample Codes

PHP

Java

.NET

Node.Js

Postman

Update Pricing Plan

post

This method allows updating only the name and trialPeriodDays fields. The plan's reference code must be provided as a path parameter. Updates can be performed via API or the iyzico merchant panel. Active subscriptions are not affected.

Path parameters

pricingPlanReferenceCodestringRequired

Reference code of the pricing plan to be updated.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

Format of the request payload.

Example: application/json

Body

application/json

namestringRequired

Updated plan name.

trialPeriodDaysintegerOptional

Updated trial period (days).

Responses

200

Successful response

application/json

400

Error response

application/json

post

/v2/subscription/pricing-plans/{pricingPlanReferenceCode}

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/pricing-plans/7515f763-5da3-4a35-8f7f-d425ae44ac04
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "name": "Updated Plan",
  "trialPeriodDays": 5
}

{
  "status": "success",
  "systemTime": 1755587559228,
  "data": {
    "referenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
    "createdDate": 1755587137033,
    "name": "Updated Plan",
    "price": 99.99,
    "paymentInterval": "MONTHLY",
    "paymentIntervalCount": 1,
    "trialPeriodDays": 5,
    "currencyCode": "TRY",
    "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
    "planPaymentType": "RECURRING",
    "status": "ACTIVE",
    "recurrenceCount": 12
  }
}

Sample Codes

PHP

Java

.NET

Node.Js

Postman

List Pricing Plans

get

Lists all pricing plans for a given product. The response is paginated.

Path parameters

productReferenceCodestringRequired

Product reference code.

Query parameters

pageintegerOptional

Page number to list.

countintegerOptional

Number of records per page.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

Format of the request payload.

Example: application/json

Responses

200

Successful response

application/json

400

Error response

application/json

get

/v2/subscription/products/{productReferenceCode}/pricing-plans

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/products/8d562f84-f8d5-441a-b086-9483fc5133a0/pricing-plans?page=1&count=20
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755561449951,
  "data": {
    "totalCount": 2,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "plan-123",
        "name": "Monthly Plan",
        "price": 99.99,
        "currencyCode": "TRY",
        "paymentInterval": "MONTHLY",
        "paymentIntervalCount": 1,
        "status": "ACTIVE"
      },
      {
        "referenceCode": "plan-456",
        "name": "Yearly Plan",
        "price": 999.99,
        "currencyCode": "TRY",
        "paymentInterval": "YEARLY",
        "paymentIntervalCount": 1,
        "status": "ACTIVE"
      }
    ]
  }
}

Sample Codes

PHP

Java

.NET

Node.Js

Postman

Get Pricing Plan Detail

get

Returns details of a pricing plan. Merchants can see all details both in the merchant panel and via API.

Path parameters

pricingPlanReferenceCodestringRequired

Pricing plan reference code.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

Format of the request payload.

Example: application/json

Responses

200

Successful response

application/json

400

Error response

application/json

get

/v2/subscription/pricing-plans/{pricingPlanReferenceCode}

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/pricing-plans/7515f763-5da3-4a35-8f7f-d425ae44ac04
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755561449951,
  "data": {
    "referenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
    "name": "Monthly Plan",
    "price": 99.99,
    "currencyCode": "TRY",
    "paymentInterval": "MONTHLY",
    "paymentIntervalCount": 1,
    "planPaymentType": "RECURRING",
    "recurrenceCount": 12,
    "trialPeriodDays": 0,
    "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
    "status": "ACTIVE",
    "createdDate": 1755552252531
  }
}

Sample Codes

PHP

Java

.NET

Node.Js

Postman

Delete Pricing Plan

delete

Deletes the specified pricing plan by reference code. Plans with active subscriptions or pending updates cannot be deleted.

Path parameters

pricingPlanReferenceCodestringRequired

Reference code of the pricing plan to delete.

Header parameters

AuthorizationstringRequired

Authorization header, IYZWSv2 ile başlayan ve base64 formatında üretilmiş imzalı hash değeridir.

Content-TypestringRequired

Format of the request payload.

Example: application/json

Responses

200

Successful response

application/json

400

Error response

application/json

delete

/v2/subscription/pricing-plans/{pricingPlanReferenceCode}

HTTPcURL

DELETE https://api.iyzipay.com/v2/subscription/pricing-plans/7515f763-5da3-4a35-8f7f-d425ae44ac04
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755561449951
}

Sample Codes

PHP

Java

.NET

Node.Js

Postman