Subscription Transactions

Activate Subscription

post

A subscription that was started as pending can be activated via this service.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription that was started as pending.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Header parameters

AuthorizationstringRequired

Authorization header; a Base64-encoded signed hash value that begins with IYZWSv2.

Content-TypestringRequired

Request body content type.

Example: application/json

Body

application/json

subscriptionReferenceCodestringOptional

Reference code of the subscription that was started as pending.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Responses

200

Successful response

application/json

statusstring · enumOptional

Indicates the result of the request. Returns success if the operation succeeds.

Possible values:

systemTimeintegerOptional

Unix timestamp (milliseconds) of the response.

400

Error response

application/json

post

/v2/subscription/subscriptions/{subscriptionReferenceCode}/activate

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/subscriptions/009dac1a-00dc-41e8-a92f-2c24b18e27b9/activate
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "referenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

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

Cancel Subscription

post

Cancels an active subscription.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription to cancel.

Example: 009dac1a-00dc-41e8-a92f-2c24b18e27b9

Header parameters

AuthorizationstringRequired

Authorization header, a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

subscriptionReferenceCodestringOptional

Subscription reference code. Can optionally be sent in the request body.

Example: a2077643-bab7-4b73-85a5-7676c78d7c66

Responses

200

Successful response

application/json

statusstring · enumOptional

Result of the request. Returns success if the operation is successful.

Possible values:

systemTimeintegerOptional

Server time of the response (epoch ms).

400

Error response

application/json

post

/v2/subscription/subscriptions/{subscriptionReferenceCode}/cancel

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/subscriptions/009dac1a-00dc-41e8-a92f-2c24b18e27b9/cancel
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "subscriptionReferenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

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

Retry Subscription Payment

post

If a recurring payment fails for a subscription, use this service to retry the charge and collect the payment.

Header parameters

AuthorizationstringRequired

Authorization header, a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

referenceCodestringRequired

Reference code of the failed payment. This is the orderReferenceCode value provided in the webhook notification for the failed subscription payment.

Example: 009dac1a-00dc-41e8-a92f-2c24b18e27b9

Responses

200

Successful response

application/json

statusstring · enumOptional

Result of the request. Returns success if the operation is successful.

Possible values:

systemTimeintegerOptional

Server time of the response (epoch ms).

400

Error response

application/json

post

/v2/subscription/operation/retry

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/operation/retry
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "referenceCode": "a2077643-bab7-4b73-85a5-7676c78d7c66"
}

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

A failed payment transaction can be retried within a maximum of 160 days. If this period is exceeded, no further payment attempts can be made for the subscription.

After the retry operation is successfully triggered, an additional webhook notification is sent for the newly created payment transaction.

Upgrade Subscription

post

You can change or upgrade the plan during the subscription, provided that the new plan belongs to the same product and the billing interval (paymentInterval and paymentIntervalCount) remains the same. Use this service for price changes.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription to upgrade.

Example: 97fb885d-69e3-49ac-8590-9d05c9c6016e

Header parameters

AuthorizationstringRequired

Authorization header, a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

upgradePeriodstring · enumRequired

When the upgrade will take effect. Values:

• NOW: Apply the change immediately.
• NEXT_PERIOD: Apply the change at the next billing period.

Example: NOWPossible values:

newPricingPlanReferenceCodestringRequired

Reference code of the target pricing plan.

Example: dbffa857-40f5-48d1-9179-e9326ffb942d

useTrialbooleanOptional

If true, includes the trial period of the upgraded plan.

Example: false

resetRecurrenceCountbooleanOptional

• true: Recalculates the subscription end date according to the new plan’s recurrenceCount.
• false: Keeps the current plan’s end date and transfers it to the new plan.

Example: true

Responses

200

Successful response

application/json

statusstring · enumOptional

Result of the request. Returns success if the operation is successful.

Possible values:

systemTimeintegerOptional

Server time of the response (epoch ms).

400

Error response

application/json

post

/v2/subscription/subscriptions/{subscriptionReferenceCode}/upgrade

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/subscriptions/97fb885d-69e3-49ac-8590-9d05c9c6016e/upgrade
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "newPricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
  "upgradePeriod": "NEXT_PERIOD",
  "useTrial": false,
  "resetRecurrenceCount": true
}

{
  "status": "success",
  "systemTime": 1755613834401,
  "data": {
    "referenceCode": "74726a5a-cc3d-4de8-b08c-3e373ea26842",
    "parentReferenceCode": "85626e75-5043-4343-89bd-3cbbf33d15ad",
    "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
    "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
    "subscriptionStatus": "ACTIVE",
    "trialDays": 0,
    "createdDate": 1755613834375,
    "startDate": 1756045826566,
    "endDate": 1787581826566
  }
}

Subscription Card Update (Checkout Form)

post

