openapi: 3.1.0
info:
  title: ItsaCheckmate Marketplace for Developers Locations OAuth API
  version: '2.2'
  description: 'ItsaCheckmate (Checkmate) is restaurant middleware that connects point-of-sale (POS) systems to delivery marketplaces and online ordering channels. The Marketplace for Developers API is an open REST API that lets technology partners build a single integration to read and write menus, orders, and locations across 50+ POS systems and 100+ ordering platforms.

    Authentication uses an OAuth-style flow: a token endpoint issues short-lived, scoped access tokens (24-hour default expiry) and refresh tokens. After obtaining a token a partner must call the Activate Location endpoint before any menu or order operation will succeed. Menu retrieval requires the `menus` scope. Order submission supports both standard and group orders via a `group_order` flag and requires a verified location.

    Endpoints documented here were confirmed from the official Checkmate developer reference (openapi-itsacheckmate.readme.io) and its llms.txt index. The reference also publishes ready-to-use Postman collections and an Update Notice webhook for real-time menu synchronization.'
  contact:
    name: ItsaCheckmate Marketplace for Developers
    url: https://openapi-itsacheckmate.readme.io/reference/getting-started
  license:
    name: ItsaCheckmate Developer Terms
    url: https://www.itsacheckmate.com/solutions/marketplace-for-developers
  x-generated-from: documentation
  x-source-url: https://openapi-itsacheckmate.readme.io/llms.txt
  x-last-validated: '2026-06-02'
servers:
- url: https://sandbox-api.itsacheckmate.com
  description: ItsaCheckmate sandbox API base URL
tags:
- name: OAuth
  description: Token issuance, refresh, and introspection.
paths:
  /oauth/token:
    post:
      tags:
      - OAuth
      operationId: createToken
      summary: ItsaCheckmate Create or Refresh Token
      description: Issues an access token and refresh token using the authorization_code grant (initial issuance) or the refresh_token grant (renewal). Access tokens expire in 24 hours by default. Tokens are scoped; the menus scope is required to call the Get Menu endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
            examples:
              CreateTokenRequestExample:
                summary: Default createToken request
                x-microcks-default: true
                value:
                  grant_type: authorization_code
                  client_id: ck_app_a1b2c3
                  client_secret: ck_secret_d4e5f6
                  redirect_uri: https://partner.example.com/oauth/callback
                  code: one_time_code_123456
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                CreateToken200Example:
                  summary: Default createToken 200 response
                  x-microcks-default: true
                  value:
                    access_token: at_a1b2c3d4e5f6
                    refresh_token: rt_g7h8i9j0k1l2
                    token_type: Bearer
                    expires_in: 86400
                    scope: menus orders
        '401':
          description: Invalid client credentials or grant
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /oauth/token/info:
    get:
      tags:
      - OAuth
      operationId: getTokenDetails
      summary: ItsaCheckmate Get Token Details
      description: Returns information about the current access token, including expiration and granted scopes, so a partner can determine when to refresh credentials before the token expires.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Token details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenInfo'
              examples:
                GetTokenDetails200Example:
                  summary: Default getTokenDetails 200 response
                  x-microcks-default: true
                  value:
                    resource_owner_id: loc_500123
                    scope:
                    - menus
                    - orders
                    expires_in: 84210
                    created_at: 1718153645
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    TokenResponse:
      title: TokenResponse
      type: object
      description: Issued access and refresh tokens.
      properties:
        access_token:
          type: string
          description: Short-lived scoped access token.
        refresh_token:
          type: string
          description: Token used to obtain a new access token.
        token_type:
          type: string
          description: Token type, always Bearer.
        expires_in:
          type: integer
          description: Lifetime of the access token in seconds. Defaults to 86400 (24 hours).
        scope:
          type: string
          description: Space-delimited list of granted scopes.
    TokenRequest:
      title: TokenRequest
      type: object
      description: OAuth-style token request body.
      required:
      - grant_type
      - client_id
      - client_secret
      properties:
        grant_type:
          type: string
          description: Grant type. Use authorization_code initially or refresh_token to renew.
          enum:
          - authorization_code
          - refresh_token
        client_id:
          type: string
          description: Client identifier from the platform app UI.
        client_secret:
          type: string
          description: Client secret from the platform app UI.
        redirect_uri:
          type: string
          description: Redirect URI. Omit for the refresh_token flow.
        code:
          type: string
          description: One-time-use authorization code. Omit for the refresh_token flow.
        refresh_token:
          type: string
          description: Refresh token. Omit for the initial authorization_code request.
    TokenInfo:
      title: TokenInfo
      type: object
      description: Introspection details for the current access token.
      properties:
        resource_owner_id:
          type: string
          description: Identifier of the location that owns the token.
        scope:
          type: array
          description: Granted scopes.
          items:
            type: string
        expires_in:
          type: integer
          description: Seconds remaining before the access token expires.
        created_at:
          type: integer
          description: Unix epoch seconds when the token was created.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth-style scoped access token issued by /oauth/token.