Send Warranty with Invoice

You can send warranties with invoice information using this service. This is the most flexible endpoint that allows creating products on-the-fly and supports extended warranties.

Important - externalLineId

The externalLineId should be a unique value in your system for each line item. This rule is enforced: a value that is already registered for your merchant account is rejected with HTTP 400 and code 4093, and a value repeated twice inside the same request is rejected with HTTP 400 and code 4092.

Customer Information

The email and phone values are not mandatory, but it's recommended to provide at least one. If neither is provided, the system will generate unique values for the customer record.

Serial Number

If serialNumber is provided, the combination of merchantCode, productCode, and serialNumber must be unique. Duplicate submissions are rejected with HTTP 400 and code 4077.

Product Creation Logic

1. If productCode is provided and exists → warranty is created for existing product
2. If productCode is provided but doesn't exist → new product is created, then warranty
3. If no productCode but brand and name provided → new product is created with defaults
4. If none of the above → error is returned
5. If insuranceId is not provided → extended warranty will not be created

External Order ID Uniqueness

We recommend keeping externalOrderId unique in your system, because this is the value you use later to look up the warranty IDs of an order or to delete a warranty.

The API does not enforce this uniqueness. If you send the same externalOrderId more than once, every request creates a new, independent warranty and each one returns HTTP 200 — nothing is rejected, updated, or de-duplicated. As a result:

• GET /individual-customer-products/external-order-id/{externalOrderId} returns all warranty IDs created with that value, not a single ID.
• If you retry a request after a timeout without knowing whether the original call succeeded, you can end up with duplicate warranties for the same order.

Retry Safety

Because externalOrderId is not a deduplication key, treat these endpoints as non-idempotent. Before retrying a request whose outcome you do not know, query the warranty IDs by external order ID endpoint and check whether the warranty already exists.

The uniqueness that is enforced is externalLineId (per merchant, and per request) and, when a serial number is sent, the merchantCode + productCode + serialNumber combination. See Error Cases below.

Request

curl --location --request POST '<BASE_URL>/individual-customers/warranty/invoice/with-product-code' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <jwtToken>' \
--data '{
  "externalOrderId": "ORD-12345",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+905551234567",
    "birthDate": "15-06-1990",
    "identificationNumber": "12345678901",
    "countryCode": "TR"
  },
  "products": [
    {
      "productCode": "PRD-001",
      "name": "iPhone 15 Pro",
      "brand": "Apple",
      "externalLineId": "LINE-001",
      "productPrice": 49999.99,
      "purchaseDate": "15-01-2024 10:30",
      "warrantyExpireDate": "15-01-2026 10:30",
      "invoiceDate": "14-01-2024 16:45",
      "invoiceNumber": "FTR-2024-000123",
      "mainCategoryName": "Electronics",
      "categoryName": "Phone",
      "subCategoryName": "Smartphone",
      "extendedWarranties": [
        {
          "insuranceId": 1,
          "insuranceName": "2 Year Extended Warranty",
          "insurancePrice": 999.99,
          "storeCode": "STR-001",
          "storeName": "Tech Store Istanbul",
          "personalName": "John Smith",
          "personalCode": "EMP-123",
          "taxNo": "1234567890",
          "refId": "REF-001"
        }
      ]
    },
    {
      "productCode": "PRD-002",
      "name": "AirPods Pro",
      "brand": "Apple",
      "externalLineId": "LINE-002",
      "productPrice": 7999.99,
      "purchaseDate": "15-01-2024 10:30"
    }
  ]
}'

Phone Number Formats

Acceptable formats:

• 544 333 22 11
• 5443332211
• +905443332211
• 905443332211
• 05443332211

Date Formats

• purchaseDate, invoiceDate and warrantyExpireDate: dd-MM-yyyy HH:mm (e.g., 01-01-2023 00:00)
• birthDate: dd-MM-yyyy (e.g., 01-01-1990)

Default behaviors:

• purchaseDate becomes the warranty start date. If it is not provided → today's date
• If warrantyExpireDate is not provided → calculated from product's warranty period
• invoiceDate and invoiceNumber record the sales invoice; they are stored as-is and do not affect the warranty dates
• If birthDate is not provided → current date

Request Body

Root Object

Parameter	Type	Required	Description
externalOrderId	String	Yes	External order ID (e.g., "ORD-12345")
customer	Object	Yes	Customer information object
products	Array	Yes	Array of product objects (1-50 items)

Customer Object

