Testbed Quick Start Guide

Email Delivery Flow

Include your token as a Bearer token in the Authorization header. Start with a read-only call to confirm auth works:

curl --include \
     --header "Authorization: Bearer YOUR_API_KEY" \
     --header "Accept-Encoding: identity" \
  'https://api-testbed.giftbit.com/papi/v1/ping'

You should get back a small JSON response confirming your token is accepted. Something like:

{
  "username": "YOUR_USERNAME",
  "displayname": "YOUR_DISPLAY_NAME",
  "info": {
    "code": "INFO_CREDENTIALS",
    "name": "Credentials are valid",
    "message": "The credentials used are valid and login attempt was successful."
  }
}

If you get a 401 instead, it's almost always one of two things: a typo in the pasted token, or a missing Bearer prefix (with the space) before it in the header.

You are now authenticated!

  3. Send a test reward

If your integration will use Giftbit to deliver rewards to recipient contacts by email, you will need to create a template in your Testbed dashboard before you use the template in test orders. Log in and go to the Templates section. Create an API format template. You can control the look and feel of the email body by editing the template. You can override or omit details such as the brand(s) and face value in the template and declare them in your API request instead. Once the required sections of the template are complete, the dashboard will provide you with the ID for the template.

Note: Direct Links and Embedded Rewards requests do not require a template.

⚠️ Templates don't carry over to production, so you'll need to re-create these when you go live.

Now you're ready to send a reward against it via the API. Here's the minimal request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_API_KEY" \
     --header "Accept-Encoding: identity" \
     --data-binary "{
    \"gift_template\": \"WIHOWIPXXXX\",
    \"contacts\": [
        {
            \"firstname\":\"Perry\",
            \"lastname\":\"Johnson\",
            \"email\":\"pjohnson@giftbit.com\"
        }
    ],
    \"price_in_cents\":2500,
    \"brand_codes\": [
        \"amazonus\"
    ],
    \"id\":\"testorder1-email\"
}" \
  'https://api-testbed.giftbit.com/papi/v1/campaign'

You should get back a response confirming the reward was created, including its ID:

{
  "info": {
    "code": "INFO_CAMPAIGN_CREATED",
    "name": "Campaign Created",
    "message": "Campaign creation has begun."
  },
  "status": 200,
  "campaign": {
    "company_name": "YOUR_COMPANY_NAME",
    "message": "<p>Hi there, here is a complimentary signup incentive for a digital gift card of your choice.</p>\n<p><span>Click the Claim button on the brand of your preference shown below.</span></p>",
    "subject": "Your incentive is here",
    "contacts": [
      {
        "email": "pjohnson@giftbit.com",
        "firstname": "Perry",
        "lastname": "Johnson",
        "message": "Contact ready"
      }
    ],
    "status": "API_CREATING",
    "uuid": "ced5dbe0166f4bd58b9300f8284XXXXX",
    "suppress_default_greeting": false,
    "delivery_type": "GIFTBIT_EMAIL",
    "price_in_cents": 2500,
    "brand_codes": [
      "amazonus"
    ],
    "contacts_success_count": 1,
    "contacts_failure_count": 0,
    "fees": {
      "cost_entries": [
        {
          "percentage": 0,
          "fee_type": "PREFUND_GIFT_COST",
          "amount_in_cents": 2500,
          "currency": "USD",
          "tax_type": "NOTAX",
          "tax_in_cents": 0,
          "number_of_gifts": 1,
          "fee_per_gift_in_cents": 2500
        },
        {
          "percentage": 50.000,
          "fee_type": "BREAKAGE_PERCENTAGE",
          "amount_in_cents": 0,
          "currency": "USD",
          "tax_type": "NOTAX",
          "tax_in_cents": 0,
          "number_of_gifts": 1,
          "fee_per_gift_in_cents": 0
        }
      ],
      "subtotal_in_cents": 2500,
      "tax_in_cents": 0,
      "tax_type": "NOTAX",
      "total_in_cents": 2500
    },
    "id": "testorder1-email",
    "gift_template": "WIHOWIPXXXX"
  }
}

Copy that ID. You'll use it in the next step, and in production. It's how your system tracks every reward it sends.

Where did the reward go? Testbed delivers all reward emails to your account email (the one you registered with) regardless of the recipient you specify. Check your inbox and you’ll see what your recipients will experience in production.

  4. Check status

Look up the reward you just sent, using the ID from step 3:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer YOUR_API_KEY" \
     --header "Accept-Encoding: identity" \
  'https://api-testbed.giftbit.com/papi/v1/campaign/{id}'

The response from /campaign shows the order’s status. Whether it's been delivered, claimed, or hit a snag. For example, a reward can come back as TEMPORARILY_UNDELIVERABLE, which is exactly the kind of state your system should watch for and act on (a resend clears it).

In production, this is how your system answers "did they get it? did they claim it?" The same endpoint lets you resend a reward (useful for an undeliverable one, or if a recipient deletes the email) or cancel it to reclaim the funds, as long as it hasn't been redeemed yet.

You can also access delivery status and claim status from /gifts using a similar request.

Here are examples of reward statuses:

DELIVERED                  the email-based reward was transmitted successfully
TEMPORARILY_UNDELIVERABLE  the email-based reward cannot be delivered due to a soft bounce
UNDELIVERABLE              the email-based reward cannot be delivered due to a permanent bounce
LINKCREATED                the link-based reward was created
SENT_AND_REDEEMABLE        the reward is waiting to be claimed
REDEEMED                   the reward was claimed
EXPIRED                    the promotional claim period has ended, the reward has not been claimed
GIVER_CANCELED             the reward was canceled by the sender

And that's the full loop! You've authenticated, sent a reward, and tracked its status. Everything from here builds on what you've already done.

A couple of things worth knowing as you keep going:

• Your code carries over. When you move to production, the calls you just made don't change — only your token, the base URL, and a bit of account setup do.
• Test freely. Your Testbed balance is virtual, so send as many rewards as you want. It's the best place to try things before they're real.