NAV
JSON

Introduction

Base URL:

GET https://api.giftup.app/ping HTTP/2.0

The Gift Up! API is organized around REST. Our API accepts JSON-encoded requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

To authorize, use this code:

GET https://api.giftup.app/ping HTTP/2.0
Authorization: Bearer {{apikey}}

Make sure to replace {{apikey}} with your API key.

Gift Up! uses API keys to allow access to the API. You can get a new API key in our dashboard. Gift Up! expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer {{apikey}}

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Content types

Specify payload and response content-types in each request:

GET https://api.giftup.app/ping HTTP/2.0
Content-Type: application/json
Accepts: application/json

Gift Up! is configured to accept JSON-encoded requests and returns JSON-encoded responses. You need to include the appropriate headers in your requests accordingly.

Accepts: application/json
Content-Type: application/json
Content-Type: application/json-patch+json (for PATCH requests)

Response codes

HTTP status code summary:

Response Code Meaning
200 - OK The request worked as expected
201 - Created The request worked as expected and the entity was created
400 - Bad Request The request was unacceptable, often due to missing a required parameter
401 - Unauthorized No valid API key provided
404 - Not Found The requested resource doesn't exist
409 - Conflict The request conflicts with another request
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential back-off of your requests
500, 502, 503, 504 - Server Errors Something went wrong on Gift Up's end. (These are rare.)

Gift Up! uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, the request is unprocessable, etc.). Codes in the 5xx range indicate an error with Gift Up's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a required parameter was omitted) include an error that briefly explains the error generated.

When inspecting the response code from Gift Up! we recommend looking for a 2xx code range (i.e. code >= 200 && code < 300) to indicate success, rather than the specific code i.e. 200 or 201.

Specifying dates

Specify requests using our format requirements:

GET https://api.giftup.app/gift-cards?createdOnOrAfter=2020-06-10T15:02:17.786Z HTTP/2.0
Accepts: application/json

Gift Up! primarily operates with UTC dates and these are exposed in all operations via our API.

Some GET endpoints that return a list of results can accept a date filter property (e.g. List all gift cards accepts a createdOnOrAfter date time property), these property values will be treated as UTC (unless specified otherwise via K below) and must confirm to one of the following set formats:

Where:

Testing the API

To enable test mode, add the following HTTP header:

GET https://api.giftup.app/ping HTTP/2.0
x-giftup-testmode: true

Gift Up! has an built-in test mode environment in every account, which does not affect your live data. Where an endpoint supports test mode, you can pass in a HTTP header to ensure your API call operates against the test data environment.

x-giftup-testmode: true

If you elect to develop against our API in live mode (i.e. you do not include this header), you will be charged our fee if you create any new orders. All other API calls are free of charge in live and test mode.

Gift cards

A gift card represents the entity sent to a recipient when a someone places an order in the Gift Up! checkout, or is issued via the dashboard/API. A gift card encapsulates a code and a balance (called remainingValue in our API) among other properties.

The parent entity to a gift card is an order. An order can contain many gift cards.

Gift card states

Allowable operations:

State Allowable operations
Active Redeem, Top up, Void, Update
Expired Redeem, Top up, Void, Update
Redeemed Top up, Update
Voided Reactivate, Update

A gift card has various properties on it that describe the current state of the gift card. The Gift Up! dashboard reflects these states in the following language:

The API does not emit these states, instead is emits the underlying properties canBeRedeemed, hasExpired, isVoided and remainingValue. It is important to consider and read these properties to achieve the desired effect when deciding whether to accept the gift card in your external system.

The gift card object

Example gift card:

{
  "canBeRedeemed": true,
  "hasExpired": false,
  "isVoided": false,
  "code": "ABC123",
  "title": "All you can eat steak!",
  "subTitle": "For use at any Juicy Joes restaurant",
  "message": "Happy Birthday! Dad",
  "fulfilledOn": "2020-06-10T15:02:18.786Z",
  "recipientName": "Dad",
  "recipientEmail": "bob.bloggs@example.com",
  "backingType": "Currency",
  "remainingValue": 100,
  "remainingUnits": null,
  "initialValue": 100,
  "initialUnits": null,
  "equivalentValuePerUnit": null,
  "terms": "Can only be used on Saturdays",
  "sku": "STEAK-8",
  "expiresOn": "2020-06-10T15:02:17.786Z",
  "voidedOn": "2020-06-10T15:02:17.786Z",
  "fulfilledBy": "Email",
  "order": {
    "createdOn": "2020-06-10T15:02:17.786Z",
    "selectedRecipient": "SomeoneElse",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "purchaserEmail": "joe.bloggs@example.com",
    "purchaserName": "Joe Bloggs",
    "tip": 0,
    "serviceFee": 0,
    "revenue": 50,
    "customFields": [
      {
        "label": "Telephone",
        "value": "202-555-0191"
      }
    ],
    "salesTaxes": [
      {
        "label": "Sales Tax",
        "amount": 10
      }
    ],
    "downloadLinks": {
      "single": {
        "imageUrl": "https://download.yourgift.cards/download/order/png/…",
        "pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
      },
      "zip": {
        "imageUrl": "https://download.yourgift.cards/download-zip/order/png/…",
        "pdfUrl": "https://download.yourgift.cards/download-zip/order/pdf/…",
      }
    }
  },
  "postalFulfilment": {
    "address": {
      "countryCode": "USA",
      "address1": "4478  Oliverio Drive",
      "address2": "",
      "city": "Wichita",
      "state": "Kansas",
      "postalCode": "67202",
      "name": "Bob Bloggs"
    },
    "shippingOptionName": "FedEx Overnight"
  },
  "emailFulfilment": {
    "emailAddress": "bob.bloggs@example.com"
  },
  "downloadLinks": {
    "imageUrl": "https://download.yourgift.cards/download/order/png/…",
    "pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
  },
  "ledger": [    
    {
      "eventOccuredOn": "2020-06-10T15:02:17.786Z",
      "value": 100,
      "whoEmail": "",
      "whoName": "",
      "eventType": "GiftCardCreated"
    },
    {
      "eventOccuredOn": "2020-06-10T15:02:17.786Z",
      "value": null,
      "whoEmail": "",
      "whoName": "",
      "eventType": "OrderPlaced"
    }
  ]
}

Properties


canBeRedeemed boolean
Will be set true if this gift card can be redeemed. Will be set to false if the gift card has already been fully redeemed or it has been voided.

An expired gift card can still be redeemed. Check hasExpired or expiredOn if this is important to you.


hasExpired boolean
Whether or not this gift card has expired


isVoided boolean
Whether or not this gift card has been voided


code string
The gift card code


title string
The main title of the gift card


subTitle string
The sub-title of the gift card (appears underneath the title in the gift card)


message string
The message included with the gift card


fulfilledOn datetime
The datetime that this gift card was fulfilled, either by email, or post


recipientName string
The recipient name on the gift card


recipientEmail string
The email address for the recipient of this gift card


backingType string
The balance backing type of this gift card. Will be one of:


remainingValue decimal
The currency balance remaining on this gift card

Only for Currency backed gift cards


remainingUnits integer
The units balance remaining on this gift card

Only for Units backed gift cards


initialValue decimal
The initial currency balance this gift card was issued with

Only for Currency backed gift cards


initialUnits integer
The initial units balance this gift card was issued with

Only for Units backed gift cards


equivalentValuePerUnit decimal
The equivalent value per unit unit this gift card was issued with (for reporting purposes only)

Only for Units backed gift cards


terms string
The terms captured when this gift card was created


sku string
The private SKU that is associated with the item this gift card is for


fulfilledBy string
Describes which method fulfilled this gift card. One of Post or Email


expiresOn datetime
The datetime that this gift card expires

Can be null


voidedOn datetime
The datetime that this gift card was voided

Can be null


order object
The order this gift card belongs to

See order definition


postalFulfilment object
Details of the postal fulfilment.

See postal fulfilment definition


emailFulfilment object
Details of the email fulfilment

See email fulfilment definition


downloadLinks object
An collection of links to download the gift card in its state at the point of download

See download links definition


ledger list
A list of events that have occurred against this gift card

See ledger entry definition


cancelledOn datetime deprecated
The datetime that this gift card was voided

This has been replaced with voidedOn


description string deprecated
The main title of the gift card

This has been replaced with title


createdOn datetime deprecated
The datetime that this gift card was created

This has been replaced with order.createdOn


orderId guid deprecated
The id of the order this gift card belongs to

This has been replaced with order.id


purchaserName string deprecated
The name of the gift card purchaser

This has been replaced with order.purchaserName


imageUrl string deprecated

This has been replaced with downloadLinks.imageUrl

Gift card postal fulfilment


address object
The address to send this gift card to

See postal address definition


shippingOptionName string
The name of the shipping option selected.

Gift card postal address


name string
The name of the recipient


address1 string
The first line of the address


address2 string
The second line of the address


city string
The city


state string
The state


postalCode string
The postal/zip code


countryCode string
The country code

3-character ISO country code

Gift card email fulfilment


emailAddress string
The email address this gift card was/will be fulfilled to

