Automatic Tip Pool Contribution Support

The sales receipt endpoints allows you to add extra receipt data that can be used for automatically providing sales and tip information for tip pools. Below will outline, in detail, the required data to support automatic tip pool contributions.

📘

Feature Restriction

If you are a Point of Sale provider and wish to add support for 7shifts Tip Pooling with your sales integration, please contact [email protected] to get started.

Required sales data

To support tip pooling, the following additional information is required to be passed though the receipts endpoint:

• Sales data
• Tip detail data
• User & role mapping information
• Unmapped sales & tip data

Below is a full description of the value in the receipt payload and how they interact with tip pools:

Sales Data

The following parameters in the receipts payload are used to support tip pools:

NOTE: The optional parameters are currently not supported in tip pools. This features may be included in further releases of the API.

Tip Detail Data

The following parameters are required in the receipts payload to support tip pools:

When passing in tip details, the following rules should be applied:

• Credit card tips must be passed in via the total tip type. The cc tip type has been deprecated and will not be included in tip pools.
• For all auto-gratuity tips, including those paid via credit card, use the gratuity tip type.
• Cash or declared tips that are collected by the employee should be included via the labor data. To be included in tip pools, they must be specified in time_punches via the tips parameter. Reference the time punch endpoint for more details.

User & Role Mapping

Tip pools can be configured to assign contributions from net sales and total tips.

For automatic contributions to be mapped to roles, the following is required:

• User must have time punches with roles assigned to them
• Receipts must specify the POS user ID or the external_user_id
• External user mapping must completed

Role Mapping

Role mapping is required as part of assigned contributions. The roles are pulled in from time clocking punches that include a role. The source can be from 7punches or a labor integrated POS. Once this is done, it will ensure that employees will be assigned the correct tips, based on their hours and roles.

Note; both contributors and receivers must have role mapped punches to properly assign the tip pool values.

Receipt User ID

You must include the POS user ID or the external_user_id value in the receipt. When a receipt does not include a value for the external_user_id, or the value is not mapped to a 7shifts user, the receipt sales and tip contribution will be unassigned.

External User Mapping

To allow receipts to be mapped to employees, a mapping must be between external_user_id used in receipts and 7shifts user_id.

We provide a full set of external user mapping endpoints to manage the mapping. We also have a bulk mapping endpoint available to minimize the amount of API calls made during the initial mappings.

Here is an example request to the create external user mapping bulk endpoint to map several users at a time:

curl --request POST --url 'https://api.7shifts.com/v2/company/12345/location/7890/external_user_mappings_bulk'
--data '
{
    "data": [
        {
            "external_user_id": "Shawna1234ExID",
            "user_id": 1235,
        },
        {
            "external_user_id": "Johnny1234ExID",
            "email": "[email protected]",
        },
        {
            "external_user_id": "Star234ExID",
            "first_name": "Jane",
            "last_name": "Star",
            "phone_number": "309939393"
        },
				{
            "external_user_id": "bc5234ExID",
            "first_name": "Bob",
            "last_name": "Carr",
        }
    ]
}
'

The create external users bulk endpoint allows you to pass in up to 100 user mappings with lookup parameters. The request parameter details are below:

The following matching criteria is applied:

1. Match on user_id
2. Match on full email address
3. Match on first_name, last_name and mobile phone_number.
4. Match on exact first_name and last_name

The return payload will return the result of the mapping. An example is below:

{
    "data": {
        "mapped": [
            {
                "external_user_id": "Shawna1234ExID",
                "user_id": 5555
            },
            {
                "external_user_id": "Johnny1234ExID",
                "user_id": 8456
            },
            {
                "external_user_id": "Star234ExID",
                "user_id": 2586
            }
        ],
        "exceptions": [
            {
                "external_user_id": "bc5234ExID",
                "reason": "not_found"
            }
        ]
    },
  "object": {
    type: "external_user_mappings"
  }
}

Unmapped Sales & Tip Data

Tip and sales receipt data are categorized as "unassigned" when:

Mapping status is unmapped or ignored
An employee’s profile isn’t correctly mapped to a 7shifts user_id. Or, this may be intentional if you have ghost profiles or takeout roles. Review the external user mapping section of this guide if you have unmapped receipts that should be assigned to a user.

Time punches are missed
This happens if an employee doesn’t clock in (or forgets to) but has sales and tip data from their shift. For example, a salaried manager who doesn’t clock in but settles a bill.

Time punches have no role associated
This happens if an employee clocks into their shift but doesn’t specify their working role. You can find their name in the detailed Tip Pooling report under the “unassigned” row.

When receipt data is categorized as unassigned, they can be added to a tip pool contribution as unassigned contributors.