Marketplace Store Status Integration

Marketplace applications must implement a store-status endpoint so that merchants can pause or resume ordering directly from POS Hub. This guide explains the contract POS Hub uses, how to validate requests, and how auto-resume scheduling works.

When POS Hub Calls Your Endpoint

POS Hub invokes your updateStoreStatusUrl whenever:

• A merchant pauses or resumes a marketplace connection from the POS Hub UI.
• A reseller triggers a pause/resume on behalf of the merchant.
• A previously scheduled resume task reaches its closedUntil timestamp (auto-resume).

Every call contains the context for the connection (account, location, connection ID) so your service can look up credentials and external store identifiers.

Endpoint Requirements

1. URL registration – Set the updateStoreStatusUrl when configuring your marketplace application in POS Hub (Developer → Application → Endpoints → Store Status URL).
2. HTTPS only – The endpoint must be served over TLS and accept JSON bodies.
3. Authentication – Protect the endpoint (e.g., OAuth bearer tokens, signed requests). Reject unauthorized calls with 401/403.
4. Idempotency – Multiple deliveries of the same payload can occur; treat them as idempotent updates.
5. Latency – Aim to respond within a few seconds so that the merchant UI reflects the change immediately.

Request Payload

POS Hub always performs a POST with the following structure:

{
  "connectionId": "con_1234abcd",
  "accountId": "acc_5678efgh",
  "locationId": "loc_9012ijkl",
  "storeStatus": "OFFLINE",
  "closedUntil": "2025-01-05T18:00:00Z",
  "closedReason": "PLANNED_CLOSURE",
  "closedReasonNotes": "Annual maintenance window"
}

Field details:

• connectionId, accountId, locationId: Use these to map back to your stored marketplace credentials.
• storeStatus: ONLINE or OFFLINE. ONLINE means resume ordering; OFFLINE means pause ordering.
• closedUntil (optional): ISO 8601 timestamp. Present only when the merchant picked a future reopen time.
• closedReason (optional): One of OPERATIONAL_ISSUES, TECHNICAL_ISSUES, OUT_OF_BUSINESS, PLANNED_CLOSURE, OTHER.
• closedReasonNotes (optional): Free-form explanation to surface to support agents or audit logs.

Validate the payload before forwarding it to the external marketplace. If the marketplace requires different enums or field names, transform them accordingly.

Expected Responses

• Success: Return 2xx (typically 204 or 200). Include a body only if you have additional info to surface to POS Hub (it will be logged, not shown to the user).
• Validation error: Return 400 with a JSON { "error": "explanation" } to display a friendly toast inside POS Hub.
• Unauthorized: Use 401/403 if the request is not signed or token verification fails.
• Server error: Return 5xx with a short message. POS Hub will display a generic failure notice and leave the store status unchanged.

POS Hub surfaces the error property (or raw body) back to the merchant, so keep the message actionable.

Auto-Resume Scheduling

When a merchant pauses a store and selects a future reopen time, POS Hub schedules a task. At the scheduled time POS Hub replays the exact same endpoint with:

{
  "connectionId": "...",
  "accountId": "...",
  "locationId": "...",
  "storeStatus": "ONLINE"
}

Your implementation should treat this as a standard resume call: reopen the store on the marketplace and return success. If the marketplace denies the resume (e.g., throttling, validation), respond with an error so that POS Hub keeps the store marked as paused and surfaces the message to the merchant.

Error Handling & Retries

• Synchronous validation – Catch missing fields, invalid timestamps, or conflicting business rules and return 400.
• Marketplace failures – If the downstream API rejects the update, relay the marketplace error message when possible.
• Network failures – Implement retry with exponential backoff on your side when calling the marketplace so that merchants are not forced to retry manually.
• Observability – Log both the inbound POS Hub payload and the outbound marketplace response (without storing PII) to simplify support investigations.

Best Practices

1. Map POS Hub reasons to marketplace-friendly copy. Provide user-facing descriptions when the marketplace lacks structured reason codes.
2. Limit pause duration. Enforce marketplace-specific maximums (e.g., 7 days) and return 400 if the merchant exceeds the allowed window.
3. Graceful degradation. If your marketplace lacks scheduled resume, emulate it by storing closedUntil in your system and making the upstream call at the right time.
4. Audit trail. Persist every pause/resume event with timestamps for compliance and dispute resolution.
5. Status reconciliation. Periodically confirm that marketplace state matches POS Hub state (e.g., nightly job) and auto-heal discrepancies.

Following these guidelines ensures merchants see immediate, predictable behavior when pausing or resuming their marketplace storefront from POS Hub.