Gift card ledger entry


eventOccuredOn datetime
The datetime this event occurred


value decimal
The currency value change introduced by this event

This will be a negative value for a redeemed event This is an equivalent currency value for Units backed gift cards


units integer
The units change introduced by this event

This will be a negative value for a redeemed event Only for Units backed gift cards


whoEmail string
The email address of the user who triggered this event


whoName string
The name of the user who triggered this event


eventType string
The type of event. One of OrderPlaced, GiftCardCreated, CreditAdded, Redeemed, Expired,Unexpired, Voided, Reactivated


imageUrl string
A link that can be presented to users which will generate a PNG file of the gift card in its state at the time of download


pdfUrl string
A link that can be presented to users which will generate a printable A4 PDF file of the gift card in its state at the time of download

Get a gift card by code

GET https://api.giftup.app/gift-cards/{code} HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns JSON structured like this:

{
  "expiresOn": "2020-06-10T15:02:17.786Z",
  "canBeRedeemed": true,
  "voidedOn": "2020-06-10T15:02:17.786Z",
  "code": "ABC123",
  "title": "All you can eat steak!",
  "subTitle": "For use at any Juicy Joes restaurant",
  "message": "Happy Birthday! Dad",
  "createdOn": "2020-06-10T15:02:17.786Z",
  "fulfilledOn": "2020-06-10T15:02:18.786Z",
  "purchaserName": "Joe",
  "recipientName": "Dad",
  "recipientEmail": "bob.bloggs@example.com",
  "backingType": "Currency",
  "remainingValue": 100,
  "remainingUnits": null,
  "initialValue": 100,
  "initialUnits": null,
  "equivalentValuePerUnit": null,
  "terms": "Can only be used on Saturdays",
  "sku": "STEAK-8",
  "order": {
    "createdOn": "2020-06-10T15:02:17.786Z",
    "selectedRecipient": "SomeoneElse",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "purchaserEmail": "joe.bloggs@example.com",
    "purchaserName": "Joe Bloggs",
    "tip": 0,
    "serviceFee": 0,
    "revenue": 50,
    "customFields": [
      {
        "label": "Telephone",
        "value": "202-555-0191"
      }
    ],
    "salesTaxes": [
      {
        "label": "Sales Tax",
        "amount": 10
      }
    ],
    "downloadLinks": {
      "single": {
        "imageUrl": "https://download.yourgift.cards/download/order/png/…",
        "pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
      },
      "zip": {
        "imageUrl": "https://download.yourgift.cards/download-zip/order/png/…",
        "pdfUrl": "https://download.yourgift.cards/download-zip/order/pdf/…",
      }
    }
  },
  "postalFulfilment": {
    "address": {
      "countryCode": "USA",
      "address1": "4478  Oliverio Drive",
      "address2": "",
      "city": "Wichita",
      "state": "Kansas",
      "postalCode": "67202",
      "name": "Bob Bloggs"
    },
    "shippingOptionName": "FedEx Overnight"
  },
  "emailFulfilment": {
    "emailAddress": "bob.bloggs@example.com"
  },
  "fulfilledBy": "Email",
  "downloadLinks": {
    "imageUrl": "https://download.yourgift.cards/download/order/png/…",
    "pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
  },
  "ledger": [    
    {
      "eventOccuredOn": "2020-06-10T15:02:17.786Z",
      "value": 100,
      "whoEmail": "",
      "whoName": "",
      "eventType": "GiftCardCreated"
    },
    {
      "eventOccuredOn": "2020-06-10T15:02:17.786Z",
      "value": null,
      "whoEmail": "",
      "whoName": "",
      "eventType": "OrderPlaced"
    }
  ]
}

Retrieves a single gift card

HTTP Request


GET https://api.giftup.app/gift-cards/{code}

URL Parameters


code string
The gift card code

Response body


Returns a gift card object

Update a gift card

Note, PATCH operations must have the Content-Type header set to application/json-patch+json

PATCH https://api.giftup.app/gift-cards/{code} HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json-patch+json
Accept: application/json

Update the properties for a gift card. This endpoint supports the standard JSON patch definition. Accepts an list of patch operations.

HTTP Request


PATCH https://api.giftup.app/gift-cards/{code}

URL Parameters


code string
The gift card code

Update gift card paths


[
  {
    "op": "replace",
    "path": "/title",
    "value": "All you can eat steak"
  },
  {
    "op": "replace",
    "path": "/expireson",
    "value": "2025-06-11T15:02:17.786Z"
  },
]

/title string
The main title of a gift card


/expireson datetime
The gift card expiry date


/receipientemail string
The email address of the recipient


/recipientname string
The name of the recipient


/sku string
The SKU for this gift card


/terms string
The gift card terms

List gift cards

GET https://api.giftup.app/gift-cards?createdOnOrAfter=2020-01-01&limit=2&offset=0 HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns JSON structured like this:

{
  "giftCards": [
    {
      "expiresOn": "2020-06-10T15:02:17.786Z",
      "canBeRedeemed": true,
      "voidedOn": "2020-06-10T15:02:17.786Z",
      "code": "ABC123",
      // …all other gift card properties…
    },
    {
      "expiresOn": null,
      "canBeRedeemed": false,
      "voidedOn": null,
      "code": "DEF456",
      // …all other gift card properties…
    }
  ],
  "total": 57,
  "hasMore": false
}

Get a list of gift cards. You can optionally provide filters.

HTTP Request


GET https://api.giftup.app/gift-cards

URL Parameters


createdOnOrAfter datetime
A UTC datetime to include only gift cards created on or after this date time.


limit integer
The number of gift cards to return

10 and must be at least 1 and no more than 100


offset integer
The number of gift cards to skip

0

HTTP Response


giftCards list
A list of gift card objects


total integer
The total number of gift cards in Gift Up! matching the createdOnOrAfter constraint


hasMore boolean
Set to true if there are more gift cards after these

Reactivate a gift card

POST https://api.giftup.app/gift-cards/{code}/reactivate HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

Will reactivate a gift card so it can be redeemed again (subject to existing, positive, remaining balance)

HTTP Request


POST https://api.giftup.app/gift-cards/{code}/reactivate

URL Parameters


code string
The gift card code to reactivate

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

{
  "isRedeemed": true
}

The gift card could not be reactivated. Please see response for details.


isRedeemed boolean
A redeemed gift card cannot be reactivated

Void a gift card

POST https://api.giftup.app/gift-cards/{code}/void HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

Will void a gift card so it can no longer be redeemed

HTTP Request


POST https://api.giftup.app/gift-cards/{code}/void

URL Parameters


code string
The gift card code to void

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

{
  "isRedeemed": true
}

The gift card could not be voided. Please see response for details.


isRedeemed boolean
A redeemed gift card cannot be voided

Top up a gift card

POST https://api.giftup.app/gift-cards/{code}/add-credit HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json

Will add balance to a gift card

HTTP Request


GET https://api.giftup.app/gift-cards/{code}/add-credit

URL Parameters


code string
The gift card code to top up

Request body


{
  "amount": 25,
  "units": null,
  "reason": "Overcooked steak"
}

amount decimal
The currency balance to add to the gift card.

Must be a number greater than 0 Required for Currency backed gift cards


units integer
The units to add to the gift card.

Must be a number greater than 0 Required for Units backed gift cards


reason string
The reason for this top-up. Will appear in the gift card history log.

Response body


A 200 response returns JSON structured like this:

{
  "remainingCredit": 75,
  "remainingUnits": null
}

remainingCredit decimal
The currency balance now available on the gift card.

Only for Currency backed gift cards


remainingUnits integer
The unit balance now available on the gift card.

Only for Units backed gift cards

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

{
  "isVoided": true
}

The gift card could not be topped up. Please see response for details.


isVoided boolean
You cannot top up a voided gift card

Redeem a gift card

POST https://api.giftup.app/gift-cards/{code}/redeem HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json

Will deduct the specified amount of balance from a gift card

HTTP Request


POST https://api.giftup.app/gift-cards/{code}/redeem

URL Parameters


code string
The gift card code to redeem

Request body


{
  "amount": 50,
  "units": null,
  "reason": "Used with Order 7597"
}

amount decimal
The currency amount to redeem against this gift card

Must be no more than the remaining currency balance on the gift card Required for Currency backed gift cards


units integer
The units to redeem off this gift card

Must be no more than the remaining units remaining on the gift card Required for Units backed gift cards


reason string
The reason for this redemption. Will appear in the gift card history log.

Response body


A 200 response returns JSON structured like this:

{
  "redeemedAmount": 50,
  "remainingCredit": 25,
  "redeemedUnits": null,
  "remainingUnits": null
}

redeemedAmount decimal
The currency amount redeemed off the gift card.

Only for Currency backed gift cards


remainingCredit decimal
The amount now available on the gift card.

Only for Currency backed gift cards


redeemedUnits integer
The units redeemed off the gift card.

Only for Units backed gift cards


remainingUnits integer
The number of units now remaining on the gift card.

Only for Units backed gift cards

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

