Skip to main content
The Giftbit API is designed to be simple yet powerful. This guide is a starting point to help you structure your integration. We encourage you to reach out to the Giftbit team at any time to discuss your program and integration at testbed@giftbit.com.

​
Reward delivery

Before you begin building, consider which delivery method best suits your system workflow and your intended user experience. There are three delivery methods.

Link-based

A unique link that can be passed to another system for delivery.

Email

Giftbit delivers a customized reward email to each recipient.

In-app

Embed an interactive reward selection area in your app or website.
You can receive a unique link and pass it to another system to deliver the reward to a recipient by email, SMS, or another distribution method. You can send a predefined reward brand or a choice between reward brands. Each reward has a customizable claim period. There are two types of links you can use here: direct_link or shortlink.
Shortlinks first direct your recipients to a landing page as part of the reward experience. This landing page includes your logo (or another image) as well as a custom message. This is great for when you want to provide the recipient with more context that reminds them who is sending the reward and why. This might be desired if you are delivering the reward in a shorter message via SMS or social channels.Use the /campaign endpoint along with the delivery_type: SHORTLINK property to request shortlink rewards.

​
Delivery option 2: Giftbit delivers your reward by email

Use the /campaign endpoint to request a reward be delivered to your recipient by email. Giftbit delivers your customized reward email to each recipient via an HTML email. You can send a predefined reward brand or a choice between reward brands. Each reward has a customizable claim period. Giftbit specializes in email deliverability and digital trust best practices. You can access records of bounces, spam complaints, and other deliverability issues to manage the quality of your recipient lists. Use the /campaign endpoint to send rewards by email.

​
Delivery option 3: Rewards embedded in your app or website

You can provide recipients with an interactive reward selection area in your app or website where they can choose from a selection of reward brands and immediately be redirected to a Giftbit URL to reveal the reward. In this type of integration, use the results from the /brands endpoint to create the interactive reward selection step in your app or website, then use the /embedded endpoint to request an embeddable URL that displays a page with the chosen reward’s code ready for use. Use the /embedded endpoint to embed a reward directly in your application.

​
Deciding between customized list or full catalog rewards

There are multiple ways to set the brands in a call to /campaign or /direct_links, depending on whether your system sends a single reward brand or offers a choice.

​
Your system hosts the choice step

If you host the interactive choice step in your app or website using the results from the /brands endpoint, you can specify the price and brand in each API call in reaction to the selection made by the recipient. If you specify the gift_template in your request, use the web interface to edit your template and check the box labeled provide in API call in the reward section of the template. Both price_in_cents and brand_code are then required in your API call for a successful response. If you don’t specify the gift_template, you are required to provide all required parameters in the API call, including price_in_cents and brand_code.

​
Your system sends one brand or a customized list of brands

If your integration always sends the same brand or list of brands for each request, you can either set the brand(s) in your template using the web interface or specify the brand_codes in the API call. If your API call contains more than one brand_codes, the recipient can choose from that list of predefined brand options.

​
Giftbit provides the choice step with all available options

With the Full Catalog option, you can bypass the need for the interactive choice step within your app or website. This format presents the recipient with the option to choose from all available reward brands at a specific price point for a specific region. To request a Full Catalog reward, omit the brand_code and specify the region along with price_in_cents in your API call, provided that the gift_template is not specified. If you specify the gift_template in your API call, use the web interface to modify your template: navigate to the reward section of the template, set the desired price and region, and select Full Catalog.
When the gift_template is specified with Full Catalog selected, and the price_in_cents provided in the API call differs from the price set in the template, the choice step for the Full Catalog reward automatically adjusts to display brands that align with the overridden price.

​
Promotional rewards

By providing an expiry date in your API call to the /campaign or /direct_links endpoint, you can limit the period in which your recipients may claim their reward. This claim period can also be set on a gift_template in the web interface by marking a template as promotional and setting a number of days the reward is eligible to be claimed. Any rewards ordered using a gift_template flagged as promotional automatically set the calculated expiry date.

​
Retrieving reward brand information

Using the /brands endpoint, you can access the list of reward brands available from Giftbit and detailed information about each brand, including the brand_code and an allowed price to include in your API calls to /campaign, /direct_links, or /embedded. A limited number of reward brands are available for testing purposes in Testbed. The complete list of production reward brands is at giftbit.com/brands. Templates allow rewards with custom messaging and branding to be richly formatted, and provide a nice separation of responsibility between content creators and developers. The custom reward content — subject, the message with formatting and rich content, and company brand image — is maintained through the web interface and WYSIWYG editor, without requiring any changes to the API calls themselves when the content changes. To get started with templates, navigate to the templates section of your Giftbit account. Each template is auto-assigned a unique uppercase short identifier shown in the web interface. This is the id you’ll use in the gift_template field of the /campaign creation request.
If you provide a template, you must omit the message and subject in the request — unless you want to override the template content in that particular request.
While we highly recommend using templates, it is not mandatory. You may specify the subject and message for your rewards via the /campaign creation request.
For shortlinks, the subject field is not leveraged; however, we still recommend setting it in the template. This allows the template to be used with both email delivery and shortlinks.

​
Reward information and management

While not required for your integration, the /gifts endpoint retrieves detailed information and status for the rewards you’ve previously ordered through the /campaign, /direct_links, or /embedded endpoints. The /gifts endpoint also allows your system to perform lifecycle and delivery-type-dependent actions, such as triggering another email delivery attempt for rewards delivered by Giftbit.