# http

Makes HTTP requests to external APIs and endpoints. The response is stored in a variable for further processing.

```liquid
{% http url: "https://api.example.com/data", method: "GET" as response %}

{% if response.ok %}
  {% log "Request successful: " | append: response.status %}
{% endif %}
```

#### Syntax

```liquid
{% http url: endpoint, method: http_method, headers: headers_object, body: body_object as result_variable %}
```

#### Parameters

| Parameter | Required | Description                                                                              |
| --------- | -------- | ---------------------------------------------------------------------------------------- |
| `url`     | Yes      | The endpoint URL to call                                                                 |
| `method`  | Yes      | HTTP method: `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`                           |
| `headers` | No       | Object containing request headers                                                        |
| `body`    | No       | Request payload (automatically JSON-stringified unless Content-Type specifies otherwise) |
| `raw`     | No       | Set to `true` to return raw text instead of parsed JSON                                  |

#### Result Object

| Property     | Type          | Description                                       |
| ------------ | ------------- | ------------------------------------------------- |
| `url`        | string        | The final URL (after redirects)                   |
| `status`     | number        | HTTP status code (200, 404, 500, etc.)            |
| `statusText` | string        | HTTP status message ("OK", "Not Found", etc.)     |
| `headers`    | object        | Response headers as key-value pairs               |
| `ok`         | boolean       | `true` if status is 200-299                       |
| `body`       | object/string | Parsed JSON response (or raw text if `raw: true`) |

Example result:

```json
{
  "url": "https://api.example.com/data",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  },
  "ok": true,
  "body": {
    "success": true,
    "data": []
  }
}
```

#### Examples

**Simple GET request:**

```liquid
{% http url: "https://api.example.com/products", method: "GET" as response %}

{% if response.ok %}
  {% for product in response.body.products %}
    {% log "Product: " | append: product.name %}
  {% endfor %}
{% else %}
  {% log "Request failed: " | append: response.status %}
{% endif %}
```

**POST request with JSON body:**

```liquid
{% json request_body %}
  {
    "name": "{{ product.title }}",
    "sku": "{{ product.sku }}",
    "price": {{ product.price }}
  }
{% endjson %}

{% json headers %}
  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{ api_token }}"
  }
{% endjson %}

{% http url: "https://api.example.com/products", method: "POST", headers: headers, body: request_body as response %}

{% if response.status == 201 %}
  {% log "Product created with ID: " | append: response.body.id %}
{% else %}
  {% log "Error: " | append: response.body.message %}
{% endif %}
```

**PUT request to update resource:**

```liquid
{% assign endpoint = "https://api.example.com/orders/" | append: order.id %}

{% json headers %}
  {
    "Content-Type": "application/json",
    "X-API-Key": "{{ API_KEY }}"
  }
{% endjson %}

{% json body %}
  {
    "status": "shipped",
    "tracking_number": "{{ tracking_number }}"
  }
{% endjson %}

{% http url: endpoint, method: "PUT", headers: headers, body: body as response %}

{% if response.ok %}
  {% log "Order updated successfully" %}
{% endif %}
```

**Form-urlencoded POST request:**

```liquid
{% json headers %}
  {
    "Content-Type": "application/x-www-form-urlencoded"
  }
{% endjson %}

{% assign form_body = "grant_type=client_credentials&client_id=" | append: CLIENT_ID | append: "&client_secret=" | append: CLIENT_SECRET %}

{% http url: "https://auth.example.com/oauth/token", method: "POST", headers: headers, body: form_body as response %}

{% if response.ok %}
  {% assign access_token = response.body.access_token %}
  {% log "Token obtained successfully" %}
{% endif %}
```

**Send data to webhook:**

```liquid
{% json payload %}
  {
    "event": "order_created",
    "order_id": {{ order.id }},
    "customer_email": "{{ order.email }}",
    "total": {{ order.total_price }},
    "timestamp": "{{ 'now' | date: '%Y-%m-%dT%H:%M:%SZ' }}"
  }
{% endjson %}

{% json headers %}
  {
    "Content-Type": "application/json"
  }
{% endjson %}

{% http url: WEBHOOK_URL, method: "POST", headers: headers, body: payload as response %}

{% log "Webhook response: " | append: response.status %}
```

**GET raw text response (e.g., CSV):**

```liquid
{% http url: "https://api.example.com/export.csv", method: "GET", raw: true as response %}

{% if response.ok %}
  {% assign csv_content = response.body %}
  {% assign rows = csv_content | parse_csv %}

  {% for row in rows %}
    {% log row %}
  {% endfor %}
{% endif %}
```

**Send XML data:**

```liquid
{% capture xml_body %}<?xml version="1.0" encoding="UTF-8"?>
<order>
  <id>{{ order.id }}</id>
  <total>{{ order.total_price }}</total>
</order>
{% endcapture %}

{% json headers %}
  {
    "Content-Type": "text/xml"
  }
{% endjson %}

{% http url: "https://api.example.com/orders", method: "POST", headers: headers, body: xml_body as response %}

{% log "XML request status: " | append: response.status %}
```

**Integrate with external CRM:**

```liquid
{% json headers %}
  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{ CRM_API_KEY }}"
  }
{% endjson %}

{% json contact_data %}
  {
    "email": "{{ customer.email }}",
    "firstName": "{{ customer.first_name }}",
    "lastName": "{{ customer.last_name }}",
    "properties": {
      "total_orders": {{ customer.orders_count }},
      "total_spent": {{ customer.total_spent }}
    }
  }
{% endjson %}

{% http url: "https://api.crm.com/contacts", method: "POST", headers: headers, body: contact_data as response %}

{% if response.ok %}
  {% log "Contact synced to CRM" %}
{% else %}
  {% log "CRM sync failed: " | append: response.body.error %}
{% endif %}
```

#### Notes

* Consumes 1 credit per request
* Request body is automatically JSON-stringified unless Content-Type is:
  * `application/x-www-form-urlencoded`
  * `multipart/form-data`
  * `text/plain`
  * `text/xml`
* Rate limited responses (429) are automatically retried with backoff
* Server errors are retried up to 3 times before failing
* Request timeout is 5 minutes
* Use `raw: true` when expecting non-JSON responses (CSV, XML, plain text)