Subscriber Transactions

After each subscription payment, a default customerReferenceCode is generated for the customer whose details are provided. Currently, this reference code can only be used to retrieve and update customer information.

Customers are created or updated based on the email parameter. For example, a unique reference code, let's say 'A', is generated for a customer when a subscription is created with email address 'X'. If the email address 'X' is used in another subscription, the customer details sent in the request are updated, and once again, a unique reference code 'A' is generated.

There are 3 different methods that can be used on subscribers.

1. Update Subscriber

2. Get Subscriber

3. List of Subscribers

Update Subscriber

post

Update all details of a subscriber via API. Provide the subscriber's customerReferenceCode as a path parameter and include the fields to be updated in the request body. At least one field in the body is required; only the provided fields will be updated.

Path parameters

customerReferenceCodestringRequired

Subscriber reference code.

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

Header parameters

AuthorizationstringRequired

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

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-TypestringRequired

Request content type.

Example: application/json

Body

application/json

Fields to update. All fields are optional, but the body must contain at least one property.

namestringOptional

First name.

Example: John

surnamestringOptional

Last name.

Example: Doe

emailstringOptional

Email address.

Example: [email protected]

gsmNumberstringOptional

GSM number. Prefer +90 format.

Example: [phone]

identityNumberstringOptional

Turkish National ID Number (11 digits).

Example: 11111111111

Responses

200

Successful response

application/json

statusstring · enumOptional

Indicates the result of the request.

Possible values:

systemTimeintegerOptional

The current epoch time in milliseconds at the moment of the response.

400

Error response

application/json

post

/v2/subscription/customers/{customerReferenceCode}

HTTPcURL

POST https://api.iyzipay.com/v2/subscription/customers/279bb493-6fda-45e9-9368-2373ea43ff8d
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "name": "John",
  "surname": "Doe",
  "email": "[email protected]",
  "gsmNumber": "[phone]",
  "identityNumber": "11111111111",
  "billingAddress": {
    "address": "address1",
    "zipCode": "34940",
    "contactName": "John Doe",
    "city": "Istanbul",
    "district": "District",
    "country": "Turkey"
  },
  "shippingAddress": {
    "address": "address",
    "zipCode": "34940",
    "contactName": "John Doe",
    "city": "Istanbul",
    "country": "Turkey"
  }
}

{
  "status": "success",
  "systemTime": 1755693772785,
  "data": {
    "referenceCode": "7e966c81-7f09-4bce-b0eb-7467086d7a50",
    "createdDate": 1755693138286,
    "status": "ACTIVE",
    "name": "John",
    "surname": "Doe",
    "identityNumber": "11111111111",
    "email": "[email protected]",
    "gsmNumber": "[phone]",
    "contactEmail": "[email protected]",
    "contactGsmNumber": "[phone]",
    "billingAddress": {
      "address": "address1",
      "zipCode": "34940",
      "contactName": "John Doe",
      "district": "District",
      "city": "Istanbul",
      "country": "Turkey"
    },
    "shippingAddress": {
      "address": "address",
      "zipCode": "34940",
      "contactName": "John Doe",
      "district": null,
      "city": "Istanbul",
      "country": "Turkey"
    }
  }
}

Sample Codes

PHP

Java

.Net

Node.js

Postman

Subscriber Detail

get

Retrieve all details of a subscriber by its reference code.

Path parameters

customerReferenceCodestringRequired

Subscriber reference code.

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

Header parameters

AuthorizationstringRequired

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

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-TypestringRequired

Request content type.

Example: application/json

Responses

200

Successful response

application/json

statusstring · enumOptionalPossible values:

systemTimeintegerOptional

The current epoch time in milliseconds at the moment of the response.

400

Error response

application/json

get

/v2/subscription/customers/{customerReferenceCode}

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/customers/7e966c81-7f09-4bce-b0eb-7467086d7a50
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1755695274336,
  "data": {
    "referenceCode": "7e966c81-7f09-4bce-b0eb-7467086d7a50",
    "createdDate": 1755693138286,
    "status": "ACTIVE",
    "name": "John",
    "surname": "Doe",
    "identityNumber": "11111111111",
    "email": "[email protected]",
    "gsmNumber": "[phone]",
    "contactEmail": "[email protected]",
    "contactGsmNumber": "[phone]",
    "billingAddress": {
      "address": "address1",
      "zipCode": "34940",
      "contactName": "John Doe",
      "district": "District",
      "city": "Istanbul",
      "country": "Turkey"
    },
    "shippingAddress": {
      "address": "address",
      "zipCode": "34940",
      "contactName": "John Doe",
      "district": "",
      "city": "Istanbul",
      "country": "Turkey"
    }
  }
}

Sample Codes

PHP

Java

.Net

Node.js

Postman

List Subscribers

get

List all subscribers with basic details.

Query parameters

pageintegerOptional

Page number to fetch.

Example: 1

countintegerOptional

Number of subscribers per page.

Example: 1

Header parameters

AuthorizationstringRequired

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

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-TypestringRequired

Request content type.

Example: application/json

Responses

200

Successful response

application/json

statusstring · enumOptionalPossible values:

systemTimeintegerOptional

The current epoch time in milliseconds at the moment of the response.

400

Error response

application/json

get

/v2/subscription/customers

HTTPcURL

GET https://api.iyzipay.com/v2/subscription/customers?page=1&count=1
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "status": "success",
  "systemTime": 1687817022470,
  "data": {
    "totalCount": 2,
    "currentPage": 1,
    "pageCount": 1,
    "items": [
      {
        "referenceCode": "e2378434-3192-426d-a821-59c49583b6d4",
        "createdDate": 1687815595481,
        "status": "ACTIVE",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "11111111111",
        "email": "[email protected]",
        "gsmNumber": "[phone]",
        "contactEmail": "[email protected]",
        "contactGsmNumber": "[phone]",
        "billingAddress": {
          "address": "Uskudar Burhaniye Mahallesi iyzico A.S",
          "zipCode": "34660",
          "contactName": "John Doe",
          "district": "Altunizade",
          "city": "Istanbul",
          "country": "Turkey"
        },
        "shippingAddress": {
          "address": "Uskudar Burhaniye Mahallesi iyzico A.S",
          "zipCode": "34660",
          "contactName": "John Doe",
          "district": "Altunizade",
          "city": "Istanbul",
          "country": "Turkey"
        }
      },
      {
        "referenceCode": "deeb305d-053e-412e-bead-bc507f771223",
        "createdDate": 1687379184912,
        "status": "ACTIVE",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "11111111111",
        "email": "[email protected]",
        "gsmNumber": "[phone]",
        "contactEmail": "[email protected]",
        "contactGsmNumber": "[phone]",
        "billingAddress": {
          "address": "Uskudar Burhaniye Mahallesi iyzico A.S",
          "zipCode": "34660",
          "contactName": "John Doe",
          "district": "Altunizade",
          "city": "Istanbul",
          "country": "Turkey"
        },
        "shippingAddress": {
          "address": "Uskudar Burhaniye Mahallesi iyzico A.S",
          "zipCode": "34660",
          "contactName": "John Doe",
          "district": "Altunizade",
          "city": "Istanbul",
          "country": "Turkey"
        }
      }
    ]
  }
}

Sample Codes

PHP

Java

.Net

Node.js

Postman