{
  "wasAlreadyRedeemed": true,
  "insufficientRemainingCredit": true,
  "insufficientRemainingUnits": false,
  "remainingCredit": 0,
  "remainingUnits": null,
  "wasVoided": false
}

The gift card could not be redeemed. Please see response for details.


wasAlreadyRedeemed boolean
The gift card has already been fully redeemed


insufficientRemainingCredit boolean
The gift card does not have enough balance to redeem the specified amount

Only for Currency backed gift cards


remainingCredit decimal
The remaining balance on the gift card

Only for Currency backed gift cards


insufficientRemainingUnits integer
The gift card does not have enough units to redeem the specified units

Only for Units backed gift cards


remainingUnits integer
The number of units remaining on the gift card.

Only for Units backed gift cards


wasVoided boolean
The gift card cannot be redeemed because it has been voided

Redeem a gift card in full

POST https://api.giftup.app/gift-cards/{code}/redeem-in-full HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

Will deduct all remaining balance from a gift card

HTTP Request


POST https://api.giftup.app/gift-cards/{code}/redeem-in-full

URL Parameters


code string
The gift card code to redeem

Request body


{
  "reason": "Used with Order 7597"
}

reason string
The reason for this redemption. Will appear in the gift card history log.

Response body


A 200 response returns JSON structured like this:

{
  "redeemedAmount": 75,
  "remainingCredit": 0,
  "redeemedUnits": null,
  "remainingUnits": null
}

redeemedAmount decimal
The currency amount redeemed off the gift card.

Only for Currency backed gift cards


remainingCredit decimal
The currency balance now available on the gift card.

Only for Currency backed gift cards


redeemedUnits integer
The units redeemed off the gift card.

Only for Units backed gift cards


remainingUnits integer
The number of units now remaining on the gift card.

Only for Units backed gift cards

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

{
  "wasAlreadyRedeemed": true,
  "insufficientRemainingCredit": true,
  "remainingCredit": 0,
  "insufficientRemainingUnits": false,
  "remainingUnits": null,
  "wasVoided": false
}

The gift card could not be redeemed. Please see response for details.


wasAlreadyRedeemed boolean
The gift card has already been fully redeemed


insufficientRemainingCredit boolean
The gift card does not have enough currency balance to redeem the specified amount

Only for Currency backed gift cards


remainingCredit decimal
The remaining balance on the gift card

Only for Currency backed gift cards


insufficientRemainingUnits boolean
The gift card does not have enough remaining units to redeem the specified units

Only for Units backed gift cards


remainingUnits decimal
The remaining units on the gift card

Only for Units backed gift cards


wasVoided boolean
The gift card cannot be redeemed because it has been voided

Items

An item for sale is an item that appears in your Gift Up! checkout.

The item object

Example item:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "All you can eat steak",
  "description": "Can be used in any of our restaurants",
  "backingType": "Currency",
  "price": 100,
  "value": 120,
  "units": null,
  "equivalentValuePerUnit": null,
  "group": "Deals",
  "detailsURL": "https://www.juicyjoes.com/our-buffet",
  "stockLevel": 100,
  "codes": [
       "JJ-GC-Q3JKK",
       "JJ-GC-8TA9A",
       "JJ-GC-LAR9G",
       "JJ-GC-CJHXD",
       "JJ-GC-DUPQE",
       "JJ-GC-4323P",
       "JJ-GC-2HZJL",
       "JJ-GC-4RDD9",
       "JJ-GC-LUH4A",
       "JJ-GC-4TY6E"
  ],
  "perOrderLimit": 1,
  "additionalTerms": "Can only be used on Monday-Thursdays",
  "sku": "all-you-can-eat"
}

Properties


id guid
Unique identifier for the item


name string
The name of the item


description string
The description of the item


backingType string
The balance backing type of this item. Will be one of:


price decimal
The price to charge the purchaser


value decimal
The currency balance to issue on the gift card when this item is purchased

Required for Currency backed gift cards


units integer
The unit balance to issue on the gift card when this item is purchased

Required for Units backed gift cards


equivalentValuePerUnit decimal
The equivalent value per unit unit to store on the gift card when this item is purchased (for reporting purposes only)

Required for Units backed gift cards


group string
The item group to allocate this item to. Leave blank to not add this item to a group.


detailsURL string
A URL to show the purchaser so they can get more information on this item

Must be a fully qualified, absolute URL, if specified


stockLevel integer
An optional integer defining the stock level available to purchase


perOrderLimit integer
An optional integer defining the limit available to purchaser in a single order


additionalTerms string
Any additional terms to apply to gift card sales containing this item. Is in addition to general terms applied.


sku string
A private SKU/item code in an external system. Will be added to gift cards sold containing this item.


codes list
An optional list of strings of pre-generated codes you would like us to issue when we sell this item

Create a new item

POST https://api.giftup.app/items  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json
{
  "name": "All you can eat steak",
  "description": "Can be used in any of our restaurants",
  "backingType": "Currency",
  "price": 100,
  "value": 120,
  "units": null,
  "equivalentValuePerUnit": null,
  "group": "Deals",
  "detailsURL": "https://www.juicyjoes.com/our-buffet",
  "stockLevel": 100,
  "codes": [
       "JJ-GC-Q3JKK",
       "JJ-GC-8TA9A",
       "JJ-GC-LAR9G",
       "JJ-GC-CJHXD",
       "JJ-GC-DUPQE",
       "JJ-GC-4323P",
       "JJ-GC-2HZJL",
       "JJ-GC-4RDD9",
       "JJ-GC-LUH4A",
       "JJ-GC-4TY6E"
  ],
  "perOrderLimit": 1,
  "additionalTerms": "Can only be used on Monday-Thursdays",
  "sku": "all-you-can-eat"
}

The above command returns a 201 response when the item has been created

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Create a new item for sale.

HTTP Request


POST https://api.giftup.app/items

Request body


See item object

Get an item by id

GET https://api.giftup.app/items/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "All you can eat steak",
  "description": "Can be used in any of our restaurants",
  "backingType": "Currency",
  "price": 100,
  "value": 120,
  "units": null,
  "equivalentValuePerUnit": null,
  "group": "Deals",
  "detailsURL": "https://www.juicyjoes.com/our-buffet",
  "stockLevel": 100,
  "codes": [
       "JJ-GC-Q3JKK",
       "JJ-GC-8TA9A",
       "JJ-GC-LAR9G",
       "JJ-GC-CJHXD",
       "JJ-GC-DUPQE",
       "JJ-GC-4323P",
       "JJ-GC-2HZJL",
       "JJ-GC-4RDD9",
       "JJ-GC-LUH4A",
       "JJ-GC-4TY6E"
  ],
  "perOrderLimit": 1,
  "additionalTerms": "Can only be used on Monday-Thursdays",
  "sku": "all-you-can-eat"
}

Returns the item object in the response body.

HTTP Request


GET https://api.giftup.app/items/{id}

URL Parameters


id guid
The id of the item to retrieve

Delete an item

DELETE https://api.giftup.app/items/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}

The above command returns a 200 response when the item has been deleted

Delete an item by id.

HTTP Request


DELETE https://api.giftup.app/items/{id}

URL Parameters


id guid
The id of the item to delete

List all items

GET https://api.giftup.app/items  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "All you can eat steak",
    "description": "Can be used in any of our restaurants",
    "backingType": "Currency",
    "price": 100,
    "value": 120,
    "units": null,
    "equivalentValuePerUnit": null,
    "group": "Deals",
    "detailsURL": "https://www.juicyjoes.com/our-buffet",
    "stockLevel": 100,
    "codes": [
       "JJ-GC-Q3JKK",
       "JJ-GC-8TA9A",
       "JJ-GC-LAR9G",
       "JJ-GC-CJHXD",
       "JJ-GC-DUPQE",
       "JJ-GC-4323P",
       "JJ-GC-2HZJL",
       "JJ-GC-4RDD9",
       "JJ-GC-LUH4A",
       "JJ-GC-4TY6E"
    ],
    "perOrderLimit": 1,
    "additionalTerms": "Can only be used on Monday-Thursdays",
    "sku": "all-you-can-eat-steak"
  },
  {
    "id": "c991b0c1-a3ce-40d6-9448-29cf4aea8e70",
    "name": "$50 gift card",
    "description": "",
    "backingType": "Currency",
    "price": 50,
    "value": 50,
    "units": null,
    "equivalentValuePerUnit": null,
    "group": "",
    "detailsURL": "",
    "stockLevel": null,
    "codes": [],
    "perOrderLimit": null,
    "additionalTerms": "",
    "sku": ""
  }
]

Get all items as a list of item objects.

HTTP Request


GET https://api.giftup.app/items

Integrations

Integrations are third-party connections to Gift Up!

Update Stripe connection

POST https://api.giftup.app/integrations/stripe/connection HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json
Accepts: application/json
{
  "enableIdeal": false,
  "enableBancontact": false,
  "enableGiropay": false,
  "enableEps": false,
  "enableMultibanco": false,
  "enablePrzelewy24": false,
  "enableWeChat": false,
  "enableAlipay": false,
  "livePublicKey": "pk_live_************",
  "liveSecretKey": "sk_live_************",
  "testPublicKey": "pk_test_************",
  "testSecretKey": "sk_test_************",
  "connectAccountId": "",
  "applicationFeePercentage": 0,
  "applicationFeeFixed": 0
}

