EditCartContent request

Using the "EditCartContent" request, the content of an order can be adjusted (before or after the activation of the debt). Using this call, articles can be removed, fees reduced or increased.

Adding articles or increasing fees has to follow certain predefined rules:

  • If the new cart value is lower than the old one, the edit will always succeed.
  • If the new cart value is higher than the old one, BillPay will perform another risk check for the customer with the new value. If this check is successful, the edit will succeed. If the result is negative, the cart value will not be increased.

The request itself cotains the information for the new desired cart. All differences between old and new cart will then be added/removed.

*Attention: This request can not change the following values: unique order reference, billing address of the customer, currency, payment method.

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

Attribute Typ Mögliche Werte Details
version String - Version number of the API
<data api_version="1.5.11">
    <!-- Request Daten -->
</data>

Default Params Node (Merchant Credentials)

Attribute Type Details
mid Int Merchant Id
pid Int Portal Id
bpsecure String MD5 hash of the API security key (delivered by BillPay)
    <default_params 
        mid="4441" 
        pid="6021" 
        bpsecure="25d55ad283aa400af464c76d713c07ad"/>

Total Node

The total node contains all generic information about the order and all relevant fees or rebates.

Attribute Mandatory? Type Possible values Details
shippingname + String AN..50 Shipping method name (e.g. "Express")
shippingprice + Int N..7 net value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross + Int N..7 gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
rebate + Int N..7 positive net value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
rebategross + Int N..7 positive gross value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
carttotalprice + Int N..7 net value of the order total (1,00 EUR = 100)
carttotalpricegross + Int N..7 gross value of the order total (1,00 EUR = 100)
currency + String Vorgabe ISO4217 3-digit currency code of the order (e.g. "EUR")
reference +* String AN..40 Unique order ID in the merchant system (allowed characters: 0-9, a-z, A-Z,.,-,_,/)

*Attention: The order reference needs to match the reference used in the preauthorization request!

    <total 
      shippingname="Express Versand" 
      shippingprice="840" 
      shippingpricegross="1000" 
      rebate="1681" 
      rebategross="2000" 
      carttotalprice="26050" 
      carttotalpricegross="31000" 
      currency="EUR" 
      reference="976692924" />

Article Data Node (List of all ordered articles)

All information concerning the pruchased products are collected in the article_data node. Every unique article is represented by an individual XML tag.

Attribute Mandatory? Type Possible Values Details
articleid + String AN..20 Unique article ID
articlequantity + Int N..7 Article quantity
articlename + String AN..50 Article name
articleprice + Int N..7 Article net price (smallest currency unit; 1,00 EUR = 100)
articlepricegross + Int N..7 Article gross price (smallest currency unit; 1,00 EUR = 100)

*Important: Article IDs have to be unique for each article.

Notice: The data provided in the editCartContent request is checked for consistency. The total sum has to match the sum of all articles and fees included in the request.

    <article_data>
         <article 
            articleid="1234" 
            articlequantity="1" 
            articlename="Shirt" 
            articleprice="10084" 
            articlepricegross="12000" />
        <article 
            articleid="2345" 
            articlequantity="1" 
            articlename="Hose" 
            articleprice="16807" 
            articlepricegross="20000" />
    </article_data>

Special Feature: Editing of partially shipped orders

In addition to the information described above, an "invoice_list" has to be added when editing partially shipped orders. This list references each individual partial invoice via the "invoice_number" parameter. In each invoice node the details of the partial shipment are described in an "invoice_params" node. Here, total amount of the invoice, shipping costs and any kind of rebates are summed up. It also contains the usual "article_data" node to highlight what articles were shipped in that particular invoice. (see examples below)

Attribut Pflicht Typ Mögliche Werte Details
invoice_number + String AN Shop-side invoice number for the partial shipment
shippingprice + Int N..7 net value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross + Int N..7 gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
rebate + Int N..7 positive net value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
rebategross + Int N..7 positive gross value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
carttotalprice + Int N..7 net value of the order total (1,00 EUR = 100)
carttotalpricegross + Int N..7 gross value of the order total (1,00 EUR = 100)
articleid + String AN..20 Unique article ID
articlequantity + Int N..7 Article quantity
articlename + String AN..50 Article name
articleprice + Int N..7 Article net price (smallest currency unit; 1,00 EUR = 100)
articlepricegross + Int N..7 Article gross price (smallest currency unit; 1,00 EUR = 100)

Full XML example (no partial shipments)

2 units of article "article001" were returned. The "articlequantity" was reduced and the "carttotalprice" and "carttotalpricegross" values were adjusted accordingly.

<?xml version="1.0" encoding="UTF-8"?>
<data api_version="1.5.11">
   <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
   <total shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="26050" carttotalpricegross="31000" currency="EUR" reference="976692924" />
   <article_data>
      <article articleid="1234" articlequantity="1" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
      <article articleid="2345" articlequantity="1" articlename="Hose" articleprice="16807" articlepricegross="20000" />
   </article_data>
</data>   

Full XML example (including a partial shipment)

The first partial shipment (onl "article001") was delivered already. 2 units of this article were returned so the "articlequantity" in the main order "article_data" as well as in the "invoice_list" were reduced and the "carttotalprice" / "carttotalpricegross" was adjusted accordingly in the main and suborder.

<?xml version="1.0" encoding="UTF-8"?>
<data api_version="1.5.11">
   <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
   <total shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="26050" carttotalpricegross="31000" currency="EUR" reference="976692924" />
  <article_data>
    <article articleid="1234" articlequantity="1" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
    <article articleid="2345" articlequantity="1" articlename="Hose" articleprice="16807" articlepricegross="20000" />
  </article_data>
  <invoice_list>
    <invoice invoice_number="INV551202291" >
      <invoice_params rebate="1681" rebategross="2000" shippingprice="840" shippingpricegross="1000" carttotalprice="9243" carttotalpricegross="11000" />
      <article_data>
        <article articleid="1234" articlequantity="1" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
      </article_data>
    </invoice>
    <invoice invoice_number="INV1046242416" >
      <invoice_params rebate="0" rebategross="0" shippingprice="0" shippingpricegross="0" carttotalprice="16807" carttotalpricegross="20000" />
      <article_data>
        <article articleid="2345" articlequantity="1" articlename="Hose" articleprice="16807" articlepricegross="20000" />
      </article_data>
    </invoice>
  </invoice_list>
</data>   

EditCartContent Response

The server response to the EditCartContent request delivers an error code (0=success) as well as a message should the request fail.

<?xml version="1.0" encoding="UTF-8"?>
<data api_version="1.5.11" customer_message="" merchant_message="" error_code="0">
</data>