{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer-resources/ingrid-api/guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["json-schema"]},"type":"markdown"},"seo":{"title":"Working with addresses","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"working-with-addresses","__idx":0},"children":["Working with addresses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Addresses are the starting point for every delivery integration. Before Ingrid"," ","can return delivery options, it needs to know where the customer is. This guide"," ","explains the address model, the server-driven form system, and how the address"," ","endpoints fit into your checkout."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-address-model","__idx":1},"children":["The address model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Ingrid API uses two address models: a base ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Address"]}," for physical locations"," ","and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DeliveryAddress"]}," that extends it with delivery-specific fields."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"address","__idx":2},"children":["Address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The base model for any physical location — warehouses, pickup points, or"," ","anywhere you need to represent a place."]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../@latest/openapi.yaml#/components/schemas/Address"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/Address"},"AddressType":{"type":"string","enum":["unknown","residential","commercial"]},"Address":{"type":"object","required":["countryCode","postalCode"],"properties":{"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code.","examples":["SE"]},"postalCode":{"type":"string","description":"Postal code.\nFormatting and validation rules are conditional and based on the country code.","examples":["12345"]},"administrativeArea":{"type":"string","description":"Required for countries:\n##### North America\n* **US** (United States) - *State*\n* **CA** (Canada) - *Province/Territory*\n* **MX** (Mexico) - *State (Estado)*\n\n##### South America\n* **BR** (Brazil) - *State (Estado)* \n* **AR** (Argentina) - *Province*\n\n##### Asia Pacific\n* **AU** (Australia) - *State/Territory*\n* **CN** (China) - *Province*\n* **JP** (Japan) - *Prefecture* \n* **MY** (Malaysia) - *State*\n* **KR** (South Korea) - *Province/City-Province*\n* **ID** (Indonesia) - *Province*\n* **TH** (Thailand) - *Province (Changwat)*\n\n##### Europe\n* **IT** (Italy) - *Province* (2-letter abbreviation like MI, RM)\n* **ES** (Spain) - *Province* \n* **IE** (Ireland) - *County*"},"subAdministrativeArea":{"type":"string","description":"Usually the District, Suburb, or Neighborhood.\nTypically not required unless explicitly specified in our documentation."},"locality":{"type":"string","description":"The primary locality of the address.\nUsually the City, Town, Village, or Municipality.","examples":["San Francisco","Stockholm"]},"subLocality":{"type":"string","description":"The neighborhood, suburb, or district within the locality.\nTypically not required unless explicitly specified in our documentation.\n\nCritical for:\n- Japan (chome/district names)\n- UK (London districts like \"Soho\" or \"Brixton\")\n- Latin America (colonia)"},"addressLines":{"type":"array","items":{"type":"string"},"description":"An ordered array of street address lines.\nIndex 0: Primary street info (Street name + Number, or Block number).\nIndex 1+: Secondary info (Apartment, Suite, Floor, Building Name).","examples":[["Gatan 1","1602"],["123 Market Street","Floor 2, Apt 4B"],["Sveavägen 1"]]},"type":{"$ref":"#/components/schemas/AddressType"}},"description":"Represents a physical location in a global context.\nDesigned to be generic enough for international addressing standards\n\nValidation is conditional and based on the country code."}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalCode"]}," are always required. Other fields are"," ","conditionally required depending on the country — see the"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/country-reference"},"children":["country reference"]}," for details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deliveryaddress","__idx":3},"children":["DeliveryAddress"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Address"]}," with fields specific to delivering a package to a person."," ","Used for the customer's destination in delivery options and order creation."]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../@latest/openapi.yaml#/components/schemas/DeliveryAddress"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/DeliveryAddress"},"AddressType":{"type":"string","enum":["unknown","residential","commercial"]},"DeliveryAddress":{"type":"object","required":["countryCode","postalCode"],"properties":{"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code.","examples":["SE"]},"postalCode":{"type":"string","description":"Postal code.\nFormatting and validation rules are conditional and based on the country code.","examples":["12345"]},"administrativeArea":{"type":"string","description":"Required for countries:\n##### North America\n* **US** (United States) - *State*\n* **CA** (Canada) - *Province/Territory*\n* **MX** (Mexico) - *State (Estado)*\n\n##### South America\n* **BR** (Brazil) - *State (Estado)* \n* **AR** (Argentina) - *Province*\n\n##### Asia Pacific\n* **AU** (Australia) - *State/Territory*\n* **CN** (China) - *Province*\n* **JP** (Japan) - *Prefecture* \n* **MY** (Malaysia) - *State*\n* **KR** (South Korea) - *Province/City-Province*\n* **ID** (Indonesia) - *Province*\n* **TH** (Thailand) - *Province (Changwat)*\n\n##### Europe\n* **IT** (Italy) - *Province* (2-letter abbreviation like MI, RM)\n* **ES** (Spain) - *Province* \n* **IE** (Ireland) - *County*"},"subAdministrativeArea":{"type":"string","description":"Usually the District, Suburb, or Neighborhood.\nTypically not required unless explicitly specified in our documentation."},"locality":{"type":"string","description":"The primary locality of the address.\nUsually the City, Town, Village, or Municipality.","examples":["San Francisco","Stockholm"]},"subLocality":{"type":"string","description":"The neighborhood, suburb, or district within the locality.\nTypically not required unless explicitly specified in our documentation.\n\nCritical for:\n- Japan (chome/district names)\n- UK (London districts like \"Soho\" or \"Brixton\")\n- Latin America (colonia)"},"addressLines":{"type":"array","items":{"type":"string"},"description":"An ordered array of street address lines.\nIndex 0: Primary street info (Street name + Number, or Block number).\nIndex 1+: Secondary info (Apartment, Suite, Floor, Building Name).","examples":[["Gatan 1","1602"],["123 Market Street","Floor 2, Apt 4B"],["Sveavägen 1"]]},"type":{"$ref":"#/components/schemas/AddressType"},"instructions":{"type":"string","description":"Additional instructions for the delivery.","examples":["Portkod 4499. Våning 5."]},"recipientName":{"type":"string","description":"The name of the recipient formatted as expected in the country it's being delivered to.","examples":["John J.Doe"]}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"where-each-model-is-used","__idx":4},"children":["Where each model is used"]},{"$$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":"Context"},"children":["Context"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Model"},"children":["Model"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer destination"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DeliveryAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/delivery/options"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/delivery/orders"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Warehouse / store origin"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fulfillmentGroups[].origins[].address"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pickup location"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Returned in delivery options and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/delivery/locations"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"server-driven-forms","__idx":5},"children":["Server-driven forms"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead of hardcoding which address fields to show for each country, you can"," ","call the address form endpoint and let the API tell your client what to render."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /v1/delivery/address/form?countryCode=SE\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Field definitions"]}," — which fields exist, their labels, validation rules,"," ","keyboard hints, and whether they are required"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Layout"]}," — a grid describing the visual order to render fields"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pre-filled values"]}," — if you also pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalCode"]},", the API can"," ","pre-fill the city and region"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This means your checkout automatically supports new countries without code"," ","changes. The API knows that Sweden needs five fields while the United States"," ","needs six (including state). Your client just renders what it's told."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-form"},"children":["address form guide"]}," for a step-by-step integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-minimum-viable-integration","__idx":6},"children":["The minimum viable integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You only need two fields to get delivery options: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalCode"]},". Everything else improves the experience but is not required to"," ","get started."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Request","header":{"title":"Request","controls":{"copy":{}}},"source":"curl -X POST https://api.ingrid.com/v1/delivery/options \\\n -H \"Authorization: Bearer \" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"purchaseCountry\": \"SE\",\n \"purchaseCurrency\": \"SEK\",\n \"externalRef\": \"cart-abc-123\",\n \"destination\": {\n \"countryCode\": \"SE\",\n \"postalCode\": \"11453\"\n },\n \"fulfillmentGroups\": [\n {\n \"items\": [\n {\n \"quantity\": 1,\n \"weight\": { \"value\": 500, \"unit\": \"g\" },\n \"dimensions\": { \"length\": 30, \"width\": 20, \"height\": 10, \"unit\": \"cm\" }\n }\n ]\n }\n ]\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Collect the full street address later — before order creation — and the customer"," ","still gets delivery options as soon as they enter their postal code."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-full-address-flow","__idx":7},"children":["The full address flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The complete address flow has four stages. Each stage is optional except"," ","fetching delivery options. Use as many as your checkout needs."]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n participant C as Checkout\n participant I as Ingrid API\n\n Note over C,I: Stage 1: Render the form\n C->>I: GET /address/form?countryCode=SE\n I-->>C: Field definitions, layout, validation rules\n\n Note over C,I: Stage 2: Autocomplete (optional)\n C->>I: GET /address/search?countryCode=SE&query=Svea\n I-->>C: Predictions\n C->>I: GET /address/details/{id}\n I-->>C: Full DeliveryAddress\n\n Note over C,I: Stage 3: Validate (recommended)\n C->>I: POST /address/validate\n I-->>C: valid / suspect / invalid + candidate\n\n Note over C,I: Stage 4: Fetch delivery options\n C->>I: POST /delivery/options\n I-->>C: Delivery groups, categories, services\n","diagramHtml":"
Ingrid APICheckoutIngrid APICheckoutStage 1: Render the formStage 2: Autocomplete (optional)Stage 3: Validate (recommended)Stage 4: Fetch delivery optionsGET /address/form?countryCode=SEField definitions, layout, validation rulesGET /address/search?countryCode=SE&query=SveaPredictionsGET /address/details/{id}Full DeliveryAddressPOST /address/validatevalid / suspect / invalid + candidatePOST /delivery/optionsDelivery groups, categories, services
"},"children":["sequenceDiagram\n participant C as Checkout\n participant I as Ingrid API\n\n Note over C,I: Stage 1: Render the form\n C->>I: GET /address/form?countryCode=SE\n I-->>C: Field definitions, layout, validation rules\n\n Note over C,I: Stage 2: Autocomplete (optional)\n C->>I: GET /address/search?countryCode=SE&query=Svea\n I-->>C: Predictions\n C->>I: GET /address/details/{id}\n I-->>C: Full DeliveryAddress\n\n Note over C,I: Stage 3: Validate (recommended)\n C->>I: POST /address/validate\n I-->>C: valid / suspect / invalid + candidate\n\n Note over C,I: Stage 4: Fetch delivery options\n C->>I: POST /delivery/options\n I-->>C: Delivery groups, categories, services\n"]},{"$$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":"Stage"},"children":["Stage"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required?"},"children":["Required?"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Render form"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/delivery/address/form"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get localized field definitions and layout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — you can build your own form"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Autocomplete"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/delivery/address/search"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Type-ahead address suggestions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — improves UX"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/delivery/address/validate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify and standardize the address"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No — recommended before order creation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivery options"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/delivery/options"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get available delivery services"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Yes"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":8},"children":["Related guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-form"},"children":["Rendering the address form"]}," — server-driven form integration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-autocomplete"},"children":["Address autocomplete"]}," — type-ahead search with expand/resolve"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-validation"},"children":["Address validation"]}," — verify and standardize addresses"]},{"$$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"]}]}]},"headings":[{"value":"Working with addresses","id":"working-with-addresses","depth":1},{"value":"The address model","id":"the-address-model","depth":2},{"value":"Address","id":"address","depth":3},{"value":"DeliveryAddress","id":"deliveryaddress","depth":3},{"value":"Where each model is used","id":"where-each-model-is-used","depth":3},{"value":"Server-driven forms","id":"server-driven-forms","depth":2},{"value":"The minimum viable integration","id":"the-minimum-viable-integration","depth":2},{"value":"The full address flow","id":"the-full-address-flow","depth":2},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"title":"Working with Addresses","description":"How addresses work in the Ingrid Delivery API and how they connect to delivery options and order creation","seo":{"title":"Working with addresses"}},"lastModified":"2026-02-24T19:14:57.409Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-resources/ingrid-api/guides/addresses","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}