The above command returns JSON structured like this:

{
  "testResult": {
      "hasWebhooks": true,
      "canReadAccount": true,
      "canReadSource": true,
      "canWritePaymentIntent": true,
      "canWriteCharge": true
    }
}

Updates/creates the credentials of your Stripe gateway connection. Must be used if you are a Stripe connect platform connecting your users to Gift Up!

HTTP Request


POST https://api.giftup.app/integrations/stripe/connection

Stripe connection object


livePublicKey string
Your Stripe live publishable API key

Must start with pk_live_


liveSecretKey string
Your Stripe live secret API key

Must start with sk_live_ or rk_live_


testPublicKey string
Your Stripe test publishable API key

We will use our test keys if nothing provided


testSecretKey string
Your Stripe test secret API key

We will use our test keys if nothing provided


connectAccountId string
The Stripe account id of who to pay when an order is placed for a gift card

Only required if your Stripe account is a Stripe connect platform account


applicationFeePercentage decimal
The application fee percentage to pass to you, the connect platform, when an order is placed for a gift card

Only required if your Stripe account is a Stripe connect platform account null


applicationFeeFixed decimal
The fixed application fee to pass to you, the connect platform, when an order is placed for a gift card

Only required if your Stripe account is a Stripe connect platform account null


enableIdeal boolean
Set to true to enable Ideal payments in your Gift Up! checkout

false


enableBancontact boolean
Set to true to enable Bancontact payments in your Gift Up! checkout

false


enableGiropay boolean
Set to true to enable Giropay payments in your Gift Up! checkout

false


enableEps boolean
Set to true to enable EPS payments in your Gift Up! checkout

false


enableMultibanco boolean
Set to true to enable Multibanco payments in your Gift Up! checkout

false


enablePrzelewy24 boolean
Set to true to enable P24 payments in your Gift Up! checkout

false


enableWeChat boolean
Set to true to enable WeChat payments in your Gift Up! checkout

false


enableAlipay boolean
Set to true to enable Alipay payments in your Gift Up! checkout

false

Get Stripe connection

GET https://api.giftup.app/integrations/stripe/connection HTTP/2.0
Authorization: Bearer {{apikey}}
Accepts: application/json

The above command returns JSON structured like this:

{
  "enableIdeal": false,
  "enableBancontact": false,
  "enableGiropay": false,
  "enableEps": false,
  "enableMultibanco": false,
  "enablePrzelewy24": false,
  "enableWeChat": false,
  "enableAlipay": false,
  "livePublicKey": "pk_live_************",
  "liveSecretKey": "sk_live_************",
  "testPublicKey": "pk_test_************",
  "testSecretKey": "sk_test_************",
  "connectAccountId": "",
  "applicationFeePercentage": 0,
  "applicationFeeFixed": 0
}

Gets the settings of your Stripe gateway connection.

HTTP Request


GET https://api.giftup.app/integrations/stripe/connection

Response body


See Stripe connection object

Orders

Orders encapsulate data relating to the transaction that created the gift cards. An order contains one or more gift cards.

The order object

Example order:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdOn": "2020-06-08T11:16:48.151Z",
  "purchaserEmail": "john@example.com",
  "purchaserName": "John Doe",
  "selectedRecipient": "Recipient",
  "tip": 0,
  "serviceFee": 0,
  "revenue": 100,
  "customFields": [
    {
      "label": "Telephone",
      "value": "01234 567780"
    }
  ],
  "salesTaxes": [
    {
      "label": "VAT",
      "amount": 12
    }
  ],
  "downloadLinks": {
    "single": {
      "imageUrl": "https://download.yourgift.cards/download/order/png/…",
      "pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
    },
    "zip": {
      "imageUrl": "https://download.yourgift.cards/download-zip/order/png/…",
      "pdfUrl": "https://download.yourgift.cards/download-zip/order/pdf/…",
    }
  }
}

Properties


id guid
Unique identifier for the order


createdOn datetime
When the order was created. In UTC.


purchaserEmail string
The email address of the purchaser


purchaserName string
The name of the purchaser


selectedRecipient string
This reflects the choice made by the customer on the checkout. Either SomeoneElse or Purchaser.


tip decimal
The tip taken for this order


serviceFee decimal
The serviceFee added to this order


revenue decimal
The revenue taken for this order


customFields list
A list of custom fields collecting during this order

See Order - Custom fields properties


salesTaxes list
A list of sales taxes collecting for this order

See Order - Sales tax properties


downloadLinks list
A list of links for downloading the gift card(s) in this order

See Order - Download links properties

Order custom fields


label string
The label to describe the custom field


value object
The value of the custom field. The type will depend on the custom field, it could be string, int or boolean

Order sales taxes


label string
The label to describe the sales tax (e.g VAT)


amount decimal
The amount collected for this sales tax


single.imageUrl string
A link that can be presented to users which will generate a PNG file of all gift cards and codes in the order, rolled up onto a single gift card image, in its state at the time of download


single.pdfUrl decimal
A link that can be presented to users which will generate a A4 printable PDF file of all gift cards and codes in the order, rolled up onto a single gift card image, in its state at the time of download


zip.imageUrl string
A link that can be presented to users which will generate a ZIP file containing all gift cards in the order, as individual PNG files, in its state at the time of download


zip.pdfUrl decimal
A link that can be presented to users which will generate a ZIP file containing all gift cards in the order, as individual A4 printable PDF files, in its state at the time of download

Get an order by id

GET https://api.giftup.app/orders/{id} HTTP/2.0
Authorization: Bearer {{apikey}}
Accepts: application/json

The above command returns JSON structured like this:

{
  "createdOn": "2020-06-08T11:16:48.151Z",
  "selectedRecipient": "SomeoneElse",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "purchaserEmail": "john@example.com",
  "purchaserName": "John Doe",
  "tip": 0,
  "serviceFee": 0,
  "revenue": 100,
  "customFields": [
    {
      "label": "Telephone",
      "value": "01234 567780"
    }
  ],
  "salesTaxes": [
    {
      "label": "My state sales tax",
      "amount": 12
    }
  ],
  "downloadLinks": {
    "single": {
      "imageUrl": "https://download.yourgift.cards/download/order/png/…",
      "pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
    },
    "zip": {
      "imageUrl": "https://download.yourgift.cards/download-zip/order/png/…",
      "pdfUrl": "https://download.yourgift.cards/download-zip/order/pdf/…",
    }
  }
}

Retrieves the details of an order that has previously been created.

HTTP Request


GET https://api.giftup.app/orders/{id}

URL Parameters


id guid
The id of the order to retrieve

Create an order

