> ## Documentation Index
> Fetch the complete documentation index at: https://developer.surecart.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cart & Checkout

> Add products to cart programmatically and customize checkout forms

SureCart provides multiple ways to add items to the cart programmatically:

1. **URL Parameters** - Redirect users to checkout with pre-filled line items
2. **Shortcodes** - Use built-in shortcodes for add-to-cart buttons
3. **Checkout Form Customization** - Add custom fields, checkboxes, or content

<Info>
  For a complete reference of available hooks, see the [Cart
  Hooks](/documentation/actions-filters/cart) and [Checkout
  Hooks](/documentation/actions-filters/checkout) documentation.
</Info>

***

## URL Parameters

The most straightforward way to add items to cart is by redirecting users to the checkout page with `line_items` query parameters.

### Basic Example

```php theme={null}
<?php
$checkout_url = add_query_arg(
    [
        'line_items' => [
            [
                'price_id' => 'price_xxxxxxxxxxxxx', // Your SureCart price ID
                'quantity' => 1,
            ],
        ],
    ],
    \SureCart::pages()->url( 'checkout' )
);
?>

<a href="<?php echo esc_url( $checkout_url ); ?>">
    Add to Cart
</a>
```

### Multiple Items

```php theme={null}
<?php
$checkout_url = add_query_arg(
    [
        'line_items' => [
            [
                'price_id' => 'price_product_one',
                'quantity' => 1,
            ],
            [
                'price_id' => 'price_product_two',
                'quantity' => 2,
            ],
        ],
    ],
    \SureCart::pages()->url( 'checkout' )
);
?>
```

### With Coupon Code

```php theme={null}
<?php
$checkout_url = add_query_arg(
    [
        'line_items' => [
            [
                'price_id' => 'price_xxxxxxxxxxxxx',
                'quantity' => 1,
            ],
        ],
        'coupon' => 'SAVE10', // Promotion code
    ],
    \SureCart::pages()->url( 'checkout' )
);
?>
```

### With Product Variant

```php theme={null}
<?php
$checkout_url = add_query_arg(
    [
        'line_items' => [
            [
                'price_id'   => 'price_xxxxxxxxxxxxx',
                'quantity'   => 1,
                'variant_id' => 'variant_xxxxxxxxxxxxx', // Optional variant
            ],
        ],
    ],
    \SureCart::pages()->url( 'checkout' )
);
?>
```

***

## Shortcodes

SureCart provides built-in shortcodes for adding products to cart.

### Add to Cart Button

```
[sc_product_cart_button id="prod_xxxxxxxxxxxxx" text="Add To Cart"]
```

<ResponseField name="Parameters" type="Shortcode Parameters">
  <Expandable title="properties">
    <ResponseField name="id" type="string" required>
      Product ID.
    </ResponseField>

    <ResponseField name="text" type="string">
      Button text. Default: "Add To Cart"
    </ResponseField>

    <ResponseField name="width" type="integer">
      Button width in pixels.
    </ResponseField>

    <ResponseField name="add_to_cart" type="boolean">
      Whether to add to cart or go directly to checkout.
    </ResponseField>
  </Expandable>
</ResponseField>

### Buy Button with Line Items

```
[sc_buy_button]
    [sc_line_item price_id="price_xxxxxxxxxxxxx" quantity="1"]
[/sc_buy_button]
```

### Multiple Line Items

```
[sc_buy_button]
    [sc_line_item price_id="price_product_one" quantity="1"]
    [sc_line_item price_id="price_product_two" quantity="2"]
[/sc_buy_button]
```

### Using Shortcodes in PHP

You can render shortcodes programmatically in PHP using WordPress's `do_shortcode` function.

```php theme={null}
<?php
echo do_shortcode( '[sc_product_cart_button id="prod_xxxxxxxxxxxxx" text="Buy Now"]' );
?>
```

For buy buttons with multiple line items:

```php theme={null}
<?php
echo do_shortcode( '
    [sc_buy_button]
        [sc_line_item price_id="price_product_one" quantity="1"]
        [sc_line_item price_id="price_product_two" quantity="2"]
    [/sc_buy_button]
' );
?>
```

***

## Checkout Form Customization

Add custom fields, checkboxes, or content to checkout forms using the `render_block` filter. This example walks you through adding a terms checkbox with server-side validation.

<Steps>
  <Step title="Add custom content before the submit button">
    Use the `render_block` filter to inject HTML before any checkout block. Target the block by checking `$block['blockName']`.

    ```php theme={null}
    add_filter( 'render_block', function( $block_content, $block ) {
        if ( 'surecart/submit' !== $block['blockName'] ) {
            return $block_content;
        }

        $checkbox = '<div class="my-terms-checkbox" style="margin-bottom: 1em;">
            <label style="display: flex; align-items: start; gap: 0.5em; cursor: pointer;">
                <input type="checkbox" name="accept_terms" value="yes" required />
                <span>I agree to the <a href="/terms" target="_blank">terms and conditions</a></span>
            </label>
        </div>';

        return $checkbox . $block_content;
    }, 10, 2 );
    ```
  </Step>

  <Step title="Add server-side validation">
    Validate custom fields using the `surecart/checkout/validate` filter. Return errors to prevent checkout submission.

    ```php theme={null}
    add_filter( 'surecart/checkout/validate', function( $errors, $args, $request ) {
        // phpcs:ignore WordPress.Security.NonceVerification.Missing
        $accept_terms = isset( $_POST['accept_terms'] ) ? sanitize_text_field( wp_unslash( $_POST['accept_terms'] ) ) : '';

        if ( 'yes' !== $accept_terms ) {
            $errors->add( 'terms_required', 'You must accept the terms and conditions.' );
        }

        return $errors;
    }, 10, 3 );
    ```

    See [Checkout Hooks](/documentation/actions-filters/checkout#form-validation) for more validation examples.
  </Step>
</Steps>

### Checkout Block Names

| Block Name            | Description              |
| --------------------- | ------------------------ |
| `surecart/submit`     | Submit/Pay button        |
| `surecart/email`      | Email field              |
| `surecart/name`       | Full name field          |
| `surecart/first-name` | First name field         |
| `surecart/last-name`  | Last name field          |
| `surecart/phone`      | Phone number field       |
| `surecart/address`    | Address fields           |
| `surecart/payment`    | Payment method selection |
| `surecart/coupon`     | Coupon code field        |
| `surecart/line-items` | Order line items         |
| `surecart/totals`     | Order totals summary     |

***

## Related

<CardGroup cols={2}>
  <Card title="Cart Hooks" icon="cart-shopping" href="/documentation/actions-filters/cart">
    Customize cart icon, visibility, and behavior.
  </Card>

  <Card title="Checkout Hooks" icon="credit-card" href="/documentation/actions-filters/checkout">
    Hook into checkout events and customize validation.
  </Card>
</CardGroup>