{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Companies, Child Companies, and Stores","description":"Complete documentation for integrating Cheqi's digital receipt platform","keywords":["cheqi","digital receipts","api","sdk","java","javascript"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"companies-child-companies-and-stores","__idx":0},"children":["Companies, Child Companies, and Stores"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi keeps four concepts separate:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["company"]}," is the legal issuer named on a receipt."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["child company"]}," is another legal issuer connected to a parent for"," ","corporate structure and administration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["store"]}," is a location owned by exactly one company. It is not a legal"," ","issuer by itself."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["integration"]}," is the software calling Cheqi. It may receive explicit"," ","grants from many issuer companies while keeping one integration credential."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"The Core Rule"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authenticated integration says ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["who is calling"]},". The short-lived company"," ","access token and active company grant say ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["which legal company it may act for"]},"."," ","A parent-child relationship never grants receipt authority by itself."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choose-the-right-model","__idx":1},"children":["Choose the Right Model"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Real-world unit"},"children":["Real-world unit"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cheqi model"},"children":["Cheqi model"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Why"},"children":["Why"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shop, restaurant, branch, webshop, or terminal under one legal entity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["It needs a location, not a separate legal identity"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subsidiary with its own registration or VAT identity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Child company"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["It is a separate legal receipt issuer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Franchisee operated by another legal entity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Child company"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["It needs independent consent, billing, reporting, and revocation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Brand or department under the same legal entity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Usually a store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An operational distinction does not create a legal issuer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Central POS or accounting platform"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integration"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One caller can be explicitly authorized by many companies"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When unsure, ask: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Which legal name and tax registration must appear as the"," ","seller?"]}," Create or select that Cheqi company, then select one of its stores."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"a-real-world-group","__idx":2},"children":["A Real-World Group"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TB\n Integration[\"Northstar central POS
one integration credential\"]\n Group[\"Northstar Group B.V.
parent company\"]\n NL[\"Northstar Retail NL B.V.
child + legal issuer\"]\n DE[\"Northstar Retail DE GmbH
child + legal issuer\"]\n Franchise[\"Independent Franchisee B.V.
child + legal issuer\"]\n\n Group -->|\"corporate relationship only\"| NL\n Group -->|\"corporate relationship only\"| DE\n Group -->|\"franchise relationship only\"| Franchise\n\n NL --> AMS[\"Amsterdam Store\"]\n NL --> RTM[\"Rotterdam Store\"]\n DE --> BER[\"Berlin Store\"]\n Franchise --> UTR[\"Utrecht Store\"]\n\n Integration -. \"explicit NL grant\" .-> NL\n Integration -. \"explicit DE grant\" .-> DE\n Integration -. \"franchisee-approved grant\" .-> Franchise\n","diagramHtml":"

corporate relationship only

corporate relationship only

franchise relationship only

explicit NL grant

explicit DE grant

franchisee-approved grant

Northstar central POS
one integration credential

Northstar Group B.V.
parent company

Northstar Retail NL B.V.
child + legal issuer

Northstar Retail DE GmbH
child + legal issuer

Independent Franchisee B.V.
child + legal issuer

Amsterdam Store

Rotterdam Store

Berlin Store

Utrecht Store

","diagramHtmlDark":"

corporate relationship only

corporate relationship only

franchise relationship only

explicit NL grant

explicit DE grant

franchisee-approved grant

Northstar central POS
one integration credential

Northstar Group B.V.
parent company

Northstar Retail NL B.V.
child + legal issuer

Northstar Retail DE GmbH
child + legal issuer

Independent Franchisee B.V.
child + legal issuer

Amsterdam Store

Rotterdam Store

Berlin Store

Utrecht Store

"},"children":["flowchart TB\n Integration[\"Northstar central POS
one integration credential\"]\n Group[\"Northstar Group B.V.
parent company\"]\n NL[\"Northstar Retail NL B.V.
child + legal issuer\"]\n DE[\"Northstar Retail DE GmbH
child + legal issuer\"]\n Franchise[\"Independent Franchisee B.V.
child + legal issuer\"]\n\n Group -->|\"corporate relationship only\"| NL\n Group -->|\"corporate relationship only\"| DE\n Group -->|\"franchise relationship only\"| Franchise\n\n NL --> AMS[\"Amsterdam Store\"]\n NL --> RTM[\"Rotterdam Store\"]\n DE --> BER[\"Berlin Store\"]\n Franchise --> UTR[\"Utrecht Store\"]\n\n Integration -. \"explicit NL grant\" .-> NL\n Integration -. \"explicit DE grant\" .-> DE\n Integration -. \"franchisee-approved grant\" .-> Franchise\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The integration credential does not multiply as companies are added. Each"," ","legal issuer creates an explicit grant. At runtime, the integration exchanges"," ","its credential for a short-lived token bound to the issuer it needs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication-and-authorization","__idx":3},"children":["Authentication and Authorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi deliberately separates these:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Object"},"children":["Object"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Answers"},"children":["Answers"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cardinality"},"children":["Cardinality"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integration credential"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Who is calling?"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Usually one integration, with two active credentials during rotation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Company grant"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which issuer may it represent, with which scopes and stores?"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One per integration/issuer pair"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Company access token"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which grant is this short-lived request context using?"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requested through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," when the integration needs to act for that issuer"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A company ID in a request is only a claim. Cheqi accepts it only when an active"," ","grant exists for the authenticated integration."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant POS as Central integration\n participant Token as Cheqi OAuth token endpoint\n participant Grant as Company grant\n participant API as Receipt API\n\n POS->>Token: client_credentials + grant_id + scope\n Token->>Grant: Validate active grant and requested scope subset\n Grant-->>Token: grant id + version + allowed stores\n Token-->>POS: Short-lived company access token\n POS->>API: Bearer token + storeId + encrypted receipt\n API->>Grant: Re-check status, version, scope, and store\n Grant-->>API: Authorized issuer context\n API-->>POS: Accepted\n","diagramHtml":"Receipt APICompany grantCheqi OAuth token endpointCentral integrationReceipt APICompany grantCheqi OAuth token endpointCentral integrationclient_credentials + grant_id + scopeValidate active grant and requested scope subsetgrant id + version + allowed storesShort-lived company access tokenBearer token + storeId + encrypted receiptRe-check status, version, scope, and storeAuthorized issuer contextAccepted","diagramHtmlDark":"Receipt APICompany grantCheqi OAuth token endpointCentral integrationReceipt APICompany grantCheqi OAuth token endpointCentral integrationclient_credentials + grant_id + scopeValidate active grant and requested scope subsetgrant id + version + allowed storesShort-lived company access tokenBearer token + storeId + encrypted receiptRe-check status, version, scope, and storeAuthorized issuer contextAccepted"},"children":["sequenceDiagram\n participant POS as Central integration\n participant Token as Cheqi OAuth token endpoint\n participant Grant as Company grant\n participant API as Receipt API\n\n POS->>Token: client_credentials + grant_id + scope\n Token->>Grant: Validate active grant and requested scope subset\n Grant-->>Token: grant id + version + allowed stores\n Token-->>POS: Short-lived company access token\n POS->>API: Bearer token + storeId + encrypted receipt\n API->>Grant: Re-check status, version, scope, and store\n Grant-->>API: Authorized issuer context\n API-->>POS: Accepted\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"why-the-parent-relationship-is-not-authority","__idx":4},"children":["Why the Parent Relationship Is Not Authority"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The hierarchy exists for organization and administration. It does not prove"," ","that a parent may legally issue receipts for a subsidiary or franchisee."," ","Changing a parent relationship therefore never changes receipt permissions."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A verified organization administrator may approve grants for wholly owned"," ","subsidiaries they administer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An independent franchisee approves its own grant and can suspend or revoke"," ","it without affecting other franchisees."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A third-party POS provider uses exactly the same grant mechanism even though"," ","it has no corporate relationship with the merchant."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"one-integration-for-thousands-of-companies","__idx":5},"children":["One Integration for Thousands of Companies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One OAuth authorization may approve several companies. The one-time"," ","authorization-code exchange returns Grant metadata for every approved company:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"grants\": [\n {\n \"issuer_company_id\": \"company-nl-uuid\",\n \"grant_id\": \"grant-uuid\",\n \"grant_version\": 3,\n \"company_legal_name\": \"Northstar Retail NL B.V.\",\n \"scopes\": [\"write_receipts\", \"read_stores\"],\n \"store_ids\": [\"store-amsterdam\", \"store-rotterdam\"],\n \"store_access_mode\": \"SELECTED_STORES\"\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /oauth2/authorization-code/exchange"]}," for this one-time exchange."," ","It returns Grant metadata only; it does not issue an access token."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The integration stores its Grant-to-customer mapping. Before operating for a"," ","company, it requests a short-lived company access token using the Grant ID:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.cheqi.io/oauth2/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"your_client_id\",\n \"client_secret\": \"your_integration_secret\",\n \"grant_id\": \"grant-uuid\",\n \"scope\": \"write_receipts\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi returns a token that is:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["valid for about 15 minutes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["bound to one company grant and grant version"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["limited to the requested subset of granted scopes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["invalidated when the grant changes, is suspended, or is revoked"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the token expires, request another through the same endpoint using the"," ","same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_id"]},". No refresh token is needed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To synchronize current Company and Store details after onboarding, call"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /oauth2/grants/{grantId}"]}," with the Company-bound access token and the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_stores"]}," scope."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"One Credential Is Not Automatic Group Authority"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The integration credential can request only issuers with an explicit active"," ","grant. Guessing another company ID or adding a child relationship grants"," ","nothing."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receipt-request-matrix","__idx":6},"children":["Receipt Request Matrix"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Access token company"},"children":["Access token company"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"storeId"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storeId"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Result"},"children":["Result"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Legal issuer"},"children":["Legal issuer"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Retail NL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Omitted"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allowed when the grant covers all stores"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Retail NL"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Retail NL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amsterdam Store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allowed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Retail NL"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Retail NL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Berlin Store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected; store belongs to another company"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Group"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amsterdam Store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected; hierarchy is not authority"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Retail DE"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Berlin Store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allowed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Northstar Retail DE"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Franchisee"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Utrecht Store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allowed only while its own grant is active"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Franchisee"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Selected-store grant"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Omitted"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected for issuance"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Any issuer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inactive store"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-scenarios","__idx":7},"children":["Common Scenarios"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"one-legal-company-with-many-shops","__idx":8},"children":["One Legal Company with Many Shops"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create one company and all shops as stores beneath it. One integration grant"," ","can cover those stores because the legal issuer is the same."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"international-group","__idx":9},"children":["International Group"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create each national legal entity as a child company and its locations as"," ","stores. Approve an explicit grant for each national company. The central"," ","platform keeps one integration credential and exchanges it for the relevant"," ","national issuer at checkout."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"dominos-style-franchise-network","__idx":10},"children":["Domino's-Style Franchise Network"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Model brand-owned shops as stores of the brand's operating company. Model each"," ","independent franchisee as its own company with its own stores."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Domino's central platform keeps one integration credential. Each franchisee"," ","approves a company grant. The platform requests a short-lived access token for"," ","the franchisee handling the sale. A franchisee can revoke only its own grant;"," ","no company-specific secrets need to be distributed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"third-party-pos-provider","__idx":11},"children":["Third-Party POS Provider"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each unrelated merchant explicitly grants the POS integration access. The POS"," ","uses the same integration credential and exchange endpoint for every merchant."," ","Corporate hierarchy is not involved."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webshop-and-physical-stores","__idx":12},"children":["Webshop and Physical Stores"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If one legal company operates both, use one company. Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storeId"]}," for online"," ","sales when the grant covers all stores, or create a webshop store when an"," ","explicit operational location is useful."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"grant-and-store-lifecycle","__idx":13},"children":["Grant and Store Lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Issuer administrators can list, update, suspend, reactivate, and revoke grants."," ","Updates create a new immutable grant revision and revoke existing tokens for"," ","that integration/company context."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A grant can cover:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["all direct stores of the issuer; or"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["an explicit set of stores owned by the issuer."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Stores are deactivated rather than deleted so historical receipts retain their"," ","location."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"scopes","__idx":14},"children":["Scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Available scope names are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_receipts"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_receipts"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write_stores"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read_stores"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["company_access"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_access"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"issuance-checklist","__idx":15},"children":["Issuance Checklist"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Determine the exact legal seller from trusted transaction configuration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request a company access token through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," with only the scopes needed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If required, select an active store owned and allowed by that issuer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reuse the same access token context through recipient resolution and"," ","encrypted submission."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", exchange again. On ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", treat the grant, scope, company, or store"," ","as unauthorized—do not silently fall back to another issuer."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":16},"children":["Related Guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/authentication/overview"},"children":["Authentication Overview"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/authentication/api-keys"},"children":["API Key Authentication"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/authentication/oauth"},"children":["OAuth 2.0 Authentication"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/receipts/sending"},"children":["Sending Receipts"]}]}]}]},"headings":[{"value":"Companies, Child Companies, and Stores","id":"companies-child-companies-and-stores","depth":1},{"value":"Choose the Right Model","id":"choose-the-right-model","depth":2},{"value":"A Real-World Group","id":"a-real-world-group","depth":2},{"value":"Authentication and Authorization","id":"authentication-and-authorization","depth":2},{"value":"Why the Parent Relationship Is Not Authority","id":"why-the-parent-relationship-is-not-authority","depth":3},{"value":"One Integration for Thousands of Companies","id":"one-integration-for-thousands-of-companies","depth":2},{"value":"Receipt Request Matrix","id":"receipt-request-matrix","depth":2},{"value":"Common Scenarios","id":"common-scenarios","depth":2},{"value":"One Legal Company with Many Shops","id":"one-legal-company-with-many-shops","depth":3},{"value":"International Group","id":"international-group","depth":3},{"value":"Domino's-Style Franchise Network","id":"dominos-style-franchise-network","depth":3},{"value":"Third-Party POS Provider","id":"third-party-pos-provider","depth":3},{"value":"Webshop and Physical Stores","id":"webshop-and-physical-stores","depth":3},{"value":"Grant and Store Lifecycle","id":"grant-and-store-lifecycle","depth":2},{"value":"Scopes","id":"scopes","depth":2},{"value":"Issuance Checklist","id":"issuance-checklist","depth":2},{"value":"Related Guides","id":"related-guides","depth":2}],"frontmatter":{"title":"Companies, Child Companies, and Stores","description":"Map legal companies, corporate relationships, and physical locations to Cheqi","seo":{"title":"Companies, Child Companies, and Stores"}},"lastModified":"2026-07-28T00:51:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/companies/structure","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}