Updates the credit card used in a subscription. In cases like payment failure or card expiry, merchants can prompt customers to update their card. The update can only be performed through the iyzico Checkout Form. A ₺1 validation charge is taken and immediately refunded to validate the updated card.

Header parameters

AuthorizationstringRequired

Authorization header, a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

callbackUrlstringRequired

Callback URL where the update result will be posted.

Example: https://www.merchant.com/callback

customerReferenceCodestringRequired

Reference code of the customer whose card will be updated.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

subscriptionReferenceCodestringOptional

If updating on a specific subscription, the subscription reference code (optional).

Example: 52c732ba-b449-460b-b553-ab21f9074300

localestring · enumOptional

Response language preference.

Example: enPossible values:

Responses

200

Successful response

application/json

statusstring · enumOptional

Operation result.

Possible values:

localestring · enumOptional

Response language.

Possible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755679946462

conversationIdstringOptional

ID sent for request/response correlation. Echoed back in the response.

Example: 04c6063d-eb03-4817-ba87-33b81e392ecf

tokenstringOptional

Token of the card update checkout form.

Example: 83832cc6-89b6-4a83-ac9f-dd996a52b2cb

checkoutFormContentstringOptional

HTML content for the checkout form where card information is updated.

tokenExpireTimeintegerOptional

Token validity period (seconds).

Example: 1800

400

Error response

application/json

post

/v2/subscription/card-update/checkoutform/initialize

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/card-update/checkoutform/initialize
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "callbackUrl": "https://www.merchant.com/callback",
  "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
  "subscriptionReferenceCode": "52c732ba-b449-460b-b553-ab21f9074300"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755679946462,
  "conversationId": "04c6063d-eb03-4817-ba87-33b81e392ecf",
  "token": "83832cc6-89b6-4a83-ac9f-dd996a52b2cb",
  "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"83832cc6-89b6-4a83-ac9f-dd996a52b2cb\",price:1.00,...}};</script>",
  "tokenExpireTime": 1800
}

Get Subscription Detail

get

Returns full details of a subscription by its reference code.

Path parameters

subscriptionReferenceCodestringRequired

Reference code of the subscription to query.

Example: 732a16cc-2ec4-4399-9aab-656cb6f5249e

Header parameters

AuthorizationstringRequired

Authorization header, a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Content-TypestringRequired

Content format of the request.

Example: application/json

Body

application/json

subscriptionReferenceCodestringOptional

Subscription reference code. Can optionally be sent in the request body.

Example: 732a16cc-2ec4-4399-9aab-656cb6f5249e

Responses

200

Successful response

application/json

statusstring · enumOptional

Result of the request.

Possible values:

systemTimeintegerOptional

Server time of the response (epoch ms).

get

/v2/subscription/subscriptions/{subscriptionReferenceCode}

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/subscriptions/732a16cc-2ec4-4399-9aab-656cb6f5249e
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

200

Successful response

{
  "status": "success",
  "systemTime": 1755617091761,
  "data": {
    "totalCount": 1,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "732a16cc-2ec4-4399-9aab-656cb6f5249e",
        "parentReferenceCode": "aa86bbf7-176f-432e-8523-7c24cc250af4",
        "pricingPlanName": "Payment Plan V2 TEST",
        "pricingPlanReferenceCode": "deadd767-7d0a-4ddb-96f2-565ad245773d",
        "productName": "test",
        "productReferenceCode": "40070483-1a6e-4641-99c0-be513edcf9f2",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "ce88a44d-a4f5-4de9-8bbb-1f170a9be219",
        "subscriptionStatus": "UNPAID",
        "trialDays": 0,
        "createdDate": 1753186413089,
        "startDate": 1753186413089,
        "endDate": 1753229613089,
        "orders": [
          {
            "referenceCode": "684279ad-5caa-40a0-ae9a-95ec097d696d",
            "price": 1.4,
            "currencyCode": "TRY",
            "startPeriod": 1753190013089,
            "endPeriod": 1753193613089,
            "orderStatus": "WAITING",
            "paymentAttempts": [
              {
                "conversationId": "90cf2fdc-bb9a-4931-be32-f65312eb379d",
                "createdDate": 1753190040185,
                "paymentStatus": "FAILED",
                "errorCode": "5034",
                "errorMessage": "buyerSurname is required"
              }
            ]
          },
          {
            "referenceCode": "0759e5ce-1668-40cb-9570-d0b6eda8d988",
            "price": 1.4,
            "currencyCode": "TRY",
            "startPeriod": 1753186413089,
            "endPeriod": 1753190013089,
            "orderStatus": "SUCCESS",
            "paymentAttempts": [
              {
                "conversationId": "123456789",
                "createdDate": 1753186413090,
                "paymentId": 24578296,
                "paymentStatus": "SUCCESS"
              }
            ]
          }
        ]
      }
    ]
  }
}

