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

# Order Bumps

> Add pre-payment offers on the checkout page to increase average order value

# Order Bumps

**Time**: \~5 minutes | **Difficulty**: Beginner

Use the Node SDK to define **order bumps** — optional add-ons shown **on the checkout page before payment**. They lift average order value without changing your main line item.

<Info>
  **Order bumps vs upsells**: Order bumps appear **before** the customer pays (same checkout session). **Upsell / post-purchase offers** run **after** payment on dedicated offer steps. See [Upsell & Downsell Funnel](/developer-tools/node-sdk/upsell-downsell-funnel) for post-checkout flows.
</Info>

***

## Prerequisites

| Requirement           | Notes                                                                 |
| --------------------- | --------------------------------------------------------------------- |
| Node.js 18+           |                                                                       |
| `@tagadapay/node-sdk` | `npm install @tagadapay/node-sdk`                                     |
| API key               | Dashboard → Settings → API Keys                                       |
| Store + processor     | [Merchant Quick Start](/developer-tools/node-sdk/merchant-quickstart) |

```ts theme={null}
import Tagada from '@tagadapay/node-sdk';

const tagada = new Tagada('your-api-key');
const STORE_ID = 'store_...';
```

***

## 1. What order bumps are

* Shown **on checkout** while the cart and payment form are visible.
* Customer can opt in (or you can **pre-check** the bump).
* Controlled by **triggers** (when to show) and optional **rules** (cart conditions).

***

## 2. Create an order bump product

Create a normal product with variant(s) and prices — the bump sells that SKU.

```ts theme={null}
const bumpProduct = await tagada.products.create({
  storeId: STORE_ID,
  name: 'Extended Warranty',
  active: true,
  isShippable: false,
  isTaxable: false,
  variants: [{
    name: 'Default',
    sku: 'BUMP-WARRANTY',
    grams: null,
    active: true,
    default: true,
    price: null,
    compareAtPrice: null,
    prices: [{
      currencyOptions: { USD: { amount: 999 } },
      recurring: false,
      billingTiming: 'usage',
      interval: null,
      intervalCount: 1,
      default: true,
    }],
  }],
});

const v0 = bumpProduct.variants[0];
```

***

## 3. Create an order bump offer

```ts theme={null}
const bump = await tagada.offers.create({
  storeId: STORE_ID,
  offerTitle: 'Extended Warranty',
  enabled: true,
  type: 'orderbump',
  triggers: [{ type: 'any', productId: null }],
  offers: [],
  orderBumpOffers: [{
    productId: bumpProduct.id,
    variantId: v0.id,
    priceId: v0.prices[0].id,
    type: 'primary',
    precheck: false,
    quantity: 1,
    titleTrans: { en: 'Add extended warranty' },
    descriptionTrans: { en: '2 years of coverage — only $9.99' },
    overrideImageUrl: null,
    displayPrice: true,
    displayCompareAtPrice: false,
  }],
});

const bumpId = bump.id;
```

***

## 4. Bump types (`orderBumpOffers[].type`)

| Type              | Role                                                        |
| ----------------- | ----------------------------------------------------------- |
| `primary`         | Main bump slot — highest visibility                         |
| `secondary`       | Additional bump row                                         |
| `vip`             | Premium positioning / styling in checkout UI                |
| `non_interactive` | Shown without a toggle (informational / fixed presentation) |

***

## 5. Trigger types (`triggers[]`)

| `type`    | Behavior                                                                |
| --------- | ----------------------------------------------------------------------- |
| `any`     | Show for all checkouts (`productId: null`)                              |
| `product` | Show when the cart matches a specific product (`productId: 'prod_...'`) |

```ts theme={null}
triggers: [{ type: 'product', productId: 'prod_main_line_item' }],
```

***

## 6. Attach to a funnel (checkout step)

On **checkout** nodes, set `stepConfig.orderBumps`:

```ts theme={null}
stepConfig: {
  orderBumps: { mode: 'custom', enabledOfferIds: [bumpId] },
}
```

| `mode`    | Meaning                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `custom`  | Only bumps listed in `enabledOfferIds` apply on this step                                               |
| `inherit` | Use the store / default bump configuration ([Step config](/developer-tools/node-sdk/step-config-guide)) |

***

## 7. List, retrieve, update, delete

```ts theme={null}
// List (response uses `upsells` array for all offer types)
const { upsells, total } = await tagada.offers.list({ storeId: STORE_ID, type: 'orderbump' });

const one = await tagada.offers.retrieve(bumpId);

await tagada.offers.update({
  id: bumpId,
  data: {
    offerTitle: 'Extended Warranty — pre-checked',
    enabled: true,
    type: 'orderbump',
    triggers: [{ type: 'any', productId: null }],
    offers: [],
    orderBumpOffers: [/* same shape as create */],
  },
});

await tagada.offers.del([bumpId]);
```

***

## 8. Order bump rules (optional)

Per bump line, `rules` restrict when that line is eligible (evaluated against the **current cart**).

| Rule `type`           | Typical fields                                    |
| --------------------- | ------------------------------------------------- |
| `CartContainsProduct` | `productId`                                       |
| `CartTotalAbove`      | `minimumAmount` (per-currency structure from API) |
| `CartTotalBelow`      | `minimumAmount`                                   |
| `CartItemCountAbove`  | `itemCount`                                       |
| `CartItemCountBelow`  | `itemCount`                                       |

```ts theme={null}
orderBumpOffers: [{
  // ...productId, variantId, priceId, type, titleTrans, etc.
  rules: [
    { type: 'CartContainsProduct', productId: 'prod_xxx' },
    { type: 'CartItemCountAbove', itemCount: 1 },
  ],
}],
```

***

## 9. SDK methods reference

| Method                                               | Description                                       |
| ---------------------------------------------------- | ------------------------------------------------- |
| `tagada.offers.create(params)`                       | Create upsell or order bump (`type: 'orderbump'`) |
| `tagada.offers.list({ storeId, type: 'orderbump' })` | Paginate / filter bumps                           |
| `tagada.offers.retrieve(id)`                         | Fetch one offer                                   |
| `tagada.offers.update({ id, data })`                 | Replace offer fields (omit `storeId` in `data`)   |
| `tagada.offers.del([ids])`                           | Delete one or more offers                         |
| `tagada.products.create` / `update`                  | Manage bump SKUs and prices                       |
| `tagada.funnels.create` / `update`                   | Set `stepConfig.orderBumps` on checkout steps     |

***

## 10. Next steps

<CardGroup cols={2}>
  <Card title="Step config (pixels & bumps)" icon="sliders" href="/developer-tools/node-sdk/step-config-guide">
    `orderBumps`, scripts, pixels, and payment setup per funnel step
  </Card>

  <Card title="Upsell & downsell funnel" icon="arrow-up-right-dots" href="/developer-tools/node-sdk/upsell-downsell-funnel">
    Post-payment offers with conditional routing
  </Card>

  <Card title="Custom checkout & pages" icon="paintbrush" href="/developer-tools/node-sdk/custom-checkout">
    Native, HTML, or Plugin SDK checkout surfaces
  </Card>

  <Card title="Merchant quick start" icon="rocket" href="/developer-tools/node-sdk/merchant-quickstart">
    End-to-end store and processor setup
  </Card>
</CardGroup>