# push

Appends an element to the end of an array. The original array is modified (mutated) with the new element added.

```liquid
{% json items %}[1, 2, 3, 4]{% endjson %}
{% push items, 5 %}

{% log items %}
{% comment %} Output: [1, 2, 3, 4, 5] {% endcomment %}
```

#### Syntax

```liquid
{% push array_name, element %}
```

#### Parameters

| Parameter    | Required | Description                               |
| ------------ | -------- | ----------------------------------------- |
| `array_name` | Yes      | The array to add the element to           |
| `element`    | Yes      | The value to append (literal or variable) |

#### Behavior

* Adds the element to the **end** of the array
* Modifies the original array (mutation)
* Element can be any type: string, number, object, array, or variable
* Supports nested array access with dot notation

#### Examples

**Push a literal value:**

```liquid
{% json numbers %}[1, 2, 3]{% endjson %}
{% push numbers, 4 %}
{% push numbers, 5 %}

{% log numbers %}
{% comment %} Output: [1, 2, 3, 4, 5] {% endcomment %}
```

**Push a variable:**

```liquid
{% json cart_items %}[]{% endjson %}
{% assign new_item = "Product A" %}
{% push cart_items, new_item %}

{% log cart_items %}
{% comment %} Output: ["Product A"] {% endcomment %}
```

**Push an object:**

```liquid
{% json orders %}[]{% endjson %}

{% json new_order %}
  {
    "id": 12345,
    "total": 99.99,
    "status": "pending"
  }
{% endjson %}

{% push orders, new_order %}

{% log orders %}
{% comment %} Output: [{"id": 12345, "total": 99.99, "status": "pending"}] {% endcomment %}
```

**Build array in a loop:**

```liquid
{% json product_titles %}[]{% endjson %}

{% for item in order.line_items %}
  {% push product_titles, item.title %}
{% endfor %}

{% log "Products ordered:" %}
{% log product_titles %}
```

**Collect filtered items:**

```liquid
{% json high_value_orders %}[]{% endjson %}

{% for order in orders %}
  {% if order.total_price > 100 %}
    {% push high_value_orders, order %}
  {% endif %}
{% endfor %}

{% log "High value orders: " | append: high_value_orders.size %}
```

**Push to nested array:**

```liquid
{% json data %}
  {
    "pending": [],
    "completed": []
  }
{% endjson %}

{% push data.pending, "task1" %}
{% push data.pending, "task2" %}
{% push data.completed, "task0" %}

{% log data %}
{% comment %}
Output: {
  "pending": ["task1", "task2"],
  "completed": ["task0"]
}
{% endcomment %}
```

**Stack implementation with push and pop:**

```liquid
{% json history %}[]{% endjson %}

{% comment %} Add to history {% endcomment %}
{% push history, "page1" %}
{% push history, "page2" %}
{% push history, "page3" %}

{% log "History: " %}
{% log history %}
{% comment %} Output: ["page1", "page2", "page3"] {% endcomment %}

{% comment %} Go back {% endcomment %}
{% pop history as current %}
{% log "Current page: " | append: current %}
{% comment %} Output: Current page: page3 {% endcomment %}
```

**Collect errors during processing:**

```liquid
{% json errors %}[]{% endjson %}
{% json processed %}[]{% endjson %}

{% for item in items %}
  {% if item.valid %}
    {% push processed, item %}
  {% else %}
    {% json error %}
      {
        "item_id": {{ item.id }},
        "message": "Validation failed"
      }
    {% endjson %}
    {% push errors, error %}
  {% endif %}
{% endfor %}

{% if errors.size > 0 %}
  {% log "Errors encountered:" %}
  {% log errors %}
{% endif %}

{% log "Successfully processed: " | append: processed.size %}
```

**Build comma-separated string from array:**

```liquid
{% json tags %}[]{% endjson %}

{% push tags, "sale" %}
{% push tags, "featured" %}
{% push tags, "new" %}

{% assign tag_string = tags | join: ", " %}
{% log "Tags: " | append: tag_string %}
{% comment %} Output: Tags: sale, featured, new {% endcomment %}
```

**Aggregate data from API calls:**

```liquid
{% json all_results %}[]{% endjson %}

{% for page in (1..5) %}
  {% assign url = "https://api.example.com/data?page=" | append: page %}
  {% http url: url, method: "GET" as response %}

  {% if response.ok %}
    {% for item in response.body.items %}
      {% push all_results, item %}
    {% endfor %}
  {% endif %}
{% endfor %}

{% log "Total items collected: " | append: all_results.size %}
```

#### Related Tags

| Tag   | Description                                 |
| ----- | ------------------------------------------- |
| `pop` | Removes and returns the last element (LIFO) |

#### Notes

* The array must exist and be a valid array, otherwise an error is thrown
* Push modifies the original array in place
* Useful for building arrays dynamically during script execution
* Works with the Liquid `| push:` filter, but the tag version supports complex values
* Supports dot notation for nested arrays (e.g., `data.items`)
* No limit on the number of elements that can be pushed