# Connect an external inventory to Adalo with a Codex-built adapter

Use Codex to adapt an inventory API into stable records Adalo can display, including numeric IDs, result keys, list and detail endpoints, and empty states.

- Canonical URL: https://adalocado.com/guides/codex-adalo-external-collections
- Verification: Documented from current sources
- Topic: APIs and Integrations
- Skill level: Advanced
- Last reviewed: 2026-10-26
- Builder and evidence scope: Visual builder External Collections documentation reviewed October 26, 2026; example adapter not deployed or tested in Adalo
- Verification owner: Adalocado editorial
- Next review: 2027-01-26
- Index status: index-now

## Short answer

Ask Codex to build a small adapter between the inventory API and an Adalo External Collection. Give it real sample responses and require stable numeric IDs, predictable fields, a documented results key, and matching list and detail behavior.

## Intended outcome

A read-only inventory connection in which Adalo displays products while an external system continues to own their data.

Let the inventory system own inventory and let Adalo own the browsing experience. Codex can build the small translation layer that makes those two systems agree on records, fields, and failure behavior.

## Requirements

- An Adalo builder and plan that support External Collections
- Upstream API documentation and redacted list and detail response samples
- A server repository and HTTPS staging host for the adapter
- A persistent store if the upstream service uses string IDs or UUIDs

## Step by step

1. **Choose the source of truth**

   Keep product names, availability, and images in the existing inventory system. Start with public catalog fields only. Ask Codex to list exactly what the app needs and omit supplier credentials, internal costs, and unrelated fields from the external view.

2. **Inspect actual upstream responses**

   Supply a list sample, a detail sample, an empty response, and the pagination documentation. Have Codex identify the ID type, nested fields, missing values, authentication, and error format. Do not design the adapter from a screenshot of a product table alone.

3. **Make identifiers stable**

   If upstream IDs are UUIDs or strings, create a durable mapping to unique numeric IDs for Adalo. Enforce uniqueness for both sides. Never number products by array position or recreate mappings on each request; existing detail links must keep resolving to the same product.

4. **Build a narrow read contract**

   Define GET /products and GET /products/:id. A list may return an items array of records with numeric id, name, stock, and imageUrl; a detail request resolves the same ID. Preserve zero quantities and document missing images. Leave write operations unavailable for the first release.

5. **Configure and test the External Collection**

   Use the staging adapter's base URL, required authorization, and the exact list results key, such as items. Confirm Get All and Get One methods and paths against the adapter contract. Use a representative record with populated fields for property detection, then test the sparse cases separately.

6. **Prove a list-to-detail journey**

   Display product names and stock in a list and pass the selected Product to a detail screen. Reorder the upstream inventory, restart the adapter, and reopen the same product. Confirm its identity stays unchanged before introducing search, paging, or inventory updates.

## Why it works

- An adapter changes the API's shape without making the app responsible for the upstream system's internal format. That gives you one place to normalize fields and errors.
- Stable identity is more important than a successful first list response. List rows, detail requests, and later references must all identify the same product over time.

## A reusable prompt for Codex

Use the attached inventory API docs and redacted response samples to build a read-only adapter for Adalo External Collections. First describe the contract for list, detail, empty, and error responses. Return stable numeric record IDs. If source IDs are strings, implement a persistent unique mapping; do not use array indexes. Normalize nested product fields and keep zero stock distinct from missing stock. Keep upstream credentials on the server. Bound upstream calls and document pagination rather than downloading the whole catalog. Add local fixture tests for reordered results, restart persistence, missing records, and empty data. Give me the exact base URL path, methods, Results Key, and property mapping to enter in Adalo.

Have Codex show one complete before-and-after record. A nested title inside product.details should become a predictable name field. Review that transformation with a real sample before accepting the field list; API documentation and observed data can differ.

## Why this is an External Collection

A catalog is a group of records that the interface browses and opens. An External Collection matches that job. A Custom Action is a better fit for a specific operation such as reserving stock after a user confirms a choice. Separating the two keeps the read model understandable.

The visual-builder documentation describes five configurable endpoint actions, including writes. This example deliberately implements only reading. Do not attach editable forms or invent successful write responses for an API that has no write route. Confirm unsupported operations fail rather than appearing to save.