POST https://api.giftup.app/orders HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json
Accepts: application/json
{  
  "orderDate": "2020-06-08T11:31:31.758Z",
  "disableAllEmails": true,
  "purchaserEmail": "john@example.com",
  "purchaserName": "John Doe",
  "itemDetails": [
    {
      "quantity": 0,
      "name": "A gift card",
      "description": "For use at Juicy Joes",
      "code": "ABC123",
      "backingType": "Currency",
      "price": 100,
      "value": 120,
      "units": null,
      "equivalentValuePerUnit": null,
      "expiresOn": "2020-06-08T11:31:31.758Z",
      "expiresInMonths": 0,
      "overrideExpiry": true,
      "sku": "MY-SKU",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "recipientDetails": {
    "recipientName": "Valerie",
    "recipientEmail": "val@example.com",
    "message": "Happy birthday!",
    "scheduledFor": "2020-06-08T11:31:31.758Z"
  }
}

The above command returns a 201 response when the order has been created:

{
  "createdOn": "2020-06-08T11:16:48.151Z",
  "selectedRecipient": "SomeoneElse",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "purchaserEmail": "john@example.com",
  "purchaserName": "John Doe",
  "tip": 0,
  "serviceFee": 0,
  "revenue": 100,
  "customFields": [],
  "salesTaxes": [],
  "downloadLinks": {
    "single": {
      "imageUrl": "https://download.yourgift.cards/download/order/png/…",
      "pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
    },
    "zip": {
      "imageUrl": "https://download.yourgift.cards/download-zip/order/png/…",
      "pdfUrl": "https://download.yourgift.cards/download-zip/order/pdf/…",
    }
  },
  "fulfilments": [
    {
      "emailAddress": "val@example.com",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "scheduledFor": "2020-06-08T11:31:31.759Z",
      "success": true
    }
  ],
  "giftCards": [
    {
      "code": "ABC123",
      "title": "A gift card",
      // …all other gift card properties…
    }
  ]
}

Create an order containing one or more gift cards. You can specify whether Gift Up! sends any emails to the recipient or not.

HTTP Request


POST https://api.giftup/app/orders

Create order properties


orderDate datetime
When the order was created. In UTC.

now


disableAllEmails boolean
If true, Gift Up! will not send any emails for this order.

false


purchaserEmail string
The email address of the purchaser


purchaserName string
The name of the purchaser


itemDetails list
The details for the gift cards to create.

See Order - Item properties


recipientDetails object
The details for the recipient of the gift card.

See Order - Recipient properties

Order item details

This is the definition for a gift card within the Order


quantity integer
Define how many of this gift card to create.

Must be at least 1, and not more than 1000


id guid
Reference an item id

If specified, all other properties apart from quantity in this object are ignored


name string
The item name, which appears as the main title on the gift card


description string
The item description, which appears as the description on the gift card, underneath the name


code string
The code to assign to the gift card. Must be unique.

Gift Up! generates code according to your account code format


backingType string
The balance backing type of this gift card. Will be one of:


price decimal
The price charged for this gift card

0 Required if id is not specified


value decimal
The initial currency balance assigned to this gift card

0 Required if id is not specified and for Currency backed gift cards


units integer
The initial unit balance assigned to this gift card

0 Required if id is not specified and for Units backed gift cards


equivalentValuePerUnit decimal
The equivalent value per unit unit to store on the gift card when this item is purchased (for reporting purposes only)

Required if id is not specified and for Units backed gift cards


expiresOn datetime
The date this gift card expires. In UTC.

Requires overrideExpiry to be set to true


expiresInMonths integer
Number of months from now, that this gift card expires

Requires overrideExpiry to be set to true


overrideExpiry boolean
Set to true to use expiresOn or expiresInMonths

false


sku string
A private identifier for you to reference. We will include this in API calls to retrieve the gift card, and in webhooks.

Order recipient details


recipientName string
The name of the recipient of the gift card


recipientEmail string
The recipient's email address


message string
The message to the recipient


scheduledFor datetime
The datetime to send this gift card. In UTC.


fulfilmentMethod string
The method of fulfilment for this order. Needs to be one of:

Email


shippingAddress object
The shipping address definition for this order. Required if fulfilmentMethod is Post

See Shipping Address properties


shippingOption object
The shipping option definition for this order. Required if fulfilmentMethod is Post

See Shipping Option properties

Order recipient shipping address details


address1 string
The first line of the address


address2 string
The second line of the address


city string
The city line of the address


state string
The state line of the address


postalCode string
The postal/zip code line of the address


countryCode string
The 3 character ISO country code line of this address

The country code for your account

Order recipient shipping option details


id guid
Reference a Shipping Option id

If specified, all other properties in this object are ignored


name string
The name of the shipping option (e.g Overnight, or 3-5 days)

Required if id is not specified


price decimal
The price of the shipping option

Required if id is not specified

Partners

Our partners API is a restricted API open to pre-approved platform partners only

Provision a Gift Up! account

POST https://api.giftup.app/partners/account/create  HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json
Accepts: application/json
{
  "email": "name@example.com",
  "name": "Joe Bloggs",
  "companyName": "My company",
  "address": "My address, Street, City, Zip code",
  "currency": "USD",
  "countryCode": "US",
  "websiteUrl": "https://www.example.com",
  "timeZone": "America/New_York",
  "inviteCode": "",
  "createAPIKey": true,
  "isPartnerResponsibleForBilling": false
}

The above command returns JSON structured like this:

[
  {
    "companyId": "408ef75c-121c-4d48-9bfe-b2bb0f3d7744",
    "companyName": "My company",
    "accountName": "",
    "currency": "USD",
    "apiKey": "eyJhbGciOi***************************90g9LT3a9lv1g"
  }
]

Creates a new Gift Up! account using the details provided.

We will always provision a new Gift Up! account unless the users email address already exists as a dashboard admin for a single Gift Up! account. In that instance we will return the existing company's details instead of creating a new account.

If you requested an API key (via createApiKey) as part of your request, and we returned an existing company, we will return null as the apiKey in the response for security reasons.

HTTP Request


POST https://api.giftup.app/partners/account/create

Payload


email string
The email address of the owner & main account admin

Must be a valid email address


name string
The full name of the owner & main account admin


companyName string
The name of the business


address string
The full postal address of the business


currency string
The currency code for the Gift Up! account

Must be a valid 3-character currency code


countryCode string
The country code of the account

Must be a valid 3-character ISO country code


websiteUrl string
The URL of the business' website

Must be a fully qualified, absolute URL


timeZone string
The IANA time zone of where the business is located

Must be a valid IANA time zone

UTC


createApiKey boolean
Set to true to return a new API key against this Gift Up! account

false


isPartnerResponsibleForBilling boolean
Set to true to take responsibility for billing on behalf of this Gift Up! account

false

Ping

A health check for the API that won’t return any account-specific information

GET

GET https://api.giftup.app/ping  HTTP/2.0
Authorization: Bearer {{apikey}}

The above command returns a response body like this:

pong

Returns pong in the response body.

HTTP Request


GET https://api.giftup.app/ping

POST

POST https://api.giftup.app/ping  HTTP/2.0
Authorization: Bearer {{apikey}}
EXAMPLE

The above command returns a response body like this:

EXAMPLE

Returns whatever you post to it, as the response body

HTTP Request


POST https://api.giftup.app/ping

Reports

Fetch financial transactions from your account

Notes:

When an order is placed multiple events will be shown in this list. For example, an order with 3 gift cards, will have 1 OrderPlaced event with 3 GiftCardCreated events.

Transactions are immutable, which means they never change. Therefore the transaction list is forward only. This explains the events Re-activated and Unexpired. If you change the expiry date on a Gift Card, then we'll write in an Unexpired event to essentially reverse the original transaction, then add a new Expired event.

If you have questions or would like more detail about how this works, drop us an email at support@giftup.com

The transaction object

Example Transaction:

[
  {
    "id": "a0aafb2e-22e7-4e1c-b0ba-181aac7d6171",
    "eventOccuredOn": "2020-06-29T12:59:25.1465461",
    "eventType": "OrderPlaced",
    "orderId": "ce009cf1-622b-4c31-b2a6-b53334ed6f83",
    "currency": "USD",
    "giftUpFee": 2.69,
    "whoName": "Alex Allen",
    "whoEmail": "alex@giftup.com",
    "orderDetails": {
      "income": 77.0000,
      "serviceFee": 0.0000,
      "tip": 0.0000,
      "shippingFee": 0.0000
    },
    "giftCard": null
  },
  {
    "id": "d13ee30e-0994-446c-a3b1-8db44443a441",
    "eventOccuredOn": "2020-06-29T12:59:25.1465461",
    "eventType": "GiftCardCreated",
    "orderId": "ce009cf1-622b-4c31-b2a6-b53334ed6f83",
    "currency": "USD",
    "giftUpFee": 0.0,
    "whoName": "Alex Allen",
    "whoEmail": "alex@giftup.com",
    "orderDetails": null,
    "giftCard": {
      "id": "63a3596c-f7ac-4e9e-a0d3-af0957841d49",
      "code": "ALX-VQDCV",
      "valueChange": 77.0000,
      "unitChange": 0
    }
  }
]

Properties


id guid
Unique identifier for the event


eventOccurredOn datetime
The datetime that this event occurred


eventType string
The type of this event

One of: OrderPlaced, GiftCardCreated, CreditAdded, Redeemed, Expired, Unexpired, Voided, Reactivated


orderId string
The id of the order that this transaction belongs to.


currency string
The 3-character currency code that this transaction was transacted in.


giftUpFee string
The Gift Up! fee incurred for this transaction.


whoName string
The name of the user who did this event

Can be null (for event triggered by your customers)


whoEmail string
The email address of the who did this event

Can be null (for event triggered by your customers)


orderDetails object
Contains financial details of the order

Will be null for all events other than OrderPlaced. See transaction order details


giftCard object
Contains financial details of the gift card

Will be null for the OrderPlaced event. See transaction gift card details


Transaction Order Details


income decimal
The revenue taken


serviceFee decimal
The service fee charged


tip decimal
The tip taken


shippingFee decimal
The shipping fee charged


Transaction Gift Card Details


id string
The gift card id


code string
The code


valueChange decimal
The currency change in value by this event

Will be negative for Redeemed


unitChange integer
The unit change in value by this event

Only for Units backed gift cards

List report transactions

GET https://api.giftup.app/reports/transactions?createdOnOrAfter=2020-01-01&createdOnOrBefore=2020-12-31limit=2&offset=0 HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns JSON structured like this:

{
  "tranasctions": [
    {
      "id": "d13ee30e-0994-446c-a3b1-8db44443a441",
      "eventOccuredOn": "2020-06-29T12:59:25.1465461",
      "eventType": "OrderPlaced",
      "orderId": "ce009cf1-622b-4c31-b2a6-b53334ed6f83",
      "currency": "USD",
      // …all other transaction properties…
    },
    {
      "id": "9debf39c-75f4-4fe4-a5c7-3a0d98e94311",
      "eventOccuredOn": "2020-06-25T15:14:21.8617105",
      "eventType": "OrderPlaced",
      "orderId": "5d91ff4c-c079-48be-b8d1-7d120df0c5bf",
      "currency": "USD",
      // …all other transaction properties…
    }
  ],
  "total": 57,
  "hasMore": false
}

Get a list of transactions. You can optionally provide filters.

HTTP Request


GET https://api.giftup.app/reports/transactions

URL Parameters


createdOnOrAfter datetime
A UTC datetime to include only transactions created on or after this date time.


createdOnOrBefore datetime
A UTC datetime to include only transactions created on or before this date time.


events string
Only return events that match this.

Can be specified multiple times e.g. …/reports/transactions?events=OrderPlaced&events=GiftCardCreated


users string
Only return users (email address) that match this.

Can be specified multiple times e.g. …/reports/transactions?users=alex@giftup.com&users=lee@giftup.com


limit integer
The number of transactions to return

20 and must be at least 1 and no more than 100


offset integer
The number of transactions to skip

0

HTTP Response


transactions list
A list of transaction objects


total integer
The total number of transactions matching the filters provided


hasMore boolean
Set to true if there are more transactions after these

Settings

Configure your account settings via our API endpoints.

Get checkout settings

GET https://api.giftup.app/settings/checkout  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

{
  "logoUrl": "https://…",
  "introductionText": "Buy a gift card from Juicy Joes",
  "fontFamily": "Arial",
  "fontSize": "16px",
  "themeColor": "#000000",
  "backgroundColor": "Light",
  "continueLinkText": "Book a table now",
  "continueLinkUrl": "https://…",
  "redirectUrl": "https://…",
  "additionalCustomHtml": "<b>Thank you</b> for your order!",
  "showBalanceChecker": true,
  "defaultFor": "SomeoneElse",
  "serviceFeeCharged": true,
  "serviceFeeFixed": 0,
  "serviceFeePercentage": 4.9,
  "tipsEnabled": true,
  "allowCustomTipValues": true,
  "overrideTipValues": [
    "10%",
    "20%",
    "30%"
  ]
}

Get your checkout settings.

HTTP Request


GET https://api.giftup.app/settings/checkout

Response body


logoUrl string
Url of the logo shown on the hosted checkout


introductionText string
A short introduction text shown above the checkout on the hosted checkout


fontFamily string
The font to use for the checkout


fontSize string
Font size for the checkout, in px. i.e. 16px.

A px based CSS font definition


themeColor string
Base color for the checkout

Either a hex #AABBCC or rgb(50, 100, 150) color


backgroundColor string
Control whether the checkout text will be white or black

Must be one of either light or dark


continueLinkText string
The text to describe an optional continue button after an order has been placed on the checkout

Must specify in combination with continueLinkUrl for button to show


continueLinkUrl string
A url for an optional continue button after an order has been placed on the checkout

Must specify in combination with continueLinkText for button to show


redirectUrl string
A url to redirect to after an order has been placed on the checkout.

Supports placeholder replacement of the following properties:

{{orderid}}, {{currency}}, {{revenue}}, {{code}}, {{sku}}, {{name}}


additionalCustomHtml string
Custom html that will be rendered after an order has been placed on the checkout

Script tags are not allowed


showBalanceChecker boolean
Whether or not to show the balance checker option on the checkout


defaultFor string
Controls who the gift card is for by default

Valid settings are:

SomeoneElse
Me
OnlySomeoneElse - will not allow user to change
OnlyMe - will not allow user to change


serviceFeeCharged boolean
Whether or not to charge a service fee


serviceFeeFixed decimal
The fixed element to a service fee

Has no effect if serviceFeeCharged is false


serviceFeePercentage decimal
The percentage element to a service fee

Has no effect if serviceFeeCharged is false


tipsEnabled boolean
Enable or disable tips on the checkout


allowCustomTipValues boolean
If true, the user can specify their own tip value


overrideTipValues list
Specify a list of string values to override the suggested tip values.

Can either be a percentage or a fixed value e.g. '10%' or '5'

Update checkout settings

Note, PATCH operations must have the Content-Type header set to application/json-patch+json

PATCH https://api.giftup.app/settings/checkout  HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json-patch+json
Accept: application/json

Update your checkout settings.

HTTP Request


PATCH https://api.giftup.app/settings/checkout

Update checkout settings paths


[
  {
    "op": "replace",
    "path": "/introductiontext",
    "value": "Buy a gift card for Juicy Joes"
  },
  {
    "op": "replace",
    "path": "/showbalancechecker",
    "value": false
  },
]

The above command returns a 200 response when the checkout settings have been updated

Definitions for the following properties are available above

/logoUrl string
You can specify either:

  1. A fully qualified, absolute URL of an uploaded image. We will download a copy of the artwork and upload it to the Gift Up! servers.
  2. A base64 encoded string representing the image. Must start with data:image.

/introductionText string


/fontFamily string


/fontSize string


/themeColor string


/backgroundColor string

Must be either Light or Dark


/continueLinkText string


/continueLinkUrl string

Minimum length: 5, maximum length: 50. Must contain at least 3 placeholders (*, @, #), but ideally 5 or more


/redirectUrl string


/additionalCustomHtml string


/showBalanceChecker boolean


/defaultFor string

Must be either SomeoneElse, OnlySomeoneElse, Me or OnlyMe


/serviceFeeCharged boolean


/serviceFeeFixed decimal

Must be at least 0


/serviceFeePercentage decimal

Must be between 0 and 100


/tipsEnabled boolean


/allowCustomTipValues boolean


/overrideTipValues list

Is a list of strings defining the custom tip values. i.e. ["5%", "10%", "20%", "5"]

Get email settings

GET https://api.giftup.app/settings/email  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

{
  "logoUrl": "https://…",
  "logoAlignment": "left",
  "logoWidth": 180,
  "fromEmail": "giftcards@juicyjoes.com",
  "fromName": "Juicy Joes",
  "giftCardEmail": {
      "subjectLine": "Here's a gift card for Juicy Joes",
      "title": "Here's a gift card for Juicy Joes",
      "introText": "Someone has sent you a gift card for Juicy Joes.",
      "footerText": "We hope you love juicy steaks..!",
      "buttonLabel": "Reserve a table now",
      "buttonUrl": "https://…",
      "buttonColour": "#ededed",
      "buttonAlignment": "left"
  },
  "receiptEmail": {
      "subjectLine": "Thank you for your order",
      "title": "Thank you for your order",
      "introText": "Thank you for ordering a gift card for someone for Juicy Joes, I'm sure they'll love it!",
      "footerText": "All the best\r\n\r\nJoe"
  }
}

Get your email settings.

HTTP Request


GET https://api.giftup.app/settings/email

Response body


logoUrl string
Url of the logo shown on the emails sent to customers


logoAlignment string
Where the email logo should sit

One of left, middle or right


logoWidth integer
The width in pixels of the logo


fromEmail string
The reply-to email address for emails sent to customers


fromName string
The email from 'display name' as displayed in email clients

{{fromName}} <here.are@yourgift.cards>


giftCardEmail object
Settings for the gift card email

See Gift card email


receiptEmail object
Settings for the receipt email

See Receipt email

Gift card email


subjectLine string
The subject line for the gift card email


title string
The headline text in the gift card email


introText string
The text to display in the introduction of the gift card email


footerText string
The text to display in the footer of the gift card email


buttonLabel string
A optional label for a button in the gift card email


buttonUrl string
An optional url for a button in the gift card email


buttonColour string
The colour for the additional button

Either a hex#AABBCC or rgb(50, 100, 150) color


buttonAlignment string
Settings for the receipt email

One of left, middle or right

Receipt email


subjectLine string
The subject line for the receipt email


title string
The headline text in the receipt email


introText string
The text to display in the introduction of the receipt email


footerText string
The text to display in the footer of the receipt email

Update email settings

Note, PATCH operations must have the Content-Type header set to application/json-patch+json

PATCH https://api.giftup.app/settings/email  HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json-patch+json
Accept: application/json

Update your email settings.

HTTP Request


PATCH https://api.giftup.app/settings/email

Update email settings paths


[
  {
    "op": "replace",
    "path": "/logowidth",
    "value": 150
  },
  {
    "op": "replace",
    "path": "/fromemail",
    "value": "joe@juicyjoes.com"
  },
  {
    "op": "replace",
    "path": "/fromname",
    "value": "Juicy Joes"
  }
]

The above command returns a 200 response when the email settings have been updated

Definitions for the following properties are available above

/logourl string
You can specify either:

  1. A fully qualified, absolute URL of an uploaded image. We will download a copy of the artwork and upload it to the Gift Up! servers.
  2. A base64 encoded string representing the image. Must start with data:image.

/logoalignment string
Must be one of left, middle or right


/logowidth integer


/fromemail string


/fromname string


/giftcardemail/subjectline string


/giftcardemail/title string


/giftcardemail/introtext string


/giftcardemail/footertext string


/giftcardemail/buttonlabel string


/giftcardemail/buttonurl string


/giftcardemail/buttoncolour string


/giftcardemail/buttonalignment string

Must be one of left, middle or right


/receiptemail/subjectline string


/receiptemail/title string


/receiptemail/introtext string


/receiptemail/footertext string

Get gift card settings

GET https://api.giftup.app/settings/gift-card  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

{
    "defaultDescription": "For use at Juicy Joe's",
    "barcodeFormat": "PDF417",
    "expiryInMonths": 12,
    "giftCardExpiresSetting": "Expires",
    "showIssuedOnDate": false,
    "showBalance": true,
    "showBarcode": true,
    "generalTerms": "Can be used at any Juicy Joes location",
    "codeFormat": "JOES-*****"
}

Get your gift card settings.

HTTP Request


GET https://api.giftup.app/settings/gift-card

Response body


defaultDescription string
The default description to display on gift cards. Can be overridden when creating an item


barcodeFormat string
The format of the barcode

Must be one of Code128, Code39, DataMatrix, PDF417, QR


expiryInMonths string
Number of months after purchase that a gift card expires

null


giftCardExpiresSetting string
Whether or not the gift card expires

Must be one of Expires or NeverExpires


showIssuedOnDate string
Show or hide the issued on date when rendering a gift card


showBalance string
Show or hide the balance when rendering a gift card


showBarcode string
Show or hide the barcode when rendering a gift card


generalTerms string
General term & conditions shared across all gift cards


codeFormat string
The format used to generate gift card codes

@ = Random letter
# = Random number
* = Random letter/number All other characters kept

Must include at least 3 randomly generated characters (@, # or *)

Update gift card settings

Note, PATCH operations must have the Content-Type header set to application/json-patch+json

PATCH https://api.giftup.app/settings/gift-card  HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json-patch+json
Accept: application/json

Update your gift card settings.

HTTP Request


PATCH https://api.giftup.app/settings/gift-card

Update gift card settings paths


[
  {
    "op": "replace",
    "path": "/barcodeformat",
    "value": "Code128"
  },
  {
    "op": "replace",
    "path": "/expiryinmonths",
    "value": 12
  },
]

The above command returns a 200 response when the gift card settings have been updated

Definitions for the following properties are available above

/defaultdescription string


/barcodeformat string

Must be one of PDF417, Code128, Code39, DataMatrix, QR


/expiryinmonths integer

Must be at least 1, can be null


/showissuedondate boolean


/showbalance boolean


/showbarcode boolean


/generalterms string


/codeformat string

Minimum length: 5, maximum length: 50. Must contain at least 3 placeholders (*, @, #), but ideally 5 or more

List gift card artwork

GET https://api.giftup.app/settings/gift-card/artwork  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

[
  {
    "id": "78770b6f-15c5-41f4-b8a9-f0a88b81593e",
    "url": "https://…",
    "sortOrder": 1
  },
  {
    "id": "44d0a2a2-2fb5-4055-9fd1-827fdad548b7",
    "url": "https://…",
    "sortOrder": 2
  }
]

Get a list of your your uploaded gift card artwork.

HTTP Request


GET https://api.giftup.app/settings/gift-card/artwork

Response body


id string
The id of the artwork


url string
The URL of the artwork


sortOrder integer
The sort order of the artwork, 1 is the default artwork shown to the purchaser initially on the checkout

Upload gift card artwork

POST https://api.giftup.app/settings/gift-card/artwork  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json
{
  "url": "https://…",
  "replaceAllExistingArtwork": false,
  "replaceArtworkId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The above command returns a 200 response when the artwork has been uploaded

Upload some new gift card artwork.

HTTP Request


POST https://api.giftup.app/settings/gift-card/artwork

Request body


url string
You can specify either:

  1. A fully qualified, absolute URL of an uploaded image. We will download a copy of the artwork and upload it to the Gift Up! servers.
  2. A base64 encoded string representing the image. Must start with data:image.

replaceAllExistingArtwork boolean
If set to true, we will delete all existing artwork before replacing with this

false


replaceArtworkId string
The id of the artwork to replace

blank

Delete gift card artwork

DELETE https://api.giftup.app/settings/gift-card/artwork/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a 200 response when the artwork has been deleted

Delete one of your uploaded gift card artwork.

HTTP Request


DELETE https://api.giftup.app/settings/gift-card/artwork/{id}

URL Parameters


id guid
The id of the artwork to delete

Get shipping settings

GET https://api.giftup.app/settings/shipping  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

{
    "enableDigitalFulfilment": true,
    "enableSelfFulfilledPostal": true,
    "enablePostalMessage": true,
    "postalShippingOptions": [
        {
            "id": "54f0a89c-a6d6-457c-a88c-294fc7d1287e",
            "name": "USA shipping",
            "price": 5.9900,
            "sortOrder": 0,
            "type": "Post",
            "countries": [
                {
                    "name": "United States",
                    "IsoCode": "USA"
                }
            ]
        },
        {
            "id": "a662aa48-3665-4de6-9e1f-c861da02f139",
            "name": "International shipping",
            "price": 9.9900,
            "sortOrder": 1,
            "type": "Post",
            "countries": []
        },
        {
            "id": "054b9ad0-9e56-45ec-ace8-104d3b00d1f7",
            "name": "Collect in-store",
            "price": 0.0000,
            "sortOrder": 2,
            "type": "Collect",
            "countries": []
        }
    ]
}

Get your shipping settings.

HTTP Request


GET https://api.giftup.app/settings/shipping

Response body


enableDigitalFulfilment boolean
Whether fulfilment by email is enabled


enableSelfFulfilledPostal boolean
Whether fulfilment by post is enabled


enablePostalMessage boolean
Whether the customer can enter a personal message when choosing a postal gift card

Only relevant if enableSelfFulfilledPostal is enabled


postalShippingOptions list
An array of shipping options presented to the purchaser

Only relevant if enableSelfFulfilledPostal is enabled See shipping option definition

Shipping option


id guid
The shipping option unique identifier


name string
The shipping option name


price decimal
The price to charge the purchaser for shipping


sortOrder integer
The ascending sort order of the shipping options


type string
The fulfilment type. Can be one of the following: Post Collect for postal or collection


countries list
Which countries are allowed for this shipping option. If empty, all countries are allowed.

See shipping option country definition

Shipping option country


name string
The country name


isoCode string
The 3 character ISO country code

Users

An user is someone who has access to your Gift Up! account. They can either be a redeem level user or an administrator with full dashboard access.

The user object

Example item:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Joe",
  "email": "joe@juicyjoes.com",
  "avatarUrl": "https://…",
  "pin": "1234",
  "isAdministrator": true,
  "emailConfirmed": true,
  "hiddenInRedeemApp": false,
  "disableSearchInRedeemApp": false
}

Properties


id guid Unique identifier for the user


name string
The name of the user


email string
The email address of the user


avatarUrl string The uploaded image of the user


pin string
The redeem pin number for the user


isAdministrator boolean
Set to true if the user is a dashboard admin


emailConfirmed boolean Set to true if the user has confirmed their email address


hiddenInRedeemApp boolean
Set to true if the user is hidden in the redeem app


disableSearchInRedeemApp boolean
Set to true if the user cannot perform a gift card search in the redeem app (they can only lookup a gift card by code)

Invite a user

POST https://api.giftup.app/users  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json
{
  "name": "Joe",
  "email": "joe@juicyjoes.com",
  "pin": "1234",
  "isAdministrator": true,
  "hiddenInRedeemApp": false,
  "disableSearchInRedeemApp": false
}

The above command returns a 200 response when the user has been invited

Invite a user to access your Gift Up! account

HTTP Request


POST https://api.giftup.app/users

Request body


See user object

List all users

GET https://api.giftup.app/users  HTTP/2.0
Authorization: Bearer {{apikey}}

The above command returns a response body like this:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Joe",
    "email": "joe@juicyjoes.com",
    "avatarUrl": "https://…",
    "pin": "1234",
    "isAdministrator": true,
    "emailConfirmed": true,
    "hiddenInRedeemApp": false,
    "disableSearchInRedeemApp": false
  },
  {
    "id": "695df468-6804-4fa3-996a-22919ceb0d30",
    "name": "Jenny",
    "email": "jenny@juicyjoes.com",
    "avatarUrl": "",
    "pin": "0963",
    "isAdministrator": false,
    "emailConfirmed": true,
    "hiddenInRedeemApp": false,
    "disableSearchInRedeemApp": true
  }
]

List of all users who have access to your Gift Up! account

HTTP Request


GET https://api.giftup.app/users

Response body


See user object

Get a user

GET https://api.giftup.app/users/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json

The above command returns a response body like this:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Joe",
  "email": "joe@juicyjoes.com",
  "avatarUrl": "https://…",
  "pin": "1234",
  "isAdministrator": true,
  "emailConfirmed": true,
  "hiddenInRedeemApp": false,
  "disableSearchInRedeemApp": false
}

Get a user by id

HTTP Request


GET https://api.giftup.app/users/{id}

URL Parameters


id guid
The id of the user to retrieve

Response body


See user object

Delete a user

DELETE https://api.giftup.app/users/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}

The above command returns a 200 response when the user has been removed from your account

Delete a user by id

HTTP Request


DELETE https://api.giftup.app/users/{id}

URL Parameters


id guid
The id of the user to delete

Update a user

Note, PATCH operations must have the Content-Type header set to application/json-patch+json

PATCH https://api.giftup.app/users/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json-patch+json

Update a user by id. This endpoint supports the standard JSON patch definition.

HTTP Request


PATCH https://api.giftup.app/users/{id}

URL Parameters


id guid
The id of the user to update

Update user paths


[
  {
    "op": "replace",
    "path": "/name",
    "value": "Joe Bloggs"
  },
  {
    "op": "replace",
    "path": "/role",
    "value": "administrator"
  },
]

The above command returns a 200 response when the user has been updated

/name string
The user's name


/pin string
The pin for use with the Gift Up! redeem app


/email string
The email address of the user


/role string
Change the role of the user.

Can be either blank/null or administrator

Webhooks

When the webhook is triggered to we will send a payload to your {targetUrl} via POST:

POST https://www.example.com/your-webhook-endpoint  HTTP/2.0
Content-Type: application/json
X-Request-Signature-Sha-256: t=1591878966388,sha256=16f67da1bcd72f87dd95534baa0223a450b68cca122d46dd017074375220b13c

You can configure webhook endpoints via the API to be notified about events that happen in your Gift Up! account. Most users configure webhooks from the Gift Up! dashboard, which provides a user interface for registering and testing your webhook endpoints.

We support 4 webhooks: OrderCreated, GiftCardCreated, GiftCardUpdated and GiftCardRedeemed.

Payload definitions

GiftCardCreated webhook payload

Example GiftCardCreated webhook payload (we include all gift card object properties):

{
  // …gift card properties…
  "remainingValueWithCurrency": "$49.99",
  "initialValueWithCurrency": "$99.98",
}

The payload fired to your targetUrl will include the basic gift card object with the following 2 extra properties:


initialValueWithCurrency string
We prettify the initial value as a currency string. i.e. "$99.99"


remainingValueWithCurrency string
We prettify the remaining value as a currency string. i.e. "$99.99"


GiftCardRedeemed webhook payload

Example GiftCardRedeemed webhook payload (we include all gift card object properties):

{
  // …gift card properties…
  "redeemedBy": "Jane",
  "redeemedByEmail": "jane@juicyjoes.com",
  "redeemedAmount": 10.50,
  "unitsRedeemed": 0,
  "occurredOn": "2020-06-08T11:16:48.151Z",
}

The payload fired to your targetUrl will include the basic gift card object with the following 4 extra properties:


redeemedBy string
The name of the user who redeemed the gift card


redeemedByEmail string
The email address of the user who redeemed the gift card


redeemedAmount decimal
The currency balance redeemed off the gift card

Only for Currency backed gift cards


unitsRedeemed integer
The unit balance redeemed off the gift card

Only for Units backed gift cards


occurredOn datetime
When the redemption event occurred. In UTC.


GiftCardUpdated webhook payload

The payload fired to your targetUrl will include the basic gift card object with no extra properties

OrderCreated webhook payload

Example OrderCreated webhook payload (we include all order object properties):

{
  // …order properties…
  "revenueWithCurrency": "$99.98"
}

The payload fired to your targetUrl will include the basic order object with the following extra property:


revenueWithCurrency string
We prettify the revenue value as a currency string. i.e. "$99.99"

Verifying calls are made by Gift Up!

Example request:

POST https://www.example.com/your-webhook-endpoint  HTTP/2.0
Content-Type: application/json
X-Request-Signature-Sha-256: t=1591878966388,sha256=16f67da1bcd72f87dd95534baa0223a450b68cca122d46dd017074375220b13c
{
  // webhook payload
}

Verifying secret in C#

var request = HttpContext.Request;

var signatureHeader = request.Headers["X-Request-Signature-Sha-256"][0];

var splitSignature = signatureHeader.Split(',');
var unixTimestamp = splitSignature[0].Split('=')[1];
var expectedsha = splitSignature[1].Split('=')[1];

var secret = ""; // your secret
var keyBytes = Encoding.UTF8.GetBytes(secret);

var requestBody = request.Content.ReadAsStringAsync();

var payload = Encoding.UTF8.GetBytes(requestBody + unixTimestamp);
using (var hmacsha256 = new HMACSHA256(keyBytes))
{
    var hashedBytes = hmacsha256.ComputeHash(payload);

    var sha = BitConverter.ToString(hashedBytes).Replace("-", "").ToLower();

    if (expectedsha == sha)
    {
      // success! this was sent by Gift Up!
    }
}

Verifying secret in node/js

const crypto = require("crypto"); 

var secret = "YOUR-SECRET"; // your webhook secret
var header = req.header("X-Request-Signature-Sha-256");
var body = req.body; // request body

var splitHeader = header.split(",");
var ts = splitHeader[0].split('=')[1];
var expectedSha = splitHeader[1].split("=")[1];

var computedSha = crypto.createHmac("sha256", secret)
                        .update(body + ts)
                        .digest("hex");

if(expectedSha == computedSha){
  // success! this was sent by Gift Up!
}

Verifying secret in Ruby/Rails

def signature_valid? 

  secret = Rails.application.secrets.gift_up_webhook_secret
  header = request.headers.fetch('X-Request-Signature-SHA-256', ',')
  body = request.body.read

  split_header = header.split(',')
  ts = split_header[0].try(:split, '=').try(:pop)
  expected_sha = split_header[1].try(:split, '=').try(:pop)

  calculated_signature = OpenSSL::HMAC.hexdigest( OpenSSL::Digest.new('sha256'), secret, body + ts ) 

  if calculated_signature == expected_sha
    # success! this was sent by Gift Up!
  end

end

When we post data to your webhook we will sign each request to your endpoint with the secret you specified when creating the webhook. This is so that you can ensure that it is Gift Up! that is posting data to you, and not a malicious third party.

The signature is contained in the X-Request-Signature-Sha-256 header.

i.e. X-Request-Signature-Sha-256: t=1591878966388,sha256=16f67da1bcd72f87dd95534baa0223a450b68cca122d46dd017074375220b13c

The header contains a timestamp (Unix timestamp in milliseconds) and the signature. The timestamp is prefixed with t= and the signature is prefixed with sha256=.

  1. Split the header using the , character, this will separate the timestamp from the signature. Split each element on = , to give you key and value.
  2. Prepare the signature to be compared. This is achieved by appending the timestamp to the end of the payload string.
  3. Compute a HMAC with the SHA256 hash function, using the secret you provided for the webhook.
  4. Compare the signature in the header, with the expected signature you calculated in 3.

The webhook object

Example webhook:

{
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://www.example.com/gift-card-created-webhook",
    "eventType": "GiftCardCreated",
    "isTestMode": false
}

Properties


id guid
Unique identifier for the webhook


url string
The delivery URL for the webhook


eventType string
The event type for this webhook. Can be one of the following: OrderCreated GiftCardCreated GiftCardUpdated GiftCardRedeemed


isTestMode boolean
If set to true, then the webhook will only fire on test data events.

Add a webhook

POST https://api.giftup.app/hooks/{event}  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json
{
  "targetUrl": "https://www.example.com/gift-card-created-webhook",
  "secret": "8dd9e9d5b03ad443ab81b295c1e8d314",
  "isTestMode": false
}

The above command returns a the webhook id in the 201 response body when the webhook has been created

A webhook endpoint must have a targetUrl and an event. You may specify the Boolean isTestMode parameter. If set to true, then the webhook will only fire on test data events.

HTTP Request


POST https://api.giftup.app/hooks/{event}

URL Parameters


event string
The event type for this webhook. Can be one of the following: order-created gift-card-created gift-card-updated gift-card-redeemed

Request body


targetUrl string
The delivery URL for the webhook


secret string
When we post data to your webhook we will sign each request to your endpoint with the secret you specified when creating the webhook. This is so that you can ensure that it is Gift Up! that is posting data to you, and not a malicious third party.

blank


isTestMode boolean
A boolean to indicate whether to fire this webhook for live or test data.

false

List all webhooks

GET https://api.giftup.app/hooks  HTTP/2.0
Authorization: Bearer {{apikey}}

The above command returns a response body like this:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://www.example.com/gift-card-created-webhook",
    "eventType": "GiftCardCreated",
    "isTestMode": false
  },
  {
    "id": "c686ca33-5abd-4b98-85cf-c838e67b079b",
    "url": "https://www.example.com/gift-card-updated-webhook",
    "eventType": "GiftCardUpdated",
    "isTestMode": false
  }
]

Retrieve all webhooks on an account

HTTP Request


GET https://api.giftup.app/hooks

Response body


A list of webhook objects

Get a webhook

GET https://api.giftup.app/hooks/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}

The above command returns a response body like this:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://www.example.com/gift-card-created-webhook",
  "eventType": "GiftCardCreated",
  "isTestMode": false
}

Retrieve a webhook by id.

HTTP Request


GET https://api.giftup.app/hooks/{id}

URL Parameters


id string
The id of the webhook to retrieve

Response body


The webhook object

Delete a webhook

DELETE https://api.giftup.app/hooks/{id}  HTTP/2.0
Authorization: Bearer {{apikey}}

The above command returns a 200 response when the webhook has been deleted

You can also delete webhook endpoints via the webhook management page in the Gift Up! dashboard.

HTTP Request


DELETE https://api.giftup.app/hooks/{id}

URL Parameters


id string
The id of the webhook to delete