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; it is unique per merchant account. A value repeated twice inside the same request is rejected with HTTP 400 and code 4092.

A value that is already registered for your merchant account by an earlier request is not rejected: no new warranty is created for that line, and the response returns the ID of the existing warranty. See Resending Line Items below.

externalLineId Is Unique Across Orders

externalLineId is checked across your whole merchant account, not per order. If a different order reuses an externalLineId that is already registered, no new warranty is created for that line item: the response returns the ID of the warranty registered by the earlier order.

Do not use per-order numbering that restarts in every order (such as L1, L2). Use a value that is globally unique in your system, for example your invoice line ID.

Line Items without externalLineId

Line items sent without an externalLineId cannot be checked for repeats. Every such line item is treated as new and creates a new warranty each time the request is sent.

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

externalOrderId is not a deduplication key; externalLineId is. If every line item carries an externalLineId, resending an order after the original request has completed is safe: line items that were already registered are skipped and their existing IDs are returned (see Resending Line Items).

Concurrent or overlapping requests for the same line items (for example, sending a retry while the first request is still being processed) are not protected and can create duplicate warranties. After a timeout, wait a short while before resending, or first query the warranty IDs by external order ID endpoint to check whether the original request succeeded. For line items without an externalLineId, always query this endpoint before retrying.

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 Resending Line Items and Error Cases below.

Resending Line Items

When a request contains an externalLineId that is already registered for your merchant account, that line item is not created again. The endpoint behaves as follows:

• All line items already registered → HTTP 200. The response contains the IDs of the existing warranties. No new warranty is created and no SMS / e-mail notification is sent.
• Some line items registered, some new → only the new line items are created. The response contains registered line items with their existing ID and new line items with their new ID, in the order of the request.
• Registered line items are not updated. Any field sent again for an already registered line item (for example newly added extendedWarranties, a serial number, a price or changed customer information) is ignored, and the request still returns HTTP 200.
• Notifications (SMS / e-mail) are sent only if at least one new line item is created, and only once per request.
• Any error in a new line item (for example a serial number conflict or a validation error) → the whole request is rejected and none of the line items are saved.

Recommended Usage

When you resend an order after the original request has completed, it is safe to send all of its line items again, including the ones that were already registered. You receive the warranty IDs for the order in a single response. Do not send the retry while the original request may still be in progress; see Retry Safety.

The response format does not change: individualCustomerProductResponseList normally contains one {id, lineId} entry per line item. If more than one warranty exists for the same externalLineId (for example, left over from concurrent requests), all of them are returned for that line item. When every line item is already registered, the order of the entries is not guaranteed. See Example - Resending an Order 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	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 cases apart while debugging. An externalLineId that is already registered for your merchant account is not an error; see Resending Line Items.

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": "INV-2024-0001-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": "INV-2024-0002-L1",
      "productPrice": 35000.00,
      "extendedWarranties": [
        {
          "insuranceId": 5,
          "insuranceName": "3 Year Protection Plan",
          "insurancePrice": 2500.00,
          "storeCode": "STORE-IST-01",
          "storeName": "MediaMarkt Istinye"
        }
      ]
    }
  ]
}

Example - Resending an Order

The order ORD-12345 from the Request above was sent earlier, and line items LINE-001 and LINE-002 were registered with IDs 12345 and 12346. The order is now resent with a third line item LINE-003 added. All three line items are sent again:

{
  "externalOrderId": "ORD-12345",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+905551234567",
    "countryCode": "TR"
  },
  "products": [
    {
      "productCode": "PRD-001",
      "externalLineId": "LINE-001",
      "productPrice": 49999.99,
      "purchaseDate": "15-01-2024 10:30"
    },
    {
      "productCode": "PRD-002",
      "externalLineId": "LINE-002",
      "productPrice": 7999.99,
      "purchaseDate": "15-01-2024 10:30"
    },
    {
      "productCode": "PRD-003",
      "name": "Apple Watch Series 9",
      "brand": "Apple",
      "externalLineId": "LINE-003",
      "productPrice": 14999.99,
      "purchaseDate": "15-01-2024 10:30"
    }
  ]
}

Response (HTTP 200):

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

• LINE-001 and LINE-002 were already registered → no new warranty is created; their existing IDs 12345 and 12346 are returned.
• LINE-003 is new → a new warranty is created and its new ID 12347 is returned.
• Because one new line item was created, the SMS / e-mail notification is sent once for this request.

If the same request is sent once more, all three line items are already registered: the response returns the IDs 12345, 12346 and 12347 with HTTP 200 (the order of the entries is not guaranteed), and no new warranty or notification is created.