Parameter	Type	Required	Description
firstName	String	Yes	Customer first name (e.g., "John")
lastName	String	Yes	Customer last name (e.g., "Doe")
email	String	No	Customer email (e.g., "john.doe@example.com")
phone	String	No	Customer phone (e.g., "+905551234567")
countryCode	Enum	No	Country code (e.g., "TR")
identificationNumber	String	No	National ID number (e.g., "12345678901")
birthDate	String	No	Birth date (format: dd-MM-yyyy)

Product Object

Parameter	Type	Required	Description
productCode	String	No*	Unique product code (e.g., "PRD-001")
name	String	No*	Product name (e.g., "iPhone 15 Pro")
brand	String	No*	Brand name (e.g., "Apple")
serialNumber	String	No	Product serial number (e.g., "SN123456789")
externalLineId	String	No	Line item ID (e.g., "LINE-001")
productPrice	Double	No	Product price (e.g., 49999.99)
purchaseDate	String	No	Purchase date (format: dd-MM-yyyy HH:mm). Used as the warranty start date.
invoiceDate	String	No	Sales invoice date (format: dd-MM-yyyy HH:mm)
invoiceNumber	String	No	Sales invoice number (e.g., "FTR-2024-000123")
warrantyExpireDate	String	No	Warranty expiration (format: dd-MM-yyyy HH:mm)
mainCategoryName	String	No	Main category name (e.g., "Electronics")
categoryName	String	No	Category name (e.g., "Phone")
subCategoryName	String	No	Sub-category name (e.g., "Smartphone")
extendedWarranties	Array	No	Array of extended warranty objects

*Either productCode OR (name AND brand) is required.

Extended Warranty Object

Parameter	Type	Required	Description
insuranceId	Integer	No*	Insurance plan ID (required for extended warranty)
insuranceName	String	No	Plan name (e.g., "2 Year Extended Warranty")
insurancePrice	Double	No	Plan price (e.g., 999.99)
storeCode	String	No	Store code (e.g., "STR-001")
storeName	String	No	Store name (e.g., "Tech Store Istanbul")
personalName	String	No	Salesperson name (e.g., "John Smith")
personalCode	String	No	Salesperson code (e.g., "EMP-123")
taxNo	String	No	Tax number (e.g., "1234567890")
refId	String	No	Reference ID (e.g., "REF-001")

*If insuranceId is not provided, extended warranty will not be created.

Country Code Enum

TR  // Turkey
US  // United States
DE  // Germany
GB  // United Kingdom
AE  // United Arab Emirates
NL  // Netherlands
FR  // France
UZ  // Uzbekistan

Response

{
  "individualCustomerProductResponseList": [
    {
      "id": 12345,
      "lineId": "LINE-001"
    },
    {
      "id": 12346,
      "lineId": "LINE-002"
    }
  ]
}

Error Cases

HTTP Status	Code	Description
400	4092	The same externalLineId is used more than once inside this request. Make each line item's value distinct.
400	4093	The externalLineId is already registered for your merchant account by an earlier request. Use a new value.
400	4077	A warranty with the same merchantCode + productCode + serialNumber combination already exists.

Info

Handle these cases by the HTTP status code and by fixing the offending field. The numeric code value is provided so you can tell the three cases apart while debugging.

Example - Simple Invoice

{
  "externalOrderId": "INV-2024-0001",
  "customer": {
    "firstName": "Ahmet",
    "lastName": "Yilmaz",
    "email": "ahmet@example.com",
    "phone": "5321234567",
    "countryCode": "TR"
  },
  "products": [
    {
      "productCode": "LAPTOP-001",
      "externalLineId": "L1",
      "productPrice": 25000.00,
      "purchaseDate": "20-01-2024 14:30"
    }
  ]
}

Example - Invoice with Extended Warranty

{
  "externalOrderId": "INV-2024-0002",
  "customer": {
    "firstName": "Ayse",
    "lastName": "Demir",
    "email": "ayse@example.com",
    "phone": "5339876543",
    "countryCode": "TR",
    "identificationNumber": "98765432101"
  },
  "products": [
    {
      "productCode": "TV-SAMSUNG-55",
      "name": "Samsung 55 inch 4K TV",
      "brand": "Samsung",
      "externalLineId": "L1",
      "productPrice": 35000.00,
      "extendedWarranties": [
        {
          "insuranceId": 5,
          "insuranceName": "3 Year Protection Plan",
          "insurancePrice": 2500.00,
          "storeCode": "STORE-IST-01",
          "storeName": "MediaMarkt Istinye"
        }
      ]
    }
  ]
}