Data entities

Group data

Everything related to a single group.

GroupMembersPermissionsTransactionsRecurring transactionsChangesCategoriesDebts

• Single group entities
• /groups/<groupId>/
• Sample

      "group_id_1": {
        "ownerColor": "#ec1561", // fallback when user doesn't have own color in userGroups (like in group preview)
        "convertedToCurrency": "USD",
        "inviteLink": "https://join.settleup.app/abcdefgh",
        "inviteLinkHash": "test",
        "inviteLinkActive": true,
        "minimizeDebts": true,
        "remindOldDebts": true,
        "name": "Dogfood",
        "premiumPurchasedBy": "user_id_1", // this is a premium group, purchased by user_id_1
        "premiumPurchasedUntil": 1457015264428, // time-limited group premium (lifetime if)
        "lastChanged": 1457015264428, // set automatically by server
        "defaultPermission": 10 // default permission for new members, enforced by server
      },
  

• Members are virtual entities unique per group
• /members/<groupId>/<memberId>/
• Sample

        "member_id_1": {
          "active": true, // whether to include member in new transactions
          "bankAccount": "532224564654/0100",
          "lightningAddress": "ln@settleup.io",
          "defaultWeight": "1", // 0 = check off by default in transactions, otherwise default weight in new transactions
          "name": "David",
          "photoUrl": "https://lh3.googleusercontent.com/-BNa-7Enz7G8/AAAAAAAAAAI/AAAAAAAA16I/4cLGMI6XXl4/s120-c/photo.jpg"
        },
  

• Permissions of users (NOT members)
• 30=owner, 20=read/write, 10=read-only
• /permissions/<groupId>/<uid>/
• Sample

        "user_id_1": {
          "level": 30
        }
  

• Tx can be expense or transfer. Income is expense with negative amounts.
• /transactions/<groupId>/<txId>/
• Category is an emoji, user can also assign custom names, see Categories tab
• Sample

        "expense_id_1": {
          "category": "☕", // category of the transaction, can be one of the defaults or custom one
          "currencyCode": "CZK",
          "dateTime": 1457015264428,
          "exchangeRates": {
            "EUR": "27.05", // 1 = X in currencyCode currency
            "USD": "21.70"
          },
          "fixedExchangeRate": false, // exchange rate changed manually, next transaction should be fixed as well
          "items": [ // first item main expense, second tip, third tax, you need to sum everything to get total
            {
              "amount": "200.33",
              "forWhom": [
                {
                  "memberId": "member_id_1",
                  "weight": "1"
                },
                {
                  "memberId": "member_id_2",
                  "weight": "2.3"
                }
              ]
            }
          ],
          "migrated": true, // not used anymore
          "purpose": "Pivo",
          "receiptUrl": "http://www.makereceipts.com/receipt_preview.jpg",
          "templateId": "template_id_1", // if it was generated from template (recurring or future)
          "timezone": "+01:00", // timezone of the user who created the transaction
          "type": "expense",
          "whoPaid": [
            {
              "memberId": "member_id_1",
              "weight": "1"
            }
          ]
        }
  

• These are transaction "templates" which the server will use to generate actuall transactions
• /recurringTransactions/<groupId>/<rtxId>/
• One-off are called future, repeated are recurring, but technically there is no difference
• Sample

        "template_id_1": {
          "lastGenerated": 1457015264428, // set by server
          "runCount": 3, // how many already generated, set by server
          "recurrence": {
            "startDate": 1457015264428,
            "endDate": 1457015264428,
            "timezoneOffsetMillis": 3600000, // timezone offset of the user creating the template, used to generate transaction at "appropriate" time
            "endCount": 10, // maximum generated repetitions
            "period": "daily",
            "frequency": 1, // every day
            "monthlySetting": "lastDayOfMonth", // mandatory, only for period=monthly
            "weeklySetting": [ "mon","wed","fri" ] // optional, only for period=weekly. If missing day is determined by startDate
          },
          "template": { 
            "currencyCode": "CZK",
            "exchangeRates": {
              "EUR": "27.05"
            },
            "fixedExchangeRate": true,
            "items": [
              {
                "amount": "200.33",
                "forWhom": [
                  {
                    "memberId": "member_id_1",
                    "weight": "1"
                  }
                ]
              }
            ],
            "purpose": "Pivo",
            "receiptUrl": "http://www.makereceipts.com/receipt_preview.jpg",
            "type": "expense",
            "whoPaid": [
              {
                "memberId": "member_id_1",
                "weight": "1"
              }
            ]
          }
        },
  

• Generated by server for each change in a group (someone added a member, deleted transaction, etc.)
• /changes/<groupId>/<changeId>/
• Sample

        "change_id_1": {
          "action": "insert",
          "by": "user_id_1", // this can be missing if the change was made by the server
          "entity": "expense",
          "entityId": "transaction_id_1",
          "entityName": "Pivo", // generated for the given entity type
          "serverTimestamp": 147454656
        },
  

• Custom category names
• /groupCategories/<groupId>/
• Sample

      "group_id_1": {
        "☕": "Coffee",
        "🍦": "Ice Cream"
      }
  

• Automatically generated debts by the server
• /debts/<groupId>/
• Sample

      "group_id_1": [{
        "from": "member_id_1",    
        "to": "member_id_2",
        "amount": "100.50" // amount in group currency
      },
      {
        "from": "member_id_1",    
        "to": "member_id_3",
        "amount": "100.50"
      }]
  

User data

Everything related to a single user

UsersUser Groups

• A logged in user
• /users/<uid>/
• Sample

      "user_id_1": {
        "currentTabId": "group_id_1", // NEW_GROUP or groupId
        "authProvider": "google",
        "email": "me@destil.cz",
        "inviteLinkHash": "test", // used for joining a group
        "name": "David Vávra",
        "photoUrl": "https://lh3.googleusercontent.com/-BNa-7Enz7G8/AAAAAAAAAAI/AAAAAAAA16I/4cLGMI6XXl4/s120-c/photo.jpg",
        "superuser": true,
        "locale": "en-us" // system locale or app-specific locale
      }
  

• Which groups a user is part of. This is a reverse of permissions, writing to these two locations should be atomic to prevent discrepencies
• /userGroups/<uid>/<groupId>
• Sample

        "group_id_1": {
          "order": 1,
          "color": "#ec1561", // custom color which overrides group ownerColor
          "member": "member_id_1" // "This is me" in the app, connection between member and user, multiple users can have same member, optional
        },