Best Practices

Recommended setup

Set up one data flow per entity

Each Coupler.io data flow exports one 7shifts entity. For a complete labor analytics setup, create separate flows for Time punches (payroll hours), Users (employee roster), Wages (pay rates), and Shifts (schedule data). Use Coupler.io's data join to combine them by user_id in your destination.

Connect with a company admin account

The 7shifts OAuth token is scoped to the account that authorized the connection. Connect with a company admin account (not a location manager) to ensure data flows can access all locations, departments, and employees across your organization.

Use the Start date to match your reporting window

Set the Start date to the beginning of your current pay period for payroll exports, or the start of your fiscal year for historical analysis. Use the date picker to set an exact date — this controls how far back Coupler.io pulls records.

Verify time zone alignment

7shifts timestamps (clocked_in, clocked_out, start, end) are returned in UTC. Your Locations entity includes the timezone field for each location. Convert UTC times to local time in your BI tool or use a formula column in Coupler.io before building dashboards.

Data refresh and scheduling

Daily refresh for Time punches

Time punch data changes throughout the day as employees clock in and managers approve punches. A daily refresh (e.g., overnight or early morning) gives your payroll team a clean, current snapshot each day without pulling intra-day changes.

Weekly or monthly refresh for organizational entities

Entities like Companies, Locations, Departments, Roles, and Assignments change infrequently. A weekly or monthly refresh is sufficient to keep your reference tables up to date without unnecessary API calls.

Refresh Shifts daily during scheduling season

Shift schedules are updated frequently by managers, especially in the days before the work week begins. Refresh the Shifts entity daily during active scheduling periods to capture the latest published schedule.

Align refresh timing with pay period close

For payroll accuracy, schedule a final Time punches refresh a few hours after the last shift of your pay period ends. This ensures all clock-outs are recorded and any manager approvals have been applied before you pull the data.

Performance optimization

Use a realistic Start date

For ongoing payroll exports, set the Start date to the beginning of your current pay period — not months or years in the past. A shorter date range means faster data flows and lower risk of timeouts, especially for high-volume locations.

Split large historical exports by period

If you need historical Time punches or Shifts data spanning multiple quarters, create one data flow per quarter and use Coupler.io's append mode in the destination to combine them into a single dataset. This avoids timeouts on large requests.

Keep reference entity flows separate from operational flows

Organizational entities (Companies, Locations, Departments, Roles) are small and fast. Keep them in separate data flows with a slower refresh schedule. This way, a slow Time punches export doesn't delay your org structure updates.

Dashboard accuracy

Filter out open shifts when calculating scheduled hours

Open shifts (unassigned shifts posted for employees to claim) appear in the Shifts entity with a null user_id. Always filter to rows where user_id is not null before calculating scheduled hours per employee.

Use approved punches for payroll calculations

The approved field on Time punches indicates whether a manager has reviewed and approved the punch. For payroll accuracy, calculate hours only from approved punches. Unapproved punches may still be under review or pending correction.

Use Worked hours and wages for quick totals

The Worked hours and wages entity provides daily pre-aggregated totals — hours, wages, and tips per employee and role — without requiring joins. Use it for labor cost dashboards. Switch to Time punches + Wages only when you need punch-level detail or need to apply your own break deduction logic.

Join Time punches and Wages for punch-level analysis

When you need individual clock-in/out records with custom break deduction logic, join Time punches with Wages on user_id and role_id. Multiply hours by wage per punch. Note that an employee may have different wage rates for different roles — join on both keys to use the correct rate.

Account for breaks in hours calculations

The breaks field on Time punches stores total break time in minutes. Whether breaks are paid or unpaid depends on your restaurant's policy. If breaks are unpaid, subtract breaks / 60 from hours to get the paid hours for each punch.

Common pitfalls to avoid

Do

• Connect with a company admin account for full location access

• Set a realistic Start date to match your pay period or reporting window

• Filter out null user_id rows when calculating scheduled shift hours

• Use approved punches for payroll calculations

• Use Worked hours and wages for daily labor totals — or join Time punches + Wages on both user_id and role_id for punch-level cost analysis

Don't

• Don't connect with a location manager account — you'll only see that location's data

• Don't set the Start date to years in the past for ongoing payroll exports — it causes slow or timed-out data flows

• Don't include open shifts (null user_id) in scheduled hours calculations

• Don't forget that timestamps are in UTC — convert to local timezone before displaying in dashboards

• Don't expect breaks to be automatically deducted from hours — apply your own break policy in your analysis

Timestamps are in UTC. The clocked_in, clocked_out, start, and end fields are returned in UTC by the 7shifts API. If your restaurant locations are in different timezones, convert timestamps using the timezone field from the Locations entity before grouping data by day or shift.