Subscription Product

The subscription primarily built around plans, and plans must be associated with products. To create a product, it is sufficient to provide only the name parameter.

A product can have multiple payment plans, and it is possible to perform all these operations both through the API and the iyzico merchant panel.

The product name is a unique value, and it is possible to create unlimited products that will be distinct from each other.

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

1. Create Product

2. Update Product

3. Get Product

4. List Products

5. Delete Product

A product can be deleted only if it does not have an associated plan. If a product associated with a plan needs to be deleted, the associated plan must be deleted first.

Create Product

post

Creates a new subscription product. The Subscription API charges on a recurring basis according to pricing plans, and each plan is linked to at least one product. There is no limit on the number of products; a product can be created by providing only a name.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content type of the request body.

Example: application/json

Body

application/json

localestringOptional

Language of iyzico response messages. Default en; tr is supported.

Example: en

conversationIdstringOptional

A reference value that can be used to match request and response.

Example: 123456789

namestringRequired

Product name.

Example: Coffee Pack

descriptionstringOptional

Product description.

Example: Turkish Coffee

Responses

200

Successful response

application/json

statusstring · enumOptional

Operation result.

Example: successPossible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755552252594

400

Bad request

application/json

post

/v2/subscription/products

HTTPcURL

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

{
  "locale": "en",
  "conversationId": "123456789",
  "name": "Coffee Pack",
  "description": "Turkish Coffee"
}

{
  "status": "success",
  "systemTime": 1755552252594,
  "data": {
    "referenceCode": "08159c1d-6fe9-4934-8a55-e191bd4119e0",
    "createdDate": "2024-10-15 12:24:12",
    "name": "Coffee Pack",
    "description": "Turkish Coffee",
    "status": "ACTIVE",
    "pricingPlans": []
  }
}

Sample Codes

PHP

Java

.Net

Node.Js

Postman

Update Product

post

Updates a subscription product. Product name and description can be edited via API or the iyzico merchant panel. Use the product’s unique reference code for API updates.

Path parameters

productReferenceCodestringRequired

Unique reference code of the product.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content type of the request body.

Example: application/json

Body

application/json

localestringOptional

Response language (en/tr).

Example: en

conversationIdstringOptional

Value used for request/response matching.

Example: 123456789

namestringRequired

New product name.

Example: Product Update

descriptionstringOptional

New product description.

Example: New description

Responses

200

Successful response

application/json

statusstring · enumOptional

Operation result.

Example: successPossible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755552931289

400

Bad request

application/json

post

/v2/subscription/products/{productReferenceCode}

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/products/{productReferenceCode}
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "123456789",
  "name": "Product Update",
  "description": "New description"
}

{
  "status": "success",
  "systemTime": 1755552995773,
  "data": {
    "referenceCode": "e935ca98-5a8f-4c67-95c9-221eb8edb081",
    "createdDate": "2024-10-10 10:09:53",
    "name": "Product Update",
    "description": "New description",
    "status": "ACTIVE",
    "pricingPlans": [
      {
        "referenceCode": "7b0e7912-c1c4-44a6-ac41-403809401458",
        "createdDate": "2024-10-10 10:10:11",
        "name": "testPlan",
        "price": 30,
        "paymentInterval": "WEEKLY",
        "paymentIntervalCount": 1,
        "trialPeriodDays": 30,
        "currencyCode": "TRY",
        "productReferenceCode": "e935ca98-5a8f-4c67-95c9-221eb8edb081",
        "planPaymentType": "RECURRING",
        "status": "ACTIVE",
        "recurrenceCount": 5
      }
    ]
  }
}

Sample Codes

PHP

Java

.Net

Node.js

Postman

Get Product

get

Retrieves details of a single product. Provide the product reference code in the request.

Path parameters

productReferenceCodestringRequired

Unique reference code of the product.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content type of the request body.

Example: application/json

Responses

200

Successful response

