Cash Register Integration
The store application shows the following page at the end of the Instore app provided by Akinon.
After this step, the payment transactions must be made on cash register;
- The store employee scans the barcode via the checkout or manually enters the order number. Meanwhile, “Cash Register” in the background fetches the order using the service provided by Akinon.
- Payment transactions are completed.
- Once the payment transactions are completed, the order is confirmed by sending a request to the order confirmation service provided by Akinon.
- When the order is confirmed, it will be transferred to the client’s ERP system via Omnitron.
Reading Orders
Request POST
URL The data needs to be sent via POST as JSON with the format shown below to the URL address provided by Akinon (brand storefront url/hooks/cash_register/pre_order/).
{
"username": "username",
"password": "password",
"order_number": "816910908011148"
}
Response
The amount of payment for the order is shown in the pre_order.unpaid_amount field. Shipping fee is included within the pre_order.shipping_amount field, not in a separate line.
The information within pre_order.basket.basket_itemset includes product information, and the Attributes field includes additional information about the product.
Within Akinon systems, SKU represents a unique product.
Note: Discounts must be displayed at the end of the receipt and not on a per-product basis. They can be seen in the
pre_order.basket.discountsfield .
{
"order_number": "816910908011148",
"pre_order": {
"basket": {
"basketitem_set": [
{
"quantity": 1,
"unit_price": "269.00",
"tax_rate": "8.00",
"currency_type": "try",
"product": [
{
"pk": 30387,
"name": "WOMEN SNEAKER",
"sku": "5637936095",
"base_code": "18WFD1728SM",
"attributes": {
"integration_config": "PASS",
"integration_inner_liner": "LEATHER",
"erp_color": "5637145463",
"integration_size": "5637145330",
"filterable_color_1": "GREY",
"erp_size": "5637145330",
"filterable_size_1": "37",
"integration_heel_height": "3,5 CM",
"integration_color": "5637145463",
"integration_material": "GLITTER",
"erp_barcode": "5471700510253",
"integration_with_leather": "UNDEFINED",
"erp_inner_liner": "LEATHER",
"integration_gender": "Female",
"erp_config": "PASS",
"erp_collection": "WINTER",
"integration_material_type": "LEATHER",
"erp_bottom_property": "TPU",
"erp_material_type": "LEATHER",
"erp_with_leather": "UNDEFINED",
"erp_country": "TURKEY",
"erp_supplier": "CEYLAN",
"erp_gender": "Female",
"badge": "new",
"integration_supplier": "CEYLAN",
"integration_collection": "WINTER",
"integration_country": "TURKEY",
"integration_product_form": "FLAT",
"erp_heel_height": "3,5 CM",
"erp_category": "SPORT",
"erp_sub_group": "SHOE",
"integration_category": "SPORT",
"integration_barcode": "5471700510253",
"erp_product_form": "FLAT",
"integration_sub_group": "SHOE",
"integration_mostra": "LEATHER",
"erp_material": "GLITTER",
"integration_bottom_property": "TPU",
"erp_mostra": "LEATHER"
},
"attribute_set": 1,
"attributes_kwargs": {
"integration_config": {
"value": "PASS",
"data_type": "dropdown",
"label": "PASS"
},
"integration_ic_astar": {
"value": "LEATHER",
"data_type": "dropdown",
"label": "LEATHER"
},
"erp_color": {
"value": "5637145463",
"data_type": "dropdown",
"label": "FUME"
},
"integration_size": {
"value": "5637145330",
"data_type": "dropdown",
"label": "37"
},
"filterable_color_1": {
"value": "GREY",
"data_type": "dropdown",
"label": "GREY"
},
"erp_size": {
"value": "5637145330",
"data_type": "dropdown",
"label": "37"
},
"filterable_size_1": {
"value": "37",
"data_type": "dropdown",
"label": "37"
},
"integration_heel_height": {
"value": "3,5 CM",
"data_type": "dropdown",
"label": "3,5 CM"
},
"integration_color": {
"value": "5637145463",
"data_type": "dropdown",
"label": "FUME"
},
"integration_material": {
"value": "GLITTER",
"data_type": "dropdown",
"label": "GLITTER"
},
"integration_with_leather": {
"value": "UNDEFINED",
"data_type": "dropdown",
"label": "UNDEFINED"
},
"erp_inner_liner": {
"value": "LEATHER",
"data_type": "dropdown",
"label": "LEATHER"
},
"integration_gender": {
"value": "Female",
"data_type": "dropdown",
"label": "Female"
},
"erp_config": {
"value": "PASS",
"data_type": "dropdown",
"label": "PASS"
},
"erp_collection": {
"value": "WINTER",
"data_type": "dropdown",
"label": "WINTER"
},
"integration_material_type": {
"value": "LEATHER",
"data_type": "dropdown",
"label": "LEATHER"
},
"erp_bottom_property": {
"value": "TPU",
"data_type": "dropdown",
"label": "TPU"
},
"erp_material_type": {
"value": "LEATHER",
"data_type": "dropdown",
"label": "LEATHER"
},
"erp_with_leather": {
"value": "UNDEFINED",
"data_type": "dropdown",
"label": "UNDEFINED"
},
"erp_country": {
"value": "TURKEY",
"data_type": "dropdown",
"label": "TURKEY"
},
"erp_supplier": {
"value": "CEYLAN",
"data_type": "dropdown",
"label": "CEYLAN"
},
"erp_gender": {
"value": "Female",
"data_type": "dropdown",
"label": "Female"
},
"integration_supplier": {
"value": "CEYLAN",
"data_type": "dropdown",
"label": "CEYLAN"
},
"integration_collection": {
"value": "WINTER",
"data_type": "dropdown",
"label": "WINTER"
},
"integration_country": {
"value": "TURKEY",
"data_type": "dropdown",
"label": "TURKEY"
},
"integration_product_form": {
"value": "FLAT",
"data_type": "dropdown",
"label": "FLAT"
},
"erp_heel_height": {
"value": "3,5 CM",
"data_type": "dropdown",
"label": "3,5 CM"
},
"erp_sub_group": {
"value": "SHOE",
"data_type": "dropdown",
"label": "SHOE"
},
"erp_category": {
"value": "SPORT",
"data_type": "dropdown",
"label": "SPORT"
},
"integration_category": {
"value": "SPORT",
"data_type": "dropdown",
"label": "SPORT"
},
"integration_bottom_property": {
"value": "TPU",
"data_type": "dropdown",
"label": "TPU"
},
"integration_sub_group": {
"value": "SHOE",
"data_type": "dropdown",
"label": "SHOE"
},
"integration_mostra": {
"value": "LEATHER",
"data_type": "dropdown",
"label": "LEATHER"
},
"erp_material": {
"value": "GLITTER",
"data_type": "dropdown",
"label": "GLITTER"
},
"erp_product_form": {
"value": "FLAT",
"data_type": "dropdown",
"label": "FLAT"
},
"erp_mostra": {
"value": "LEATHER",
"data_type": "dropdown",
"label": "LEATHER"
}
},
"extra_attributes": {},
"productimage_set": [
{
"pk": 111426,
"status": "active",
"image": "https://cdn.akinon.net/products/",
"order": 1,
"specialimage_set": []
},
{
"pk": 111631,
"status": "active",
"image": "https://cdn.akinon.net/products/",
"order": 2,
"specialimage_set": []
},
{
"pk": 111804,
"status": "active",
"image": "https://cdn.akinon.net/products/",
"order": 3,
"specialimage_set": []
},
{
"pk": 111989,
"status": "active",
"image": "https://cdn.akinon.net/products/",
"order": 4,
"specialimage_set": []
},
{
"pk": 112633,
"status": "active",
"image": "https://cdn.akinon.net/products/",
"order": 9,
"specialimage_set": []
},
{
"pk": 112656,
"status": "active",
"image": "https://cdn.akinon.net/products/",
"order": 10,
"specialimage_set": []
}
],
"price": "249.99",
"in_stock": true,
"currency_type": "try",
"retail_price": "499",
"unit_type": "qty",
"absolute_url": "/product/30387/",
"productvideo_set": [],
"product_type": "0",
"stock": 4
}
],
"total_quantity": 1,
"total_amount": "269.00",
"total_discount_amount": "25.00",
"discounts": [
{
"description": "Discount 10% in Cart!",
"discount": "25.00"
},
{
"description": "Free cargo",
"discount": "0.00"
}
],
"upsell_messages": [],
"total_product_amount": "294.00",
"pk": 75448,
"created_date": "2018-09-14T08:18:20.197416Z",
"modified_date": "2018-09-14T08:18:20.197433Z"
}
],
"shipping_address": {
"pk": 127894,
"email": "john.doe@mail.com",
"phone_number": "05555555555",
"first_name": "John",
"last_name": "Doe",
"country": {
"pk": 1,
"name": "Turkey",
"code": "tr"
},
"city": {
"pk": 80,
"name": "ISTANBUL",
"country": 1
},
"line": "Yıldız Teknik Üniversitesi. Teknopark B2 Blok No: 417",
"title": "YTU",
"township": {
"pk": 950,
"name": "ESENLER",
"city": 80
},
"district": {
"pk": 17280,
"name": "ÇİFTE HAVUZLAR MAH",
"city": 80,
"township": 950
},
"postcode": "34220",
"notes": null,
"company_name": "",
"tax_office": "",
"tax_no": "",
"e_bill_taxpayer": false,
"is_corporate": false,
"primary": false
},
"billing_address": {
"pk": 127894,
"email": "john.doe@akinon.com",
"phone_number": "05555555555",
"first_name": "John",
"last_name": "Doe",
"country": {
"pk": 1,
"name": "Turkey",
"code": "tr"
},
"city": {
"pk": 80,
"name": "ISTANBUL",
"country": 1
},
"line": "Yıldız Teknik Üniversitesi. Teknopark B2 Blok No: 417",
"title": "YTU",
"township": {
"pk": 950,
"name": "ESENLER",
"city": 80
},
"district": {
"pk": 17280,
"name": "ÇİFTE HAVUZLAR MAH",
"city": 80,
"township": 950
},
"postcode": "34220",
"notes": null,
"company_name": "",
"tax_office": "",
"tax_no": "",
"e_bill_taxpayer": false,
"is_corporate": false,
"primary": false
},
"shipping_option": {
"pk": 1,
"name": "Standard Delivery",
"slug": "ups",
"logo": null,
"shipping_amount": 0
},
"billing_and_shipping_same": true,
"payment_option": {
"pk": 2,
"name": "Pay Cash",
"payment_type": "cash_register",
"payment_type_label": "Cash Register"
},
"notifications": null,
"shipping_amount": "0.00",
"total_amount": "269.00",
"unpaid_amount": "269.00",
"loyalty_money": "0.00",
"currency_type_label": "TL",
"installment": null,
"redirect_to_three_d": null,
"delivery_option": {
"pk": 1,
"slug": "default",
"name": "Home Delivery",
"delivery_option_type": "customer",
"sort_order": 0
},
"retail_store": null,
"payment_choice": null,
"phone_number": null,
"gift_box": null,
"staff_email": "john.doe@lacoste.com.tr",
"staff_id": "6570",
"store_id": "5694"
}
}
}
Completing Orders
POST Complete Cash Register Order
Path https://{storefront_url}/hooks/cash_register/complete/
To notify that a payment has been successfully completed, data needs to be sent via a POST request in JSON format. This data must adhere to the following structure and be sent to the URL provided by Akinon (brand storefront url/hooks/cash_register/complete/). The information to include consists of the order number obtained from either a scanned barcode or manual input is sent with order_number, the document number received from the cash register is sent with transaction_id, and the order amount is sent with amount.
NOTE
The value sent as amount will be compared with the order amount.
Request
{
"username": "username",
"password": "password",
"order_number": "816910908011148",
"amount": "269.00",
"transaction_id": "document_no"
}
Applying Cash Register Offers
When physical stores has campaigns, these promotions can be applied by sending offer details with the request.
The cash register should calculate the discount and send the offer details in the request.
Example Scenario 1
An example scenario where two campaigns are sent in the same request is provided below.
Campaign 1:
In the physical store, there is a campaign called "2+1 Promotion." This means that if a customer buys two products, they will get one product for free. In the event that there are only two products available in the physical store, the third product can be purchased online.
Assume that the product price is $15 each. When a customer buys three products, the cashier charges a total of $30, one of the products is provided for free, reducing the cost per product to $10. Therefore, a $5 discount is applied to the product purchased online.
- Campaign name: 2+1 Promotion
- Product price: $15
- Cashier charges $30 for 3 products, which means one of the products is free, making the cost per product $10.
Campaign 2:
In the physical store, there is a 20% discount campaign. However, since one product is not available in the store, it will be purchased online.
Assume that the product price is $50. When this product is purchased with a 20% discount applied, the cashier charges only $40 for one product. Therefore, a $10 discount is applied to the product.
- Campaign name: 20% discount
- Product price: $50
- Cashier charges $40 for 1 product with a 20% discount applied.
In this case, the cashier needs to send the following request to the API for the above-mentioned campaigns:
Request
{
"username": "username",
"password": "password",
"order_number": "816910908011148",
"amount": "65.00",
"discounted_amount": "50.00",
"transaction_id": "document_no",
"promotions": [
{
"benefit_amount": "5.00",
"description": "2+1 Promotion",
"affected_basket_items": [
1
]
},
{
"benefit_amount": "10.00",
"description": "20% discount",
"affected_basket_items": [
2
]
}
]
}
Example Scenario 2
- Campaign name: 20% discount for buying 3 products
- Product 1 price: $10
- Product 2 price: $20 (missing in physical store)
- Product 3 price: $25 (missing in physical store)
Request
{
"username": "username",
"password": "password",
"order_number": "816910908011148",
"amount": "45.00",
"discounted_amount": "36.00",
"transaction_id": "document_no",
"promotions": [
{
"benefit_amount": "9.00",
"description": "20% discount for buying 3 products",
"affected_basket_items": [
1,
2
]
}
]
}
| Field | Type | Description | Required |
|---|---|---|---|
| discounted_amount | String(decimal in 2-digit precision) | The amount of the product after applying the discount. | Yes |
| promotions | CashRegisterPromotion[] | The details of the promotion list. | Yes |
| Field | Type | Description | Required |
|---|---|---|---|
| benefit_amount | String(decimal in 2-digit precision) | The amount of the discount, either a fixed value or a percentage in decimal form. | Yes |
| description | String(max. 512) | The name of the promotion. | No - Default: Cash Register Promotion |
| affected_basket_items | Integer[] | The list of the basket item id/pk that are affected by the promotion. | No - Default: empty list |
NOTE
If there is no promotion, above fields can be omitted. Empty list of affected_basket_items applies the promotion to all basket items.
Response
The response includes information about the store and the employee involved in processing the order. A result of "0" indicates successful completion of the operation. Otherwise, an error description will be displayed within the error_message value. Upon successful completion, the Instore application will display the "Transaction completed successfully" page.
{
"transaction_id": "269.00",
"order_number": "816910908011148",
"result": 0,
"error_message": "",
"amount": "269.00",
"staff_id": 232,
"staff_email": "staff@email.com",
"store_id": "123"
}