# 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."}}}}}} ```