Link Search Menu Expand Document

Using ARTS POSLog to add a basket

Contents

Overview

This endpoint allows API clients to POST a basket to Spaaza by uploading a transaction XML file in the NRF’s ARTS POSLog format.

Note that it is only possible to upload a single transaction per XML file.

Note also that the ARTS POSLog endpoint follows very similar logic to the add-basket API endpoint.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version Change details
>= 1.5.2 The endpoint now returns a user_not_found warning if a user identifier is passed, but the user is not found
>= 1.5.1 Endpoint allows item price rounding to 4 decimal places instead of the previous 2, same rounding shown in response fields
>= 1.5.0 Initial version

Permissions and Authentication

This API call requires a valid Spaaza session. The session can be as follows:

  • Admin authentication: the performing user needs to be logged in and have write access for the chain on behalf of which the call is being made.

Constructing Baskets

The endpoint accepts XML files in the ARTS POSLog format. The XML is parsed, and various parts are used to create a basket.

Sample XML Request

There follows a sample ARTS POSLog XML file containing the elements and attributed required by the Spaaza endpoint. Other elements and attributes may be included in the XML file, but are not required for successful processing.

<?xml version="1.0" encoding="utf-8"?>
<POSLog xmlns="http://www.nrf-arts.org/IXRetail/namespace/" xmlns:VRArtsPoslogExt="http://schemas.vismaretail.com/poslog/">
    <Transaction>
        <BusinessUnit>
            <UnitID>10001</UnitID>
        </BusinessUnit>
        <TransactionID>2311070000000118065001042000</TransactionID>
        <OperatorID OperatorType="Cashier" OperatorName="John Doe Cashier">1</OperatorID>
        <CurrencyCode>SEK</CurrencyCode>
        <RetailTransaction TransactionStatus="Finished">
            <LineItem>
                <Sale>
                    <POSIdentity POSIDType="GTIN">
                        <POSItemID>6417469261017</POSItemID>
                    </POSIdentity>
                    <POSIdentity POSIDType="RSID">
                        <POSItemID>2000500500008</POSItemID>
                    </POSIdentity>
                    <MerchandiseHierarchy Level="Group">6498</MerchandiseHierarchy>
                    <Description>COFFEEGRANDE</Description>
                    <UnitCostPrice>18.00000</UnitCostPrice>
                    <SuggestedPrice>20.00000</SuggestedPrice>
                    <ExtendedAmount>0.00000</ExtendedAmount>
                    <Quantity Units="1.00" UnitOfMeasureCode="EA">1.00000</Quantity>
                    <RetailPriceModifier MethodCode="Promotion">
                        <Amount Action="Subtract">20.00000</Amount>
                        <Description>FREE_COKE_130903</Description>
                    </RetailPriceModifier>
                </Sale>
                <SequenceNumber>1</SequenceNumber>
            </LineItem>
            <LineItem>
                <Coupon CouponType="ElectronicCoupon">
                    <ScanCode>ABEANZ_100</ScanCode>
                </Coupon>
                <SequenceNumber>2</SequenceNumber>
            </LineItem>
            <LineItem CancelFlag="false">
                <Discount>
                    <Amount Action="Subtract">20.00000</Amount>
                    <Percent Action="Subtract">9.09</Percent>
                    <Description>FREE_COKE_130903</Description>
                </Discount>
                <SequenceNumber>2</SequenceNumber>
            </LineItem>
            <LineItem>
                <Tender TypeCode="Sale" TenderType="Cash">
                    <Amount>200.00000</Amount>
                </Tender>
                <SequenceNumber>3</SequenceNumber>
            </LineItem>
            <LineItem>
                <Tax>
                    <TaxableAmount>178.57000</TaxableAmount>
                    <Amount>21.43000</Amount>
                    <Percent>12.00</Percent>
                </Tax>
                <SequenceNumber>4</SequenceNumber>
            </LineItem>
            <Total CurrencyCode="SEK" TotalType="TransactionNetAmount">200.00000</Total>
            <Total TotalType="VRExt:TransactionVatRateAmount" VRArtsPoslogExt:VATRate="12.00" VRArtsPoslogExt:VATExclAmount="178.57000" VRArtsPoslogExt:VATAmount="21.43000">200.00000</Total>
            <Customer>
                <CustomerID>2000057</CustomerID>
                <CustomerName>
                    <Name>Jane Doe</Name>
                </CustomerName>
            </Customer>
        </RetailTransaction>
        <EndDateTime>2023-11-07T05:01:09</EndDateTime>
        <VRArtsPoslogExt:UniqueReceiptNumber>000000010001004043417</VRArtsPoslogExt:UniqueReceiptNumber>
    </Transaction>
