Skip to content

Discounted Basket Transfer ​

A discounted basket is sent to the same service as Cash Basket Transfer (POST /basket). The difference is that allowances (discount) information is added to the product lines, and the totalAllowance and paidAmount fields are added to the basket summary. CASH, CREDITCARD, GIFT or OPEN_ACCOUNT can be used as the payment type.

POINTS TO CONSIDER IN THE CALCULATION

1. All amounts are sent VAT inclusive.

FieldMeaning
items[].product.price.grossPriceUndiscounted, VAT-inclusive unit price of the product
items[].allowances[].priceVAT-inclusive discount amount applied to the whole line (quantity × unit price). It is not per unit.
price.grossPriceUndiscounted, VAT-inclusive basket total
price.totalAllowanceSum of the discount amounts sent on the lines (VAT inclusive)
price.paidAmountAmount to be collected: grossPrice − totalAllowance

2. totalAllowance must always be sent. Even if the lines contain allowances, if totalAllowance is not sent or is sent as 0, the discounts are ignored and the basket is created with the undiscounted amount.

3. totalAllowance must exactly match the sum of the line discounts, to the kuruş. Otherwise the 2081 - Discount amount is wrong error is returned.

4. Distribute the subtotal discount to the products over the VAT-inclusive amount. For example, if a 40.00 TL discount is applied to the subtotal, distribute this amount in proportion to the VAT-inclusive line amounts, round each line to 2 decimals and add the remaining kuruş to the last line. The discounts on the lines must add up to exactly 40.00.

Do not split the VAT-exclusive (tax base) amount across the lines and then add VAT to each line and round it. The rounding on each line may push the total 1 kuruş up or down.

5. A 1 kuruş difference is normal. On discounted lines, Ödeal rounds the tax base and VAT to 2 decimals per line; the basket and invoice totals are made up of the line totals (GİB document arithmetic). Therefore a difference of at most 1 kuruş may occur between your grossPrice − totalAllowance calculation and the total calculated by Ödeal, and this difference is accepted. If the difference exceeds 1 kuruş, the 2044 - Invalid sale price or 2092 - Calculations in the basket summary are wrong error is returned.

6. It is normal for the receipt and the invoice to show different discount figures. The information receipt shows the VAT-inclusive discount total (totalAllowance), while the invoice shows the VAT-exclusive discount amount (deducted from the tax base).

Fields ​

The discount is sent with the allowances array under items[]:

FieldTypeDescription
pricedecimalFor an amount-based discount, the VAT-inclusive discount amount applied to the whole line
ratedecimalFor a rate-based discount, the percentage value (e.g. 10 = 10%)
isRateBasedbooleanRequired. false for an amount-based discount, true for a rate-based discount
subTypestringLINE: line (product) discount, SUB: the line's share of the subtotal discount
orderintegerOrder of application when a line has more than one discount

ORDER OF APPLICATION

If a line has more than one discount, LINE discounts are applied first, followed by SUB discounts. Discounts of the same type are applied in the order of their order value.

RESTRICTIONS

  • The basket total after the discount cannot be less than 1 TL (2304).
  • No discount is applied to current account and advance information receipts, since no products are sent in them.

Example Scenario ​

The basket contains three products and a VAT-inclusive 40.00 TL discount will be applied to the subtotal:

ProductQtyVAT-incl. unitVATLine amountShareLine discount
Gözleme2120.0010%240.00240 / 40523.70
Ayran335.0010%105.00105 / 40510.37
Cola160.0020%60.0060 / 4055.93
Total405.0040.00

After rounding the line discounts to 2 decimals, their total is exactly 40.00, so no kuruş adjustment was needed. Had the total differed from 40.00, the difference would have been added to the last line.

Request ​

POST https://api.sandbox.odeal.com/integration/api/v1/basket

Headers: X-ODEAL-MERCHANT-KEY, X-ODEAL-SECRET-KEY, Content-Type: application/json