application/json

statusstring · enumOptional

Operation result.

Example: successPossible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755552931289

400

Bad request

application/json

get

/v2/subscription/products/{productReferenceCode}

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/products/{productReferenceCode}
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755552931289,
  "data": {
    "referenceCode": "e935ca98-5a8f-4c67-95c9-221eb8edb081",
    "createdDate": "2024-10-10 10:09:53",
    "name": "KingOfProduct",
    "description": "DescriptionOfProduct",
    "status": "ACTIVE",
    "pricingPlans": [
      {
        "referenceCode": "7b0e7912-c1c4-44a6-ac41-403809401458",
        "createdDate": "2024-10-10 10:10:11",
        "name": "testPlan",
        "price": 30,
        "paymentInterval": "WEEKLY",
        "paymentIntervalCount": 1,
        "trialPeriodDays": 30,
        "currencyCode": "TRY",
        "productReferenceCode": "e935ca98-5a8f-4c67-95c9-221eb8edb081",
        "planPaymentType": "RECURRING",
        "status": "ACTIVE",
        "recurrenceCount": 5
      }
    ]
  }
}

Sample Codes

PHP

Java

.Net

Node.Js

Postman

List Products

get

Lists subscription products. Use this to fetch all products and their linked plans. To reduce latency and payload size, pagination is used so you can retrieve the product list page by page.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content type of the request body.

Example: application/json

Body

application/json

pageintegerOptional

Returns products for the specified page.

Example: 1

countintegerOptional

Number of products per page.

Example: 20

Responses

200

Successful response

application/json

statusstring · enumOptional

Operation result.

Example: successPossible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755552794380

400

Bad request

application/json

get

/v2/subscription/products

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/products
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "page": 1,
  "count": 1
}

{
  "status": "success",
  "systemTime": 1755552794380,
  "data": {
    "totalCount": "2",
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "b59fbf3d-5b74-45a3-836e-97f708462a95",
        "createdDate": "2024-10-15 12:19:52",
        "name": "Coffee Pack",
        "description": "Turkish Coffee",
        "status": "ACTIVE",
        "pricingPlans": []
      },
      {
        "referenceCode": "e935ca98-5a8f-4c67-95c9-221eb8edb081",
        "createdDate": "2024-10-10 10:09:53",
        "name": "KingOfProduct",
        "description": "DescriptionOfProduct",
        "status": "ACTIVE",
        "pricingPlans": [
          {
            "referenceCode": "7b0e7912-c1c4-44a6-ac41-403809401458",
            "createdDate": "2024-10-10 10:10:11",
            "name": "testPlan",
            "price": 30,
            "paymentInterval": "WEEKLY",
            "paymentIntervalCount": 1,
            "trialPeriodDays": 30,
            "currencyCode": "TRY",
            "productReferenceCode": "e935ca98-5a8f-4c67-95c9-221eb8edb081",
            "planPaymentType": "RECURRING",
            "status": "ACTIVE",
            "recurrenceCount": 5
          }
        ]
      }
    ]
  }
}

Sample Codes

PHP

Java

.Net

Node.Js

Postman

Delete Product

delete

Deletes a subscription product. Products can be deleted via API or the iyzico merchant panel only when there are no plans linked to the product.

Path parameters

productReferenceCodestringRequired

Unique reference code of the product.

Header parameters

AuthorizationstringRequired

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

Content-TypestringRequired

Content type of the request body.

Example: application/json

Responses

200

Successful response

application/json

statusstring · enumOptional

Operation result.

Example: successPossible values:

systemTimeintegerOptional

Operation time (epoch ms).

Example: 1755553111881

400

Bad request

application/json

delete

/v2/subscription/products/{productReferenceCode}

HTTPcURL

DELETE https://api.iyzipay.com/v2/subscription/products/{productReferenceCode}
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

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

Sample Codes

PHP

Java

.Net

Node.Js

Postman