---
title: "Queue offline changes and resolve · Agent Wranglers"
url: https://agentwranglers.se/playbook/mobile-apps/data-on-the-device/offline-sync
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Queue offline changes and resolve conflicts on the server

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Data on the device](https://agentwranglers.se/playbook/mobile-apps/data-on-the-device.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: MOB-26
- Level: Recommended
- Chapter: [Data on the device](https://agentwranglers.se/playbook/mobile-apps/data-on-the-device)
- Rule: Save changes made offline in a local queue and send them in order when the network returns. Each change carries an idempotency key and the version it was based on.
- How: Mobile networks drop often, so a lost reply must not mean a lost or doubled change. Write the change to the local database and the queue in one transaction, then show it at once. Send each queued change with an idempotency key, as [accept idempotency keys on POST](https://agentwranglers.se/playbook/api-design/reliability/idempotency-keys) says. Send the version the change was based on, and let the server refuse stale ones, as [never save over a newer version](https://agentwranglers.se/playbook/app-ui/forms/edit-conflicts) says. Show the person each conflict instead of dropping their change. Tell people they are offline as [say when the network is gone](https://agentwranglers.se/playbook/app-ui/permissions-flags-and-failures/offline-behaviour) describes.
- Check: In airplane mode, make 5 changes, then restore the network and drop the first reply. The server holds each change once. A change to a record edited elsewhere shows a conflict.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### TypeScript example

```ts
async function saveOffline(change: Change) {
  await db.transaction(async tx => {
    await tx.workouts.put(change.record);
    await tx.outbox.add({ ...change, idempotencyKey: crypto.randomUUID(), baseVersion: change.record.version });
  });
  void flushOutbox();
}
```

### Kotlin example

```kotlin
suspend fun saveOffline(change: Change) = db.withTransaction {
    db.workouts().upsert(change.record)
    db.outbox().insert(OutboxItem(change, idempotencyKey = UUID.randomUUID().toString(), baseVersion = change.record.version))
}
```

## Related rules

- [Accept idempotency keys on POST](https://agentwranglers.se/playbook/api-design/reliability/idempotency-keys) in API design
- [Never save over a newer version](https://agentwranglers.se/playbook/app-ui/forms/edit-conflicts) in App interface
- [Say when the network is gone](https://agentwranglers.se/playbook/app-ui/permissions-flags-and-failures/offline-behaviour) in App interface

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/mobile-apps/data-on-the-device/offline-sync">Agent Wranglers mobile apps playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Wipe local data at sign-out](https://agentwranglers.se/playbook/mobile-apps/data-on-the-device/wipe-on-sign-out)
- [Data on the device](https://agentwranglers.se/playbook/mobile-apps/data-on-the-device)