Xero

Go to developer.xero.com and sign in with your Xero credentials. Click **New app** in the top right. Give it a name (e.g. 'Bubble Integration'), select **Web app** as the integration type, set your company or application name and URL. In the app's OAuth 2.0 credentials section, you will find your **Client ID** and **Client Secret**. Copy both — you will need them for the authorization URL and token exchange. Under **Redirect URIs**, click Add and enter your Bubble callback page URL: `https://your-app.bubbleapps.io/xero-callback` (adjust to your actual app domain). Save the app. In your Bubble editor, create a new page named `xero-callback`. This page will handle the OAuth redirect from Xero. Keep it visually minimal — users see it for only a moment before being redirected to your main dashboard. In the Bubble Data tab, add these fields to the User data type: - `xero_access_token` (text) - `xero_refresh_token` (text) - `xero_tenant_id` (text) - `xero_token_issued_at` (date) Go to the **Privacy** tab, click User, and add a rule: 'This User is Current User' — mark all four xero_ fields as readable only by the owner. This prevents token leakage between users of your app.

1// Bubble User data type — new fields
2{
3  "xero_access_token": "text",
4  "xero_refresh_token": "text",
5  "xero_tenant_id": "text",       // Retrieved from GET /connections after OAuth
6  "xero_token_issued_at": "date"  // For 25-minute refresh check
7}
8
9// Privacy rule:
10// When: This User is Current User
11// Read: xero_access_token, xero_refresh_token, xero_tenant_id, xero_token_issued_at

Add a **Button** element to your main page with the text 'Connect Xero'. Add a workflow to this button with one action: **Navigate → Open an external URL**. The Xero OAuth authorization URL format: `https://login.xero.com/identity/connect/authorize?response_type=code&client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&scope=openid profile email accounting.transactions accounting.contacts offline_access&state=[STATE]` Key scopes to include: - `accounting.transactions` — read/write invoices, bank transactions, payments - `accounting.contacts` — read/write contacts (customers, suppliers) - `offline_access` — required to receive a refresh token; without this, users must re-authorize every 30 minutes - `openid profile email` — standard OIDC scopes for user identification Build this URL dynamically in Bubble's workflow: 1. Base: `https://login.xero.com/identity/connect/authorize` 2. Append `?response_type=code&client_id=` + your Xero Client ID 3. `&redirect_uri=` + URL-encoded callback page URL 4. `&scope=openid+profile+email+accounting.transactions+accounting.contacts+offline_access` 5. `&state=` + Current User's Unique ID (CSRF protection) The `offline_access` scope is mandatory for the refresh token — if you omit it, the token response from Xero will not include a refresh_token, and users will need to re-authorize every 30 minutes.

1// Xero OAuth Authorization URL
2https://login.xero.com/identity/connect/authorize
3  ?response_type=code
4  &client_id=<YOUR_CLIENT_ID>
5  &redirect_uri=https%3A%2F%2Fyour-app.bubbleapps.io%2Fxero-callback
6  &scope=openid+profile+email+accounting.transactions+accounting.contacts+offline_access
7  &state=<Current User Unique ID>
8
9// Xero redirects to callback with:
10https://your-app.bubbleapps.io/xero-callback
11  ?code=ABC123def456
12  &scope=openid+profile+email+accounting.transactions+accounting.contacts+offline_access
13  &session_state=xyz
14  &state=<same_state_value>

This is the most important step. The /xero-callback page must do three things in sequence: extract the authorization code, exchange it for tokens, and immediately call GET /connections to retrieve the tenantId. All three must happen in one Backend Workflow to be atomic. Create a Backend Workflow named 'Xero OAuth Complete'. On your xero-callback page, add a workflow 'When page is loaded → Run Backend Workflow → Xero OAuth Complete'. The Backend Workflow steps: **Step 1 — Extract the code:** Use 'Get data from page URL' → parameter name `code`. Store as a local workflow parameter. **Step 2 — Token exchange POST:** - URL: `https://identity.xero.com/connect/token` - Method: POST - Headers: `Authorization: Basic [base64(clientId:clientSecret)]`, `Content-Type: application/x-www-form-urlencoded` - Body: `grant_type=authorization_code&code=[code]&redirect_uri=[your_callback_url]` - Response: access_token, refresh_token (60-day inactivity expiry), expires_in (1800 seconds) **Step 3 — IMMEDIATELY call GET /connections with the new token:** - URL: `https://api.xero.com/connections` - Method: GET - Header: `Authorization: Bearer [access_token from step 2]` - Response: array of connected tenants, each with tenantId, tenantName, tenantType - Extract: `[0].tenantId` (first tenant) or let users choose if they have multiple Xero organizations **Step 4 — Save all three values atomically:** In one 'Make changes to Current User' step: - xero_access_token = token response.access_token - xero_refresh_token = token response.refresh_token - xero_tenant_id = connections response.[0].tenantId - xero_token_issued_at = Current date/time Then navigate to your main dashboard page.

