A location is a site where a business operates, with its own address, processing profile, and industry (MCC). The business is the anchor; a single legal entity can run many locations, each its own merchant ID (MID), with its own processing profile and features. For the full field list, jump to the Request reference.

Common use cases

• Add a single location with its processing profile.
• Run many locations under one business, each with its own MID.
• Add a location later and set different features at different locations.

🚧

PENDING-PUBLISH

The boarding API Reference is pending publication; the ref: targets on this page are placeholders. Replace each with the real boarding-spec operationId once the boarding reference ships.

Scenarios

One EIN is one business; locations are how that one business operates in more than one place. Each location becomes its own merchant ID (MID) and carries its own processing profile and features.

graph TD
    B([Acme Coffee LLC<br/>one EIN, one identity])
    B --> L1[Downtown cafe]
    B --> L2[Airport kiosk]
    B --> L3[Mall store]
    L1 --> M1([MID 1<br/>Surcharge off, 3DS on])
    L2 --> M2([MID 2<br/>Surcharge on, 3DS off])
    L3 --> M3([MID 3<br/>Account Updater on])

Before you begin (all scenarios)

• You have the businessId the location belongs to.
• You have the site's address, processing profile, and MCC (industry).
• Your cardMix percentages (swiped, MOTO, eCommerce) total 100.

Scenario 1: Add a location

Add a site where the business operates. Make a POST request to /v1/businesses/{businessId}/locations.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/locations \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Store 1",
    "address": { "line1": "901 Commerce St", "city": "Austin", "stateProvince": "TX",
                 "postalCode": "78701", "countryCode": "US" },
    "phone": "+14155550521",
    "processingProfile": {
      "estimatedMonthlyVolume": 50000.00,
      "avgTicket": 150.00,
      "highTicket": 5000.00,
      "cardMix": { "swipedPercent": 90, "motoPercent": 5, "ecomPercent": 5 }
    },
    "operational": { "isSeasonal": false },
    "industry": { "mccCode": "5411", "description": "Retail grocery" }
  }'

Response: 201 Created

{
  "id": "loc_12",
  "uri": "/v1/businesses/{businessId}/locations/loc_12",
  "name": "Store 1",
  "status": "PENDING"
}

A location carries its own address plus a processing profile (estimated monthly volume, average and high ticket, and a cardMix of swiped, MOTO, and eCommerce percentages that must total 100) and an industry (MCC code and description). Volume and card mix live here because they're per-site facts, not company-wide ones. Seasonal sites also carry an operational block (isSeasonal, and openMonths when seasonal).

Scenario 2: Add a location later and set its features

Add a second site to a business that already exists, then set that location's features independently of the others. Enable a service and its features at the location with a PATCH request to /v1/businesses/{businessId}/locations/{locationId}/services.

# 1. Add the new location
curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/locations \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Airport kiosk",
    "address": { "line1": "3600 Presidential Blvd", "city": "Austin", "stateProvince": "TX",
                 "postalCode": "78719", "countryCode": "US" },
    "processingProfile": { "estimatedMonthlyVolume": 20000.00, "avgTicket": 25.00, "highTicket": 500.00,
      "cardMix": { "swipedPercent": 100, "motoPercent": 0, "ecomPercent": 0 } },
    "industry": { "mccCode": "5814", "description": "Fast food" }
  }'

# 2. Set this location's features
curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/locations/{locationId}/services \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "payin": { "card": { "enabled": true, "features": { "mxAdvantage.surcharge": { "enabled": true } } } } }'

The same business can run different features at different locations: one storefront on surcharge, another on 3-D Secure. See Configure services and the supported services and features.

When is it one business vs. two?

The test is the tax ID: locations that share one EIN are one business with many locations; a different EIN is a separate business, onboarded on its own.

graph TD
    Q{Do the sites<br/>share one EIN?}
    Q -->|Same EIN| ONE([One business, many locations<br/>add each site under the same businessId])
    Q -->|Different EIN| TWO([Separate business<br/>onboard it on its own])

• Same EIN: one business with multiple locations.
• Different EIN: a separate business, onboarded on its own.

Manage locations

• List or read one: GET /v1/businesses/{businessId}/locations, or GET /v1/businesses/{businessId}/locations/{locationId} for one.
• Update: PATCH /v1/businesses/{businessId}/locations/{locationId} changes name, address, phone, email, processingProfile, operational, or overrides.
• Remove: DELETE /v1/businesses/{businessId}/locations/{locationId} closes the site.

Funding sits at the business

Bank accounts are held on the business, not the location. Every location settles through the business's account(s), and a single account can serve as funding, billing, or both.

Request reference

The rules in one line each

• Boundary: same EIN is one business; a different EIN is a different business.
• One location, one MID: each location on a business gets its own merchant ID; add another location and it mints another MID. Even a single-site merchant has one location, and it's the location plus its service that creates the MID.
• Provisioning level: the card pay-in service is provisioned at the location; a banking service would sit at the business.
• Bank accounts: held at the business; every location settles through the business's account(s). A per-location account is not supported.
• Features: set per location on .../locations/{locationId}/services.
• Seasonality: set on the location's operational block (isSeasonal, and openMonths when seasonal).

🚧

PENDING-PUBLISH

Provisioning level: that the card pay-in service is provisioned at the location and a banking service at the business is being confirmed by QA. Verify before publish.

Statuses

A location moves through PENDING as its site details and service are validated, then activates with the business's service. Re-read the business to follow the change. See Status lifecycle and Underwriting exceptions for resolving a rejected location.

Sandbox testing

Use the sandbox to add locations and set per-location features before going live.

Go live

The shared pre-production checklist is in Getting Started. Specific to locations:

• Every location has an MCC (industry) and a cardMix totaling 100.
• Seasonal sites carry an operational block with openMonths.
• Per-location features are set where they should differ.

Best practices

Next steps

See also

• Bank accounts: funding held at the business that every location settles through
• Supported services and features: the features you can set per location
• Businesses: how locations fit the entity model