## Handle UUIDs without losing identity

Adalo's published External Collections instructions require numeric record IDs. If the source product is prod_blue_bicycle, a mapping row might assign numeric ID 1042. The detail endpoint looks up 1042, resolves the upstream identifier, and returns that product with ID 1042 again. Treat this as persistent application data.

A shortcut such as index plus one breaks when sorting changes. A hash can collide unless collision handling is part of the design. A durable mapping with database uniqueness rules is easier to inspect. Do not reuse a deleted product's numeric ID for an unrelated product.

## Keep freshness and request volume visible

Write down whether stock is live or cached and how old a cached value may be. If the inventory service fails, distinguish temporarily unavailable stock from a genuine zero. A convincing-looking stale number is a product decision, not merely an adapter detail.

Start with fixture data and a small staging catalog. Use sequential spot checks to verify the integration, and set upstream timeouts and request bounds in the adapter. When you add pagination, inspect a real request trace from the editor; a nextCursor field in JSON does not establish that Adalo will follow it automatically.

## What still needs checking

- Original written adapter design; numeric IDs, result mapping, and pagination still need testing against the actual Adalo editor and upstream API.

## Data model

| Collection | Properties | Relationships |
| --- | --- | --- |
| Upstream Products | Source string or UUID; title; stock quantity; image URL | The upstream inventory remains the source of truth |
| Product ID Map on the server | Stable numeric ID; unique upstream ID | One persistent mapping for each upstream Product |
| Products external view in Adalo | Numeric id; name; stock; image URL | List and detail views resolve through the same adapter mapping |

## Common failures

### The list test succeeds but the app shows no products

Check whether the response is a plain array or wraps records under items, records, or another key. Set the actual Results Key and re-run property detection with a populated record.

### A saved product opens a different record later

Look for IDs derived from list positions or a mapping held only in memory. Replace that with a persistent, unique upstream-to-numeric mapping and verify the detail endpoint uses it.

### Only the first part of the inventory is visible

Inspect upstream pagination and the requests Adalo actually sends. Implement and document the supported paging or search behavior; do not fetch every upstream page on each screen load.

## Testing checklist

- [ ] The list and detail endpoints return the same stable numeric ID for a product across adapter restarts and upstream sort changes.
- [ ] An unknown product ID produces a genuine not-found response rather than the first product in the list.
- [ ] An empty inventory, a missing image, and a zero stock quantity each display intentionally.
- [ ] Filtering and pagination follow a documented contract without silently showing a partial result as a complete catalog.
- [ ] The first release rejects create, update, and delete requests because the catalog is read-only.
- [ ] The results key matches the returned JSON exactly
- [ ] List and detail routes share persistent numeric identifiers
- [ ] Public responses contain only approved catalog fields
- [ ] Write routes remain unavailable until explicitly implemented and tested

## Limitations

- This guide covers the documented visual-builder External Collections workflow; confirm support in your builder and plan.
- The proposed adapter is original design guidance, not a deployed connector or a reproduced Adalo configuration.
- External Collections do not automatically mirror data into Adalo's internal database or provide offline synchronization.
- The initial example uses a public product catalog; private data requires verified user identity and authorization on every relevant server route.
## Sources

- [OpenAI: Prompting Codex](https://learn.chatgpt.com/docs/prompting)
- [Adalo: External Collections with API](https://help.adalo.com/integrations/external-collections-with-apis)
- [Adalo: Custom Actions versus External Collections](https://help.adalo.com/integrations/custom-actions/custom-actions-vs.-external-collections)

## Changelog

- 2026-10-26: Created an external inventory example with stable ID mapping and a read-only API contract.

## Related resources

- [Build an AI listing assistant for Adalo with Codex and a Custom Action](https://adalocado.com/guides/codex-adalo-custom-actions)
- [Debug an Adalo workflow with Codex using records and evidence](https://adalocado.com/guides/codex-adalo-debugging)
- [Lists in Adalo, from data to layout](https://adalocado.com/guides/adding-styling-lists)

Markdown version: https://adalocado.com/guides/codex-adalo-external-collections.md