json
{
  "referenceCode": "ISK-20261023-0001",
  "externalDeviceKey": "KASA-01",
  "customer": {
    "type": "INDIVIDUAL",
    "name": "Ayşe",
    "surname": "Yılmaz",
    "identityNumber": "10000000146",
    "gsmNumber": "5321234567",
    "email": "[email protected]",
    "city": "İstanbul",
    "town": "Kadıköy",
    "address": "Caferağa Mah. Örnek Sok. No:1"
  },
  "price": {
    "grossPrice": 405.00,
    "totalAllowance": 40.00,
    "paidAmount": 365.00
  },
  "items": [
    {
      "quantity": 2,
      "product": {
        "referenceCode": "GZL-01",
        "name": "Gözleme",
        "unitCode": "C62",
        "price": { "grossPrice": 120.00, "vatRatio": 10, "sctRatio": 0 }
      },
      "allowances": [
        { "price": 23.70, "isRateBased": false, "subType": "SUB", "order": 1 }
      ]
    },
    {
      "quantity": 3,
      "product": {
        "referenceCode": "AYR-01",
        "name": "Ayran",
        "unitCode": "C62",
        "price": { "grossPrice": 35.00, "vatRatio": 10, "sctRatio": 0 }
      },
      "allowances": [
        { "price": 10.37, "isRateBased": false, "subType": "SUB", "order": 1 }
      ]
    },
    {
      "quantity": 1,
      "product": {
        "referenceCode": "KLA-01",
        "name": "Cola",
        "unitCode": "C62",
        "price": { "grossPrice": 60.00, "vatRatio": 20, "sctRatio": 0 }
      },
      "allowances": [
        { "price": 5.93, "isRateBased": false, "subType": "SUB", "order": 1 }
      ]
    }
  ],
  "paymentOptions": [
    { "type": "CASH", "amount": 365.00 }
  ]
}

Result Calculated by Ödeal ​

ProductLine amountDiscount (VAT incl.)Tax baseVATPayable
Gözleme240.0023.70196.6419.66216.30
Ayran105.0010.3786.038.6094.63
Cola60.005.9345.069.0154.07
Total405.0040.00327.7337.27365.00

Why Does a 1 Kuruş Difference Occur? ​

In the example below, three products with a VAT-inclusive unit price of 30.204 TL (25.17 TL excluding VAT, 20% VAT) are sold, two of each. The subtotal is 181.22 TL and a VAT-exclusive 10.00 TL (12.00 TL VAT inclusive) discount is to be applied to the subtotal.

Line discounts senttotalAllowanceDiscount on invoice (VAT excl.)Grand total
4.00 / 4.00 / 4.0012.003.33 + 3.33 + 3.33 = 9.99169.23
4.00 / 4.00 / 4.0112.013.33 + 3.33 + 3.34 = 10.00169.22

In the first row, when 12.00 TL is split equally across three lines, each line's tax base discount of 3.333 is rounded to 3.33; the invoice shows a 9.99 discount and a 169.23 total. In the second row, the kuruş difference is given to the last line, so the invoice discount is exactly 10.00 and the grand total is 169.22.

RECOMMENDATION

If you want the discount amount on the invoice to exactly match your target value, distribute the target amount to the lines with 2 decimals and give the kuruş difference to a single line. Calculate each line's VAT-inclusive equivalent from this amount, round it and send it. In this case the VAT-inclusive discount total shown on the receipt (12.01 in the example above) may differ at the kuruş level; this is not an error.

Error Codes ​

CodeMessagePossible cause
2044Invalid sale priceThe difference between grossPrice − totalAllowance and the total calculated by Ödeal is more than 1 kuruş
2049Discount amount cannot be greater than the gross priceA line discount is greater than the line amount
2080Discount is wrongThe product's grossPrice does not match the line calculation
2081Discount amount is wrongtotalAllowance is not equal to the sum of the line discounts
2088isRateBased must be sentThe allowances[].isRateBased field is missing
2089Discount amount must be sentprice is missing in an amount-based discount
2090Discount rate must be sentrate is missing in a rate-based discount
2092Calculations in the basket summary are wrongThe difference between paidAmount and the total calculated by Ödeal is more than 1 kuruş
2304Basket amount cannot be below 1 TLThe total after the discount is below 1 TL

Ödeal A.Ş.