Search Subscriptions

get

Retrieve subscription and payment details by filtering with various parameters, or without any parameters. For example, by sending only subscriptionStatus, you can list subscriptions with that status.

Path parameters

subscriptionReferenceCodestringOptional

Reference code of the subscription to query.

Example: 97fb885d-69e3-49ac-8590-9d05c9c6016e

customerReferenceCodestringOptional

Customer reference code.

Example: 279bb493-6fda-45e9-9368-2373ea43ff8d

pricingPlanReferenceCodestringOptional

Reference code of the pricing plan used in the subscription.

Example: dbffa857-40f5-48d1-9179-e9326ffb942d

parentstringOptional

Parent reference code used for matching in subscription updates.

Example: 670489f2-9224-4a71-af6c-7044d22f5d73

subscriptionStatusstring · enumOptional

Subscription status filter.

Example: ACTIVEPossible values:

startDateintegerOptional

Subscription start date.

Example: 2025-08-24 14:30:26

endDateintegerOptional

Subscription end date (epoch ms).

Example: 2025-08-24 14:30:26

pageintegerOptional

Page number.

Example: 1

countintegerOptional

Number of records per page.

Example: 20

Header parameters

AuthorizationstringRequired

Authorization header, a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Content-TypestringRequired

Content format of the request.

Example: application/json

Responses

200

Successful response

application/json

statusstring · enumOptional

Result of the request.

Possible values:

systemTimeintegerOptional

Server time of the response (epoch ms).

404

Example response for a wrong endpoint (e.g., typo).

application/json

get

/v2/subscription/subscriptions

HTTPcURL (multiple filters)

GET https://api.iyzipay.com/v2/subscription/subscriptions?startDate=2025-08-24 14:30:26&endDate=2026-08-24 14:30:26&subscriptionStatus=ACTIVE 
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755683471024,
  "data": {
    "totalCount": 4,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "74726a5a-cc3d-4de8-b08c-3e373ea26842",
        "parentReferenceCode": "85626e75-5043-4343-89bd-3cbbf33d15ad",
        "pricingPlanName": "Pricing Plan Name",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613834375,
        "startDate": 1756045826566,
        "endDate": 1787581826566,
        "orders": [
          {
            "referenceCode": "0ad2563a-f5b7-4a6c-b6ec-9dc7548493ec",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045826566,
            "endPeriod": 1758724226566,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "52c732ba-b449-460b-b553-ab21f9074300",
        "parentReferenceCode": "670489f2-9224-4a71-af6c-7044d22f5d73",
        "pricingPlanName": "Pricing Plan Name",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613786569,
        "startDate": 1756045757180,
        "endDate": 1787581757180,
        "orders": [
          {
            "referenceCode": "9723fa25-0968-4677-bd9a-559389252b58",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045757180,
            "endPeriod": 1758724157180,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "d5044ccc-f346-4a8c-81e7-272516a330a9",
        "parentReferenceCode": "6f0d463e-9a32-47ea-9a17-53d283f7f6ba",
        "pricingPlanName": "Pricing Plan Name",
        "pricingPlanReferenceCode": "dbffa857-40f5-48d1-9179-e9326ffb942d",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 0,
        "createdDate": 1755613607741,
        "startDate": 1756045126208,
        "endDate": 1787581126208,
        "orders": [
          {
            "referenceCode": "e8c6d7f2-556d-4976-a44f-82e7f5b533c0",
            "price": 10,
            "currencyCode": "TRY",
            "startPeriod": 1756045126208,
            "endPeriod": 1758723526208,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      },
      {
        "referenceCode": "5e4b1ec2-b0c0-47bf-b1bf-8656355cb82d",
        "parentReferenceCode": "7a67a645-3d81-4207-bab4-76beade2f6be",
        "pricingPlanName": "Current Plan",
        "pricingPlanReferenceCode": "7515f763-5da3-4a35-8f7f-d425ae44ac04",
        "productName": "Tea",
        "productReferenceCode": "8d562f84-f8d5-441a-b086-9483fc5133a0",
        "customerEmail": "[email protected]",
        "customerGsmNumber": "[phone]",
        "customerReferenceCode": "279bb493-6fda-45e9-9368-2373ea43ff8d",
        "subscriptionStatus": "ACTIVE",
        "trialDays": 5,
        "trialStartDate": 1755609729652,
        "trialEndDate": 1756041729652,
        "createdDate": 1755609702703,
        "startDate": 1755609729652,
        "orders": [
          {
            "referenceCode": "664a7e09-8ca2-45d8-9996-b340a94d90cb",
            "price": 99.99,
            "currencyCode": "TRY",
            "startPeriod": 1756041729652,
            "endPeriod": 1758720129652,
            "orderStatus": "WAITING",
            "paymentAttempts": []
          }
        ]
      }
    ]
  }
}