</POSLog>

Required XML Elements and Attributes

Top-Level Elements

The following top-level elements and attributes are required:

  • <POSLog>: (object, required) The root element of the ARTS POSLog XML file.
  • <Transaction>: (object, required) The root element of the transaction. The Spaaza ARTS POSLog endpoint only supports a single transaction per XML file.

Please ensure that these elements and attributes are correctly included in the XML file for proper parsing and basket creation.

All elements described within the rest of this document are contained within the <POSLog> => <Transaction> elements.

Identifying the Retailer Details

The overall retailer details are contained in the following request header and NOT within the XML document:

Header Name Header Value & Description
X-Spaaza-Session-Chain-ID (integer, required) The Spaaza Chain ID of the retailer.

Further retailer details of the retailer are described as follows:

Branch and Employee Details

The branch and employee details are described in the following XML elements and their attributes:

Element Name Element Value & Description Attribute Name Attribute Description
<BusinessUnit> => <UnitID> (integer, optional) A retailer-specific branch code used by the retailer to identify individual branches in a chain. If this value is not supplied, nor is a valid branch_business_id supplied, or if this value is supplied and there is no branch found with a matching branch_business_owner_code, then the basket is recorded as a basket for the chain with no branch associated with it and a warning is returned.    
<BusinessUnit> => <OperatorID> (string, optional) A number or string used to identify a retailer employee associated with the transaction. Commonly this may be a store assistant or other member of staff. If no employee is associated with the transaction this value should not be included.    
    <OperatorName> (string, optional) The name of a retailer employee associated with the transaction. This information is commonly used on electronic receipts and in analytics. If no employee is associated with the sale this attribute should not be included.

Describing the Overall Basket Contents

The following XML elements and attributes describe top-level basket/transaction properties:

Element Name Element Value & Description Attribute Name Attribute Description
<TransactionID> (string, can be numeric, mandatory) An identifier in the retailer’s system used to identify a particular user basket. This is stored by Spaaza and can be used to identify individual baskets at a later time, such as during any returns or refund process which may be in place. Please note that if a chain opts to be strict about repeating transaction IDs, when an add-basket call is made using a <TransactionID> value which already exists in the Spaaza system, this will return a warning with Status Code 311 (basket_already_exists) and will return the previous existing basket.    
<EndDateTime> (timestamp, optional) The timestamp of the basket. The timezone is assumed to be in UTC. If this element is not supplied, the timestamp of receipt will be used.    

Currency used for the basket (basket_currency)

The following XML elements and attributes describe the currency of the basket:

Element Name Element Value & Description Attribute Name Attribute Description
<CurrencyCode> (string, optional) The ISO-4217 three letter code of the currency used in the basket calculations. If the currency_id field is not supplied this field can be used exclusively.    

Individual <RetailTransaction> elements

The following XML elements and attributes describe individual <LineItem> elements inside the <RetailTransaction> element in the ARTS POSLog document:

Element Name Element Value & Description Attribute Name Attribute Description
<Sale> (object, optional) This <LineItem> element describes a single sale item in the basket. See the section Line Item of Type <Sale> below. The <Sale> element can be repeated multiple times to describe multiple items in the basket.    
<Coupon> (object, optional) This <LineItem> element describes a single voucher redeemed in the basket. See the Basket Discounts and Vouchers section below. The <Coupon> element can be repeated multiple times to describe multiple items in the basket.    
<Discount> (object, optional) This <LineItem> element describes a single discount item in the basket. See the 3rd-Party Promotions section below. The <Discount> element can be repeated multiple times to describe multiple items in the basket.    
<Tender> (object, optional) This <LineItem> element describes a single payment method tender item in the basket. See the Payment Methods section below. The <Tender> element can be repeated multiple times to describe multiple items in the basket.    
    <TenderType> (string, mandatory for <Tender> line item) The type of tender used to pay for the basket. This is free-form, but is normally a value similar to the following: Cash, Creditcard, Debit
<Tax> (object, optional) This <LineItem> element describes a single tax item in the basket. See the Basket Tax Structure section below. The <Tax> element can be repeated multiple times to describe multiple items in the basket.    
<Total> (object, optional) This <LineItem> element describes a single total item in the basket. See the Basket Total Amount section below. The <Total> element can be repeated multiple times to describe multiple items in the basket.    
<Customer> (object, optional) This <LineItem> element describes a single customer item in the basket. See the Customer Information section below. The <Customer> element can be repeated multiple times to describe multiple items in the basket.    
<SequenceNumber> (integer, optional) A retailer-specific sequence number of the line item.    

Line Item of Type <Sale> - Basket Item

The <Sale> line item is used to describe sale items in the basket. The <Sale> line item contains the following XML elements and their attributes:

Element Name Element Value & Description Attribute Name Attribute Description
POSIdentity A sale item identifier in the POS    
    <POSIDType> (string, optional) The type of identifier used to identify the sale item in the POS. This can be one of the following values: GTIN, RSID. Spaaza uses the element with the GTIN attribute, if present, as the barcode of the sale item. It the GTIN attribute is not present, spaaza will use the RSID attribute if it is present.
<POSIdentity> => <POSItemID> The value of the sale item identifier in the POS    
<MerchandiseHierarchy> (string, optional) The product or SKU identifier used by the retailer to identify the basket item. The <MerchandiseHierarchy> value must already be included in the Spaaza system if the product is to be recognised. <Level> (string, optional) The level of the merchandise hierarchy code. This can be one of the following values: Group.
    <Level> (string, optional) The level of the merchandise hierarchy code. This can be one of the following values: Group.
<Description> (string, optional) The name or description of the sale item.    
<UnitCostPrice> (float, optional) The single-unit cost price of the sale item.    
<SuggestedPrice> (float, optional) The original gross price being charged for 1 quantity unit of an item. Note that this does not change if the quantity is increased. Note also that if vouchers are being redeemed, this value is not reduced.    
<ExtendedAmount> (float, mandatory) The price being charged for 1 quantity unit of an item net of any Spaaza vouchers being redeemed on it. Note that this does not change if the quantity is increased or decreased. Please see also the <SuggestedPrice> element.    
<Quantity> (float, optional, default 1) The quantity of an item. If this is not supplied the quantity is assumed to be 1.    

Line Item of Type <Coupon> - Basket Discounts and Vouchers (basket_vouchers)

[To be completed]

