Segments are predefined filters that encapsulate business logic. They provide consistent, reusable filtering that matches Square dashboard behavior.
Note
Tip: Views like Sales include curated segments such as Sales.online, Sales.in_store, Sales.new_customers, and Sales.returning_customers. These are often simpler than building equivalent filters on raw cubes.
{ "measures": ["Orders.net_sales"], "segments": ["Orders.closed_checks"] }
Returns net sales for only fully paid orders—excludes open checks and unpaid orders.
{ "measures": ["Sales.net_sales"], "segments": [ "Sales.in_store", "Sales.has_tip" ] }
Returns net sales for orders that are both in-store AND have a tip. Multiple segments are combined with AND logic.
Note
Segments vs Filters for AND/OR Logic: Segments are always combined with AND logic (all conditions must be true). For OR logic within a single condition (e.g., "location A OR location B"), use a filter with the equals operator and multiple values. You can combine both—use segments for business logic AND filters for specific OR conditions.
| Segment | Purpose |
|---|---|
Orders.closed_checks | Fully paid/settled orders (recommended for sales reports) |
Orders.open_checks | Orders awaiting payment |
Orders.awaiting_capture | Orders awaiting payment capture |
Orders.fully_paid | Fully paid orders |
Orders.has_tip | Orders with a tip |
Orders.no_tip | Orders without a tip |
Orders.has_customer | Orders linked to a customer |
Views provide additional curated segments that simplify common filtering patterns.
| Segment | Description |
|---|---|
Sales.online | Online sales channels |
Sales.in_store | In-store sales channels |
Sales.has_tip | Orders with a non-zero tip |
Sales.no_tip | Orders with no tip |
Sales.has_customer | Orders linked to an identified customer |
Sales.new_customers | Only new customers |
Sales.returning_customers | Only returning customers |
| Segment | Description |
|---|---|
ItemSales.sales | Only sales transactions (excludes returns) |
ItemSales.returns | Only return transactions |
ItemSales.has_customer | Orders linked to an identified customer |
ItemSales.new_customers | Only new customers |
ItemSales.returning_customers | Only returning customers |
Note
Tip: View segments like Sales.online and Sales.in_store replace the need to filter by sales channel ID manually. Use views for the simplest querying experience.
{ "measures": ["Orders.net_sales"], "filters": [{ "member": "Orders.state", "operator": "equals", "values": ["COMPLETED"] }, { "member": "Orders.check_state", "operator": "equals", "values": ["CLOSED"] }] }
{ "measures": ["Orders.net_sales"], "segments": ["Orders.closed_checks"] }
- Simpler queries - One segment replaces multiple filter conditions
- Consistent logic - Same business rules across all queries
- Dashboard parity - Matches Square dashboard behavior
- Centrally maintained - Filter definitions managed by Square
1. Always Use Orders.closed_checks for Sales Reports
{ "measures": ["Orders.net_sales"], "segments": ["Orders.closed_checks"] }
This ensures you're only counting fully paid orders, matching dashboard totals.
{ "measures": ["Orders.net_sales"], "segments": ["Orders.closed_checks"], "filters": [{ "member": "Orders.location_id", "operator": "equals", "values": ["LOC_123"] }] }
Use segments for business logic, filters for specific criteria.
Not all cubes have the same segments. Use the metadata endpoint or Schema Explorer to see what's available for each cube.