{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer-resources/ingrid-api/guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Rendering the address form","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"rendering-the-address-form","__idx":0},"children":["Rendering the address form"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The address form endpoint returns everything your client needs to render a"," ","localized address form for any supported country — field definitions, validation"," ","rules, keyboard hints, and layout. Instead of hardcoding per-country form logic,"," ","your client renders what the API tells it to."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An Ingrid API key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A country code for the customer's destination (typically from their cart or"," ","session)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":2},"children":["Overview"]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n participant C as Checkout\n participant I as Ingrid API\n\n C->>I: GET /address/form?countryCode=SE\n I-->>C: fields, layout, validationRules\n\n Note over C: Render form using layout order\n\n C->>I: GET /address/form?countryCode=SE&postalCode=11453\n I-->>C: fields + values (locality pre-filled)\n\n Note over C: Update form with pre-filled values\n","diagramHtml":"
Ingrid APICheckoutIngrid APICheckoutRender form using layout orderUpdate form with pre-filled valuesGET /address/form?countryCode=SEfields, layout, validationRulesGET /address/form?countryCode=SE&postalCode=11453fields + values (locality pre-filled)
"},"children":["sequenceDiagram\n participant C as Checkout\n participant I as Ingrid API\n\n C->>I: GET /address/form?countryCode=SE\n I-->>C: fields, layout, validationRules\n\n Note over C: Render form using layout order\n\n C->>I: GET /address/form?countryCode=SE&postalCode=11453\n I-->>C: fields + values (locality pre-filled)\n\n Note over C: Update form with pre-filled values\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-request-the-form-configuration","__idx":3},"children":["Step 1: Request the form configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call the form endpoint with the customer's country code:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Request","header":{"title":"Request","controls":{"copy":{}}},"source":"curl -X GET \"https://api.ingrid.com/v1/delivery/address/form?countryCode=SE\" \\\n -H \"Authorization: Bearer \"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response","header":{"title":"Response","controls":{"copy":{}}},"source":"{\n \"meta\": {\n \"countryCode\": \"SE\",\n \"direction\": \"ltr\",\n \"language\": \"sv-SE\"\n },\n \"fields\": {\n \"postalCode\": {\n \"label\": \"Postnummer\",\n \"required\": true,\n \"uiType\": \"text\",\n \"hint\": \"123 45\",\n \"keyboard\": \"numeric\",\n \"autocomplete\": \"postal-code\",\n \"validationRegex\": \"^\\\\d{3}\\\\s?\\\\d{2}$\",\n \"errorMessage\": \"Ange ett giltigt postnummer (5 siffror)\"\n },\n \"addressLines\": {\n \"label\": \"Gatuadress\",\n \"required\": true,\n \"uiType\": \"text\",\n \"hint\": \"Sveavägen 1\",\n \"keyboard\": \"default\",\n \"autocomplete\": \"street-address\"\n },\n \"locality\": {\n \"label\": \"Ort\",\n \"required\": true,\n \"uiType\": \"text\",\n \"hint\": \"Stockholm\",\n \"keyboard\": \"default\",\n \"autocomplete\": \"address-level2\"\n }\n },\n \"layout\": [\n [\"postalCode\"],\n [\"addressLines\"],\n [\"locality\"]\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains three key parts:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Part"},"children":["Part"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it is"},"children":["What it is"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How to use it"},"children":["How to use it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country, text direction, language"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Set text direction on your form container. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["language"]}," for locale-aware formatting."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A dictionary of field definitions keyed by field name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["required"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uiType"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validationRegex"]},", and other properties per field."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A 2D grid — outer array is rows, inner array is columns"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Iterate this for render order"]},", not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]},". Each string references a key in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-render-the-form","__idx":4},"children":["Step 2: Render the form"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Iterate the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layout"]}," array to determine which fields to render and in what"," ","order. Each row in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layout"]}," is an array of field names that should appear on the"," ","same line."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For each field name in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layout"]},", look up its definition in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," and render"," ","the appropriate UI component:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"uiType value"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uiType"]}," value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Render as"},"children":["Render as"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Text input. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["keyboard"]}," for mobile keyboard type and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hint"]}," for placeholder text."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["select"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dropdown or picker. Populate with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," array from the field definition."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hidden"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hidden field. Include the value in form submission but do not display."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Iterate layout, not fields"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["layout"]}," for rendering order. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," dictionary is unordered"," ","and may contain fields not intended for display in the current layout."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-pre-fill-from-postal-code","__idx":5},"children":["Step 3: Pre-fill from postal code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the customer enters a postal code, re-fetch the form configuration with"," ","both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalCode"]},". The response may include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]}," object"," ","with pre-filled data:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Request","header":{"title":"Request","controls":{"copy":{}}},"source":"curl -X GET \"https://api.ingrid.com/v1/delivery/address/form?countryCode=SE&postalCode=11453\" \\\n -H \"Authorization: Bearer \"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response (values only)","header":{"title":"Response (values only)","controls":{"copy":{}}},"source":"{\n \"values\": {\n \"locality\": \"Stockholm\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]}," is present, update the corresponding form fields with the"," ","pre-filled data. This saves the customer from typing their city manually."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Not all countries support pre-fill from postal code. If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]}," is absent or"," ","empty, leave the fields editable as normal."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-validate-client-side","__idx":6},"children":["Step 4: Validate client-side"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validationRegex"]}," from each field definition for instant client-side"," ","validation before form submission. If validation fails, display the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMessage"]}," from the field definition."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a first pass only. For thorough verification against postal reference"," ","data, use the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-validation"},"children":["address validation endpoint"]}," after the"," ","customer completes the form."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"re-fetch-on-country-change","__idx":7},"children":["Re-fetch on country change"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the customer changes their country, you MUST re-fetch the form configuration"," ","with the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]},". Different countries have different fields, layout,"," ","validation rules, and languages. Do not cache form configurations across"," ","countries."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":8},"children":["Error handling"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it occurs"},"children":["When it occurs"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]}," parameter"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500 Internal Server Error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server-side issue — retry with exponential backoff"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":9},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-autocomplete"},"children":["Address autocomplete"]}," — add type-ahead search to"," ","the address form"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-validation"},"children":["Address validation"]}," — verify the address before"," ","creating an order"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/country-reference"},"children":["Country reference"]}," — country-specific field"," ","requirements and formatting rules"]}]}]},"headings":[{"value":"Rendering the address form","id":"rendering-the-address-form","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Overview","id":"overview","depth":2},{"value":"Step 1: Request the form configuration","id":"step-1-request-the-form-configuration","depth":2},{"value":"Step 2: Render the form","id":"step-2-render-the-form","depth":2},{"value":"Step 3: Pre-fill from postal code","id":"step-3-pre-fill-from-postal-code","depth":2},{"value":"Step 4: Validate client-side","id":"step-4-validate-client-side","depth":2},{"value":"Re-fetch on country change","id":"re-fetch-on-country-change","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Rendering the Address Form","description":"How to render a localized address form using the server-driven form endpoint","seo":{"title":"Rendering the address form"}},"lastModified":"2026-02-24T19:14:57.409Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-resources/ingrid-api/guides/address-form","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}