# Subscription Transactions

The services included in the subscription transactions are listed below.

1. [Initialize Subscription](#initialize-subscription)
2. [Activate Subscription](#post-v2-subscription-subscriptions-subscriptionreferencecode-activate)
3. [Retry Subscription Payment](#post-v2-subscription-operation-retry)
4. [Upgrade Subscription](#post-v2-subscription-subscriptions-subscriptionreferencecode-upgrade)
5. [Cancel Subscription](#post-v2-subscription-subscriptions-subscriptionreferencecode-cancel)
6. [Get Subscription Details](#get-v2-subscription-subscriptions-subscriptionreferencecode)
7. [Search Subcriptions](#get-v2-subscription-subscriptions)
8. [Subscription Card Update](#post-v2-subscription-card-update-checkoutform-initialize)

### Initialize Subscription

If you have completed all the steps, you can now start the subscription process.

Subscription can be started in 2 different ways.

1. [Checkout Form](#initializing-subscription-via-checkout-form)
2. [NON-3DS](#post-v2-subscription-initialize)

Both methods above give the same result, but there is a difference in the way they are used. 

The subscription process always starts with an ACTIVE or PENDING status. If the status is PENDING or the status is ACTIVE but a trial period is specified in the payment plan, iyzico only validates the card in the subscription request. Card validation takes place with a 1 TL withdrawal and subsequent refund. Apart from this, no transaction or payment takes place. 

If the subscription status is ACTIVE and no trial period is specified in the planning, the payment specified in the plan is taken from the card and the subscription is started. 

Each subscription requires a card information. Your customers can start a subscription with the cards they have stored in the iyzico environment or with a new card. When requesting a card update, the `subscriptionReferenceCode` of the relevant subscription must be sent. In this case, only the card information of the relevant subscription will be updated.

#### Table of Subscription Status

<table><thead><tr><th width="140">DURUMU</th><th>AÇIKLAMA</th></tr></thead><tbody><tr><td><strong>ACTIVE</strong></td><td>Bir abonelik aktif ise ve ödemeler düzenli olarak alınıyorsa status active olur.</td></tr><tr><td><strong>PENDING</strong></td><td>Bir abonelik durdurulmuşsa status pending olur.</td></tr><tr><td><strong>UNPAID</strong></td><td>Abonelik sırasında ödeme alınamamış ise status unpaid olur.</td></tr><tr><td><strong>UPGRADED</strong></td><td>Abonelik başka bir plan ile güncellenmişse status upgraded olur.</td></tr><tr><td><strong>CANCELED</strong> </td><td>Abonelik iptal edilmişse status cancelled olur.</td></tr><tr><td><strong>EXPIRED</strong></td><td>Abonelik periyodu bitmişse status expired olur. Karttan başka bir ödeme alınmaz.</td></tr></tbody></table>

#### Initializing Subscription via Checkout Form

To create a checkout form, merchants must submit the following information.&#x20;

* Payment Plan Reference Code
* Customer information
* Subscription Status
* CallBackURL (the address where the Checkout Form result will be posted)

`CallBackUrl` is given by member merchants during the request and determines the page to which the end user will be directed after payment. Redirection occurs as soon as the customer makes the payment. At this point, the payment request was sent to the bank and the result was processed by iyzico. The member business must check whether the payment has been received with a separate request. If the card validation or first payment is successful, all other processes are carried out by iyzico.

{% hint style="info" %}
If your customer has a card stored in the iyzico environment, the option to pay with a stored card will appear on the checkout form. In this case, our member businesses do not need to send an additional request.
{% endhint %}

Via iyzico Checkout Form, an `htmlContent` parameter is returned as a result of the form creation request. When this javascript code snippet is printed on the page, the iyzico library is ready to be loaded into any of the “divs” mentioned below. The checkout form will appear when the page is completely loaded.

The divs where the checkout form will be loaded can be responsive or popup. Examples are given below.

```html
<div id="iyzipay-checkout-form" class="responsive"></div>
```

```html
<div id="iyzipay-checkout-form" class="popup"></div>
```

## Initialize Subscription (iyzico Checkout Form)

> Used to start a subscription with iyzico Checkout Form. Returns the form content and token.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/checkoutform/initialize":{"post":{"summary":"Initialize Subscription (iyzico Checkout Form)","description":"Used to start a subscription with iyzico Checkout Form. Returns the form content and token.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormInitializeRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormInitializeResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionCheckoutFormInitializeRequest":{"type":"object","required":["callbackUrl","pricingPlanReferenceCode","subscriptionInitialStatus","customer"],"properties":{"locale":{"type":"string","description":"Language code. Default is `tr`. Send `\"en\"` to create the checkout form in English.","enum":["tr","en"]},"callbackUrl":{"type":"string","description":"Callback URL to which the payment result will be sent."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"conversationId":{"type":"string","description":"Optional correlation value to match request/response pairs."},"customer":{"$ref":"#/components/schemas/SubscriptionCustomer"}}},"SubscriptionCustomer":{"description":"Buyer information.","type":"object","required":["name","surname","email","gsmNumber","identityNumber","billingAddress"],"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer E.164 when possible (e.g., +905555555555)."},"identityNumber":{"type":"string","description":"National ID (string)."},"billingAddress":{"$ref":"#/components/schemas/SubscriptionBillingAddress"},"shippingAddress":{"$ref":"#/components/schemas/SubscriptionShippingAddress"}}},"SubscriptionBillingAddress":{"type":"object","description":"Billing address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Billing address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"SubscriptionShippingAddress":{"type":"object","description":"Shipping address.","properties":{"address":{"type":"string","description":"Shipping address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"StartSubscriptionCheckoutFormInitializeResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"Echoes the value you sent in the request."},"token":{"type":"string","description":"Token of the checkout form."},"checkoutFormContent":{"type":"string","description":"HTML content of the checkout form."},"tokenExpireTime":{"type":"integer","description":"Token validity time in seconds."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_subscription_with_checkout_form.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCheckoutFormInitializeSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L14">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L377">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/luswnz6/3-1-1-1-initialize-checkoutform">Postman</a></td></tr></tbody></table>

## Initialize Subscription (NON3D)

> Start a subscription without the hosted checkout form, using your own payment form via NON3D service.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/initialize":{"post":{"summary":"Initialize Subscription (NON3D)","description":"Start a subscription without the hosted checkout form, using your own payment form via NON3D service.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionNon3DRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionNon3DResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionNon3DRequest":{"type":"object","required":["pricingPlanReferenceCode","customer","paymentCard","subscriptionInitialStatus"],"properties":{"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"conversationId":{"type":"string","description":"Optional correlation value to match request/response pairs."},"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"customer":{"$ref":"#/components/schemas/SubscriptionCustomer"},"paymentCard":{"description":"Card information.","$ref":"#/components/schemas/PaymentCard"}}},"SubscriptionCustomer":{"description":"Buyer information.","type":"object","required":["name","surname","email","gsmNumber","identityNumber","billingAddress"],"properties":{"name":{"type":"string","description":"First name."},"surname":{"type":"string","description":"Last name."},"email":{"type":"string","description":"Email address."},"gsmNumber":{"type":"string","description":"GSM number. Prefer E.164 when possible (e.g., +905555555555)."},"identityNumber":{"type":"string","description":"National ID (string)."},"billingAddress":{"$ref":"#/components/schemas/SubscriptionBillingAddress"},"shippingAddress":{"$ref":"#/components/schemas/SubscriptionShippingAddress"}}},"SubscriptionBillingAddress":{"type":"object","description":"Billing address.","required":["address","contactName","city","country"],"properties":{"address":{"type":"string","description":"Billing address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"SubscriptionShippingAddress":{"type":"object","description":"Shipping address.","properties":{"address":{"type":"string","description":"Shipping address line."},"zipCode":{"type":"string","description":"ZIP/Postal code."},"contactName":{"type":"string","description":"Contact person."},"city":{"type":"string","description":"City."},"country":{"type":"string","description":"Country."}}},"PaymentCard":{"type":"object","required":["cardHolderName","cardNumber","expireMonth","expireYear","cvc"],"properties":{"cardHolderName":{"type":"string","description":"Cardholder name."},"cardNumber":{"type":"string","description":"Card number."},"expireMonth":{"type":"string","description":"Expiry month."},"expireYear":{"type":"string","description":"Expiry year."},"cvc":{"type":"string","description":"CVC/CVV."}}},"StartSubscriptionNon3DResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the request result; `success` if the operation succeeded."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Unique code used to match updates on the merchant side."},"customerReferenceCode":{"type":"string","description":"Unique customer code created from user info (based on email and gsmNumber)."},"subscriptionStatus":{"type":"string","description":"Subscription status.","enum":["ACTIVE","PENDING"]},"pricingPlanReferenceCode":{"type":"string"},"trialDays":{"type":"integer","description":"Trial period defined in the plan."},"trialStartDate":{"type":"integer","description":"Start time of the trial period (epoch ms)."},"trialEndDate":{"type":"integer","description":"End time of the trial period (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_subscription_api.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionInitializeSample.java#L22">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L62">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L426">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/iag178u/3-1-2-1-initialize-subscription-payment">Postman</a></td></tr></tbody></table>

## Retrieve Checkout Form Result

> After the checkout form flow completes, query the subscription creation result with the returned token.

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/checkoutform/{token}":{"get":{"summary":"Retrieve Checkout Form Result","description":"After the checkout form flow completes, query the subscription creation result with the returned token.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Token returned by checkout form initialize for this operation."},{"name":"conversationId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional correlation value you send in the request to match with the response."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionCheckoutFormResultResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionCheckoutFormResultResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"locale":{"type":"string","enum":["tr","en"]},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."},"conversationId":{"type":"string","description":"Echoes the value you sent in the request."},"token":{"type":"string","description":"Token of the checkout form."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Unique code used to match updates on the merchant side."},"customerReferenceCode":{"type":"string","description":"Unique customer code created from user info (based on email and gsmNumber)."},"subscriptionStatus":{"type":"string","description":"Subscription status.","enum":["ACTIVE","PENDING"]},"pricingPlanReferenceCode":{"type":"string"},"trialDays":{"type":"integer","description":"Trial period defined in the plan. No charge during this period."},"trialStartDate":{"type":"integer","description":"Start time of the trial period (epoch ms)."},"trialEndDate":{"type":"integer","description":"End time of the trial period (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retrieve_subscription_checkout_form_result.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCheckoutFormSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L415">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/fdkvoby/3-1-1-2-retrieve-subscription-after-completed-checkoutform">Postman</a></td></tr></tbody></table>

## Initialize Subscription (Existing Customer)

> If the user already has an active subscription, you can start a new one with customerReferenceCode. If the user does not have an active subscription, no new subscription is started with customerReferenceCode.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription – Initialize","version":"1.0.0"},"tags":[{"name":"Subscription","description":"Subscription operations"}],"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/initialize/with-customer":{"post":{"summary":"Initialize Subscription (Existing Customer)","description":"If the user already has an active subscription, you can start a new one with customerReferenceCode. If the user does not have an active subscription, no new subscription is started with customerReferenceCode.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionWithCustomerRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSubscriptionWithCustomerResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is produced in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"The request content type."}},"schemas":{"StartSubscriptionWithCustomerRequest":{"type":"object","required":["subscriptionInitialStatus","pricingPlanReferenceCode","customerReferenceCode"],"properties":{"subscriptionInitialStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Initial status. If `PENDING`, subscription will not start until activated."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan to start the subscription."},"customerReferenceCode":{"type":"string","description":"Reference code of the existing customer. Must already have an active subscription to start a new one with this flow."}}},"StartSubscriptionWithCustomerResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the created subscription."},"parentReferenceCode":{"type":"string","description":"Reference code to correlate subscription updates on the merchant side."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the plan linked to the created subscription."},"customerReferenceCode":{"type":"string","description":"Reference code of the related customer."},"subscriptionStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Subscription status."},"trialDays":{"type":"integer","description":"Trial period (days)."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"startDate":{"type":"integer","description":"Start time (epoch ms)."},"endDate":{"type":"integer","description":"End time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates an unsuccessful request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Current unix timestamp at the response time."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/create_subscription_with_customer_reference_code.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionInitializeSample.java#L75">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L516">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/224cvf3/3-1-2-2-initialize-subscription-payment-for-existing-customer">Postman</a></td></tr></tbody></table>

## Activate Subscription

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

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Activate Subscription","version":"1.0.1"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/activate":{"post":{"summary":"Activate Subscription","description":"A subscription that was started as pending can be activated via this service.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription that was started as pending."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header; a Base64-encoded signed hash value that begins with IYZWSv2."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Request body content type."}},"schemas":{"ActivateSubscriptionRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Reference code of the subscription that was started as pending."}}},"ActivateSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Indicates the result of the request. Returns `success` if the operation succeeds."},"systemTime":{"type":"integer","description":"Unix timestamp (milliseconds) of the response."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates the result of the request (failure)."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Unix timestamp (milliseconds) of the response."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/activate_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L38">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L123">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L315">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/xswkakr/7-1-activate-subscription">Postman</a></td></tr></tbody></table>

## Retry Subscription Payment

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

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/operation/retry":{"post":{"summary":"Retry Subscription Payment","description":"If a recurring payment fails for a subscription, use this service to retry the charge and collect the payment.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrySubscriptionPaymentRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrySubscriptionPaymentResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"RetrySubscriptionPaymentRequest":{"type":"object","required":["referenceCode"],"properties":{"referenceCode":{"type":"string","description":"Reference code of the failed payment. This is the **orderReferenceCode** value provided in the webhook notification for the failed subscription payment.\n"}}},"RetrySubscriptionPaymentResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retry_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L84">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L141">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L291">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/krob5w3/7-2-retry-subscription">Postman</a></td></tr></tbody></table>

## Cancel Subscription

> Cancels an active subscription.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/cancel":{"post":{"summary":"Cancel Subscription","description":"Cancels an active subscription.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to cancel."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"CancelSubscriptionRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Subscription reference code. Can optionally be sent in the request body."}}},"CancelSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/cancel_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L19">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L181">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L304">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/0xuvqlz/7-3-cancel-subscription">Postman</a></td></tr></tbody></table>

## Upgrade Subscription

> 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.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}/upgrade":{"post":{"summary":"Upgrade Subscription","description":"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.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to upgrade."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeSubscriptionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeSubscriptionResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"UpgradeSubscriptionRequest":{"type":"object","required":["upgradePeriod","newPricingPlanReferenceCode"],"properties":{"upgradePeriod":{"type":"string","enum":["NOW","NEXT_PERIOD"],"description":"When the upgrade will take effect.\nValues:\n- **NOW**: Apply the change immediately.\n- **NEXT_PERIOD**: Apply the change at the next billing period.\n"},"newPricingPlanReferenceCode":{"type":"string","description":"Reference code of the target pricing plan."},"useTrial":{"type":"boolean","description":"If **true**, includes the trial period of the upgraded plan."},"resetRecurrenceCount":{"type":"boolean","description":"- **true**: Recalculates the subscription end date according to the new plan’s **recurrenceCount**.  \n- **false**: Keeps the current plan’s end date and transfers it to the new plan.\n"}}},"UpgradeSubscriptionResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request. Returns **success** if the operation is successful."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the newly created subscription."},"parentReferenceCode":{"type":"string","description":"Reference code used by the merchant to correlate subscription updates."},"pricingPlanReferenceCode":{"type":"string"},"customerReferenceCode":{"type":"string"},"subscriptionStatus":{"type":"string","enum":["ACTIVE","PENDING"],"description":"Subscription status."},"trialDays":{"type":"integer","description":"Trial period of the plan (days)."},"createdDate":{"type":"integer","description":"Creation time (epoch ms)."},"startDate":{"type":"date","description":"Start time (epoch ms)."},"endDate":{"type":"date","description":"End time (epoch ms)."}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/upgrade_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionOperationSample.java#L57">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L159">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L326">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/o6rygn3/7-4-upgrade-subscription">Postman</a></td></tr></tbody></table>

## Get Subscription Detail

> Returns full details of a subscription by its reference code.

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions/{subscriptionReferenceCode}":{"get":{"summary":"Get Subscription Detail","description":"Returns full details of a subscription by its reference code.","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":true,"schema":{"type":"string"},"description":"Reference code of the subscription to query."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubscriptionDetailOptionalRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSubscriptionDetailResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"GetSubscriptionDetailOptionalRequest":{"type":"object","properties":{"subscriptionReferenceCode":{"type":"string","description":"Subscription reference code. Can optionally be sent in the request body."}}},"GetSubscriptionDetailResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","description":"Pagination information and subscription records.","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer","description":"Current page number."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Detailed subscription records.","items":{"$ref":"#/components/schemas/SubscriptionDetailItem"}}}}}},"SubscriptionDetailItem":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Subscription reference code."},"parentReferenceCode":{"type":"string","description":"Reference used by the merchant to correlate subscription updates."},"pricingPlanName":{"type":"string","description":"Name of the pricing plan linked to the subscription."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the pricing plan linked to the subscription."},"productName":{"type":"string","description":"Product name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"customerEmail":{"type":"string","description":"Customer email address."},"customerGsmNumber":{"type":"string","description":"Customer GSM number."},"customerReferenceCode":{"type":"string","description":"Customer reference code."},"subscriptionStatus":{"type":"string","description":"Subscription status.\n\nValues:\n- **ACTIVE**: Subscription is active and payments are being collected regularly.\n- **PENDING**: Subscription is paused.\n- **UNPAID**: Payment could not be collected during the subscription.\n- **UPGRADED**: Subscription has been updated to another plan.\n- **CANCELED**: Subscription is canceled.\n- **EXPIRED**: Subscription period ended; no further charges are attempted.\n","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"trialDays":{"type":"integer","description":"Trial period (days) of the pricing plan."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."},"orders":{"type":"array","description":"List of periods (orders) within the subscription.","items":{"$ref":"#/components/schemas/SubscriptionOrder"}}}},"SubscriptionOrder":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the subscription period (order)."},"price":{"type":"decimal","description":"Period price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency."},"startPeriod":{"type":"integer","description":"Start time of the period (epoch ms)."},"endPeriod":{"type":"integer","description":"End time of the period (epoch ms)."},"orderStatus":{"type":"string","description":"Period status.","enum":["WAITING","SUCCESS","FAILED"]},"paymentAttempts":{"type":"array","description":"Payment attempts made for this period.","items":{"$ref":"#/components/schemas/SubscriptionPaymentAttempt"}}}},"SubscriptionPaymentAttempt":{"type":"object","description":"A single payment attempt for a subscription period.","properties":{"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"createdDate":{"type":"integer","description":"Creation time of the attempt (epoch ms)."},"paymentStatus":{"type":"string","description":"Result of the payment attempt.","enum":["SUCCESS","FAILED"]},"paymentId":{"type":"integer","description":"Payment ID for a successful payment. Present only when **SUCCESS**."},"errorCode":{"type":"string","description":"Error code for a failed payment. Present only when **FAILED**."},"errorMessage":{"type":"string","description":"Error message for a failed payment. Present only when **FAILED**."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/retrieve_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L199">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L342">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/7go66rr/3-2-3-retrieve-subscription">Postman</a></td></tr></tbody></table>

## Search Subscriptions

> 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.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/subscriptions":{"get":{"summary":"Search Subscriptions","description":"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.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"},{"name":"subscriptionReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Reference code of the subscription to query."},{"name":"customerReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Customer reference code."},{"name":"pricingPlanReferenceCode","in":"path","required":false,"schema":{"type":"string"},"description":"Reference code of the pricing plan used in the subscription."},{"name":"parent","in":"path","required":false,"schema":{"type":"string"},"description":"Parent reference code used for matching in subscription updates."},{"name":"subscriptionStatus","in":"path","required":false,"schema":{"type":"string","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"description":"Subscription status filter."},{"name":"startDate","in":"path","required":false,"schema":{"type":"integer"},"description":"Subscription start date."},{"name":"endDate","in":"path","required":false,"schema":{"type":"integer"},"description":"Subscription end date (epoch ms)."},{"name":"page","in":"path","required":false,"schema":{"type":"integer"},"description":"Page number."},{"name":"count","in":"path","required":false,"schema":{"type":"integer"},"description":"Number of records per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSubscriptionsResponse"}}}},"404":{"description":"Example response for a wrong endpoint (e.g., typo).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"SearchSubscriptionsResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Result of the request."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."},"data":{"type":"object","description":"Pagination information and subscription records.","properties":{"totalCount":{"type":"integer","description":"Total record count."},"currentPage":{"type":"integer","description":"Current page number."},"pageCount":{"type":"integer","description":"Total page count."},"items":{"type":"array","description":"Detailed subscription records.","items":{"$ref":"#/components/schemas/SubscriptionDetailItem"}}}}}},"SubscriptionDetailItem":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Subscription reference code."},"parentReferenceCode":{"type":"string","description":"Reference used by the merchant to correlate subscription updates."},"pricingPlanName":{"type":"string","description":"Name of the pricing plan linked to the subscription."},"pricingPlanReferenceCode":{"type":"string","description":"Reference code of the pricing plan linked to the subscription."},"productName":{"type":"string","description":"Product name."},"productReferenceCode":{"type":"string","description":"Product reference code."},"customerEmail":{"type":"string","description":"Customer email address."},"customerGsmNumber":{"type":"string","description":"Customer GSM number."},"customerReferenceCode":{"type":"string","description":"Customer reference code."},"subscriptionStatus":{"type":"string","description":"Subscription status.\n\nValues:\n- **ACTIVE**: Subscription is active and payments are being collected regularly.\n- **PENDING**: Subscription is paused.\n- **UNPAID**: Payment could not be collected during the subscription.\n- **UPGRADED**: Subscription has been updated to another plan.\n- **CANCELED**: Subscription is canceled.\n- **EXPIRED**: Subscription period ended; no further charges are attempted.\n","enum":["ACTIVE","PENDING","UNPAID","UPGRADED","CANCELED","EXPIRED"]},"trialDays":{"type":"integer","description":"Trial period (days) of the pricing plan."},"trialStartDate":{"type":"integer","description":"Trial start time (epoch ms)."},"trialEndDate":{"type":"integer","description":"Trial end time (epoch ms)."},"createdDate":{"type":"integer","description":"Subscription creation time (epoch ms)."},"startDate":{"type":"integer","description":"Subscription start time (epoch ms)."},"endDate":{"type":"integer","description":"Subscription end time (epoch ms)."},"orders":{"type":"array","description":"List of periods (orders) within the subscription.","items":{"$ref":"#/components/schemas/SubscriptionOrder"}}}},"SubscriptionOrder":{"type":"object","properties":{"referenceCode":{"type":"string","description":"Reference code of the subscription period (order)."},"price":{"type":"decimal","description":"Period price."},"currencyCode":{"type":"string","enum":["TRY","USD","EUR"],"description":"Currency."},"startPeriod":{"type":"integer","description":"Start time of the period (epoch ms)."},"endPeriod":{"type":"integer","description":"End time of the period (epoch ms)."},"orderStatus":{"type":"string","description":"Period status.","enum":["WAITING","SUCCESS","FAILED"]},"paymentAttempts":{"type":"array","description":"Payment attempts made for this period.","items":{"$ref":"#/components/schemas/SubscriptionPaymentAttempt"}}}},"SubscriptionPaymentAttempt":{"type":"object","description":"A single payment attempt for a subscription period.","properties":{"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"createdDate":{"type":"integer","description":"Creation time of the attempt (epoch ms)."},"paymentStatus":{"type":"string","description":"Result of the payment attempt.","enum":["SUCCESS","FAILED"]},"paymentId":{"type":"integer","description":"Payment ID for a successful payment. Present only when **SUCCESS**."},"errorCode":{"type":"string","description":"Error code for a failed payment. Present only when **FAILED**."},"errorMessage":{"type":"string","description":"Error message for a failed payment. Present only when **FAILED**."}}},"NotFoundErrorResponse":{"type":"object","properties":{"timestamp":{"type":"integer","description":"Server time (epoch ms)."},"status":{"type":"integer","description":"HTTP status code."},"error":{"type":"string","description":"Short error description."},"path":{"type":"string","description":"Requested path."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/search_subscription.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionSearchSample.java#L17">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L218">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L353">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/5onz787/3-2-4-search-subscriptions">Postman</a></td></tr></tbody></table>

