Documentation Summary
This document highlights the integration of Gensys with NetSuite and develop the sync between Item and Cash Sale sync.
Requirement
The client requires to integrate the following features from Gensys to NetSuite and NetSuite to Gensys:
- Products from NetSuite to Gensys
- Cash Sales from Gensys to NetSuite
- Cash refund from Gensys to NetSuite
- Exchange transaction Sync from Gensys to NetSuite
We will be importing the historical data for the following records into Gensys.
- Item records from NetSuite to Gensys
Scope of the Integration
Prerequisites:
- The Gensys should be set up by the Gensys team. All the outlets and initial set-up should be completed to start the development.
- Provide a sandbox/staging site for the Gensys if possible.
Field Customizations
The Item, Cash Sale need to be customised, and we need to add a checkbox field and a text field for each record. These fields will display under a custom subtab called “Gensys Sync”.
- When a sync between NetSuite and Gensys occurs, we will check the check box in the corresponding record in NetSuite.
- Text field for storing the unique ID of each record in Gensys in their corresponding records in NetSuite.
- For Cash Sales, there will be a Gensys Status field in the custom subtab.
- For all records in NetSuite, there will be a “Last Sync Date” to show the latest sync date and time.
Custom Record for API Information
We will create a custom record to store the API details in NetSuite. We will be storing the domain URL, authorization and permission type in the custom record which will be helpful for the NetSuite user to edit the details such as update in authorization token through a custom record in NetSuite.
We will be using the authorization to the Genesys website. The client credentials and access token will be saved in the custom record.
Custom Record for Handling the Gensys
We will be creating a custom record to handle the outlet identifiers such as the outlet ID to create Cash Sales or details in the Gensys website or mapping the location record in NetSuite to an outlet in Gensys Website.
Master Data Integration
Real time Item Sync from NetSuite to Gensys
We need an API from Gensys side for a real time integration from NetSuite to Gensys.
Item record contains following fields:
- NetSuite Item internal Id
- Item Id
- Item Name
- category
- Subcategory
- Brand
- Department
- UPC Code
- Item description
- Barcode
- Unit type
- Tax Schedule
- Subsidiary
- Item Price details and barcodes are stored inside Product Multi Units Custom record.
- As sample of product multi-unit record has been attached below:
- Following tax schedules available in NetSuite:
- VAT-5%
- ZERO
- The Item sync from NetSuite to Gensys is real-time one-way sync.
- Once the item created/updated in NetSuite, the item will be created or modified in Gensys.
- NetSuite is considering the NetSuite item internal id or Item ID(SKU) as unique id for Item in NetSuite.
- Items should be added always at the NetSuite Side
Sample JSON Containing Item details:
{
“success”: true,
“total”: 1,
“data”: [
{
“item_internal_id”:”33494″,
“item_id” :”23321-FJ MIXED FRUIT 1.4 LTR”,
“item_name”: “FJ MIXED FRUIT 1.4 LTR”,
“category_id”: “5”,
“category_name”:”DIARY”,
“subcategory”: “2”,
“subcategory_name”: “YOGHURT & CHILLED DESSERT”,
“brand_id”:”2″,
“brand_name”:”AMGT”,
“department_id”:”7″,
“department_name”:”DIARY, CHEESE & EGGS”,
“upc_code”:”6281007070775″,
“item_description”:”test”,
“unit_type”:”PCS”,
“tax_schedule”:”UAE-5%”,
“subsidiary”:”Parent Company”,
“product_multi_units”: [
{
“netsuite_internal_id”: 10378253,
“location_id”: 1,
“location_name”: “France-Mohideen supermarket LLC”,
“unit”:”PCS”,
“barcode”: “6281007040129”,
“sales_price”: “3.99”
},
{
“netsuite_internal_id”: 10378253,
“location_id”: 2,
“location_name”: “China-Mohideen supermarket LLC”,
“unit”:”PCS”,
“barcode”: “6281007040129”,
“sales_price”: “4”
},
{
“netsuite_internal_id”: 10378253,
“location_id”: 3,
“location_name”: “Freshday-Mohamed Ali moideen T”,
“unit”:”PCS”,
“barcode”: “6281007040129”,
“sales_price”: “5”
},
{
“netsuite_internal_id”: 10378253,
“location_id”: 1,
“location_name”: “Rashidiya – Mohd Ali mohideen”,
“unit”:”PCS”,
“barcode”: “6281007040129”,
“sales_price”: “3.99”
}
]
}
]
}
Note
- The create/update/deletion of item records in the Gensys will not be reflected in the NetSuite.
- Field mapping of item data from NetSuite to Gensys will be confirmed in the initial stage of development.
- Whenever an item is deleted/inactivated in NetSuite, the same item will be inactivated in Gensys.
- The creation or addition of variants in NetSuite can be reflected in GenSys but not the deletion of variants/parent record.
- We are considering only inventory items for the item sync.
- There should be fields in GenSys for storing the sales price of items for different subsidiaries.
Cash Sale and Cash Refund Sync from Gensys to NetSuite
- The Sync will be a scheduled integration from Gensys to NetSuite.
- GenSys should provide a public URL with authentication for us to fetch sales-created data
- NetSuite will access the public URL provided by Gensys using the API key and fetch the sales data at the end of the day and create consolidated cash sales in NetSuite.
Note:
- Cash Sales will be created in Deposited status in NetSuite.
- Shipping methods are not considered since no methods are available in Gensys.
- Removing a line item from a Cash Sale record while updating a Cash Sale in NetSuite will not be reflected in the Gensys website.
- Any update or creation of Gensys Cash Sale details in NetSuite will not be reflected on the Gensys Website.
- Field mapping will be confirmed at the initial stage of development.
- Item records will be available in the NetSuite and if any item is not available, we will be throwing an error in the custom record when Cash Sale creation.
- Payment method will not be recorded at the NetSuite side and all the payments should be completed at the POS side.
Item exchange
For POS integration with NetSuite, positive amounts should be added to the cash sale transaction, and negative quantities should be used for cash refunds in the event of an exchange at the Point of Sale (POS). This will ensure accurate accounting and tracking of sales and returns in the NetSuite system. The integration should be set up to handle these scenarios appropriately to maintain accurate records and financial reporting.
Fields Required
We require the following fields from Gensys for creating the cash sales in NetSuite.
| Fields | Subfields |
| Order (Cash sale main data) | Gensys Unique IDBill NumberBill dateLocation idMemoCounterClassType: Cash Sale/Cash RefundTotal priceSubtotalTotal tax rate.Currency |
| Item (per item line) | Gensys Unique IDNetSuite Item IdSKUBarcodeQuantityIs taxableGross Amount |
Sample Request
{
locationID: “1”,
locationName: “Rashidya”,
date: “4/8/2023”,
pageIndex: 1
}
Sample JSON response for cash sale:
{
success: true,
total_lines: 100,
totalPages: “1”,
isLastPage: “true”,
sales_data: [
{
id: 123,
bill_no: 10378253,
bill_date: ‘2023-08-04T09:53:25’,
date_created: ‘2023-08-04T00:00:00’,
location_id: ‘1’,
location_name: ‘France-Mohideen supermarket LLC’,
memo: ‘Test’,
counter_id: 1,
counter_name: ‘POS-3-RASHIDIYA’,
class: 2,
class_name: ‘Mohideen’,
sub_total: 30.0,
tax_total: 0.99,
total_amount: 30.99,
currency: ‘AED’,
items: [
{
bill_no: 10378253,
netsuite_item_id: ‘33495’,
item_name: ‘ALMARAI MILK FULL FAT 3% 500ML’,
barcode: ‘6281007040129’,
quantity: 2,
rate: 5.00,
amount: 10.00,
taxcode: ‘UAE-5%’,
tax_amount: 5.00,
gross_amount: 15.00
},
{
bill_no: 10378253,
netsuite_item_id: ‘33494’,
item_name: ‘23321-FJ MIXED FRUIT 1.4 LTR’,
barcode: ‘6281007034678’,
quantity: 5,
rate: 5.00,
amount: 25.00,
taxcode: ‘UAE-5%’,
tax_amount: 5.00,
gross_amount: 30.00
}
]
}
]
}
Error Handling
- We will be creating a field for storing the error that occurs during item sync in the Item record in NetSuite.
- To handle errors, a custom record will be created for every Cash Sale/cash refund. Any error that occurs while creating a Cash Sale/cash refund will be recorded in the Cash Sale/cash refund sync custom record fields.
- For every Cash Sale/cash refund there will be creating an instance containing the details. If there is no error occurs during creation and there will be no value appearing in the custom record error handling field.
- Using this custom record, errors related to Cash Sales, and cash refund syncs are handled. If any errors occur during any sync, they will be recorded in related fields of the custom record.
- An email will send to specific employees if there is an error occur during other Cash Sale /cash refund creation.
Technical Summary
Item Sync:
- Inventory item: Real-time sync from NetSuite to GenSys (Create/update)
Cash Sale Sync:
- Scheduled sync from GenSys to NetSuite (Creation only)
Cash Refund Sync:
- Scheduled sync from GenSys to NetSuite (Creation only)
GenSys API:
- Public URL should be available for us to fetch the details and write the items’ Data.
- The response or request body should be in JSON format.
- Direct read and write operations on the NetSuite database are not permissible. Instead, all actions involving database operations will be carried out through API calls and scripts within the NetSuite platform.
- In NetSuite, it is standard practice to round every currency value to two decimal places. This ensures consistent and accurate representation of currency amounts throughout the system.
- There should not be any whitelisting in the API as NetSuite has dynamically generated IP addresses.
- Filters such as location, date, and pagination should be there for filtering the data in the API.
- API response should be paginated.
- SQL operations at the POS side cannot be achievable from our end
Assumptions
- Field mapping should be confirmed in the initial stage of development.
- All sync will be a one-way flow of data.
- Integration will be active for new records created in NetSuite or updates that happen in NetSuite. The migration of existing/historical data will be out of the scope of this development.
- All the Cash Sales will be created as status “Deposited” in NetSuite
- Customer in the cash sales will be a static one exclusively created POS integration.
- Applicable only to inventory. Not applicable to special Cash Sales, drop-ship, kits, services, item groups, other charges items, or Matrix items.
- No tax details will be considered while creating the Cash Sale. The tax details will not be automatically sourced by NetSuite, and we won’t override any Tax information.
- Promotions or discounts will not be stored in NetSuite.
- The deletion of the cash refund and cash sale will not be considered.
- Class or department classifications in transactions are out of the scope of this development.
- Warehouse locations will not include any bin management.
- Single master data can only be sent at a time for item records sync.
- We are not considering the exchange rate of transactions in NetSuite and assuming that the currency is always AED.
- We will not be considering multiple currencies and assume that there is only one base currency.
- Date format of the data sent to Gensys API as a parameter will be UTC format and the date format in NetSuite will be followed according to the global preference set up in the account.
- The integrations’ performance depends on the number of processors in the account.
- Discounts or promotions will be calculated and applied at the Point of Sale (POS) side. These discounts will be included with the Gross amount at the item level. There will be no body-level discount added to the cash sale. This approach allows for transparent and item-specific discounts while maintaining a clear and accurate record of the cash sale transaction.
- Image URL sync is not considered in the sync.
- We assume that there is always a 5% tax when is taxable is true.
- We will turn off the current IPOS sync when the new Gensys POS is live and all sales data in IPOS should be handled properly.
Risk
- If there is mandatory fields while sending data to Gensys and which will not be a mandatory field in NetSuite, we might need to make it a mandatory field in NetSuite.
- Cash sales/cash refunds created in NetSuite will not be reflected in GenSys
- Creation or updates of items in GenSys will not be reflected in NetSuite. So, this will be affecting the integration of sales if any creation or update takes place in the POS side
- While we are deleting the records in GenSys, it will not be reflected in NetSuite.
- We can Cash sale record with around 1000 item lines: Cash Sale – NetSuite (Mohideen Retail SANDBOX).and NetSuite recommends creating transactions to be created as 500 items as best practice considering the validations per line.
- In the future, if there is any update in tax calculation or any current processes in our NetSuite side, GenSys needs to update accordingly.
- Inventory level sync is not considered. It is the best practice to sync the inventory stock but as per the current item configuration, different multi-units are created as custom records and hence their stock is not able to be calculated individually. This is limiting the inventory level sync and there is a chance of underwater selling at the NetSuite side which is not a best practice considering the Costing calculation in NetSuite.
- Scalability of location should be handled properly for future updates.
- Customer-level data is not stored in NetSuite and customer-level reports are not available.
- Customer loyalty is not handled at NetSuite.
- Promotions and Discounts are not handled at NetSuite, it is handled at the POS side.
- As it is a scheduled sync from POS to NetSuite and consolidated sales data is created per day, there will not be a real-time view of inventory from NetSuite.
- POS-wise data needs to be consolidated per location and bill numbers need to be unique identifiers for easy management.
- In the future, if the eCommerce or new locations has been added, transaction lines will increase.