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. Delete Payment Plan

4. Get Payment Plan

5. List of Payment Plans

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 Payment Plan

POST https://api.iyzipay.com/v2/subscription/products/{product_reference}/pricing-plans

Request Body

Name	Type	Description
conversationId	String	A value that can be sent during the request and received in the response, used to match the request and response. The most common usage is the plan number of the merchant.
locale	String	It is used to set the language of the text returned as a result of the iyzico request. The default value is TR (Turkish).
name*	String	Plan name. A value should be entered that provides a brief description related to the payment plan.
productReferenceCode*	String	The reference code of the product to which the plan will be associated.
recurrenceCount	Integer	Determines how many times the payment period will be repeated. For example, if you set this value to 12 for a plan that receives monthly payments, payments will be collected for 12 months.
planPaymentType*	String	Specifies the subscription type. The value entered should be RECURRING.
trialPeriodDays	Integer	Used as a trial period or free usage period. If this value is entered, the first payment is collected after the specified number of days from the day of entry.
paymentIntervalCount*	Integer	Determines the frequency of the payment period. For example, if the paymentInterval value is WEEKLY and the paymentIntervalCount value is 2, payments are collected every 2 weeks.
paymentInterval*	String	Determines the period for collecting recurring payments. It can take values of DAILY, WEEKLY, MONTHLY, YEARLY.
currencyCode*	String	The currency in which the payment will be collected. It can be TL (Turkish Lira), USD (US Dollar), EUR (Euro), etc. Ensure that currencies other than TL are defined in your account.
price*	Decimal	The amount to be charged from the card during payment intervals. The current subscription price for the plan.

200: OK

{
    "status": "success",
    "systemTime": 1686865372192,
    "data": {
        "referenceCode": "fb4f08bb-b95b-44e8-a7f4-4111c0fa99d9",
        "createdDate": 1686865372183,
        "name": "Ödeme Planı",
        "price": 440.40,
        "paymentInterval": "MONTHLY",
        "paymentIntervalCount": 1,
        "trialPeriodDays": 0,
        "currencyCode": "TRY",
        "productReferenceCode": "235dbc68-d281-4626-9c85-98002e558ce7",
        "planPaymentType": "RECURRING",
        "status": "ACTIVE",
        "recurrenceCount": 12
    }
}

Create Payment Plan Response

Parameter Name	Type	Description
status	String	It indicates the result of the request. If the transaction is successful, it returns a 'success' value.
systemTime	Long	The returned result is the current Unix timestamp value at that moment.
referenceCode	String	The unique reference code for the created plan. It is used to update or delete a plan, view plan details, and initiate a subscription.
createdDate	Long	The date of plan creation
name	String	The name of the plan.
productReferenceCode	String	The reference code of the product associated with the plan. The product information sent in the request is returned.
price	Decimal	The value sent in the request is returned. It is the amount to be collected from the card during payment intervals.
currencyCode	String	The value sent in the request is returned. It is the currency in which the payment will be collected.
paymentInterval	String	The value sent in the request is returned. It determines the period for collecting recurring payments.
paymentIntervalCount	Integer	The value sent in the request is returned. It determines the frequency of the payment period
trialPeriodDays	Integer	The value sent in the request is returned. If this value was not sent, it returns as 0.
planPaymentType	String	It returns the value RECURRING, indicating that the payment is recurring.
recurrenceCount	Integer	The value sent in the request is returned. It determines how many times the payment period will be repeated (optional).
status	String	It indicates the status of the plan. It takes the value ACTIVE.

Update Payment Plan

This method allows only the updating of the name and trialPeriodDays parameters. To update a plan, the unique reference code associated with that plan must be used. Updating can be done both through the API and the iyzico merchant panel.

Update Payment Plan

POST https://api.iyzipay.com/v2/subscription/pricing-plans/{pricingPlanReferenceCode}

Request Body

Name	Type	Description
conversationId	String	A value that can be sent during the request and received in the response, used to match the request and response. The most common usage is the plan number of the merchant.
locale	String	It is used to set the language of the text returned as a result of the iyzico request. The default value is TR (Turkish).
name*	String	Plan name. A value should be entered that provides a brief description related to the payment plan.
pricingPlanReferenceCode*	String	The reference code of the product to which the plan will be associated.
trialPeriodDays	Integer	Used as a trial period or free usage period. If this value is entered, the first payment is collected after the specified number of days from the day of entry.

200: OK

{
    "status": "success",
    "systemTime": 1686865996746,
    "data": {
        "referenceCode": "fb4f08bb-b95b-44e8-a7f4-4111c0fa99d9",
        "createdDate": 1686865372183,
        "name": "Update Plan",
        "price": 440.40000000,
        "paymentInterval": "MONTHLY",
        "paymentIntervalCount": 1,
        "trialPeriodDays": 10,
        "currencyCode": "TRY",
        "productReferenceCode": "235dbc68-d281-4626-9c85-98002e558ce7",
        "planPaymentType": "RECURRING",
        "status": "ACTIVE",
        "recurrenceCount": 12
    }
}

Update Payment Plan Response

