# Initialize Subscription
## 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."}}}}}}
```
## 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."}}}}}}
```
## 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."}}}}}}
```
## 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.
```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."}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.iyzico.com/en/getting-started/preliminaries/api-reference-beta/subscription/subscription/initialize-subscription.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.