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.

​
Deciding between delivery methods

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

Link-based

When your system places an order, it is fulfilled as a link-based reward that can be passed to another system for delivery.
Link-based formats include Shortlinks, Direct Links, and Embedded Rewards.

Email

When your system places an order, it is fulfilled by Giftbit as an email-based reward delivered to the specified contact.
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. There are three types of links you can use here: direct_link, shortlink, or embedded.
Embedded Rewards skip both the landing page and the claim steps and lead to the gift code reveal step for a single reward brand.Use the /embedded endpoint to create an embedded reward.

​
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.

​
Deciding between customized list or full catalog rewards

There are multiple ways to set the reward brand options 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

You can use the information available from the /brands endpoint to host the interactive reward brand choice step in your app or website. The /brands endpoint provides retail partner names, logos, and allowed price ranges for presenting a selection of reward brands. When your system places an order in reaction to a selection in your interactive choice step, your system will specify the brand_code and price_in_cents for the selected reward brand. If the request specifies a gift_template, the brand_code in the request will override the reward brand(s) in the template.

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

If your integration always sends the same single reward brand, or a fixed list of reward brands, you can either preselect the reward brand(s) in the template using the web interface or specify one or multiple brand_codes and a price_in_cents in the request. If multiple brand_codes are specified, Giftbit provides a choice of reward brand options in the claim steps. This allows your integration to skip building an interactive choice step.

​
Giftbit provides the choice step with all available options

If you choose to offer the full selection of reward brands for a given region, instead of specifying a reward brand or list of brands on a request-by-request basis, you can request a Full Catalog reward by omitting the brand_code and instead specifying the region and price_in_cents in the request. If you specify a gift_template in the request, you can set the region in your template and select the Full Catalog format using the web interface.

​
Deciding between expiring and non-expiring rewards

​
Standard Rewards

Standard rewards have an unlimited claim period. You can place an order for a Standard Reward by omitting the expiry from the request, or by toggling the format to Standard in the gift_template using the web interface.

​
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 potential 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.
Please use the /gifts endpoint responsibly by following these guidelines:
  • Observe rate limits when requesting reward information from the /gifts endpoint.
  • Once rewards reach a final outcome such as CLAIMED, ADMIN_CANCELED, USER_CANCELED, or EXPIRED the state of the reward will not change again. Discontinue requesting reward information once a final outcome is determined.
  • Please have error handling in place for requests to /gifts and discontinue requesting reward information if your request produces an INVALID or EXPIRED reward response.