Line Item of Type <Discount> - 3rd-Party Promotions {#3rd-party-promotions}

[To be completed]

Line Item of Type <Tender> - Payment Methods

The <Tender> line item is used to describe a method used to pay for the basket.

Note that Spaaza will only observe the <Tender> element if its TenderType attribute is set.

Note that Spaaza records the payment methods used to pay for a basket, but no logic is applied to them and they are independent of other amounts in the basket.

The <Tender> line item contains the following XML elements and their attributes:

Element Name Element Value & Description Attribute Name Attribute Description
<Amount> (mandatory, float) The amount of the payment paid with this method.    

If an error is detected in the payment methods POSTed a warning will be returned inline in the XML response, but the basket will still be processed and no payment method saved.

Line Item of Type <Tax> - Basket Tax Structure

Multiple tax rates can be applied to a basket. This section shows the total amount present for each tax rate.

Note that Spaaza records the tax rates applied to a basket, but no logic is applied to them and they are independent of other amounts in the basket.

Element Name Element Value & Description Attribute Name Attribute Description
<Amount> (mandatory, float) The total currency amount of tax paid at a particular rate.    
<Percent> (mandatory, float) A percentage rate at which tax is charged on this basket.    

Line Item of Type <Total> - Basket Total Amount

The total currency/tender price paid by a customer is described in a <Total> element with attribute <TotalType> set to “TransactionNetAmount”. <Total> elements with <TotalType> attributes set to other values are ignored.

Element Name Element Value & Description Attribute Name Attribute Description
<Total> (optional, float) The total price of the basket sale/transaction to be paid by the shopper in currency. This value is used to record the total gross revenue to the retailer for the items purchased in this basket, a value which is also used to calculate effects on member programmes such as loyalty schemes. If the total price of <Sale> line items in the basket does not add up to the <Total> value, the <Total> value value is used for these calculations. If this field is not populated, a value of 0 is recorded rather than returning an error.    
    <TotalType> (mandatory, string) The type of <Total>. The only value accepted by Spaaza is “TransactionNetAmount” - all other values will be ignored.

Line Item of Type <Customer> - Customer Information

The customer information is described in the following XML elements and their attributes:

Element Name Element Value & Description Attribute Name Attribute Description
<Customer> => <CustomerID> (string, optional) The membership number or code for the shopper. If an unrecognised code or no code is given, the shopper is presumed to be anonymous.    

Note if it is not possible to identify the shopper based on the fields supplied, the basket is considered to be an “anonymous” basket (see below) and a warning will be returned in the response.

Transactions with no customer information (anonymous transactions)

It is possible to upload a transaction without specifying a shopper’s member number. In that case, pass in null as the parameter to user, instead of the user object, or do not include the <Customer> object in the XML.

Interpreting the response

The endpoint uses the ARTSUtil class to convert the XML object into an associative array, which then matches the JSON format used by the add-basket API endpoint.

Sample XML Response 

<?xml version="1.0"?>
<root>
    <result>
        <code>1</code>
        <status>ok</status>
    </result>
    <results>
        <basket>
            <basket_country_code>NL</basket_country_code>
            <basket_items>
                <item_0>
                    <excluded_from_spaaza/>
                    <inventory_owner_code/>
                    <is_identified>1</is_identified>
                    <item_barcode>469261017</item_barcode>
                    <item_is_promotional/>
                    <item_original_price>20</item_original_price>
                    <item_price>0</item_price>
                    <item_quantity>1</item_quantity>
                    <item_quantity_unit>item</item_quantity_unit>
                    <item_subtotal>0</item_subtotal>
                    <product>
                        <brand/>
                        <category/>
                        <created_date>2023-12-07 12:59:20</created_date>
                        <description/>
                        <id>291934</id>
                        <image_url/>
                        <last_modified_date>2023-12-07 12:59:20</last_modified_date>
                        <name>COFFEEGRANDE</name>
                        <owner_code>6498</owner_code>
                        <price>20</price>
                        <product_variant>
                            <barcode>
                                <item_0>
                                    <barcode>469261017</barcode>
                                    <deleted/>
                                    <id>3708887</id>
                                </item_0>
                            </barcode>
                            <colour/>
                            <condition>new</condition>
                            <cost_price>18</cost_price>
                            <created_date>2023-12-07 12:59:20</created_date>
                            <id>3100542</id>
                            <image_url/>
                            <last_modified_date>2023-12-07 12:59:20</last_modified_date>
                            <price>20</price>
                            <size/>
                            <web_url/>
                        </product_variant>
                        <season/>
                        <webshop_url/>
                    </product>
                    <retailer_item_code>1</retailer_item_code>
                    <spaaza_product_variant_id>3100542</spaaza_product_variant_id>
                </item_0>
                <item_1>
                    <excluded_from_spaaza/>
                    <inventory_owner_code/>
                    <is_identified>1</is_identified>
                    <item_barcode>2000500500008</item_barcode>
                    <item_is_promotional/>
                    <item_original_price>200</item_original_price>
                    <item_price>200</item_price>
                    <item_quantity>1</item_quantity>
                    <item_quantity_unit>item</item_quantity_unit>
                    <item_subtotal>200</item_subtotal>
                    <product>
                        <brand/>
                        <category/>
                        <created_date>2023-12-07 12:59:20</created_date>
                        <description/>
                        <id>291935</id>
                        <image_url/>
                        <last_modified_date>2023-12-07 12:59:20</last_modified_date>
                        <name>KT SKINKA</name>
                        <owner_code>3182</owner_code>
                        <price>200</price>
                        <product_variant>
                            <barcode>
                                <item_0>
                                    <barcode>2000500500008</barcode>
                                    <deleted/>
                                    <id>3708888</id>
                                </item_0>
                            </barcode>
                            <colour/>
                            <condition>new</condition>
                            <cost_price>20</cost_price>
                            <created_date>2023-12-07 12:59:20</created_date>
                            <id>3100543</id>
                            <image_url/>
                            <last_modified_date>2023-12-07 12:59:20</last_modified_date>
                            <price>200</price>
                            <size/>
                            <web_url/>
                        </product_variant>
                        <season/>
                        <webshop_url/>
                    </product>
                    <retailer_item_code>7</retailer_item_code>
                    <spaaza_product_variant_id>3100543</spaaza_product_variant_id>
                </item_1>
            </basket_items>
            <basket_platform_type>in_store</basket_platform_type>
            <basket_tax>
                <item_0>
                    <id>28391</id>
                    <tax_rate>0.12</tax_rate>
                    <tax_total>21.43</tax_total>
                </item_0>
            </basket_tax>
            <basket_timestamp_iso8601>2023-11-07T05:01:09+00:00</basket_timestamp_iso8601>
            <basket_timezone_name>+00:00</basket_timezone_name>
            <basket_total_price>200</basket_total_price>
            <basket_vouchers_applied/>
            <chain_id>1795</chain_id>
            <currency_id>3</currency_id>
            <employee>
                <employee_code>1</employee_code>
                <employee_name>John Doe Cashier</employee_name>
            </employee>
            <honour_vouchers_applied/>
            <id>554436</id>
            <payment_methods>
                <item_0>
                    <id>64876</id>
                    <payment_amount>200</payment_amount>
                    <payment_method>Cash</payment_method>
                </item_0>
            </payment_methods>
            <purchase_progress>
                <item_0>
                    <balance_new>10</balance_new>
                    <balance_previous>10</balance_previous>
                    <campaign_id>2355</campaign_id>
                    <campaign_type>points_wallet</campaign_type>
                    <is_default/>
                    <mutations/>
                    <title>Entries Wallet</title>
                </item_0>
                <item_1>
                    <balance_new>2</balance_new>
                    <balance_previous>2</balance_previous>
                    <campaign_id>2313</campaign_id>
                    <campaign_type>points_wallet</campaign_type>
                    <is_default>1</is_default>
                    <mutations/>
                    <title>Tree Wallet</title>
                </item_1>
                <item_2>
                    <balance_new>15</balance_new>
                    <balance_previous>15</balance_previous>
                    <campaign_id>2314</campaign_id>
                    <campaign_type>wallet</campaign_type>
                    <is_default>1</is_default>
                    <mutations/>
                    <title>ACME Wallet</title>
                </item_2>
            </purchase_progress>
            <regenerated_rewards/>
            <retailer_basket_code>2311070000000118065001042000-a132</retailer_basket_code>
            <return_transactions/>
            <supplementary_basket_codes/>
            <vouchers_created/>
        </basket>
        <user>
            <authentication_point_identifier/>
            <member_number>2000057</member_number>
            <member_programme>spaaza</member_programme>
            <spaaza_user_id>3928713</spaaza_user_id>
        </user>
        <result_type>POSLog</result_type>
    </results>
</root>

Error Handling

The endpoint includes error handling to manage potential issues during the XML parsing and basket creation process.