---
title: "Quikly Swap"
---

Quikly Swap campaigns incentivize a specific action in exchange for an offer. You can easily layer in urgency or scarcity by limiting rewards, or configuring offers that decrease in value over time. For example, the marketing message could be:

** Sign up in the next 24 hours to receive $10 off your order, or in the next 48 hours for $5 off your next order. **

Or, alternatively:

** The first 500 people to sign up will receive a code good for 20% off. **

## Overview
Swap campaigns are generally comprised of three visual components:
 - **instructions banner:** conveys real-time offer detail  (current offer eligilbilty, quantity or time left, etc)
 - **offer presentation:** offer codes, fine print, terms
 - **redemption banner:** display any previously claimed offers, useful during checkout

In terms of the API, the basic concept for a Swap campaign is to 1) query for offer details, 2) trigger an event that indicates the targeted action was completed, and 3) query for claimed offer details.

Campaigns can be configured to be visible to all users, or only those that have obtained a unique access key via an activation URL.

## Instructions Banner

Use the following query to fetch dynamic content useful to explain what action is needed to receive the offer, as well as what offers are available.

![Swap Instructinos](./images/swap-instructions.png)

```graphql
query InstructionsQuery($hashid: String!) {
  quikly(hashid: $hashid) {
    id
    instructionsStatic: customContentFor(key: "embed_instructions_static")
    instructionsUpcoming: customContentFor(key: "embed_instructions_upcoming_offer")
    instructionsExpiring: customContentFor(
      key: "embed_instructions_expiring_offer"
    )
    instructionsLast: customContentFor(key: "embed_instructions_last_offer")
    dealClosedTitle: customContentFor(key: "deal_closed")
    dealClosedSubtitle: customContentFor(key: "deal_closed_subtitle")
    ended
    claimBySpeed
    incentiveTiers {
      id
      rank
      description
      upperResponseTime
      quantity
      claimCount
      allClaimed
    }
  }
}
```
The fields include:
- `quikly`refers to the campaign instance
- `customContentFor` loads text content from the CMS
- `ended` is a boolean value indicating if the campaign has expired
- `claimBySpeed` is a boolean value indicating if the offer value is determined by the speed of response rather than rank
- `incentiveTiers` provides info about the offer types available

## Claiming an Offer
To claim an offer, send the user's email address to the `createEmbeddedClaim` mutation. This returns a unique offer identifier (`qid`) and `receiptToken` used to securely fetch offer details, as well as the user's `authToken` which can then be used to identify this user on subsequent interactions with the API via the [authorization header](/graphql-api).

```graphql
mutation createEmbeddedClaim(
  $dealHashid: String!
  $email: String!
) {
  createEmbeddedClaim(
    input: { dealId: $dealHashid, email: $email }
  ) {
    errors {
      key
      message
    }
    user {
      id
      authToken
    }
    order {
      id
      qid
      receiptToken
    }
  }
}
```
You should store the `qid`, `receiptToken` from the `order` object locally to retrieve the offer detail.

## Fetching Offer Detail
Use the `getOrder` query to fetch offer details. At a minimum you'll probably want top display the `itemFullDescription` the `codes`, but the API also provides access to other useful content as demonstrated in the Offer Detail screen below.

![Swap Offer Details](./images/swap-offer.png)

```graphql
query getOrder($orderId: Int!, $receiptToken: String!) {
  order(
    orderId: $orderId
    receiptToken: $receiptToken
  ) {
    id
    qid
    expirationDate
    itemFullDescription
    itemInstructions
    finePrint
    codes: codesWithLabelsAndBarcodes {
      instore
      pin
      value
      label
    }
    links {
      id
      name
      url
      position
    }
    quikly {
      id
      hashid
      termsUrl
      congratsMessage: customContentFor(key: "claim_congrats")
      congratsHeader: customContentFor(key: "claim_congrats_embedded_header")
      congratsSubheader: customContentFor(
        key: "claim_congrats_embedded_subheader"
      )
      redeemCopy: customContentFor(key: "embed_redeem_body")
    }
  }
}
```

If you wanted to simply display a banner like the image below, you may end up building a query like this:

![Swap Offer Details](./images/swap-redemption.png)

```graphql
query getOrder($orderId: Int!, $receiptToken: String!) {
  order(
    orderId: $orderId
    receiptToken: $receiptToken
  ) {
    id
    qid
    redeemCopy
    codes: codesWithLabelsAndBarcodes {
      pin
      value
    }
  }
}
```

At this point, referencing the `OrderType` in the [GraphiQL Explorer](https://graphql-explorer.quiklydemo.com) will be very useful!