> 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/spiffyjs/elements.md).

# Elements

`<spiffy-element>` is a single embed element for dropping Spiffy surfaces into your page: checkouts, customer and affiliate portals, affiliate registration, and management views for one subscription or payment plan. Set `type` to pick the surface, then pass that type's attributes.

```html
<spiffy-element type="checkout" url="https://example.spiffy.co/checkout/my-checkout"></spiffy-element>
```

SpiffyJS also turns plain links to your checkouts into popups by default, so you only need an element when you want something embedded in-line on the page.

### Types

| `type`               | Attributes                           | Renders                                                              |
| -------------------- | ------------------------------------ | -------------------------------------------------------------------- |
| `checkout`           | `url` (required)                     | An in-line checkout                                                  |
| `customer-portal`    | `token` (optional)                   | The customer's full portal: subscriptions, payment plans, and orders |
| `affiliate-portal`   | `token` (optional)                   | The affiliate portal                                                 |
| `affiliate-register` | none                                 | The affiliate registration form                                      |
| `subscription`       | `ref` (required), `token` (optional) | One subscription's management view                                   |
| `payment-plan`       | `ref` (required), `token` (optional) | One payment plan's management view                                   |

**`token`** - an SSO magic-link token, for signing the customer or affiliate straight in instead of showing a login form. Requires an API connection with Spiffy to request portal tokens.

**`ref`** - the id of the subscription or payment plan the element should manage. Resolve it via the API the same way you resolve the SSO token (see below).

#### Checkout

```html
<spiffy-element type="checkout" url="https://example.spiffy.co/checkout/my-checkout"></spiffy-element>
```

`url` also accepts query parameters, so you can pass additional data to your checkout the same way you would with a direct link.

#### Customer and affiliate portals

```html
<spiffy-element type="customer-portal" token="..."></spiffy-element>
<spiffy-element type="affiliate-portal" token="..."></spiffy-element>
```

Without `token`, the embed shows a login form. With `token`, the customer or affiliate lands signed in.

#### Affiliate registration

```html
<spiffy-element type="affiliate-register"></spiffy-element>
```

#### Subscription and payment plan elements

```html
<spiffy-element type="subscription" ref="12345" token="..."></spiffy-element>
<spiffy-element type="payment-plan" ref="67890" token="..."></spiffy-element>
```

By default the customer portal shows everything a customer has: every subscription, payment plan, and order. `type="subscription"` and `type="payment-plan"` skip straight to one item's management view instead. That's useful when a customer has other purchases that don't belong in the surface you're embedding in, like a SaaS app that should only expose billing for its own subscription and nothing else the customer bought from you.

To set this up:

1. Resolve the subscription or payment plan id for the customer you're embedding, server-side, through the Spiffy API (the same place you already resolve the SSO token).
2. Mint an SSO magic-link `token` for that customer, as you do today.
3. Embed with both `ref` and `token` set.

The customer lands signed in, directly on that item's management page, with no way to reach the rest of their portfolio.

### Compatibility mode

```html
<div class="spiffy-element__container" data-type="subscription" data-ref="12345" data-token="..."></div>
```

`data-type` maps to `type`; the other `data-*` attributes map to their matching element attribute (`data-url`, `data-token`, `data-ref`).

***

## Legacy elements

`spiffy-checkout`, `spiffy-portal`, and `spiffy-affiliate-register` still work and aren't going anywhere. New integrations should use `<spiffy-element>` instead: it does everything these do, plus single-item management for subscriptions and payment plans, which the legacy elements don't have.

| Legacy                                               | Use instead                                      |
| ---------------------------------------------------- | ------------------------------------------------ |
| `<spiffy-checkout url="...">`                        | `<spiffy-element type="checkout" url="...">`     |
| `<spiffy-portal type="customer">`                    | `<spiffy-element type="customer-portal">`        |
| `<spiffy-portal type="affiliate">`                   | `<spiffy-element type="affiliate-portal">`       |
| `<spiffy-affiliate-register>`                        | `<spiffy-element type="affiliate-register">`     |
| `<spiffy-portal type="customer" subscription="...">` | `<spiffy-element type="subscription" ref="...">` |

### `spiffy-checkout`

```html
<spiffy-checkout url="https://example.spiffy.co/checkout/my-checkout"></spiffy-checkout>
```

**Properties**

* `url` (required) - the URL of the checkout you want to load in-line. Also accepts URL parameters for passing additional data to your checkout

**Compatibility Mode**

```html
<div class="spiffy-checkout__container" data-url="https://example.spiffy.co/checkout/my-checkout"></div>
```

### `spiffy-portal`

```html
<spiffy-portal type="customer"></spiffy-portal>
```

**Properties**

* `type` (default `customer`) - toggle the type of portal to embed. Valid values are `customer` or `affiliate`
* `token` (default `null`) - pass in an authentication token for single sign-on functionality.\
  \&#xNAN;*This requires an API connection with Spiffy to request customer portal tokens*

**Compatibility Mode**

```html
<div class="spiffy-portal__container" data-type="customer"></div>
```

### `spiffy-affiliate-register`

```html
<spiffy-affiliate-register></spiffy-affiliate-register>
```

**Compatibility Mode**

```html
<div class="spiffy-affiliate-register__container"></div>
```