## Subscription Card Update (Checkout Form)

> 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.<br>

```json
{"openapi":"3.0.3","info":{"title":"Subscription - Retry / Cancel / Upgrade / Search / Detail / Card Update","version":"1.0.0"},"servers":[{"url":"https://api.iyzipay.com","description":"iyzico API"}],"paths":{"/v2/subscription/card-update/checkoutform/initialize":{"post":{"summary":"Subscription Card Update (Checkout Form)","description":"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.**\nA **₺1** validation charge is taken and immediately refunded to validate the updated card.\n","tags":["Subscription"],"parameters":[{"$ref":"#/components/parameters/AuthHeader"},{"$ref":"#/components/parameters/ContentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCardUpdateCheckoutFormRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCardUpdateCheckoutFormResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"AuthHeader":{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Authorization header, a signed hash value that starts with **IYZWSv2** and is generated in Base64 format."},"ContentTypeHeader":{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string"},"description":"Content format of the request."}},"schemas":{"InitializeCardUpdateCheckoutFormRequest":{"type":"object","required":["callbackUrl","customerReferenceCode"],"properties":{"callbackUrl":{"type":"string","description":"Callback URL where the update result will be posted."},"customerReferenceCode":{"type":"string","description":"Reference code of the customer whose card will be updated."},"subscriptionReferenceCode":{"type":"string","description":"If updating on a specific subscription, the subscription reference code (optional).\n"},"locale":{"type":"string","enum":["tr","en"],"description":"Response language preference."}}},"InitializeCardUpdateCheckoutFormResponse":{"type":"object","properties":{"status":{"type":"string","enum":["success","failure"],"description":"Operation result."},"locale":{"type":"string","enum":["tr","en"],"description":"Response language."},"systemTime":{"type":"integer","description":"Operation time (epoch ms)."},"conversationId":{"type":"string","description":"ID sent for request/response correlation. Echoed back in the response."},"token":{"type":"string","description":"Token of the card update checkout form."},"checkoutFormContent":{"type":"string","description":"HTML content for the checkout form where card information is updated."},"tokenExpireTime":{"type":"integer","description":"Token validity period (seconds)."}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["failure"],"description":"Indicates a failed request."},"errorCode":{"type":"string","description":"Error code."},"errorMessage":{"type":"string","description":"Error message."},"systemTime":{"type":"integer","description":"Server time of the response (epoch ms)."}}}}}}
```

#### Sample Codes

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="https://github.com/iyzico/iyzipay-php/blob/master/samples/subscription-samples/card_update_customer.php">PHP</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-java/blob/master/src/test/java/com/iyzipay/sample/subscription/SubscriptionCardUpdateCheckoutFormInitializeSample.java">Java</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-dotnet/blob/master/Iyzipay.Samples/SubscriptionSample.cs#L246">.NET</a></td></tr><tr><td><a href="https://github.com/iyzico/iyzipay-node/blob/master/samples/IyzipaySubscriptionSamples.js#L259">Node.js</a></td></tr><tr><td><a href="https://www.postman.com/iyzico/iyzico/request/aoe23xd/4-1-1-initialize-checkoutform">Postman</a></td></tr></tbody></table>

{% hint style="info" %}
Merchants can send the locale and conversationId parameters in all requests, but this is not mandatory. The locale parameter determines the language of the response. If specified as “EN”, error messages will be received in English. Conversation id is a value that software developers can use to match requests and responses. If this parameter is sent, the same value will be received in the response.
{% endhint %}

With this request, a checkout form is created and when the customer makes the payment, token information is sent to the specified `callBackUrl` address. In this case, the card has been updated successfully.