{"title":"Api - Liquid Tag Reference","slug":"api-tag-reference","url":"https://support.storeconnect.com/articles/api-tag-reference","url_markdown":"https://support.storeconnect.com/articles/api-tag-reference.md","subtitle":null,"summary":"The `api` block tag makes an outbound HTTP request from a Liquid template and exposes the result as a `response` object, so you can call external services without Apex.","type":"Developer_Documentation","video_url":"","keywords":"liquid, tags, api, block tag, http, request, callout, storeconnect","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"The `api` block tag makes an outbound HTTP request (an \"API callout\") from a Liquid template. It runs **server-side** during the render, so you can integrate with external services — payment providers, shipping rate calculators, auth servers, any REST endpoint — without writing Apex, and without exposing credentials to the browser.\n\nThe result of the request is available inside the block as the [`response` object](api-response-liquid-object-reference).\n\n## Syntax\n\n\n```liquid\n\n{% api url: '\u003curl\u003e', method: '\u003cmethod\u003e', headers: \u003cmap\u003e, data: \u003cmap\u003e, async: false %}\n  \u003c!-- runs after the request completes; `response` is available here --\u003e\n{% endapi %}\n```\n\n\n| Property | Value |\n|----------|-------|\n| **Tag Name** | `api` |\n| **Type** | Block tag |\n| **Source** | StoreConnect |\n\n## Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `url` | String | The endpoint to call. Required. |\n| `method` | String | The HTTP method: `'GET'`, `'POST'`, `'PUT'`, `'PATCH'`, or `'DELETE'`. |\n| `headers` | Map | Request headers. Build with a [`new` Map](new-tag-reference) — either from a JSON string or with the `set_key` filter (e.g. to add an `Authorization` header). |\n| `data` | Map | The request body, sent as JSON. Use for `POST`/`PUT`/`PATCH`. |\n| `bearer` | String | Bearer token; sent as an `Authorization: Bearer` header. |\n| `username` | String | HTTP basic-auth username (pair with `password`). |\n| `password` | String | HTTP basic-auth password. |\n| `async` | Boolean | Set `false` to make a **blocking** request so the `response` is available inside the block. With `true` the request is dispatched fire-and-forget and no `response` is returned. |\n\n## Description\n\nWhen `async: false`, the body of the block runs after the request completes and the [`response` object](api-response-liquid-object-reference) exposes `response.status`, `response.body` (parsed automatically when the endpoint returns JSON), and `response.headers`. Always check `response.status` for success before reading `response.body`.\n\n## Examples\n\n### GET request\n\n\n```liquid\n\n{% liquid\n  new Map headers = '{ \"Accept\": \"application/json\" }'\n  assign forecast = ''\n  api url: 'https://api.example.com/v1/forecast?city=denver', method: 'GET', headers: headers, async: false\n    if response.status \u003e= 200 and response.status \u003c 300\n      assign forecast = response.body.summary\n    endif\n  endapi\n%}\n{{ forecast }}\n```\n\n\n### POST request with a JSON body\n\nBuild the request body as a Map with the [`set_key`](set-key-filter-reference) filter; StoreConnect serializes it to JSON:\n\n\n```liquid\n\n{% liquid\n  new Map headers = '{ \"Content-Type\": \"application/json\", \"Accept\": \"application/json\" }'\n\n  new Map body\n  assign body = body | set_key: 'name', 'Ada Lovelace'\n  assign body = body | set_key: 'email', 'ada@example.com'\n\n  api url: 'https://api.example.com/v1/contacts', method: 'POST', headers: headers, data: body, async: false\n    if response.status \u003e= 200 and response.status \u003c 300\n      assign new_id = response.body.id\n    else\n      debug status: response.status, error: response.body\n    endif\n  endapi\n%}\n```\n\n\n### Authenticated request\n\nPass a bearer token with the `bearer` parameter — the tag adds the `Authorization: Bearer` header for you:\n\n\n```liquid\n\n{% api url: 'https://api.example.com/v1/account', method: 'GET', bearer: access_token, async: false %}\n  {% assign account = response.body %}\n{% endapi %}\n```\n\n\n## Additional recommendations\n\n- **Cache expensive or rate-limited calls.** Wrap the block in a [`cache` tag](cache-tag-reference) so the storefront does not call the external service on every render — for example, cache an auth token for less than its stated lifetime and reuse it across requests.\n- **Keep secrets server-side.** Because the callout runs during the render, API keys and secrets never reach the browser. Store them in store or theme variables rather than hardcoding them in the template.\n- **Guard on `status`.** Treat only `2xx` as success; log `response.body` on failure while developing with the [`debug` tag](debug-tag-reference)."}