Documentation

How GeoCart evaluates location and controls Add to Cart

This guide covers Product Groups, country and state rules, ATC behaviors, the theme embed, storefront evaluation, and billing limits.

Open the setup tutorial Jump to behaviors

Admin

1. App dashboard

The dashboard shows your current plan, usage meters (groups, location rules, products), and a quick setup guide. Nav includes Product Groups, Location Rules, Analytics (Growth/Pro), Billing, and Settings.

Core

2. Product Groups

A Product Group is the configuration unit: name, status, priority, assigned products/collections, country policy, state rows, behavior, and optional message. When multiple groups match a product, higher priority wins. Inactive groups are ignored.

Policy

3. Country Availability

Set at the group level — not by adding every country as a location row:

All Countries

Worldwide; only state rules create restrictions.

Only Selected

Allowed countries you pick; all others unavailable.

Exclude Selected

Everywhere except the countries you exclude.

Example

Only India + restricted MH/MP: USA blocked automatically; India + Punjab available.

Rules

4. State restrictions

After the country gate, GeoCart checks whether the visitor’s state is restricted for that group. Pick an allowed country, select restricted states, and save. Restricted states never appear in the selector popup.

Storefront

5. ATC behaviors

  • Hide Add to Cart — hide ATC and related buy buttons; message only
  • Show Available State Selector — ATC disabled until an allowed state is confirmed
  • Show Shipping Availability — status message; enable/disable ATC; no picker

Theme

6. Theme integration

Enable GeoCart ATC Control under Theme → Customize → App embeds. Rules sync to shop metafields (geocart.rules / geocart.settings). App Proxy under /apps/geocart/* provides config, geo, product check, and analytics endpoints.

Flow

7. Storefront evaluation

  1. Resolve visitor country (Shopify localization / proxy geo / test query params)
  2. Apply Country Availability — if denied, stop
  3. Apply state restrictions for matching groups
  4. Run the group behavior (hide / selector / availability)

Test with ?geocart_country=IN&geocart_state=MH on a product URL.

Plans

8. Billing & limits

Plans are managed in-app via Shopify Billing. Free includes limited groups and rules. Starter unlocks state targeting and collections. Growth adds analytics. Pro removes caps. See Pricing.

Note

9. Important limitation

Hiding Add to Cart is a UX restriction, not complete purchase security. Determined buyers may still reach checkout through other paths. Document this honestly in store policies if needed.