Parameter Name	Type	Description
status	String	It indicates the result of the request. If the transaction is successful, it returns a 'success' value.
systemTime	Long	The returned result is the current Unix timestamp value at that moment.
referenceCode	String	The unique reference code for the created plan. It is used to update or delete a plan, view plan details, and initiate a subscription.
createdDate	Long	The date of plan creation.
name	String	The name of the plan.
productReferenceCode	String	The reference code of the product associated with the plan. The product information sent in the request is returned.
price	Decimal	The value sent in the request is returned. It is the amount to be collected from the card during payment intervals.
currencyCode	String	The value sent in the request is returned. It is the currency in which the payment will be collected.
paymentInterval	String	The value sent in the request is returned. It determines the period for collecting recurring payments.
paymentIntervalCount	Integer	The value sent in the request is returned. It determines the frequency of the payment period
trialPeriodDays	Integer	The value sent in the request is returned. If this value was not sent, it returns as 0.
planPaymentType	String	It returns the value RECURRING, indicating that the payment is recurring.
recurrenceCount	Integer	The value sent in the request is returned. It determines how many times the payment period will be repeated (optional).
status	String	It indicates the status of the plan. It takes the value ACTIVE.

Delete Payment Plan

A plan can only be deleted if it has no associated subscriptions. To delete a plan, the merchant must use the plan reference code. The request is responded to as either success or failure. Success means the plan has been successfully deleted.

Delete Payment Plan

DELETE https://api.iyzipay.com/v2/subscription/pricing-plans/{pricingPlanReferenceCode}

Request Body

Name	Type	Description
pricingPlanReferenceCodee*	String	The reference code of the product to which the plan will be associated.

200: OK

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

Delete Payment Plan Response

Parametre ismi	Tip	Açıklama
status	String	Yapılan isteğin sonucunu belirtir. İşlem başarılı ise success değeri döner.
systemTime	Long	Dönen sonucun o anki unix timestamp değeridir.

Get Payment Plan

Merchant businesses can view all the details of a plan both through the merchant panel and via API requests.

Get Payment Plan

GET https://api.iyzipay.com/v2/subscription/pricing-plans/{pricingPlanReferenceCode}

Request Body

Name	Type	Description
pricingPlanReferenceCode*	String	The reference code of the product to which the plan will be associated.

200: OK

{
    "status": "success",
    "systemTime": 1686866781049,
    "data": {
        "referenceCode": "d507f394-5823-4260-b942-23782045eaac",
        "createdDate": 1686866768055,
        "name": "Ödeme Planı",
        "price": 440.40000000,
        "paymentInterval": "MONTHLY",
        "paymentIntervalCount": 1,
        "trialPeriodDays": 0,
        "currencyCode": "TRY",
        "productReferenceCode": "235dbc68-d281-4626-9c85-98002e558ce7",
        "planPaymentType": "RECURRING",
        "status": "ACTIVE",
        "recurrenceCount": 12
    }
}

Get Payment Plan Response

Parameter Name	Type	Description
status	String	It indicates the result of the request. If the transaction is successful, it returns a 'success' value.
systemTime	Long	The returned result is the current Unix timestamp value at that moment.
referenceCode	String	The unique reference code for the created plan. It is used to update or delete a plan, view plan details, and initiate a subscription.
createdDate	Long	The date of plan creation.
name	String	The name of the plan.
productReferenceCode	String	The reference code of the product associated with the plan. The product information sent in the request is returned.
price	Decimal	The value sent in the request is returned. It is the amount to be collected from the card during payment intervals.
currencyCode	String	The value sent in the request is returned. It is the currency in which the payment will be collected.
paymentInterval	String	The value sent in the request is returned. It determines the period for collecting recurring payments.
paymentIntervalCount	Integer	The value sent in the request is returned. It determines the frequency of the payment period
trialPeriodDays	Integer	The value sent in the request is returned. If this value was not sent, it returns as 0.
planPaymentType	String	It returns the value RECURRING, indicating that the payment is recurring.
recurrenceCount	Integer	The value sent in the request is returned. It determines how many times the payment period will be repeated (optional).
status	String	It indicates the status of the plan. It takes the value ACTIVE.

List of Payment Plans

All plans and the products they are associated with can be viewed in the response to this request. The response is sent in pages.

List of Payment Plans

GET https://api.iyzipay.com/v2/subscription/products/{product_reference}/pricing-plans

Request Body

Name	Type	Description
page*	Integer	It retrieves all the plans for the specified page.
count*	Integer	It specifies how many plans will be listed per page.

200: OK

{
    "status": "success",
    "systemTime": 1686867184729,
    "data": {
        "totalCount": 2,
        "currentPage": 1,
        "pageCount": 1,
        "items": [
            {
                "referenceCode": "d507f394-5823-4260-b942-23782045eaac",
                "createdDate": 1686866768055,
                "name": "Ödeme Planı",
                "price": 440.40000000,
                "paymentInterval": "MONTHLY",
                "paymentIntervalCount": 1,
                "trialPeriodDays": 0,
                "currencyCode": "TRY",
                "productReferenceCode": "235dbc68-d281-4626-9c85-98002e558ce7",
                "planPaymentType": "RECURRING",
                "status": "ACTIVE",
                "recurrenceCount": 12
            },
            {
                "referenceCode": "a3dde7ac-dff4-4d96-a6da-5780aeee9c9a",
                "createdDate": 1675684471828,
                "name": "testop",
                "price": 100.00000000,
                "paymentInterval": "MONTHLY",
                "paymentIntervalCount": 1,
                "trialPeriodDays": 0,
                "currencyCode": "TRY",
                "productReferenceCode": "235dbc68-d281-4626-9c85-98002e558ce7",
                "planPaymentType": "RECURRING",
                "status": "ACTIVE"
            }
        ]
    }
}

List of Payment Plan Response

Parametre ismi	Tip	Açıklama
status	String	It indicates the result of the request. If the transaction is successful, it returns a 'success' value.
systemTime	Long	The returned result is the current Unix timestamp value at that moment.
totalCount	String	It indicates the total number of results.
currentPage	Integer	It specifies which page the listing is for.
pageCount	Integer	It indicates the total number of pages of results.
items	Array Object	It is an array containing plan details.