> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/js-api/overview.md).

# Overview

Spiffy Checkout JavaScript interface API

The JS Interface API enables you to tap into your checkout's data and modify things via custom code directly on your checkout.

{% hint style="info" %}
**The JavaScript Interface API is different from SpiffyJS**\
which is used for embedding and interacting with Spiffy Elements. This interface API may be introduced into SpiffyJS in the future but in the meantime this is available on your checkouts via custom code.
{% endhint %}

## checkout.ready()

All of your custom code that uses this interface needs to be wrapped in a `ready` call so it runs AFTER the checkout is interactable

<pre class="language-markup"><code class="lang-markup"><strong>&#x3C;script>
</strong>checkout.ready(() => {
    /* ...do your stuff here! */
})
&#x3C;/script>
</code></pre>

If the checkout is already interactable when you call `ready`, your function runs immediately. That makes it safe to call late: from a deferred or `async` script, from code added to the page after load, or from inside another `ready` callback.

## checkout.data

This is the main way to access the current state of the checkout. Access checkout data any time within `checkout.ready` including inside events to inform any of your custom logic.

<pre class="language-markup"><code class="lang-markup"><strong>&#x3C;script>
</strong>checkout.ready(() => {
    console.log(checkout.data)
    /* ...do your stuff here! */
})
&#x3C;/script>
</code></pre>

## checkout.on()

Add event listeners to checkout events

<pre class="language-markup"><code class="lang-markup">&#x3C;script>
checkout.ready(() => {
    checkout.on('change:field', (ev) => {
        /* ...do your stuff here! */
<strong>    })
</strong>})
&#x3C;/script>
</code></pre>

### Available Events

* `change:field` - *when a field value is changed*
* `change:item` - *when an item is added/changed on the order*
* `change:discount` - *when the discount/promo code changes*
* `change:payplan` - *when the selected payment plan changes*
* `change:order` - *when the order changes/total is recalculated*
* `change:paymethod` - *when the selected payment method changes*

## checkout.set()

Change fields and selections on the checkout

```markup
<script>
checkout.ready(() => {
    checkout.set('field', 'name_first', 'Taco')
})
</script>
```

#### Fields

```javascript
checkout.set('field', name, value)
```

* `name: String` - *field name, this is the same name that would be used to set the field via the URL*
* `value: String` - *the value to set the field to*

#### Items

```javascript
checkout.set('item', block_id, index, status)
```

* `block_id: Int` - *block ID that this item exists on as an Option. This can be found by inspecting the block element you're looking to hide*
* `index: Int` - *the index of the Item's option*
* `status: Boolean` - *optional*, *default: false - whether we are adding/removing this item*

#### Payment Plan

```javascript
checkout.set('payplan', id)
```

* `id: Int` - *optional, default: null* - *ID of the payment plan to select, null/undefined will set it to single-pay*

#### Discount

```javascript
checkout.set('discount', code)
```

* `code: String` - optional, default: null - promo code to apply, null will remove the currently applied promo

#### Payment Method

```javascript
checkout.set('paymethod', method)
```

* `method: String` - *payment method to select*
  * `paypal` - PayPal payment method
  * `stripe` - credit card via Stripe
  * `expressPay` - ApplePay and other express pay options when available

## checkout.show()/hide()

Hide and show sections, blocks, options and payment methods.

```markup
<script>
checkout.ready(() => {
    checkout.hide('block', 173)
    checkout.show('block', 449)
})
</script>
```

Hiding controls what the customer sees. It changes the order in exactly one case:

* **Hiding an option that is currently selected deselects it.** The customer chose it, so leaving it on the order would bill them for a line they can no longer see or remove. Nothing is selected in its place — a block can end up with no selection, and choosing which option should be selected is yours to do with `checkout.set('item', …)`.
* **Hiding a block or a section changes nothing about the order.** Those are widgets rather than choices, so whatever is selected inside stays selected and is still charged.

{% hint style="info" %}
**To charge for something without showing it, hide its block rather than its option.**\
That's the difference between the two: hiding the picker keeps the sale, hiding the chosen option cancels it.
{% endhint %}

A worked pair, locking a customer to the tier they already chose on your sales page:

```markup
<script>
checkout.ready(() => {
    // pick the tier first, then take the cheaper ones away
    checkout.set('item', 173, 2, true)
    checkout.hide('option', 173, [0, 1])
})
</script>
```

Two things follow from the block's own rules rather than from `hide()`:

* Some blocks only make sense as a choice. A subscription block, for example, stops displaying once a single option is left. That option is still selected and still sold; there's just nothing left to pick.
* A section with nothing visible left in it disappears too, so you don't have to hide the section separately after hiding its blocks.

A hidden block never blocks the Complete Purchase button, since the customer has no way to fill in fields they cannot see. Name, email and address are still required — those are checked when the order is submitted and the checkout will report an error — but your own custom fields are not, so a block you hide is a block whose custom fields you won't collect.

Visibility lives in the checkout's own state, so a re-render won't undo it. You can call `hide()` immediately inside `ready()`, with no wait or timeout — it is applied as soon as the checkout finishes loading. Something hidden that way can be briefly visible first, because the page arrives from the server before your code has had a say. If that matters for what you are hiding, style it out with Custom CSS as well as hiding it.

#### Sections

```javascript
checkout.hide('section', section_id)
checkout.show('section', section_id)
```

* section\_id`: Int` - *ID of the section to hide. This can be found by inspecting the section element you're looking to hide*

#### Blocks

```javascript
checkout.hide('block', block_id)
checkout.show('block', block_id)
```

* block\_id`: Int` - *ID of the block to hide. This can be found by inspecting the block element you're looking to hide*

#### Options

```javascript
checkout.hide('option', block_id, indexes)
checkout.show('option', block_id, indexes)
```

* block\_id`: Int` - *ID of the block to hide. This can be found by inspecting the block element you're looking to hide*
* `indexes: Int|Array` - Index or array of indexes of the options you want to hide

#### Payment Method

```javascript
checkout.hide('paymethod', method)
checkout.show('paymethod', method)
```

* `method: String` - *payment method to hide/show*
  * `paypal` - PayPal payment method
  * `stripe` - credit card via Stripe
  * `expressPay` - ApplePay and other express pay options when available
