Listing business accounts, stores, and POS terminals

Purpose of this guide

This guide covers how to use the API when you want to list a ReceiptRoller user's business accounts, stores, and POS terminals from a mobile app or server app. Common use cases are:

• A screen that lets the user choose "which business account to act as" inside the app
• A screen that lists the stores under the selected business account and switches the target of reports or operations
• A screen that lists the POS terminals of a selected store and picks a target for transaction lookup or terminal QR linkage
• A business app where one user accesses multiple business accounts

Prerequisites

• You have registered an app in the Developer Dashboard
• You have obtained a user-bound access token via the OAuth 2.0 authorization code flow (if you support multiple business accounts, turn off the "bind the token to one business account at authorization time" checkbox in your app settings — see the native mobile app guide for details)
• Base URL: https://receiptroller.io

1. List the business accounts the user belongs to

First, retrieve the business accounts the current user is a member of.

GET /api/v1/me/organizations
Authorization: Bearer {access_token}

Query parameters (optional)

• page — page number (starts at 1, default 1)
• pageSize — number of items per page (default 100, max 1000)

Example response

{
  "organizations": [
    {
      "id": "a04507de-043a-4b47-b0a3-6204562f6e20",
      "name": "株式会社レシートローラー",
      "role": "Owner"
    },
    {
      "id": "7c2e0e9b-1f3a-4c6d-8a01-2b9f4d5e6c00",
      "name": "サンプル小売株式会社",
      "role": "Member"
    }
  ],
  "page": 1,
  "pageSize": 100,
  "totalCount": 2,
  "totalPages": 1
}

Notes

• id is the business account ID (UUID). Use it as-is in the next request
• role is the user's permission role (Owner / Member / ProductManager, etc.)
• When totalPages is 2 or more, advance page to retrieve all records — the key point is to not stop after displaying only the first page on the mobile app side

2. List the stores under a business account

Using the id obtained in step 1, retrieve the store list.

GET /api/v1/me/organizations/{organizationId}/stores
Authorization: Bearer {access_token}

Query parameters (optional)

• includeDeleted — whether to include deleted stores (default false). Usually not needed

Example response

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "role": "Owner",
  "stores": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "渋谷店",
      "storeType": "Retail",
      "primaryCategory": "コーヒーショップ",
      "status": "Active",
      "isDeleted": false,
      "isPosConnected": true,
      "address": {
        "country": "JP",
        "prefecture": "東京都",
        "city": "渋谷区",
        "line1": "宇田川町1-1",
        "line2": "",
        "postalCode": "150-0042",
        "latitude": 35.6595,
        "longitude": 139.7005
      },
      "phone": "03-1234-5678",
      "websiteUrl": "https://example.com/shibuya",
      "updatedAt": "2026-05-30T12:34:56Z"
    }
  ],
  "totalCount": 1
}

Notes

• id is the store ID. Pass it as storeId to report APIs such as /api/v1/sales/*
• If the calling user is not a member of that business account, 403 Forbidden is returned
• includeDeleted=true includes deleted stores, but don't add it in a normal app (you would accidentally display closed stores)

3. List the POS terminals under a store

Using the store id obtained in step 2, retrieve the POS terminals registered to that store.

GET /api/v1/me/organizations/{organizationId}/stores/{storeId}/pos-terminals
Authorization: Bearer {access_token}

Query parameters (optional)

• includeDeleted — whether to include deleted terminals (default false)

Example response

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "terminals": [
    {
      "id": "term-001",
      "name": "レジ1（フロント）",
      "vendor": "Smaregi",
      "integrationType": "API",
      "location": "1F カウンター",
      "serialNumber": "SMG-2024-0001",
      "isActive": true,
      "publicTerminalId": "T-XYZ123",
      "transactionCount": 4821,
      "lastSyncAt": "2026-06-01T03:00:00Z",
      "lastSyncStatus": "Success",
      "lastTransactionAt": "2026-06-01T11:42:18Z",
      "updatedAt": "2026-06-01T03:00:00Z"
    }
  ],
  "totalCount": 1
}

Security note

• A POS terminal's vendor credentials (apiKey / apiSecret / accessToken / refreshToken) are never returned. The response is operational metadata only
• If the store does not belong to the specified business account, 404 is returned (to prevent references to another tenant by guessing an ID)

4. (Optional) Retrieve all POS terminals across a business account at once

When you want to see, for example, "how far POS sync has progressed across the whole account," you can also list all POS terminals of a business account. Each terminal carries a storeId and storeName, so you can group by store.

GET /api/v1/me/organizations/{organizationId}/pos-terminals
Authorization: Bearer {access_token}

Example response

{
  "organizationId": "a04507de-043a-4b47-b0a3-6204562f6e20",
  "role": "Owner",
  "terminals": [
    {
      "storeId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "storeName": "渋谷店",
      "terminal": {
        "id": "term-001",
        "name": "レジ1（フロント）",
        "vendor": "Smaregi",
        "integrationType": "API",
        "isActive": true,
        "lastSyncAt": "2026-06-01T03:00:00Z",
        "lastSyncStatus": "Success"
      }
    }
  ],
  "totalCount": 1
}

Use the store-scoped version in section 3 (/stores/{storeId}/pos-terminals) when building a per-store selection UI, and use this endpoint when you want a cross-store view on a dashboard.

A typical flow (mobile app)

1. Store the access token obtained via OAuth in secure storage (iOS Keychain / Android EncryptedSharedPreferences)
2. On app launch, call GET /api/v1/me/organizations and show the business account selection UI
3. When the user picks a business account, get the store list with GET /api/v1/me/organizations/{organizationId}/stores
4. When a store is selected, get the POS terminals with GET /api/v1/me/organizations/{organizationId}/stores/{storeId}/pos-terminals
5. Hold the selected business account ID / store ID / terminal ID locally and pass them to subsequent business APIs
6. When the user chooses "switch," return to the selection UI and repeat the same flow

Error responses

Related articles

• For native mobile apps: multi-business-account access and the OAuth flow
• API authentication guide (OAuth 2.0 authorization code flow)
• OAuth scope list and availability
• Creating a new app