1// Step 1: Token exchange
2{
3  "method": "POST",
4  "url": "https://identity.xero.com/connect/token",
5  "headers": {
6    "Authorization": "Basic <base64(clientId:clientSecret)>",
7    "Content-Type": "application/x-www-form-urlencoded"
8  },
9  "body": "grant_type=authorization_code&code=<code>&redirect_uri=<callback_url>"
10}
11
12// Token response:
13{
14  "access_token": "eyJhbGciOiJSU...",
15  "expires_in": 1800,
16  "token_type": "Bearer",
17  "refresh_token": "Ix8B7O8ndBzMs..."
18}
19
20// Step 2: GET /connections (immediately after)
21{
22  "method": "GET",
23  "url": "https://api.xero.com/connections",
24  "headers": {
25    "Authorization": "Bearer <access_token from above>"
26  }
27}
28
29// Connections response:
30[
31  {
32    "id": "abc123-def456-...",
33    "tenantId": "94e98484-7c28-4f6b-90e9-e8ea1e2e5432",
34    "tenantName": "Demo Company (AU)",
35    "tenantType": "ORGANISATION"
36  }
37]

In the Bubble editor, go to **Plugins → API Connector**. Click **Add another API** and name it 'Xero'. Set the base URL to `https://api.xero.com/api.xro/2.0`. In the **Shared headers** section, add two headers: **Header 1 — Authorization (Private):** - Name: `Authorization` - Value: `Bearer [access_token]` where `[access_token]` is a parameter placeholder - Check the **Private** checkbox — this prevents the token from appearing in browser requests **Header 2 — Xero-tenant-id:** - Name: `Xero-tenant-id` - Value: `[tenant_id]` where `[tenant_id]` is a parameter placeholder - Do NOT mark this as Private (tenant IDs are identifiers, not secrets) — but DO populate it from the User's stored xero_tenant_id field at call time Add a third shared header: `Accept: application/json`. Without this, Xero returns XML which Bubble cannot parse. Now add the Initialize Call: click **Add a call**, name it 'Get Organisation'. Set method to GET, path to `/Organisation`. Set **Use as: Data**. In the test parameter fields, enter a valid access_token and the stored tenantId from your test user account. Click **Initialize call**. A successful 200 response returns your Xero organization name, country, and financial year settings. If you get 403, the tenant ID is wrong or missing. If you get 401, the access token has expired — you need to run the token refresh workflow first to get a fresh token.

1// API Connector — Xero group configuration
2{
3  "api_name": "Xero",
4  "base_url": "https://api.xero.com/api.xro/2.0",
5  "shared_headers": [
6    {
7      "name": "Authorization",
8      "value": "Bearer <access_token>",
9      "private": true   // Token stays server-side
10    },
11    {
12      "name": "Xero-tenant-id",
13      "value": "<tenant_id>"  // NOT private — but populate from User record
14    },
15    {
16      "name": "Accept",
17      "value": "application/json"
18    }
19  ]
20}
21
22// Initialize Call — GET /Organisation:
23{
24  "method": "GET",
25  "path": "/Organisation",
26  "use_as": "Data"
27}
28
29// Expected response:
30{
31  "Organisations": [
32    {
33      "Name": "Demo Company (AU)",
34      "LegalName": "Demo Company (AU)",
35      "CountryCode": "AU",
36      "BaseCurrency": "AUD",
37      "FinancialYearEndDay": 31,
38      "FinancialYearEndMonth": 3
39    }
40  ]
41}

Add the invoice list call: click **Add a call** in your Xero API group, name it 'Get Invoices'. Set method to GET, path to `/Invoices`. Add query parameters: - `Status`: AUTHORISED (filter to approved invoices; other options: DRAFT, SUBMITTED, VOID, PAID) - `order`: DueDate ASC (sort by due date) - `page`: 1 (Xero uses page-based pagination, 100 records per page) Xero's 60 calls/minute rate limit applies per tenant. For a Repeating Group loading a paginated invoice list, stay well within this limit by caching the results in Bubble's database rather than fetching live on every page load. **Handling Xero's date format.** Xero returns dates in a non-standard format: `/Date(1703548800000+0000)/`. This is not ISO 8601 — it is milliseconds since epoch wrapped in a string. To display it in Bubble, use the following expression chain: 1. Get the date string field from the API response (e.g. `DueDate`: '/Date(1703548800000+0000)/') 2. In Bubble, use `:extract with regex` with the pattern `(\d+)` to extract just the number 3. The number is in milliseconds — divide by 1000 to get a Unix timestamp in seconds 4. Use Bubble's `:formatted as date` to display it For the POST /Invoices call (creating invoices): set method to POST, path to `/Invoices`, Use as: Action. The request body must include Type (ACCREC for accounts receivable invoice), Contact (with ContactID), LineItems array, and DueDate. Add a contact call: GET `/Contacts` with a `searchTerm` parameter for customer lookup when building the invoice creation form.

