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:

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:

ParameterTypeDescription
net_totalintegernet_total of the receipt pre tax, post-discounts, and pre tips. The value is in cents. This value is used when tip-in is based on net sales.
receipt_datedate timeThe receipt_date is used to allocate sales and tips employees gain during their shifts.

If the user is not clocked in during the receipt_date, it will not be included in the tip pool calculations for that user and the sales and tips will be unassigned.
location_idintegerThe 7shifts location ID of where the sale took place.
revenue_center (optional)stringrevenue_centers are service areas, tables or devices. The value should be the external revenue center ID for the POS. This is used to filter sales and tip contributions in tip pools.

Not currently supported for tip pools at this time
dining_option (optional)stringdining_option are different order channels such as dine-in, take-out, or delivery. The value should be the external dining option ID for the POS. This is used to filter sales and tip contributions in tip pools.

Not currently supported for tip pools at this time
receipt_lines (optional)arrayreceipt_lines contains an array of all the receipt lines. Each array object describes a single receipt line.
receipt_lines.external_category_ids (optional)array of stringsexternal_category_ids contains an array of item IDs that map to an items category such as liquor, retail, food. This is used to filter sales and tip contributions in tip pools.

Not currently supported for tip pools at this time
receipt_lines.net_item_price (optional)integernet_item_price is the item net price pre tax, post-discounts, and pre tips. The value is in cents. This value is used when tip-in is based on net sales.

Not currently supported for tip pools at this time

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:

ParameterTypeDescription
tipsintegertips contains all of the tips collected in the receipt, the value is in cents. The tips value should contain all of the values of the tip_details.
tip_detailsarraytip_details contains an array of all the tip details for a receipt. Each array object describes a single tip contribution.
tip_details.typestringtip_details.type describes the tip type. The value can be one of the following:
- cc (deprecated)
- cash (unsupported)
- declared(unsupported)
- net (unsupported)
- total
- gratuity

Tip pools only support two different tip types:
- Credit card tips (cc tips). Use the total tip type
- Auto-gratuities. Use the gratuity tip type
tip_details.valueintegertip_details.value is the value of the tip type in cents.

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:

ParameterTypeDescription
external_user_idstringThe POS user ID. This must be unique to a location.
user_idintegerThe 7shifts user_id.
emailstringThe users email.
phone_numberstringThe users mobile phone number. First name and last name must be provided when using phone number.
first_namestringThe users first name.
last_namestringThe users last name.

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.