apiary.apib

FORMAT: 1A
HOST: https://api-testbed.giftbit.com/papi/v1

# Giftbit API
Giftbit's REST API allows you to automatically order rewards and send them to your recipients. Delivery can be handled either by links that are intergrated into another system’s workflow or by emails that are sent through the Giftbit system. 

This document includes a definitive list of endpoints defined under the 'Reference' section, an error code reference, code examples, and a guide to getting started.

Sign up at [testbed.giftbit.com](http://testbed.giftbit.com) and visit the `Account -> API keys` section to generate an API token for the Testbed environment. Your Testbed account provides a large virtual account balance, so you can try placing orders and redeeming test cards to observe the recipient experience. 

Giftbit has dedicated technical and business resources to help you understand which implementation path is right for your integration. Email sales@giftbit.com to get assistance with your project.

When your integration is ready to launch, sign up at [www.giftbit.com](http://www.giftbit.com) and contact sales@giftbit.com to signal production readiness. The Giftbit team will enable permissions to generate an API token in your production account.

## Environments and URLs
### Testbed API root
<em>`https://api-testbed.giftbit.com/papi/v1`</em>

 <em><a href="https://testbedapp.giftbit.com/register/index" target="_blank">Sign up for testbed</a></em> and get building right away.

### Production API root
<em>`https://api.giftbit.com/papi/v1`</em>

See the 'Going Live' section of the Getting Started guide below for production considerations and instructions on getting production API access.

### Environment differences
Here is a list of the key differences between Giftbit’s Testbed and Production APIs:

* Reward emails and other notifications sent through Testbed will be sent to the email address you provided for your username instead of the specified recipient email(s).
* Testbed rewards include a header notification identifying them as test emails and pages.
* There is a limited number of reward brands available in Testbed. The complete list of Production reward brands is found at [www.giftbit.com/brands](https://www.giftbit.com/brands/)
* You will have a different API token and separate account settings setup for Testbed and Production.
* To encourage continuous integration testing against the Testbed API, you are provided with a large virtual account balance in Testbed.
* Your Testbed account comes with test credit cards to simulate USD and CAD credit card payments to Giftbit. These card numbers are intended for testing purposes only and do not use real money.

## Authentication
Authenticate with the Giftbit API by sending your API token prefixed by the word `Bearer` (case sensitive) and a space in the “Authorization” HTTP header.  The `/ping` endpoint is a convenient way to test your authentication.

## HTTP success and error codes
Your API integration should always check the HTTP response code to ensure correct handling of success and error conditions.

**Only** an HTTP status of 200 means the request was successful. For non-200 responses, the predictable response body (described below) will give you details on why the request failed. We suggest logging any failure response body as best practice; the Giftbit support team will need the full response body to assist with troubleshooting. This section gives details on the response codes and recommended actions.

### Success responses

**200:**  Success.  See the reference section for success response formats for each endpoint.

### Error responses
All non-200 responses should be treated as an error and either retried, or the request fixed and then retried.  This section details the different potential non-200 responses. To assist with your programmatic error handling and troubleshooting, all error response bodies are returned in the following JSON format:

```
{
    "error": {
        "code": "<value>",
        "name": "<value>",
        "message": "<value>"
    },
    "status": <value>
}
```

* "code": an enum style error code that represents the problem and will not change.
* "name": a human readable error name.
* "message": request specific information about the error.
* "status": an integer that matches the http status code returned.

Example:

```
{
    "error": {
        "code": "ERROR_CAMPAIGN_INVALID_BRAND",
        "name": "Invalid Brand or Brand/Price combination",
        "message": "brand_code: itunesus - price_in_cents: 50000 - The brand_code provided is not valid or not available for the given price"
    },
    "status": 422
}
```

### Error response codes

**400:** Error due to a malformed request body such as broken JSON or missing required element. Requires fixing up the request body.

**401/403:** An authentication or authorization failure. Generally related to a missing or invalid API key. Ensure you are authenticating correctly.

**402:** Credit Card charge failure. Request was correct, but card was not charged.

***422:*** The request is formatted correctly but one or more parameters in the body or URL are not valid. An example would be trying to create an order with a reward value outside of the allowed range for that brand. Ensure the request parameters are valid.

***429:*** Too many requests. The Giftbit API uses adaptive rate limiting that allows burstiness and should generally not interfere with valid usage patterns. It is recommended that if you do recieve a 429 response, your code automatically retry your request with a backoff delay. Note that you can simulate this condition in the Testbed environment to assist with your error handling development without actually producing a high request rate by passing a `SIMULATE-RATELIMIT` header with a value of `true` for any request. If you feel you are being frequently rate limited in a valid usage pattern, please contact support.

***5xx:*** An unexpected error on the Giftbit side. Retry the request, and if failures persist contact support.  Note that the response body format in the 5xx case may not match the common error response format described.

#### Handling Timeouts

If you receive a network timeout or other unexpected response (such as a 5xx) when creating a order or an embedded reward, resend the POST request to `/campaign`, `/direct_link`, or `/embedded` using the same supplied `id`. The supplied `id` is idempotent, Giftbit will only ever create one order with a given supplied `id`. The supplied `id` must always be unique across different requests.

We highly recommend using exponential backoff with a limited amount of tries for timeouts and unexpected responses (such as a 5xx) with clear logging or alerts to allow for investigation.

## Getting started

The Giftbit API is designed to be simple yet powerful.  This mini-guide serves as a starting point to structure your integration. We encourage you to reach out to the Giftbit team at anytime to discuss the details of your program and integration at testbed@giftbit.com.

### Reward delivery

Before you begin building your integration, you should consider which delivery method is best suited to your system workflow and your intended user experience. There are three delivery methods: (1) link-based, (2) email, or (3) in-app rewards.

#### Delivery option 1: Another system delivers a link
You can recieve 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`.

##### Direct links go straight to a reward

Direct links go to either a predefined reward brand or a choice between reward brands. This provides the minimum necessary user interface without additional messaging or branding. This is great for when your link delivery method already includes a lot of detail and you don't need to provide anymore context. For example, direct links are perfect for merging into emails delivered by a system other than Giftbit. 

You can use the `/direct_links` endpoint to request direct link rewards.

#####  Shortlinks include a customized landing page

Shortlinks will 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.

You can use the `/campaign` endpoint along with the `delivery_type: SHORTLINK` property to request shortlink rewards.

#### Delivery option 2: Giftbit delivers your reward by email

You can 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.
Email delivery uses the `/campaign` endpoint described in the Reference section.

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

##### Building your own interactive selection step
In this type of integration, you can use the results from the `/brands` endpoint to create the interactive reward selection step in your app or website and then use the `/embedded` endpoint to request an embeddable URL which displays a page with the chosen reward's code ready for use. 

To get a URL directly to a reward page with the code, use the `/embedded` endpoint described in the Reference section.

### 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 will send a single reward brand or offer 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` will be required in your API call for a successful response.

If you don't specify the `gift_template` you will be required to provide all the required parameters in the API call, including the `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, you can 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 choose to specify the `gift_template` in your API call, you should 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.

In cases where 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 will automatically adjust to display brands that align with the overridden price.

### Promotional rewards option

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 will automatically set the calculated `expiry` date.

### Retrieving reward brand information

By using the `/brands` endpoint, you can access the list of reward brands available from Giftbit and detailed information about each reward 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 found at [www.giftbit.com/brands](https://www.giftbit.com/brands/).

Searching, filtering, and result paging uses the `/brands` endpoint described in the Reference section.

### Using templates with email and shortlink rewards

Templates allow rewards with custom messaging and branding to be richly formatted and provide a nice separation of responsibility between content creators and developers.

This is done by allowing the custom reward content (subject, the message with formatting and rich content, and company brand image) to be 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 will be 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. 
Note that if you provide a template then 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.

*NOTE:* For Shortlinks, the `subject` field won't be 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 as well the status of the rewards you've prevously 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.

## Going live

When your integration is ready to launch, sign up at www.giftbit.com and contact sales@giftbit.com to signal production readiness. The Giftbit team will enable permissions to generate an API token in your production account.

## Providing feedback on the API documentation

The Giftbit team makes heavy use of external APIs ourselves, and we know how frustrating it can be when the documentation is unclear or doesn't match the actual API behaviour. If you find any such problems with ours, don't hesitate to let us know via testbed@giftbit.com.

## Ping [/ping]
`GET /ping` provides a way to test your authentication and check the health of the Giftbit API.

### ping [GET /ping]
+ Request
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Response 200
    + Attributes
        + username (string) - The username associated with the credentials provided.
        + displayname (string) - The display name associated with the credentials provided.
        + info
            + code (string) - Status code for the request. Values
                   INFO_CREDENTIALS - Credentials are valid.

            + Body
                {
                    "username":"example_merchant@giftbit.com",
                    "displayname":"Example Merchant",
                    "info":
                        {
                            "code":"INFO_CREDNTIALS",
                            "name":"Credentials are valid",
                            "message":"The credentials used are valid and login attempt was successful."
                        }
                }

+ Response 401

        {
            "status":401,
            "error":{
                "code": "ERROR_UNAUTHORIZED",
                "name": "Unauthorized",
                "message": "Access Token missing or invalid"
            }
        }


## Brands [/brands]

`GET /brands` returns a list of reward brands available from Giftbit and detailed information, including the `brand_code` and an allowed price to include in your API calls to `/campaign`, `/direct_link`, or `/embedded`. 
Some brands only allow certain fixed values, while others have an allowed range.
You can restrict the results list with any combination of price, currency, region, or search terms. The `/brands` endpoint supports the paging of results.

`GET /brands/{brand_code}` retrieves extended information about the specified brand.

### list brands [GET /brands{?region}{?max_price_in_cents}{?min_price_in_cents}{?currencyisocode}{?search}{?limit}{?offset}{?embeddable}]
+ Parameters
    + region (number, optional) - Limits the results to brands that are available in the provided region as per the `id` returned from the `/region` endpoint.
    + `max_price_in_cents` (number, optional) - Limits the results to brands that have an available reward option less than or equal to this value.
    + `min_price_in_cents` (number, optional) - Limits the results to brands that have an available reward option greater than or equal to this value.
    + currencyisocode (string, optional) - Limits the results to brands that have an available reward matching the provided currency. Options:
        * CAD
        * USD
        * AUD
    + search (string, optional) - Limits the results to brands containing the search term provided in their name, description, or other fields.
    + limit (number, optional) - Limits the number of results to the provided value. Default value is 20.
    + offset (number, optional)- Offsets the results by provided value. Used for paging through results. Default value is 0.
    + embeddable(boolean, optional) - If supplied with a `true` value, brands that cannot be used for in-app delivery via the `embedded` endpoint will be omitted.

+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Response 200

    + Attributes
        + brands
            + `brand_code` (string) - A unique alphanumeric identifier for the brand.  Used as input to the `/campaign` endpoint when sending your reward offers.
            + `name` (string) - The name of the Brand.
            + `disclaimer` (string, optional) - Certain brands have disclaimer text that must appear along with the brand when displayed.  This field will be omitted if there is no disclaimer for the given brand.
            + `image_url`  - A full URL to the brand's image to display.  Will always be a secure (https) image URL.
        + info
            + `code` (string) - A status code for the request. Possible values: `INFO_BRANDS_RETRIEVED`
        + `number_of_results` (number) - The number of results returned.
        + `limit` (number) - The maximum number of results that can be returned.
        + `offset` (number) - The offset into the results.
        + `total_count` (number) - The total number of results that matched request.

    + Body

            {
               "brands": [
                    {
                        "brand_code": "AMZNCOM",
                        "name": "Amazon.com",
                        "image_url": "https://uploadedimages.giftbit.com/550/amazon-30ec8f7a-616a-46aa-aa3f-cafbca10bddc.jpg",
                        "disclaimer": "Amazon.com Gift Cards (\"GCs\") sold by Giftbit Inc., an authorized and independent reseller of Amazon.com Gift Cards. Except as required by law, GCs cannot be transferred for value or redeemed for cash. GCs may be used only for purchases of eligible goods at Amazon.com or certain of its affiliated websites. For complete terms and conditions, see http://www.amazon.com/gc-legal. GCs are issued by ACI Gift Cards, Inc., a Washington corporation. All Amazon ®, ™ & © are IP of Amazon.com, Inc. or its affiliates. No expiration date or service fees."
                    },
                    {
                        "brand_code": "WHOLEFOODS",
                        "name": "Whole Foods Market",
                        "image_url": "https://uploadedimages.giftbit.com/wholefoods/wholefoodsgiftbit-f629cfa4-c7f1-4c6f-9a67-f8ee144b8db7.png"
                    }
                ],
               "number_of_results":2,
               "info":{
                  "code":"INFO_BRANDS_RETRIEVED",
                  "name":"Brand(s) Retrieved",
                  "message":"A list of brands or single brand has been retrieved"
               },
               "limit":20,
               "offset":0,
               "total_count":2
            }

### retrieve brand [GET /brands/{brand_code}]
+ Parameters
    + `brand_code` (string, required) - Retrieve a single brand by brand_code.

+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Response 200

    + Attributes
        + brands
            + `brand_code` (string) - A unique alphanumeric identifier for the brand.  Used as input to the `/campaign` endpoint when sending your reward offers.
            + `name` (string) - The name of the Brand.
            + `disclaimer` (string, optional) - Certain brands have disclaimer text that must appear along with the brand when displayed.  This field will be omitted if there is no disclaimer for the given brand.
            + `image_url`  - A full URL to the brand's image to display.  Will always be a secure (https) image URL.
            + `regions` (array[number]) - a list of region ids (corresponding to the `/regions` endpoint in which this brand is available
            + `fund_currencyisocode` (string) - The three character currency code for this brand.
            + `variable_price` (boolean) - true if this brand allows rewards to be created of any value within a range. False if only a set of fixed prices is allowed.  If true, `min_price_in_cents` and `max_price_in_cents` will be set in the response.  If false, `allowed_prices_in_cents' will be set
            + `min_price_in_cents` (number, optional) - Gives the minimum possible reward value for variable price brands.  Will be present in the response only if variable_price=true
            + `max_price_in_cents` (number, optional) - Gives the maximum possible reward value for variable price brands.  Will be present in the response only if variable_price=true
            + `allowed_prices_in_cents` (array[number], optional) - Gives the possible reward values for non variable price brands.  Will be present in the response only if variable_price=false

        + info
            + `code` (string) - A status code for the request. Possible values: `INFO_BRANDS_RETRIEVED`

    + Body

            {
                "brand": {
                    "brand_code": "WHOLEFOODS",
                    "name": "Whole Foods Market",
                    "image_url": "https://uploadedimages.giftbit.com/wholefoods/wholefoodsgiftbit-f629cfa4-c7f1-4c6f-9a67-f8ee144b8db7.png",
                     "regions": [
                        2
                    ],
                    "fund_currencyisocode": "USD",
                    "inapp_available": true,
                    "variable_price": false,
                    "allowed_prices_in_cents": [
                        1000,
                        2500,
                        5000,
                        10000
                    ]
                },
                "info": {
                    "code": "INFO_BRANDS_RETRIEVED",
                    "name": "Brand(s) Retrieved",
                    "message": "A list of brands or single brand has been retrieved"
                }
            }

+ Response 422

    + Body

            {
                "error": {
                    "code": "ERROR_BRANDS_NO_SUCH_BRAND",
                    "name": "No brand found",
                    "message": "No brand found matching that code"
                },
                "status": 422
            }

## Regions [/regions]

`GET /regions` returns a list of the regions that filter results from the `/brands` endpoint. Regions are used to request a Full Catalog reward from the `/campaign` or `/direct_links` endpoint.

## list regions [GET /regions]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Response 200
    + Attributes
        + regions
            + id (number) - A numeric identifier for the region.
            + name (string) - The name of the region.
            + `image_url` (string) - An image for the region.
        + info
            + code (string) - Status code. [`INFO_RETRIEVED_REGIONS`]

    + Body

            {
                "regions": [
                    {
                        "id": 1,
                        "name": "Canada",
                        "image_url": "https://s3-us-west-2.amazonaws.com/staticimageskiind/flags/CA@3x.png"
                    },
                    {
                        "id": 2,
                        "name": "USA",
                        "image_url": "https://s3-us-west-2.amazonaws.com/staticimageskiind/flags/US@3x.png"
                    },
                    {
                        "id": 3,
                        "name": "Global",
                        "image_url": "https://s3-us-west-2.amazonaws.com/staticimageskiind/flags/GLBL@3x.png"
                    },
                    {
                        "id": 4,
                        "name": "Australia",
                        "image_url": "https://s3-us-west-2.amazonaws.com/staticimageskiind/flags/AU@3x.png"
                    }
                ],
                "info": {
                    "code": "INFO_RETRIEVED_REGIONS",
                    "name": "Regions Retrieved",
                    "message": "A list of regions has been retrieved."
                }
            }

## Data Structures

### Contact
+ email: pjohnson@giftbit.com (required)
+ firstname: Perry (optional)
+ lastname: Johnson (optional)


## Email Orders [/campaign]

`POST /campaign` places an order for one or more emailed rewards by default. See the "create email order" reference for detailed information on the request and response bodies.

The use of `gift_template` in API calls to `/campaign` is optional; however, all required parameters must be specified in the API call or set in the template using the web interface for a successful response. These template parameters include `subject`, `message`, `price_in_cents`, and `brand_codes` (or `region` for Full Catalog rewards). 

Include the optional parameter `expiry` to create a promotional reward with a limited claim period.

If you do not specify the `delivery_type` the request will default to an email reward delivered by Giftbit, and at least one valid contact will be required.

`GET /campaign/id` retrieves the status and information about the specified order.

### create email order [POST /campaign]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

    + Attributes
        + message: `Example: The reward message!` (string, optional) - Reward email message. Required if no supplied template.
        + subject: `Example: Please enjoy this reward!` (string, optional) - Reward email subject. Required if no supplied template.
        + `gift_template`: `Example: ABCDE` (string, optional) - The template id used for this order, as per the template section of your web account.  Recommended, but not required if providing the `message` and `subject` as part of the create order API call.
        + `contacts` (array[Contact], required) - A list of contact objects and is required.
        + `price_in_cents`: `2500` (number, required) - the value of the offer you are sending, in cents.  A value of 2500 would send a $25 reward offer for the given brand(s)
        + `brand_codes`: `Example:["itunesus","amazonus"]` (array[string], optional) - custom list of one or more brand_code as given by the `/brands` endpoint to send in your order. Use this to limit choice to a few select brands. Not applicable to Full Catalog choice.
        + `region`: `Example: Canada` (string, optional) - + `region`: `Example: Canada` (string, optional) - Specifies the geographical region for the Full Catalog from which recipients can select a brand during the claim process.
        + expiry: `Example: YYYY-MM-dd` (string, optional) - The order's claim before date. After the end of this date (in Pacific Standard Time), recipients in this order will not be able to redeem their reward offers and the appropriate portion of the credits for any unclaimed reward offers will be returned to your account.  It may not exceed one year from the time of creation.
        + id: `Example: abc123` (string, required) - An identifier for the order assigned by the client (you).  Must be unique across all your orders.  If an unexpected error occurs sending your order, you can safely send the same POST again with the same `id`.


    + Body

            {
                "gift_template": "XDKHE",
                "contacts": [
                    {
                        "firstname":"Perry",
                         "lastname":"Johnson",
                         "email":"pjohnson@giftbit.com"
                     },
                     {
                        "firstname":"Rita",
                         "lastname":"Robson",
                         "email":"rrobson@giftbit.com"
                     }
                ],
                "price_in_cents":5000,
                "brand_codes": [
                    "itunesus",
                    "amazonus"
                 ],
                "expiry":"2018-11-01",
                "id":"clientProvidedGiftId_abc123"
            }

+ Response 200
    + Attributes
        + info
            + code (string) - Status code for request. Possibilities:
                    `INFO_CAMPAIGN_CREATED` - Order creation has begun successfully
                    `INFO_CAMPAIGN_CREATED_FUNDS_REQUIRED` - Order creation request was successfully received by Giftbit but there are insufficient funds in your Giftbit account to cover the cost of the order. Note you do not need to resend the order. It will automatically be sent when there are enough funds in your account.
                    `INFO_CAMPAIGN_CREATED_FUNDS_PENDING` - The order creation request was successfully received by Giftbit but pending funds (such as a cheque or wire transfer that you sent) have not yet cleared. Note you do NOT need to resend the order as soon as your pending funds clear and become available, the order will be automatically delivered to your recipients.
            + name (string) - human readable status name
            + message (string) - request context specific message
        + campaign
            + company_name (string) - The sender's business name
            + message (string) - The message for the order.
            + subject (string) - The subject for the order.
            + contacts (object) - A list of contacts the order is being sent to.
            + price_in_cents (number) - The amount of the reward offer to each recipient.
            + brand_codes (array[string]) - Custom list of reward brand(s) sent.
            + region (string) - Full Catalog region name. Possibilities: USA, Canada
            + status (string) - The status of the order. Possibilities:
                API_CREATING - The order is in the process of being created.
                AWAITING_FUNDS - The order has not yet been delivered to the recipient(s)
                        because of insufficient funds in your Giftbit account. You do NOT need to
                        resend the order as soon as you add funds to your account or your pending
                        funds clear, the order will be automatically delivered to your recipients.
                CAMPAIGN_CREATED - The order has been created. Note the reward emails may still be in the process of being delivered at this point.
            + uuid (string) - A unique identifier for the order generated by Giftbit. This id can be used to retrieve the order.
            + `delivery_type` (string) - The delivery type of the order. Possibilities:

                    GIFTBIT_EMAIL

            + expiry (string) - The order's claim before date as described in creation parameters.
            + `contact_success_count` (number) - The number of contacts added successfully.
            + `contact_failure_count` (number) - The number of contacts that could not be added to the order. This occurs for instance when a contact email has been flagged as undeliverable.
            + fees - Information about the cost of the order and any associated fees at creation or completion time.
            + id (string) - The client provided id for the order.
    + Body

            {
               "info":{
                  "code":"INFO_CAMPAIGN_CREATED",
                  "name":"Campaign Created",
                  "message":"Campaign creation has begun."
               },
               "status":200,
               "campaign":{
                  "company_name":"Company Name",
                  "message":"Thanks for being such an awesome customer!",
                  "subject":"Please enjoy this reward!",
                  "contacts":[
                     {
                        "email":"pjhonson@giftbit.com",
                        "firstname":"Perry",
                        "added_succesfully":true,
                        "lastname":"Johnson",
                        "message":"New contact"
                     },
                     {
                        "email":"rrobson@giftbit.com",
                        "firstname":"Rita",
                        "added_succesfully":true,
                        "lastname":"Robson",
                        "message":"New contact"
                     }
                  ],
                  "price_in_cents": 5000,
                  "brand_codes": [
                        "itunesus",
                        "amazonus"
                  ],
                  "status":"API_CREATING",
                  "uuid":"9a405b513c11413aaac593a0c2e1a15d",
                  "suppress_default_greeting":false,
                  "delivery_type":"GIFTBIT_EMAIL",
                  "expiry":"2017-05-01",
                  "contacts_success_count":2,
                  "contacts_failure_count":0,
                  "fees":{
                    "cost_entries":[
                      {
                        "percentage":0,
                        "fee_type":"PREFUND_GIFT_COST",
                        "amount_in_cents":2000,
                        "currency":"USD",
                        "tax_type":"NOTAX",
                        "tax_in_cents":0,
                        "number_of_gifts":2,
                        "fee_per_gift_in_cents":1000
                      },
                      {
                        "percentage":0.000,
                        "fee_type":"BREAKAGE_PERCENTAGE",
                        "amount_in_cents":0,
                        "currency":"USD",
                        "tax_type":"NOTAX",
                        "tax_in_cents":0,
                        "number_of_gifts":2,
                        "fee_per_gift_in_cents":0
                      }
                    ],
                    "subtotal_in_cents":2000,
                    "tax_in_cents":0,
                    "tax_type":"NOTAX",
                    "total_in_cents":2000
                 },
                 "id":"clientProvidedGiftId_abc123"
              }
            }

+ Response 422
    + Attributes
        + status (number) - the http status code
        + error
            + code (string) - An enum-style error code desribing the reason for failure.
            + name (string) - human readable error name
            + message (string) - request context specific error message

    + Body

            {
                "error": {
                    "code": "ERROR_CAMPAIGN_INVALID_BRAND",
                    "name": "Invalid Brand or Brand/Price combination",
                    "message": "brand_code: itunesus - price_in_cents: 50000 - The brand_code provided is not valid or not available for the given price"
                },
                "status": 422
            }


### retrieve order by ID [GET /campaign/{id}]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Parameters
    + `id`: clientProvidedGiftId_abc123 (required) - The order id. This id is the identifier for the order assigned by the client or the uuid which is assigned by Giftbit.

+ Response 200
    + Attributes
        + info
            + code (string) - Status code for the request. [INFO_CAMPAIGN_RETRIEVED]
        + campaign (object) - The returned order object.
    + Body

            {
               "info":{
                  "code":"INFO_CAMPAIGN_RETRIEVED",
                  "name":"Campaign Retrieved",
                  "message":"A campaign or list of campaigns has been retrieved."
               },
               "campaign":{
                  "company_name":"Company Name",
                  "message":"Thanks for being such an awesome customer!",
                  "subject":"Please enjoy this reward!",
                  "contacts":[
                     {
                        "email":"pgibbons@giftbit.com",
                        "firstname":"Peter",
                        "lastname":"Gibbons"
                     },
                     {
                        "email":"brobson@giftbit.com",
                        "firstname":"Bob",
                        "lastname":"Robson"
                     }
                  ],
                  "price_in_cents": 5000,
                  "brand_codes": [
                        "itunesus"
                  ],
                  "status":"CAMPAIGN_CREATED",
                  "uuid":"ee0d3f657fb640c987033e63a82e2279",
                  "suppress_default_greeting":false,
                  "delivery_type":"GIFTBIT_EMAIL",
                  "expiry":"2017-05-01",
                  "fees":{
                     "cost_entries":[
                        {
                           "percentage":0,
                           "fee_type":"PREFUND_GIFT_COST",
                           "amount_in_cents":2000,
                           "currency":"USD",
                           "tax_type":"NOTAX",
                           "tax_in_cents":0,
                           "number_of_gifts":2,
                           "fee_per_gift_in_cents":1000
                        },
                        {
                           "percentage":0.00,
                           "fee_type":"BREAKAGE_PERCENTAGE",
                           "amount_in_cents":0,
                           "currency":"USD",
                           "tax_type":"NOTAX",
                           "tax_in_cents":null,
                           "number_of_gifts":2,
                           "fee_per_gift_in_cents":0
                        }
                     ],
                     "subtotal_in_cents":2000,
                     "tax_in_cents":0,
                     "tax_type":"NOTAX",
                     "total_in_cents":2000
                  },
                  "id":"clientProvidedGiftId_abc1232"
               }
            }

## Shortlinks Orders [/shortlink]

Shortlink rewards are an alternative to email rewards delivered by Giftbit. They still include the custom branding and messaging on an initial landing page. Once you retrieve the short URL for a shortlink reward, your system can distribute the shortlink to your recipient using an alternative email system, SMS, or another distribution method.  

A request `POST /campaign` with `delivery_type: "SHORTLINK"` places an order for one or more shortlink rewards.

The use of `gift_template` in API calls to `/campaign` is optional; however, all required parameters must be specified in the API call or set in the template using the web interface for a successful response. These template parameters include `message`, `price_in_cents`, and `brand_codes` (or `region` for Full Catalog rewards).

Include the optional parameter `expiry` to create a promotional reward with a limited claim period.

`GET /links/{id}` retrieves the URL for the link-based reward following the order creation process. 
The URL will be ready after a short delay following the successful response from `/campaign`. 
We recommend polling the `/links` endpoint every 5 minutes until the URL is ready.

Optionally, you can specify a recipient contact in the API call to create a shortlink reward, and the resulting shortlink will be associated with the specified contact in the web interface and reporting. 
Giftbit will not attempt to deliver shortlink rewards by email when you associate shortlinks with contacts.

### create shortlink order [POST /campaign]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

    + Attributes
        + message: `Example: The reward message!` (string, optional) - Reward email message. Required if no supplied template.
        + `gift_template`: `Example: ABCDE` (string, optional) - The template id used for this order, as per the template section of your web account.  Recommended, but not required if providing the `message` as part of the create shortlink order API call.
        + `delivery_type`: `Example: Shortlink` (string, required) - Must be set to "SHORTLINK"
        + `link_count` (number, required) - Amount of reward links to generate (must be a positive integer)
        + `price_in_cents`: `2500` (number, required) - the value of the offer you are sending, in cents.  A value of 2500 would send a $25 reward offer for the given brand(s)
        + `brand_codes`: `Example:["itunesus","amazonus"]` (array[string], required) - a list of one or more brand_code as given by the `/brands` endpoint to send in your order.  To give your recipients a choice, simply provide more than one brand_code; recipients will then get to choose the brand they prefer as part of the claim process.
        + expiry: `Example: YYYY-MM-dd` (string, optional) - The order's claim before date. After the end of this date (in Pacific Standard Time), recipients in this order will not be able to redeem their reward offers and the appropriate portion of the credits for any unclaimed reward offers will be returned to your account.  It may not exceed one year from the time of creation.
        + id: `Example: abc123` (string, required) - An identifier for the order assigned by the client (you).  Must be unique across all your orders.  If an unexpected error occurs sending your order, you can safely send the same POST again with the same `id`.

    + Body

            {
                "gift_template": "XDKHE",
                "delivery_type": "SHORTLINK",
                "link_count": 1,
                "price_in_cents": 2500,
                "brand_codes": [
                  "itunesus",
                  "amazonus"
                ],
                "expiry":"2023-07-07",
                "id":"clientProvidedGiftId_abc123"
            }


+ Response 200
    + Attributes
        + info
            + code (string) - Status code for request. Possibilities:
                    `INFO_CAMPAIGN_CREATED` - Order creation has begun successfully
                    `INFO_CAMPAIGN_CREATED_FUNDS_REQUIRED` - Order creation request was successfully received by Giftbit but there are insufficient funds in your Giftbit account to cover the cost of the order. Note you do not need to resend the order. It will automatically be sent when there are enough funds in your account.
                    `INFO_CAMPAIGN_CREATED_FUNDS_PENDING` - The order creation request was successfully received by Giftbit but pending funds (such as a cheque or wire transfer that you sent) have not yet cleared. Note you do NOT need to resend the order as soon as your pending funds clear and become available, the order will be automatically delivered to your recipients.
            + name (string) - human readable status name
            + message (string) - request context specific message
        + campaign
            + company_name (string) - The sender's business name
            + message (string) - The message for the order.
            + subject (string) - The subject for the order.
            + contacts (object) - A list of contacts the order is being sent to.
            + price_in_cents (number) - The amount of the reward offer to each recipient.
            + brand_codes (array[string]) - Custom list of reward brand(s) sent.
            + region (string) - Full Catalog region name. Possibilities: USA, Canada
            + status (string) - The status of the order. Possibilities:
                API_CREATING - The order is in the process of being created.
                AWAITING_FUNDS - The order has not yet been delivered to the recipient(s)
                        because of insufficient funds in your Giftbit account. You do NOT need to
                        resend the order as soon as you add funds to your account or your pending
                        funds clear, the order will be automatically delivered to your recipients.
                CAMPAIGN_CREATED - The order has been created. Note the reward emails may still be in the process of being delivered at this point.
            + uuid (string) - A unique identifier for the order generated by Giftbit. This id can be used to retrieve the order.
            + `delivery_type` (string) - The delivery type of the order. Possibilities:

                    SHORTLINK

            + expiry (string) - The order's claim before date as described in creation parameters.
            + fees - Information about the cost of the order and any associated fees at creation or completion time.
            + id (string) - The client provided id for the order.
            + link_count (number) - Amount of reward links generated.
            
    + Body


            {
              "info": {
                "code": "INFO_CAMPAIGN_CREATED",
                "name": "Campaign Created",
                "message": "Campaign creation has begun."
              },
              "status": 200,
              "campaign": {
                "company_name":"Company Name",
                "message": "Thanks for being such an awesome customer!",
                "subject": "Please enjoy this reward!",
                "contacts": [],
                "status": "API_CREATING",
                "uuid": "49e90cb2616b4893b55871a1786f84b0",
                "suppress_default_greeting": false,
                "delivery_type": "SHORTLINK",
                "price_in_cents": 2500,
                "brand_codes": [
                    "itunesus",
                    "amazonus"
                ],
                "expiry": "2023-07-07",
                "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": "clientProvidedGiftId_abc123",
                "link_count": 1
                }
              }


### retrieve shortlink URLs [GET /links/{id}]

+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Parameter
    + id: `clientProvidedGiftId_abc123` (number, required) - The client provided id of the order.

+ Response 200
    + Attributes
        + info
            + code (string) - Status code for request. Possibilities:
                    `INFO_LINKS` - Your reward offers are ready and the links are returned.
                    `INFO_LINKS_GENERATION_IN_PROGRESS` - Giftbit is still preparing your reward offers. Try again in 5 minutes
            + name (string) - human readable status name
            + message (string) - request context specific message
        + shortlinks (array) - A list of shortlink objects

    + Body

            {
               "info":{
                  "code":"INFO_LINKS_GENERATION_IN_PROGRESS",
                  "name":"Links have not yet completed generating; request again in 5 minutes",
                  "message":"Link generation is not complete. Large orders will take some time to process and may be held for manual review; use the /campaign endpoint for more detail on your order"
               }
            }


+ Response 200
    + Body
    
            {
              "info": {
                "code": "INFO_LINKS",
                  "name": "Link information retrieved",
                  "message": "Returned links for requested Campaign"
              },
              "shortlinks": [
                  {
                  "number": 1,
                  "shortlink": "http://gtbt.co/q5WmFXVjCAh"
                  }
              ],
              "number_of_results": 1,
              "limit": 50,
              "offset": 0,
              "total_count": 1
            }

## Direct Links Orders [/direct_links]

Direct links are URLs that go straight to rewards that have minimal Giftbit branding and no template content or message.

The reward URLs are immediately generated and returned in the API response and can be delivered through another channel or system.

A direct link reward can be configured to be either a full catalog of options in a specific region, or a custom reward of one or more specific brands. When viewing the direct link, the recipient sees their selection of available brand options (if applicable), and then claims their reward.

A `POST /direct_links` request is used to place an order for direct link rewards.

Required parameters for the API include `price_in_cents` and `brand_codes` (or `region` for Full Catalog rewards).

Include the optional parameter `expiry` to create a promotional reward with a limited claim period.

Each API request should also include an `id` set by you.

Optionally, you can set a `link_count` in your request to generate more than one direct link at a time.

`GET /links/{id}` retrieves the direct link URLs for the order (if needed in the future).

### create direct link order [POST /direct_links]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

    + Attributes
        + id: `Example: abc123` (string, required) - An identifier for the order assigned by the client (you).  Must be unique across all your orders.  If an unexpected error occurs sending your order, you can safely send the same POST again with the same `id`.
        + `price_in_cents`: `2500` (number, required) - the value of the offer you are sending, in cents.  A value of 2500 would send a $25 reward offer for the given brand(s).
        + expiry: `Example: YYYY-MM-dd` (string, optional) - The order's claim before date. After the end of this date (in Pacific Standard Time), recipients in this order will not be able to redeem their reward offers and the appropriate portion of the credits for any unclaimed reward offers will be returned to your account.  It may not exceed one year from the time of creation.
        + `brand_codes`: `Example:["itunesus","amazonus"]` (array[string], optional) - a list of one or more brand_codes as given by the `/brands` endpoint to send in your order.  To give your recipients a choice, simply provide more than one brand_code; recipients will then get to choose the brand they prefer as part of the claim process. Brand codes must be from the same region.
        + `region` : `Example: USA` (string, optional) - 
        + `link_count`: `10` (number, optional) - Amount of reward links to generate (must be a positive integer)

    + Body

            {
                "id":"clientProvidedId_abc123",
                "price_in_cents": 2500,
                "expiry":"2025-01-01",
                "region": "USA",
                "link_count": 1
            }


+ Response 200
    + Attributes
        + info
            + code (string) - Status code for request. Possibilities:
                    `INFO_CAMPAIGN_CREATED` - Order creation has begun successfully
                    `INFO_CAMPAIGN_CREATED_FUNDS_REQUIRED` - Order creation request was successfully received by Giftbit but there are insufficient funds in your Giftbit account to cover the cost of the order. Note you do not need to resend the order. It will automatically be sent when there are enough funds in your account.
                    `INFO_CAMPAIGN_CREATED_FUNDS_PENDING` - The order creation request was successfully received by Giftbit but pending funds (such as a cheque or wire transfer that you sent) have not yet cleared. Note you do NOT need to resend the order as soon as your pending funds clear and become available, the order will be automatically delivered to your recipients.
            + name (string) - human readable status name
            + message (string) - request context specific message
        + direct_links (array) - A list of direct link URLs
        + campaign
            + company_name (string) - The sender's business name
            + message (string) - The message for the order.
            + subject (string) - The subject for the order.
            + contacts (object) - A list of contacts the order is being sent to.
            + price_in_cents (number) - The amount of the reward offer to each recipient.
            + brand_codes (array[string]) - Custom list of reward brand(s) sent.
            + region (string) - Full Catalog region name. Possibilities: USA, Canada
            + status (string) - The status of the order. Possibilities:
                API_CREATING - The order is in the process of being created.
                AWAITING_FUNDS - The order has not yet been delivered to the recipient(s)
                        because of insufficient funds in your Giftbit account. You do NOT need to
                        resend the order as soon as you add funds to your account or your pending
                        funds clear, the order will be automatically delivered to your recipients.
                CAMPAIGN_CREATED - The order has been created. Note the reward emails may still be in the process of being delivered at this point.
            + uuid (string) - A unique identifier for the order generated by Giftbit. This id can be used to retrieve the order.
            + `delivery_type` (string) - The delivery type of the order. Possibilities:

                    DIRECT_LINK

            + expiry (string) - The order's claim before date as described in creation parameters.
            + fees - Information about the cost of the order and any associated fees at creation or completion time.
            + id (string) - The client provided id for the order.

    + Body

            {
                "info": {
                "code": "INFO_CAMPAIGN_CREATED",
                "name": "Campaign Created",
                "message": "Campaign creation has begun."
              },
              "status": 200,
              "direct_links": [
                "https://reward.giftbit.com/getReward/dl-59ec25692ca940358fcd51e91e3d1fdb"
              ],
              "campaign": {
                "company_name":"Company Name",
                "message": "Here is your reward!",
                "subject": null,
                "contacts": [],
                "status": "API_CREATING",
                "uuid": "aa10bbe7bfa64b4a81d61d3ade419653",
                "suppress_default_greeting": false,
                "delivery_type": "DIRECT_LINK",
                "region": "USA",
                "expiry": "2025-01-01",
                "fees": {
                  "cost_entries": [
                    {
                      "percentage": 0,
                      "fee_type": "PREFUND_GIFT_COST",
                      "amount_in_cents": 2500,
                      "currency": "CAD",
                      "tax_type": "NOTAX",
                      "tax_in_cents": 0,
                      "number_of_gifts": 1,
                      "fee_per_gift_in_cents": 0
                    },
                    {
                      "percentage": 35.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
                    },
                    {
                      "percentage": 0,
                      "fee_type": "UPFRONT_PER_GIFT_FEE",
                      "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": "clientProvidedId_abc123"
              }
            }


### retrieve direct link URLs [GET /links/{id}]

+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Parameter
    + id: `clientProvidedGiftId_abc123` (number, required) - The client provided id of the order.

+ Response 200
    + Attributes

        + info
            + code (string) - Status code for request. Possibilities:
                    `INFO_LINKS` - Your reward offers are ready and the links are returned.
                    `INFO_LINKS_GENERATION_IN_PROGRESS` - Giftbit is still preparing your reward offers. Try again in 5 minutes
            + name (string) - human readable status name
            + message (string) - request context specific message
        + directlinks (array) - A list of direct link objects
        
    + Body


            {
              "info": {
                "code": "INFO_LINKS",
                  "name": "Link information retrieved",
                  "message": "Returned links for requested Campaign"
              },
              "directlinks": [
                  {
                  "link": "https://reward.giftbit.com/getReward/dl-59ec25692ca940358fcd51e91e3d1fdb",
                  "number": 1
                  }
              ],
              "number_of_results": 1,
              "limit": 50,
              "offset": 0,
              "total_count": 1
            }


## Embedded Rewards [/embedded]

A `POST /embedded` request is used to place an reward order for a specific brand for immediate in-app delivery in your app or website. The response includes a URL where the recipient will reveal their reward code.

In-app rewards are designed to be embedded into an existing app with minimal Giftbit branding and with no template content or message during the claim process.

Each API call specifies the `price_in_cents` and the `brand_code` and unique supplied `id` and produces a single reward.

Recipients are automatically directed to the card without additional claim steps.

All rewards are automatically claimed. They cannot be canceled.

### create embedded reward [POST /embedded]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

    + Attributes

        + `price_in_cents`: `2500` (number, required) - the value of the digital reward you are creating, in cents.  A value of 2500 would create a $25 reward for the given brand.
        + `brand_code`: `Example:itunesus` (string, required) - a brand_code as given by the `/brands` endpoint.
        + id: `Example: abc123` (string, required) - An identifier for the order assigned by the client (you).  Must be unique across all your orders.  If an unexpected error occurs sending your order, you can safely send the same POST again with the same `id`.



    + Body

            {
                "brand_code": "itunesus",
                "price_in_cents" : 2500,
                "id": "myGift12345"
            }

+ Response 200
    + Attributes
        + info
            + code (string) - Status code for request. Possibilities:
                    `INFO_CAMPAIGN_CREATED` - Order creation has begun successfully
                    `INFO_CAMPAIGN_CREATED_FUNDS_REQUIRED` - Order creation request was successfully received by Giftbit but there are insufficient funds in your Giftbit account to cover the cost of the order. Note you do not need to resend the order. It will automatically be sent when there are enough funds in your account.
                    `INFO_CAMPAIGN_CREATED_FUNDS_PENDING` - The order creation request was successfully received by Giftbit but pending funds (such as a cheque or wire transfer that you sent) have not yet cleared. Note you do NOT need to resend the order as soon as your pending funds clear and become available, the order will be automatically delivered to your recipients.

        + campaign
            + price_in_cents (number) - The amount of the reward.
            + brand_code (string) - The brand of reward.
            + uuid (string) - A unique identifier for the order generated by Giftbit. This id can be used to retrieve the order.
        + fees - Information about the cost of the order and any associated fees at creation or completion time.
        + id (string) - The client provided id for the order.
        + gift_link (string) - The unique reward link for embedding your reward as per the integration guide.
    + Body

            {
                 "info": {
                 "code": "INFO_CAMPAIGN_CREATED",
                 "name": "Campaign Created",
                 "message": "Campaign creation has begun."
                 },

                 "status": 200,
                 "campaign": {
                     "uuid": "5ac9cea1234d47f5be3592ad0fe7cc76",
                     "fees": {
                         "cost_entries": [
                         {
                             "percentage": 0,
                             "fee_type": "PREFUND_GIFT_COST",
                             "amount_in_cents": 1000,
                             "currency": "USD",
                             "tax_type": "NOTAX",
                             "tax_in_cents": 0,
                             "number_of_gifts": 1,
                             "fee_per_gift_in_cents": 1000
                         },
                         {
                             "percentage": 0,
                             "fee_type": "UPFRONT_PER_GIFT_FEE",
                             "amount_in_cents": 75,
                             "currency": "USD",
                             "tax_type": "NOTAX",
                             "tax_in_cents": 0,
                             "number_of_gifts": 1,
                             "fee_per_gift_in_cents": 75
                         }
                         ],
                     "subtotal_in_cents": 1075,
                     "tax_in_cents": 0,
                     "tax_type": "NOTAX",
                     "total_in_cents": 1075
                    },
                     "id": "gift12345",
                     "brand_code": "itunesus",
                     "price_in_cents" : 2500
                },
                "gift_link":
                "https://testbedapp.giftbit.com/embeddedRewards/index/5ac9cea1234abcf5be35
                92ad0fe7cc76"
            }

+ Response 422
    + Attributes
        + status (number) - the http status code
        + error
            + code (string) - An enum-style error code desribing the reason for failure.
            + name (string) - human readable error name
            + message (string) - request context specific error message

    + Body

            {
                "error": {
                    "code": "ERROR_CAMPAIGN_INVALID_BRAND",
                    "name": "Invalid Brand or Brand/Price combination",
                    "message": "brand_code: itunesus - price_in_cents: 50000 - The brand_code provided is not valid or not available for the given price"
                },
                "status": 422
            }


## Funds [/funds]
`GET /funds` retrieves a real-time overview of your account balance. You can request a report through the web interface for individual funding event details.

`POST /funds` is used to top up your account balance with a credit card payment. You can use the web interface to place a credit card on file for each currency you plan to fund. The success response will provide your updated account balance.

Contact finance@giftbit.com to inquire about other accepted payments, such as ACH, bank transfers, and automated direct debit payments.

### retrieve funding information [GET /funds]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Response 200
    + Attributes
        + fundsbycurrency - USD, CAD, PRO (demo credits)
        + `available_in_cents` (number) - Value, in cents of available funds in your account. This is your purchasing power for new reward orders.
        + `pending_in_cents` (number) - Value, in cents, of funds for your account that have been sent by you but yet fully processed by Giftbit. These will move to available balance once processed.
        + `reserved_in_cents` (number) - Value, in cents, of funds that are held to cover the cost of outstanding reward offers that have not yet been claimed and are still within the claim before date.
    + Body

            {
              "info": {
                "code": "INFO_FUNDS",
                "name": "Fund information retrieved",
                "message": "Your current fund information was retrieved."
              },
              "fundsbycurrency": {
                "USD": {
                  "available_in_cents": 196525,
                  "pending_in_cents": 0,
                  "reserved_in_cents": 41500
                },
                "CAD": {
                  "available_in_cents": 6600,
                  "pending_in_cents": 0,
                  "reserved_in_cents": 1000
                },
                "PRO": {
                  "available_in_cents": 0,
                  "pending_in_cents": 0,
                  "reserved_in_cents": 0
                }
              }
            }

### add funds through credit card [POST /funds]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

    + Attributes
        + currencyisocode: `Example: USD` (string, required) - Which currency to add funds in. Options: CAD, USD
        + fund_amount_in_cents: `25000` (number, required) - Amount of money to fund in cents. Subject to minimums that can be found in the web application under "Purchase Credits -> Auto-charge".
        + id: `Example: abc123` (string, required) - An identifier for the funding event assigned by the client (you).  Must be unique across all your funding events.  If an unexpected error occurs, you can safely send the same POST again with the same `id`.

    + Body

            {
                "currencyisocode": "USD",
                "fund_amount_in_cents": 25000,
                "id": "clientProvidedId_abc123"
            }

+ Response 200
    + Attributes
        + fundsbycurrency - USD, CAD, PRO (demo credits)
        + `available_in_cents` (number) - Value, in cents of available funds in your account. This is your purchasing power for new reward orders.
        + `pending_in_cents` (number) - Value, in cents, of funds for your account that have been sent by you but yet fully processed by Giftbit. These will move to available balance once processed.
        + `reserved_in_cents` (number) - Value, in cents, of funds that are held to cover the cost of outstanding reward offers that have not yet been claimed and are still within the claim before date.
    + Body

            {
              "info": {
                "code": "INFO_FUNDS_ADDED",
                "name": "Funds updated",
                "message": "Your funds have been updated."
              },
              "fundsbycurrency": {
                "USD": {
                  "available_in_cents": 196525,
                  "pending_in_cents": 0,
                  "reserved_in_cents": 41500
                },
                "CAD": {
                  "available_in_cents": 6600,
                  "pending_in_cents": 0,
                  "reserved_in_cents": 1000
                },
                "PRO": {
                  "available_in_cents": 0,
                  "pending_in_cents": 0,
                  "reserved_in_cents": 0
                }
              }
            }

+ Response 402
    + Attributes
        + status (number) - the http status code
        + error
            + code (string) - An enum-style error code desribing the reason for failure.
            + name (string) - human readable error name
            + message (string) - request context specific error message

    + Body

            {
                "error": {
                    "code": "ERROR_FUNDS_CARD_ERROR",
                    "name": "Credit card transaction failed",
                    "message": "Transaction failed. We were unable to charge your card. Go to web app to update your credit card."
                },
                "status": 402
            }

+ Response 400
    + Attributes
        + status (number) - the http status code
        + error
            + code (string) - An enum-style error code desribing the reason for failure.
            + name (string) - human readable error name
            + message (string) - request context specific error message

    + Body

            {
                "error": {
                    "code": "ERROR_FUNDS_INVALID_FUND_AMOUNT",
                    "name": "Invalid fund amount.",
                    "message": "10000 is an invalid fund amount. Minimum in cents: 25000, Maximum in cents: 1000000"
                },
                "status": 400
            }

## Rewards [/gifts]
This set of endpoints serves multiple purposes - it allows for the resending or cancellation of individual rewards, as well as the retrieval of their details. 

However, it's important to note that once a reward has been claimed by the recipient, it cannot be cancelled. Additionally, rewards that have been delivered in-app via the `/embedded` endpoint are not eligible for resending or cancellation.

A reward is created automatically as a result of a successful `POST` to `/campaign`, `/direct_links`, or `/embedded`. An API call can create multiple rewards with a single order if the API call specifies multiple contacts or a `link_count` greater than 1.

All date/time fields are in Pacific Standard Time.

### list rewards [GET /gifts{?uuid}{?campaign_uuid}{?campaign_id}{?price_in_cents_greater_than}{?price_in_cents_less_than}{?recipient_name}{?recipient_email}{?delivery_status}{?status}{?created_date_greater_than}{?created_date_less_than}{?delivery_date_greater_than}{?delivery_date_less_than}{?redelivery_count_greater_than}{?redelivery_count_less_than}{?redeemed_date_greater_than}{?redeemed_date_less_than}{?limit}{?offset}{?sort}{?order}]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Parameters
    + uuid (string, optional) - Return the reward with matching uuid.
    + campaign_uuid (string, optional) -​Filter rewards by the order with the matching uuid.
    + `campaign_id` (string, optional) -​Filter rewards by the order with the matching order id.
    + `price_in_cents_greater_than` (number, optional) -​Filter reward by their price in cents. Rewards from a reward of choice order may not have this value set. `price_in_cents_greater_than` can be used to filter rewards with prices in cents greater than the supplied value.
    + `price_in_cents_less_than` (number, optional) -​Filter reward by their price in cents. Rewards from a reward of choice order may not have this value set. `price_in_cents_less_than` can be used to filter rewards with prices in cents less than the supplied value.
    + `recipient_name` (string, optional) - Filter rewards by the name, or part of the name of the recipient. The search string must be at least 3 characters long.
    + `recipient_email` (string, optional) -​Filter rewards by the email address, or part of the email of the recipient. The search string must be at least 3 characters long.
    + `delivery_status` (string, optional) - Filter rewards by their delivery status. Delivery status can be one of `UNSENT`, `DELIVERED`, `UNDELIVERABLE`, `TEMPORARILY_UNDELIVERABLE`, `UNSUBSCRIBED`, `COMPLAINT`.
    + status (string, optional) - Filter rewards by their status. Options: `SENT_AND_REDEEMABLE`, `REDEEMED`, `TO_CHARITY`, `GIVER_CANCELLED`, or `EXPIRED`.
    + `created_date_greater_than` (string, optional) - Filter rewards by their created date. Format `yyyy-MM-dd HH:mm:ss`.
    + `created_date_less_than` (string, optional) - Filter rewards by their created date. Format `yyyy-MM-dd HH:mm:ss`.
    + `delivery_date_greater_than` (string, optional) - Filter rewards by their delivery date. Format `yyyy-MM-dd HH:mm:ss`.
    + `delivery_date_less_than` (string, optional) - Filter rewards by their delivery date. Format `yyyy-MM-dd HH:mm:ss`.
    + `redelivery_count_greater_than` (number, optional) - Filter rewards by their redelivery count.
    + `redelivery_count_less_than` (number, optional) - Filter rewards by their redelivery count.
    + `redeemed_date_greater_than` (number, optional) - Filter rewards by their  redeemed date. Format `yyyy-MM-dd HH:mm:ss`.
    + `redeemed_date_less_than` (number, optional) - Filter rewards by their  redeemed date. Format `yyyy-MM-dd HH:mm:ss`.
    + limit (number, optional) - The maximum number of rewards to return at once. Default 20.
    + offset (number, optional) - The offset of the first reward in the total results. Default 0.
    + sort (string, optional) - The property you'd like to sort by. Options: `campaign_id`, `price_in_cents`, `recipient_name`, `recipient_email`, `delivery_status`, or status.
    + order (string, optional) - The order to sort by. Options: asc or desc. Default desc.

+ Response 200
    + Attributes
        + gifts
            + uuid (string) - A unique identifier for the reward generated by Giftbit.
            + `campaign_uuid` (string) - A unique identifier for order genereated by Giftbit.
            + `delivery_status` (string) - The delivery status of the reward.
                    UNSENT - The reward has been created but is not yet sent.
                    DELIVERED - The reward has been sent, and no bounce or other problem notifications have been received. This is the successful delivery status.
                    LINKCREATED - Deprecated.
                    UNDELIVERABLE - There has been a fatal issue with delivering the reward. This is often
                        caused by attempting to send a reward to an email address that does not exist. We
                        suggest double-checking the recipient address and changing or removing it for future
                        orders.
                    TEMPORARILY_UNDELIVERABLE - There has been a temporary email deliverability
                        issue to this recipient. This can be caused by issues like a full mailbox for their email
                        address. While they may eventually get their reward, It is not guaranteed so we suggest
                        following up with this recipient and resending their reward if necessary via the web
                        interface or the `/gifts` API endpoint.
                    UNSUBSCRIBED - Your recipient unsubscribed from the unsubscribe link in this or a
                        previous reward offer email. You should remove them from all future orders as Giftbit
                        will return an error if you attempt to send to them again.
                    COMPLAINT - Your recipient marked the reward message as spam. You should remove
                        them from all future orders as Giftbit will return an error if you attempt to send to
                        them again.
            + status (string) - The status of the reward offer.

                    SENT_AND_REDEEMABLE - The reward offer is created and is still redeemable.
                    REDEEMED - The reward offer has been claimed.
                    TO_CHARITY - Deprecated.
                    GIVER_CANCELLED - The reward offer was canceled by the sender.
                    EXPIRED - The reward offer is expired because its claim before passed before it was redeemed.

            + `management_link_dashboard` (string) - A link to viewing the reward offer in your Giftbit account.
            + `redelivery_count` (number) - The number of times the reward was resent to the recipient.
            + `campaign_id` (string) - The id of order provided by the client.
            + `price_in_cents` (number) - The value of the reward offer in cents.
            + `marketplacegift_id` (string) - DEPRECATED.  Refer to brand_code. The id of the marketplace reward associated with the offer.
            + `brand_code` (string) The brand of the reward offer.  Will not be set if multiple brands were included in the order and the recipient has not chosen their brand as part of the claim process.
        + `number_of_results` (number) - The number of rewards returned from the request.
        + limit (number) - The maximum number of rewards to be returned from the request.
        + offset (number) - The offset into the rewards returned from the request.
        + `total_count` (number) - The total number of rewards that matched request. These can be paged through using offset and limit.
        + info
            + code (string) - Status code of request. [INFO_GIFTS]
    + Body

            {
               "gifts":[
                  {
                     "uuid":"d30be501ed2546e580c5c9eaf56633d9",
                     "campaign_uuid":"8f5835dfb637413793c5d55f8ea95e23",
                     "delivery_status":"DELIVERED",
                     "status":"SENT_AND_REDEEMABLE",
                     "management_dashboard_link":"http://testbedapp.giftbit.com/campaign/campaignInfo?uuid=8f5835dfb637413793c5d55f8ea95e23&gift_uuid=d30be501ed2546e580c5c9eaf56633d9",
                     "redelivery_count":0,
                     "campaign_id":"may11",
                     "price_in_cents":500,
                     "brand_code":"itunesus",
                     "marketplacegift_id":"1",
                     "created_date":"2016-05-11 12:18:25",
                     "delivery_date":"2016-05-11 12:18:32",
                  }
               ],
               "number_of_results":1,
               "limit":1,
               "offset":0,
               "total_count":8355,
               "info":{
                  "code":"INFO_GIFTS",
                  "name":"Gift information retrieved",
                  "message":"Returned gifts matching your search parameters."
               },
               "status":200
            }


### retrieve reward [GET /gifts/{uuid}]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Parameters
    + uuid (required, string) - The uuid of the reward. Not to be mistaken for the uuid or id of the order.

+ Response 200

    + Body

            {
               "gift":{
                  "uuid":"d30be501ed2546e580c5c9eaf56633d9",
                  "campaign_uuid":"8f5835dfb637413793c5d55f8ea95e23",
                  "delivery_status":"DELIVERED",
                  "status":"SENT_AND_REDEEMABLE",
                  "management_dashboard_link":"http://testbedapp.giftbit.com/campaign/campaignInfo?uuid=8f5835dfb637413793c5d55f8ea95e23&gift_uuid=d30be501ed2546e580c5c9eaf56633d9",
                  "redelivery_count":0,
                  "campaign_id":"may11",
                  "price_in_cents":500,
                  "brand_code":"itunesus",
                  "marketplacegift_id":"1",
                  "created_date":"2016-05-11 12:18:25",
                  "delivery_date":"2016-05-11 12:18:32",
               },
               "info":{
                  "code":"INFO_GIFTS",
                  "name":"Gift information retrieved",
                  "message":"Returned gifts matching your search parameters."
               },
               "status":200
            }




### resend reward [PUT /gifts/{uuid}]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

    + Attributes
        + resend: true (boolean, required)

+ Parameters
    + uuid (required, string) - The uuid of the reward. Not to be mistaken for the uuid or id of the order.


+ Response 200

    + Body

            {
               "gift":{
                  "uuid":"7e0ef82bc386493498f145578268f1b2",
                  "campaign_uuid":"f11712f1102248ea94c47bdd3ed95690",
                  "delivery_status":"DELIVERED",
                  "status":"SENT_AND_REDEEMABLE",
                  "management_dashboard_link":"http://testbedapp.giftbit.com/campaign/campaignInfo?uuid=f11712f1102248ea94c47bdd3ed95690&gift_uuid=7e0ef82bc386493498f145578268f1b2",
                  "redelivery_count":1,
                  "recipient_email":"tim+1@giftbit.com",
                  "recipient_name":"tim1",
                  "price_in_cents":500,
                  "brand_code": "itunesus",
                  "marketplacegift_id":"1",
                  "created_date":"2016-05-11 14:18:44",
                  "delivery_date":"2016-05-11 14:18:47"
               },
               "info":{
                  "code":"INFO_GIFTS_RESENT",
                  "name":"Gift resent",
                  "message":"The gift has been resent."
               },
               "status":200
            }

### cancel reward [DELETE /gifts/{uuid}]
+ Request (application/json)
    + Headers

            Authorization: Bearer YOUR_API_KEY
            Accept-Encoding: identity

+ Parameters
    + uuid (required, string) - The uuid of the reward. Not to be mistaken for the uuid or id of the order.

+ Response 200

    + Body

            {
               "gift":{
                  "uuid":"d30be501ed2546e580c5c9eaf56633d9",
                  "campaign_uuid":"8f5835dfb637413793c5d55f8ea95e23",
                  "delivery_status":"LINKCREATED",
                  "status":"GIVER_CANCELLED",
                  "management_dashboard_link":"http://testbedapp.giftbit.com/campaign/campaignInfo?uuid=8f5835dfb637413793c5d55f8ea95e23&gift_uuid=d30be501ed2546e580c5c9eaf56633d9",
                  "redelivery_count":0,
                  "campaign_id":"may11",
                  "price_in_cents":500,
                  "brand_code":"itunesus",
                  "marketplacegift_id":"1",
                  "created_date":"2016-05-11 12:18:25",
                  "delivery_date":"2016-05-11 12:18:32"
               },
               "info":{
                  "code":"INFO_GIFTS_CANCELED",
                  "name":"Gift canceled",
                  "message":"The gift has been canceled."
               },
               "status":200
            }