1// GET /Invoices — call configuration
2{
3  "method": "GET",
4  "path": "/Invoices",
5  "params": {
6    "Status": "AUTHORISED",
7    "order": "DueDate ASC",
8    "page": "1"
9  },
10  "use_as": "Data"
11}
12
13// Xero date format — non-standard:
14// Raw: "/Date(1703548800000+0000)/"
15// Bubble: :extract with regex (\d+) → "1703548800000" → divide by 1000 → formatted as date
16
17// POST /Invoices — create invoice body
18{
19  "Type": "ACCREC",
20  "Contact": {
21    "ContactID": "<contact_id>"
22  },
23  "LineItems": [
24    {
25      "Description": "Consulting services",
26      "Quantity": 1.0,
27      "UnitAmount": 500.00,
28      "AccountCode": "200"
29    }
30  ],
31  "DueDate": "/Date(1703548800000+0000)/",
32  "Status": "AUTHORISED"
33}
34
35// Invoice response item:
36{
37  "InvoiceID": "abc123-def456-...",
38  "InvoiceNumber": "INV-0001",
39  "Total": 500.00,
40  "AmountDue": 500.00,
41  "DueDate": "/Date(1703548800000+0000)/"
42}

Xero access tokens expire in 30 minutes. To avoid mid-workflow 401 errors when a user is actively using your app, build a refresh check that runs at the start of every workflow touching Xero. In Bubble's Backend Workflows, create a new workflow named 'Refresh Xero Token'. This workflow runs as the current user. Workflow steps: 1. **Condition**: Only proceed if `Current User's xero_token_issued_at` is more than 25 minutes ago (5-minute buffer). Use Bubble's date comparison: `xero_token_issued_at < Current date/time - 25 minutes`. 2. **POST to the Xero refresh endpoint:** - URL: `https://identity.xero.com/connect/token` - Headers: `Authorization: Basic [base64(clientId:clientSecret)]`, `Content-Type: application/x-www-form-urlencoded` - Body: `grant_type=refresh_token&refresh_token=[Current User's xero_refresh_token]` 3. **Save the new access_token** (and optionally the refresh_token if Xero issued a new one — Xero does NOT rotate refresh tokens, but include the save in case behavior changes): In one 'Make changes to Current User' step, set xero_access_token to the response access_token and xero_token_issued_at to current date/time. Note: Unlike QuickBooks, Xero's refresh tokens do NOT rotate on each use. The same refresh_token remains valid for 60 days of inactivity. This means a failed access_token save is less catastrophic — you can retry using the same refresh_token. Still, save atomically as a best practice. At the start of every Bubble workflow that calls a Xero endpoint, add 'Run Backend Workflow → Refresh Xero Token' as the first action. This keeps your access tokens fresh automatically. RapidDev's team has built Bubble apps with complex OAuth patterns like this — if you want a free architecture review before going live, visit rapidevelopers.com/contact.

1// Xero token refresh POST
2{
3  "method": "POST",
4  "url": "https://identity.xero.com/connect/token",
5  "headers": {
6    "Authorization": "Basic <base64(clientId:clientSecret)>",
7    "Content-Type": "application/x-www-form-urlencoded"
8  },
9  "body": "grant_type=refresh_token&refresh_token=<Current User's xero_refresh_token>"
10}
11
12// Refresh response:
13{
14  "access_token": "eyJhbGciOiJSU...",  // NEW access token
15  "expires_in": 1800,
16  "token_type": "Bearer",
17  "refresh_token": "Ix8B7O8ndBzMs..."  // Same or new refresh token
18}
19
20// Bubble Backend Workflow condition:
21// When: Current User's xero_token_issued_at < Current date/time - 25 minutes
22// Action: Make changes to Current User
23//   xero_access_token = response.access_token
24//   xero_token_issued_at = Current date/time
25
26// Note: Xero refresh tokens do NOT rotate — same token valid 60 days inactivity
27// (Compare QuickBooks which invalidates on each use)