SwiftPOS Integration Details

The SwiftPOS integration has two distinct "modes". The first is cash accounting, the other is liability accounting. The distinction between the two is stark, and the decision to use one or the other would generally be made early on in the setup process.

In both modes, customers and orders are created in SwiftPOS when purchases are created in YGB.

 

Cash Mode

The core object being synced is a purchase. At the point that a customer makes a purchase, the revenue will be realised, and a completed, paid order will be created in SwiftPOS. As this mode is the much simpler of the two, the focus of this guide will be around liability mode.

 

Liability Mode

The core object being synced is a booking. A purchase with multiple bookings will be split into multiple orders. At the time an admin booking is made (walk-in etc) an open order will be created for payment on SwiftPOS. At the time a customer booking is made, an order will be created where the payment type goes to a liability clearing account.

Each day, at a pre-agreed time (editable in integration settings) the system will collect all customer created bookings and create an additional order for each one to turn the payments held in the liability clearing account into fully realised revenue. If the line item relating to a booking had been voided (such as what would happen if a booking is cancelled and refunded) the liability payment to the clearing account will be reversed and revenue not realised.

Initial Setup

There are several settings with comments around what the fields are for in the Manage Integrations settings page which can be accessed from the venue admin panel.

Read the settings carefully - they will explain if a field is required or not. Whether they are required or not may be conditional on other settings.

Screen capture shown here - for the most up to date version, please go direct to the settings page:

Data Flow

As mentioned above, the flow of data is heavily dependent on the mode selected. This section will cover the flow in liability mode only.

Customer Accounts

When any customer record is created or updated in YGB, or when a purchase goes to paid, the user record will be checked. On checking, an attempt willl be made by YGB to retrieve a SwiftPOS user. If the user doesn't exist yet in SwiftPOS it will create a new record for them.

It will create the user with whichever classificationId is set up in the integration settings above.

Admin Created Booking

An admin created booking is one created by a staff member. Regardless of the method that this booking is created with, it will immediately trigger creation of an open order in SwiftPOS. The intention then is that staff operating the SwiftPOS till will take appropriate payment for the order. As far as YGB is concerned, the purchase is resolved off-platform.

Customer Created Booking

A booking initiated by a customer will be immediately created in Swift as a closed order with the payment type going to the clearing account media ID as set up in the settings above. The item on this order will have a generic menu item ID as specified on the online booking ID setting, and a value set at 0. This order will not be touched by YGB until the batch job is run.

 

Scheduled Batch Job

Every day, at the hour specified in the integration settings, YGB will make a request for all customer created purchases in the previous calendar day (on the venue's timezone).

Any booking in this list that has had its line item voided will have a new order created with the original payments reversed, to show that revenue was not realised.

Any other booking will now have a new order created with the correct menu item IDs that the booking's bay/course option has, and a movement of payments from the clearing account to revenue.

Requirements for Operation

Please read carefully all sections of this guide. If for some reason the integration is not functioning as expected, it is likely one of these basic steps has not been followed.

 

Media IDs

For YGB to create orders in SwiftPOS in liability mode, the system must have the correct media IDs set. A media ID in SwiftPOS generally represents a payment method. The last 3 settings on the Manage Integrations page must be set correctly. Please reach out to your account manager with SwiftPOS if you are unsure.

 

Menu Item IDs

For a specific item to be created in SwiftPOS it must have a menuItemId set on its metadata. In regards to a booking, the items that must have this property set are the bay options and course options for bay and course bookings respectively.

You can see the metadata properties you have available to you in YGB Admin > Settings > Extra properties. You will have a view that looks something like this:

If you do not have a property in this list called menuItemId please reach out to support and ask that one is set up for you. It must match menuItemId exactly, including correct casing. It is possible you will not be able to set this property up yourself.

Assignment of Menu Item IDs

Now that the metadata property exists, you must make sure it is correctly assigned to your bay options. Depending on if you operate bay or course bookings, go to the appropriate settings area in the YGB admin panel. In the case of bay bookings, go to Settings > Bay Options.

Once here, select a bay option, and scroll to the bottom of the editor that appears.

You will see a section at the bottom "add a property". Once selected, one of the available options will be the menuItemId that was set up earlier. Select the property and add in the appropriate menuItemId that you have from SwiftPOS. If you're unsure how to get your menuItemIds, reach out to your SwiftPOS account manager.

Ensure any changes made are saved before exiting the editor.