openapi: 3.0.1
info:
  title: Terminal Shop Address View API
  description: Public REST API for Terminal, a developer-focused coffee company. The API powers product browsing, carts, orders, subscriptions, addresses, cards, profiles, personal access tokens, and OAuth apps - the same surface behind the `ssh terminal.shop` storefront and the official SDKs. All monetary amounts are integers in US cents. Authentication is a Bearer personal access token (`trm_live_*` in production, `trm_test_*` in the dev sandbox) or an OAuth 2.0 access token.
  termsOfService: https://www.terminal.shop/terms
  contact:
    name: Terminal Support
    url: https://www.terminal.shop
  version: '1.0'
servers:
- url: https://api.terminal.shop
  description: Production
- url: https://api.dev.terminal.shop
  description: Dev sandbox (no real charges)
security:
- bearerAuth: []
tags:
- name: View
paths:
  /view/init:
    get:
      operationId: initView
      tags:
      - View
      summary: Get app data
      description: Get all data needed to render the Terminal storefront app in a single request - region plus the current user's products, profile, addresses, cards, cart, orders, subscriptions, tokens, and apps.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/InitView'
components:
  schemas:
    Address:
      type: object
      required:
      - id
      - city
      - country
      - created
      - name
      - street1
      - zip
      properties:
        id:
          type: string
        city:
          type: string
        country:
          type: string
        created:
          type: string
        name:
          type: string
        street1:
          type: string
        street2:
          type: string
        zip:
          type: string
        province:
          type: string
        phone:
          type: string
    ProductTags:
      type: object
      properties:
        app:
          type: string
        color:
          type: string
        featured:
          type: boolean
        market_eu:
          type: boolean
        market_global:
          type: boolean
        market_na:
          type: boolean
    Profile:
      type: object
      required:
      - user
      properties:
        user:
          type: object
          required:
          - id
          - email
          - fingerprint
          - name
          - stripeCustomerID
          properties:
            id:
              type: string
            email:
              type: string
              nullable: true
            fingerprint:
              type: string
              nullable: true
            name:
              type: string
              nullable: true
            stripeCustomerID:
              type: string
    OrderItem:
      type: object
      required:
      - id
      - amount
      - quantity
      properties:
        id:
          type: string
        amount:
          type: integer
          format: int64
        quantity:
          type: integer
          format: int64
        description:
          type: string
        productVariantID:
          type: string
    CartShipping:
      type: object
      properties:
        service:
          type: string
        timeframe:
          type: string
    ProductVariant:
      type: object
      required:
      - id
      - name
      - price
      properties:
        id:
          type: string
        name:
          type: string
        price:
          type: integer
          format: int64
          description: Price of the variant in US cents.
        tags:
          type: object
          additionalProperties: true
    CardExpiration:
      type: object
      required:
      - month
      - year
      properties:
        month:
          type: integer
          format: int64
        year:
          type: integer
          format: int64
    Token:
      type: object
      required:
      - id
      - token
      - created
      properties:
        id:
          type: string
        token:
          type: string
          description: Masked or full token identifier.
        created:
          type: string
    Card:
      type: object
      required:
      - id
      - brand
      - created
      - expiration
      - last4
      properties:
        id:
          type: string
        brand:
          type: string
        created:
          type: string
        last4:
          type: string
        expiration:
          $ref: '#/components/schemas/CardExpiration'
    Product:
      type: object
      required:
      - id
      - name
      - description
      - variants
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/ProductVariant'
        order:
          type: integer
          format: int64
          description: Sort order of the product.
        subscription:
          type: string
          enum:
          - allowed
          - required
          description: Whether subscriptions are allowed or required for this product.
        tags:
          $ref: '#/components/schemas/ProductTags'
    OrderAmount:
      type: object
      required:
      - shipping
      - subtotal
      properties:
        shipping:
          type: integer
          format: int64
        subtotal:
          type: integer
          format: int64
    SubscriptionSchedule:
      oneOf:
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - fixed
          interval:
            type: integer
            format: int64
      - type: object
        required:
        - type
        - interval
        properties:
          type:
            type: string
            enum:
            - weekly
          interval:
            type: integer
            format: int64
            description: Number of weeks between orders.
    InitView:
      type: object
      required:
      - region
      - products
      - profile
      - addresses
      - cards
      - cart
      - orders
      - subscriptions
      - tokens
      - apps
      properties:
        region:
          type: string
          enum:
          - eu
          - na
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        profile:
          $ref: '#/components/schemas/Profile'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        cards:
          type: array
          items:
            $ref: '#/components/schemas/Card'
        cart:
          $ref: '#/components/schemas/Cart'
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
        apps:
          type: array
          items:
            $ref: '#/components/schemas/App'
    Subscription:
      type: object
      required:
      - id
      - productVariantID
      - quantity
      - addressID
      - cardID
      - created
      - price
      properties:
        id:
          type: string
        productVariantID:
          type: string
        quantity:
          type: integer
          format: int64
        addressID:
          type: string
        cardID:
          type: string
        created:
          type: string
        price:
          type: integer
          format: int64
          description: Price of the subscription line in cents.
        next:
          type: string
          description: Next scheduled order date.
        schedule:
          $ref: '#/components/schemas/SubscriptionSchedule'
    OrderShipping:
      type: object
      required:
      - city
      - country
      - name
      - street1
      - zip
      properties:
        city:
          type: string
        country:
          type: string
        name:
          type: string
        street1:
          type: string
        street2:
          type: string
        zip:
          type: string
        province:
          type: string
        phone:
          type: string
    OrderTracking:
      type: object
      properties:
        number:
          type: string
        service:
          type: string
        status:
          type: string
          enum:
          - PRE_TRANSIT
          - TRANSIT
          - DELIVERED
          - RETURNED
          - FAILURE
          - UNKNOWN
        statusDetails:
          type: string
        statusUpdatedAt:
          type: string
        url:
          type: string
    CartItem:
      type: object
      required:
      - id
      - productVariantID
      - quantity
      - subtotal
      properties:
        id:
          type: string
        productVariantID:
          type: string
        quantity:
          type: integer
          format: int64
        subtotal:
          type: integer
          format: int64
    Order:
      type: object
      required:
      - id
      - amount
      - created
      - items
      - shipping
      - tracking
      properties:
        id:
          type: string
        amount:
          $ref: '#/components/schemas/OrderAmount'
        created:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        shipping:
          $ref: '#/components/schemas/OrderShipping'
        tracking:
          $ref: '#/components/schemas/OrderTracking'
        index:
          type: integer
          format: int64
    Cart:
      type: object
      required:
      - items
      - subtotal
      - amount
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
        subtotal:
          type: integer
          format: int64
          description: Subtotal of the items in the cart, in cents.
        amount:
          $ref: '#/components/schemas/CartAmount'
        addressID:
          type: string
        cardID:
          type: string
        shipping:
          $ref: '#/components/schemas/CartShipping'
    App:
      type: object
      required:
      - id
      - name
      - redirectURI
      - secret
      properties:
        id:
          type: string
        name:
          type: string
        redirectURI:
          type: string
        secret:
          type: string
    CartAmount:
      type: object
      required:
      - subtotal
      properties:
        subtotal:
          type: integer
          format: int64
        shipping:
          type: integer
          format: int64
        total:
          type: integer
          format: int64
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Personal access token (`trm_live_*` in production, `trm_test_*` in the dev sandbox) or OAuth 2.0 access token, passed as `Authorization: Bearer <token>`.'