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.
Controlling display name
You can pass a header of x-giftup-displayname to override the display name used in API calls.
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. (Reserved for future use.) 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:
yyyy-MM-dde.g. "2020-07-30"yyyy-MM-dd HH:mme.g. "2020-07-30 16:35"yyyy-MM-dd HH:mm:sse.g. "2020-07-30 16:35:06"yyyy-MM-ddTHH:mm:ss.fffffffKe.g. "2020-07-30T16:35:06.0000000" / "2020-07-30T16:35:06.0000000Z"yyyy-MM-ddTHH:mm:ss.fffKe.g. "2020-07-30T16:35:06.000" / "2020-07-30T16:35:06.000Z"yyyy-MM-ddTHH:mm:ssKe.g. "2020-07-30T16:35:06" / "2020-07-30T16:35:06-07:00"yyyy-MM-ddTHH:mmKe.g. "2020-07-30T16:35" / "2020-07-30T16:35Z"- Round-trip date/time pattern e.g. "2009-06-15T13:45:30.0000000-07:00"
- RFC1123 pattern e.g. "Mon, 15 Jun 2009 20:45:30 GMT"
Where:
yyyyis the 4 digit yearMMis the 2 digit monthddis the 2 digit day of the monthHHis the 2 digit hours, in 24 hour notationmmis the 2 digit minutesssis the 2 digit secondsfffis the 3 digit millisecondsKis the time zone information specifier. E.g.Zfor UTC (aka Zulu), or-07:00,-0700for the offset in hours
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.
Rate limits
Request throughput per API key:
Sustained: 5 requests per second
Burst (example): 10 requests per second for up to 5 minutes
The Gift Up API use a leaky bucket algorithm to manage requests. This algorithm lets your app make an large amount of requests in infrequent bursts over time. This model ensures that apps that manage API calls responsibly will always have room in their buckets to make a burst of requests if needed.
The general throughput target for any given API key is 5 requests per second for a sustained period. We do not guarantee these limits, but we aim to achieve this throughput.
If you are using our API beyond these limits we will slow down your calls to us by up to several seconds, and eventually for more severe cases, we will block your API key being used for several minutes by returning a HTTP 429 response.
Metadata
Example: Adding metadata to 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",
"revenue": 100,
// …all other order properties…
"metadata": {
"a key": "a value",
"another key": "another value"
}
}
Orders and some Report transactions have a metadata parameter. You can use this parameter to attach key-value data to these Gift Up! objects.
You can specify up to 20 keys, and the value can be any type supported by the JSON spec, including string, boolean, object, array, number etc…
Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on an Order object. Metadata is not used by Gift Up! and won't be seen by your customers.
Companies
A company is also known as a Gift Up account. Multiple users can have access to a single Gift Up company.
The company object
Example item:
{
"id": "cd6228d8-8ed6-4264-b28a-eb5a5736e81e",
"name": "Juicy Joes Steakhouse",
"currency": "GBP",
"onboardingCompleted": true,
"canShowCheckout": true,
"isCheckoutLive": true
}
Properties
Unique identifier for the company. This is also referred to as a site id when installing a checkout.
The name of the company
Have all onboarding steps been completed
Have enough onboarding steps been completed to allow the checkout to render.
Has the checkout been seen in the wild.
Get company
GET https://api.giftup.app/company HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
The above command returns a response body like this:
{
"id": "cd6228d8-8ed6-4264-b28a-eb5a5736e81e",
"name": "Juicy Joes Steakhouse",
"currency": "GBP",
"onboardingCompleted": true,
"canShowCheckout": true,
"isCheckoutLive": true
}
Get the current company details for the provided API key
HTTP Request
GET https://api.giftup.app/company
Response body
See company object
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 Not Yet Valid 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:
- Active a gift card that has a positive balance and is not voided or expired
- Expired a gift card that has a positive balance, is not voided but has expired based on its
expiredOndate - Not Yet Valid a gift card that has a positive balance, is not voided but is yet to become valid based on the
validFromdate - Redeemed a gift card that has a zero balance
- Voided a gift card that has a positive balance and has been voided
The API does not emit these states, instead is emits the underlying properties canBeRedeemed, hasExpired, notYetValid, 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,
"notYetValid": 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",
"validFrom": null,
"voidedOn": "2020-06-10T15:02:17.786Z",
"fulfilledBy": "Email",
"order": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orderNumber": "10152",
"createdOn": "2020-06-10T15:02:17.786Z",
"selectedRecipient": "SomeoneElse",
"purchaserEmail": "joe.bloggs@example.com",
"purchaserName": "Joe Bloggs",
"tip": 0,
"serviceFee": 0,
"shippingFee": 0,
"currency": "USD",
"revenue": 50,
"customFields": [
{
"label": "Telephone",
"value": "202-555-0191"
}
],
"salesTaxes": [
{
"label": "Sales Tax",
"amount": 20,
"type": "exclusive"
}
],
"notes": [
{
"id": "09666ea2-403b-4ae0-9566-729c702e8970",
"content": "My note",
"createdOn": "2024-06-08T11:18:48.151Z",
"username": "Staff name"
}
],
"metadata": {},
"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/…",
}
},
"payment": {
"provider": "Stripe",
"transactionId": "ch_1HoUlaLci192ejy9tlDvIPT0"
}
},
"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",
"scheduledFor": "2020-12-25T08:00:00.000Z"
},
"downloadLinks": {
"artworkUrl": "https://cdn.giftup.app/assets/…",
"imageUrl": "https://download.yourgift.cards/download/order/png/…",
"pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
"appleWalletUrl": "https://download.yourgift.cards/download/order/apple-wallet/…",
"googleWalletUrl": "https://download.yourgift.cards/download/google-pay/…"
},
"ledger": [
{
"transactionId": "8b517a5a-9c88-4f30-ad71-30cabc6df0a6",
"eventOccuredOn": "2020-06-10T15:02:17.786Z",
"eventOccuredAtLocationId": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"value": 100,
"whoEmail": "",
"whoName": "",
"eventType": "GiftCardCreated"
},
{
"transactionId": "0dbf6d24-3503-4d9f-acfb-8ac6522e5f3e",
"eventOccuredOn": "2020-06-10T15:02:17.786Z",
"eventOccuredAtLocationId": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"value": null,
"whoEmail": "",
"whoName": "",
"eventType": "OrderPlaced"
}
]
}
Properties
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.
hasExpired or expiredOn if this is important to you.notYetValid or validFrom if this is important to you.
Whether or not this gift card has expired, based on its expiresOn date
Whether or not this gift card is valid, based on its validFrom date
Whether or not this gift card has been voided
The gift card code
The main title of the gift card
The sub-title of the gift card (appears underneath the title in the gift card)
The message included with the gift card
The datetime that this gift card was fulfilled, either by email, or post
The recipient name on the gift card
The email address for the recipient of this gift card
The balance backing type of this gift card. Will be one of:
CurrencyUnits
The currency balance remaining on this gift card
Currency backed gift cards
The units balance remaining on this gift card
Units backed gift cards
The initial currency balance this gift card was issued with
Currency backed gift cards
The initial units balance this gift card was issued with
Units backed gift cards
The equivalent value per unit unit this gift card was issued with (for reporting purposes only)
Units backed gift cards
The terms captured when this gift card was created
The private SKU that is associated with the item this gift card is for
Describes which method fulfilled this gift card. One of Post or Email
The datetime that this gift card expires
The datetime that this gift card is valid from
The datetime that this gift card was voided
The order this gift card belongs to
Details of the postal fulfilment.
Details of the email fulfilment
An collection of links to download the gift card in its state at the point of download
A list of events that have occurred against this gift card
Gift card postal fulfilment
The address to send this gift card to
The name of the shipping option selected.
Gift card postal address
The name of the recipient
The first line of the address
The second line of the address
The city
The state
The postal/zip code
The country code
Gift card email fulfilment
The email address this gift card was/will be fulfilled to
The UTC datetime that the email is requested to be sent
Gift card ledger entry
The datetime this event occurred
The id of the the location where the event occurred
The currency value change introduced by this event
redeemed eventUnits backed gift cards
The units change introduced by this event
redeemed eventUnits backed gift cards
The email address of the user who triggered this event
The name of the user who triggered this event
The type of event. One of OrderPlaced, GiftCardCreated, CreditAdded, Redeemed, Expired,Unexpired, Voided, Reactivated
The id of the report transaction object.
Gift card download links
A link to a PNG file that represents the artwork selected for the gift card, this is either chosen by the purchaser (in the case of a choice being presented to them), or defined by your gift card settings
A link that can be presented to users which will generate a composite PNG file of the gift card in its state at the time of download
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
A link that can be presented to users which will generate a downloadable gift card for Apple device wallets
A link that can be presented to users which will generate a downloadable gift card for Google wallets
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:
{
"canBeRedeemed": true,
"hasExpired": false,
"notYetValid": 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",
"validFrom": null,
"voidedOn": "2020-06-10T15:02:17.786Z",
"fulfilledBy": "Email",
"order": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orderNumber": "10152",
"createdOn": "2020-06-10T15:02:17.786Z",
"selectedRecipient": "SomeoneElse",
"purchaserEmail": "joe.bloggs@example.com",
"purchaserName": "Joe Bloggs",
"tip": 0,
"serviceFee": 0,
"shippingFee": 0,
"revenue": 50,
"customFields": [
{
"label": "Telephone",
"value": "202-555-0191"
}
],
"salesTaxes": [
{
"label": "Sales Tax",
"amount": 20,
"type": "exclusive"
}
],
"metadata": {},
"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/…",
}
},
"payment": {
"provider": "Stripe",
"transactionId": "ch_1HoUlaLci192ejy9tlDvIPT0"
}
},
"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",
"scheduledFor": "2020-12-25T08:00:00.000Z"
},
"downloadLinks": {
"artworkUrl": "https://cdn.giftup.app/assets/…",
"imageUrl": "https://download.yourgift.cards/download/order/png/…",
"pdfUrl": "https://download.yourgift.cards/download/order/pdf/…",
"appleWalletUrl": "https://download.yourgift.cards/download/order/apple-wallet/…",
"googleWalletUrl": "https://download.yourgift.cards/download/google-pay/…"
},
"ledger": [
{
"transactionId": "8b517a5a-9c88-4f30-ad71-30cabc6df0a6",
"eventOccuredOn": "2020-06-10T15:02:17.786Z",
"eventOccuredAtLocationId": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"value": 100,
"whoEmail": "",
"whoName": "",
"eventType": "GiftCardCreated"
},
{
"transactionId": "0dbf6d24-3503-4d9f-acfb-8ac6522e5f3e",
"eventOccuredOn": "2020-06-10T15:02:17.786Z",
"eventOccuredAtLocationId": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"value": null,
"whoEmail": "",
"whoName": "",
"eventType": "OrderPlaced"
}
]
}
Retrieves a single gift card
HTTP Request
GET https://api.giftup.app/gift-cards/{code}
URL Parameters
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
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"
},
]
The main title of a gift card
The gift card expiry date
The gift card valid from date
The email address of the recipient
The name of the recipient
The SKU for this gift card
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 via the URL parameters below.
HTTP Request
GET https://api.giftup.app/gift-cards
URL Parameters
Include only gift cards in this state
active, expired, redeemed or voided
A UTC datetime to include only gift cards created on or after this date time
A UTC datetime to include only gift cards updated on or after this date time
Include only gift cards for this particular order id
Include only gift cards with this private SKU value
Include only gift cards with this recipient email address
Include only gift cards with this purchaser email address
Include only gift cards where the transaction id returned by your payment provider matches this value
The number of gift cards to return
The number of gift cards to skip
HTTP Response
A list of gift card objects
The total number of gift cards in Gift Up! matching the createdOnOrAfter constraint
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
The gift card code to reactivate
Request body
Example request body:
{
"reason": "An optional reason for reactivating this gift card",
"locationId": null,
"metadata": {
"key": "value"
}
}
The reason for reactivating. Will appear in the gift card history log.
The location id where this event occurred at.
A key-value data store of metadata provided to us by you.
Error - 422 Unprocessable Entity
A 422 response returns JSON structured like this:
{
"isRedeemed": true,
"isAlreadyActive": false
}
The gift card could not be reactivated. Please see response for details.
A redeemed gift card cannot be reactivated
An active 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
The gift card code to void
Request body
Example request body:
{
"reason": "An optional reason for voiding this gift card",
"locationId": null,
"metadata": {
"key": "value"
}
}
The reason for voiding. Will appear in the gift card history log.
The location id where this event occurred at.
A key-value data store of metadata provided to us by you.
Error - 422 Unprocessable Entity
A 422 response returns JSON structured like this:
{
"isRedeemed": true,
"isAlreadyVoided": false
}
The gift card could not be voided. Please see response for details.
A redeemed gift card cannot be voided
A voided gift card cannot be voided again
Top up a gift card
POST https://api.giftup.app/gift-cards/{code}/top-up HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json
Will add balance to a gift card
HTTP Request
POST https://api.giftup.app/gift-cards/{code}/top-up
URL Parameters
The gift card code to top up
Request body
Example request body:
{
"amount": 25,
"units": null,
"reason": "Optional reason for topping up this gift card",
"locationId": null,
"metadata": {
"key": "value"
}
}
The currency balance to add to the gift card.
Currency backed gift cards
The units to add to the gift card.
Units backed gift cards
The reason for this top-up. Will appear in the gift card history log.
The location id where this event occurred at.
A key-value data store of metadata provided to us by you.
Response body
A 200 response returns JSON structured like this:
{
"transactionId": "d9d587ae-fada-431c-e7af-08d885934bd4",
"remainingCredit": 75,
"remainingUnits": null
}
The id of the report transaction object.
The currency balance now available on the gift card.
Currency backed gift cards
The unit balance now available on the gift card.
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.
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
The gift card code to redeem
Request body
Example request body:
{
"amount": 50,
"units": null,
"reason": "Used with Order 7597",
"locationId": null,
"metadata": {
"ExternalOrderId": "7597"
}
}
The currency amount to redeem against this gift card
Currency backed gift cards
The units to redeem off this gift card
Units backed gift cards
The reason for this redemption. Will appear in the gift card history log.
The location id where this event occurred at.
A key-value data store of metadata provided to us by you.
Response body
A 200 response returns JSON structured like this:
{
"transactionId": "d9d587ae-fada-431c-e7af-08d885934bd4",
"redeemedAmount": 50,
"remainingCredit": 25,
"redeemedUnits": null,
"remainingUnits": null
}
The id of the report transaction object.
The currency amount redeemed off the gift card.
Currency backed gift cards
The amount now available on the gift card.
Currency backed gift cards
The units redeemed off the gift card.
Units backed gift cards
The number of units now remaining on the gift card.
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.
The gift card has already been fully redeemed
The gift card does not have enough balance to redeem the specified amount
Currency backed gift cards
The remaining balance on the gift card
Currency backed gift cards
The gift card does not have enough units to redeem the specified units
Units backed gift cards
The number of units remaining on the gift card.
Units backed gift cards
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
The gift card code to redeem
Request body
Example request body:
{
"reason": "Used with Order 7597",
"locationId": null,
"metadata": {
"ExternalOrderId": "7597"
}
}
The reason for this redemption. Will appear in the gift card history log.
The location id where this event occurred at.
A key-value data store of metadata provided to us by you.
Response body
A 200 response returns JSON structured like this:
{
"transactionId": "d9d587ae-fada-431c-e7af-08d885934bd4",
"redeemedAmount": 75,
"remainingCredit": 0,
"redeemedUnits": null,
"remainingUnits": null
}
The id of the report transaction object.
The currency amount redeemed off the gift card.
Currency backed gift cards
The currency balance now available on the gift card.
Currency backed gift cards
The units redeemed off the gift card.
Units backed gift cards
The number of units now remaining on the gift card.
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.
The gift card has already been fully redeemed
The gift card does not have enough currency balance to redeem the specified amount
Currency backed gift cards
The remaining balance on the gift card
Currency backed gift cards
The gift card does not have enough remaining units to redeem the specified units
Units backed gift cards
The remaining units on the gift card
Units backed gift cards
The gift card cannot be redeemed because it has been voided
Undo a redemption
POST https://api.giftup.app/gift-cards/{code}/undo-redemption HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Will reverse a previous redemption
HTTP Request
POST https://api.giftup.app/gift-cards/{code}/undo-redemption
URL Parameters
The gift card code to redeem
Request body
Example request body:
{
"transactionId": "d9d587ae-fada-431c-e7af-08d885934bd4",
"reason": "An optional reason",
"metadata": {
"key": "value"
}
}
The transactionId that you'd like to undo the redemption of. This is returned when redeeming, also available in the ledger property for a Gift Card
The reason for this undo. Will appear in the gift card history log.
A key-value data store of metadata provided to us by you.
Response body
A 200 response returns JSON structured like this:
{
"transactionId": "9f3d414d-07da-4792-99d8-08a6aad1038d",
"amountReversed": 1.0000,
"unitsReversed": 0,
"alreadyReversed": false,
"remainingCredit": 49.0000,
"remainingUnits": null
}
The id of the report transaction object representing the undo request.
The currency amount added back the gift card.
Currency backed gift cards
The currency balance now available on the gift card.
Currency backed gift cards
The units added back to the gift card.
Units backed gift cards
The number of units now remaining on the gift card.
Units backed gift cards
True if this transaction has already been reversed, otherwise false
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.
The gift card has already been fully redeemed
The gift card does not have enough currency balance to redeem the specified amount
Currency backed gift cards
The remaining balance on the gift card
Currency backed gift cards
The gift card does not have enough remaining units to redeem the specified units
Units backed gift cards
The remaining units on the gift card
Units backed gift cards
The gift card cannot be redeemed because it has been voided
Transfer balances between gift cards
POST https://api.giftup.app/gift-cards/transfer-balances HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Transfers a balance form one or more source gift cards to a single destination gift card
HTTP Request
POST https://api.giftup.app/gift-cards/transfer-balances
Request body
Example request body:
{
"sourceGiftCards": [ "ABC123", "ABC456" ],
"destinationGiftCard": "ABC789",
"reason": "An optional reason",
"locationId": null,
"metadata": {
"key": "value"
}
}
A list of gift card codes. These balance(s) will be moved to the destination gift card.
The destination's gift card code. This is where the balance(s) of the source gift card(s) will be moved to.
The reason for transferring the balance(s). Will appear in the gift card history log.
The location id where this event occurred at.
A key-value data store of metadata provided to us by you.
Response body
A 200 response returns JSON structured like this:
{
"transferredCredit": 75,
"transferredUnits": null
}
The currency balance moved to the destination gift card.
Currency backed gift cards
The units moved to the destination gift card.
Units backed gift cards
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",
"priceType": "Specified",
"price": 100,
"value": 120,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"availableFrom": null,
"availableUntil": null,
"overrideValidFrom": false,
"validFrom": null,
"validFromInDays": null,
"overrideExpiry": false,
"expiresOn": null,
"expiresInMonths": 3,
"expiresInDays": 90,
"group": "Deals",
"groupId": "574852a4-0ad8-4878-91cd-9494c9cedc9a",
"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
Unique identifier for the item
The name of the item
The description of the item
The balance backing type of this item. Will be one of:
CurrencyUnits
Currency
The price type of this item. Will be one of:
SpecifiedCustom
backingType is of type Currency
Specified
The price to charge the purchaser
backingType is Currency & priceType is Specified, or backingType is Units
The currency balance to issue on the gift card when this item is purchased
Currency backed gift cards
The unit balance to issue on the gift card when this item is purchased
Units backed gift cards
The equivalent value per unit unit to store on the gift card when this item is purchased (for reporting purposes only)
Units backed gift cards
The minimum price the customer can enter when buying this custom value item
backingType is Currency and priceType is Custom
The maximum price the customer can enter when buying this custom value item
backingType is Currency and priceType is Custom
The scheduled datetime that the customer can buy this item on your checkout. In UTC.
Whether or not this item overrides the default valid from.
The datetime that gift cards created from this item will be valid from. In UTC.
The number of days after creation that gift cards created from this item will be valid from. In UTC.
Whether or not this item overrides the default expiry.
The datetime that gift cards created from this item will expire. In UTC.
The number of months after creation that gift cards created from this item will expire. In UTC.
The number of days after creation that gift cards created from this item will expire. In UTC.
The scheduled datetime that the customer can no longer buy this item on your checkout. In UTC.
The item group name this item is part of.
The item group id this item is part of.
A URL to show the purchaser so they can get more information on this item
An optional integer defining the stock level available to purchase
An optional integer defining the limit available to purchaser in a single order
Any additional terms to apply to gift card sales containing this item. Is in addition to general terms applied.
A private SKU/item code in an external system. Will be added to gift cards sold containing this item.
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",
"priceType": "Specified",
"price": 100,
"value": 120,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"availableFrom": "2020-06-10T15:02:17.786Z",
"availableUntil": null,
"group": null,
"groupId": "574852a4-0ad8-4878-91cd-9494c9cedc9a",
"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 with the item object in the response body
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
// …all other item properties…
}
Create a new item for sale.
HTTP Request
POST https://api.giftup.app/items
Request body
See item object
Update an item
Note, PATCH operations must have the Content-Type header set to
application/json-patch+json
PATCH https://api.giftup.app/items/{id} HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json-patch+json
Accept: application/json
Update the properties of an item. This endpoint supports the standard JSON patch definition. Accepts an list of patch operations.
HTTP Request
PATCH https://api.giftup.app/items/{id}
URL Parameters
The id of the item to update
Update item paths
[
// change the name of an item
{
"op": "replace",
"path": "/name",
"value": "All you can eat steak"
},
// change the price of an item
{
"op": "replace",
"path": "/price",
"value": 99.99
},
// add a code to end of the codes collection
{
"op": "add",
"path": "/codes/-",
"value": "BCA987"
}
]
You can manipulate the
codescollection using commandsaddandremovecombined with the position you want to add or remove from. When adding, the item will be added before the item in the specified index.To add to the end of the collection, the index position is specified as a
-e.g./codes/-. To add to beginning use0e.g./codes/0
[
{
"op": "add",
"path": "/codes/0",
"value": "BCA987"
},
{
"op": "add",
"path": "/codes/-",
"value": "BCA123"
},
{
"op": "remove",
"path": "/codes/1",
"value": "23723"
}
]
Duplicate codes specified when updating, will be de-duplicated on the way through.
If a code is included that is already assigned to a different item, or has been used in a gift card already. You'll receive a 400 error.
The name of the item
The description of the item
Any additional terms to apply to gift card sales containing this item. Is in addition to general terms applied.
The price to charge the purchaser
The currency balance to issue on the gift card when this item is purchased
A URL to show the purchaser so they can get more information on this item
A private SKU/item code in an external system. Will be added to gift cards sold containing this item.
A list of strings of pre-generated codes you would like us to issue when we sell this item
An integer defining the stock level available to purchase
An integer defining the limit available to purchaser in a single order
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",
"priceType": "Specified",
"price": 100,
"value": 120,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"availableFrom": "2020-06-10T15:02:17.786Z",
"availableUntil": null,
"group": "Deals",
"groupId": "574852a4-0ad8-4878-91cd-9494c9cedc9a",
"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
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
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",
"priceType": "Specified",
"price": 100,
"value": 120,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"availableFrom": "2020-06-10T15:02:17.786Z",
"availableUntil": "2023-12-31T23:59:59.999Z",
"group": "Deals",
"groupId": "574852a4-0ad8-4878-91cd-9494c9cedc9a",
"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",
"priceType": "Custom",
"price": null,
"value": null,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": 50,
"maximumPrice": null,
"availableFrom": null,
"availableUntil": null,
"overrideExpiry": false,
"expiresOn": null,
"expiresInMonths": 12,
"expiresInDays": null,
"overrideValidFrom": false,
"validFrom": null,
"validFromInDays": 3,
"group": "",
"detailsURL": "",
"stockLevel": null,
"codes": [],
"perOrderLimit": null,
"additionalTerms": "",
"sku": ""
}
]
Get all items as a list of item objects. You can optionally provide filters via the URL parameters below.
HTTP Request
GET https://api.giftup.app/items
URL Parameters
Include only items in this group
Item groups
An item group is a container for the items that appears in your Gift Up! checkout.
The item group object
Example item:
{
"id": "18a7318d-fbfd-4473-be84-fb13d33d52aa",
"name": "Fixed value gift cards",
"description": "Choose from the following fixed value gift cards, which can be used in any of our restaurants",
"sortOrder": 0,
"autoExpand": false
}
Properties
Unique identifier for the group
The name of the group
The description of the group
The sort order for how the groups appear in the checkout (ascending)
Whether to expand the items by default in this group on the checkout
Create a new item group
POST https://api.giftup.app/groups HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json
{
"name": "Fixed value gift cards",
"description": "Choose from the following fixed value gift cards, which can be used in any of our restaurants",
"sortOrder": 0,
"autoExpand": false
}
The above command returns a 200 response when the item group has been created
Create a new item group.
HTTP Request
POST https://api.giftup.app/groups
Request body
Update an item group
Note, PATCH operations must have the Content-Type header set to
application/json-patch+json
PATCH https://api.giftup.app/groups/{id} HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json-patch+json
Accept: application/json
Update the properties of an item group. This endpoint supports the standard JSON patch definition. Accepts an list of patch operations.
HTTP Request
PATCH https://api.giftup.app/groups/{id}
URL Parameters
The id of the item group to update
Update item group paths
[
// change the name of an item group
{
"op": "replace",
"path": "/name",
"value": "All you can eat steak"
},
// change the description of an item group
{
"op": "replace",
"path": "/description",
"value": "A new description"
},
// change the autoExpand property of an item group
{
"op": "replace",
"path": "/autoExpand",
"value": true
}
]
The name of the item group
The description of the item group
Tthe autoExpand property of an item group
Get an item group by id
GET https://api.giftup.app/groups/{id} HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
The above command returns a response body like this:
{
"id": "18a7318d-fbfd-4473-be84-fb13d33d52aa",
"name": "Fixed value gift cards",
"description": "Choose from the following fixed value gift cards, which can be used in any of our restaurants",
"sortOrder": 0,
"autoExpand": false
}
Returns the itemgroup object in the response body.
HTTP Request
GET https://api.giftup.app/groups/{id}
URL Parameters
The id of the item group to retrieve
Delete an item group
DELETE https://api.giftup.app/groups/{id} HTTP/2.0
Authorization: Bearer {{apikey}}
The above command returns a 200 response when the item group has been deleted
Delete an item group by id.
HTTP Request
DELETE https://api.giftup.app/groups/{id}
URL Parameters
The id of the item group to delete. Will return a BadRequest response if there are items in the item group.
List all item groups
GET https://api.giftup.app/groups HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
The above command returns a response body like this:
[
{
"id": "18a7318d-fbfd-4473-be84-fb13d33d52aa",
"name": "Fixed value gift cards",
"description": "Choose from the following fixed value gift cards, which can be used in any of our restaurants",
"sortOrder": 0,
"autoExpand": false
},
{
"id": "46effd24-ef9d-4a32-80dd-90c11a9a8010",
"name": "Custom value gift cards",
"description": "Choose a value instead, which can be used in any of our restaurants",
"sortOrder": 1,
"autoExpand": true
}
]
Get all item groups as a list of item group objects.
HTTP Request
GET https://api.giftup.app/groups
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,
"enablePayPal": false,
"enableKlarna": false,
"enableAffirm": false,
"enableAfterpayClearpay": false,
"enableFpx": false,
"enableBlik": false,
"enableCashApp": false,
"enableGrabPay": false,
"enablePayNow": false,
"enablePromptPay": false,
"enablePix": false,
"enableZip": false,
"livePublicKey": "pk_live_************",
"liveSecretKey": "sk_live_************",
"testPublicKey": "pk_test_************",
"testSecretKey": "sk_test_************",
"connectAccountId": "",
"applicationFeePercentage": 0,
"applicationFeeFixed": 0,
"statementDescriptor": "",
"reviewAction": "Continue"
}
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
Your Stripe live publishable API key
Your Stripe live secret API key
Your Stripe test publishable API key
Your Stripe test secret API key
The Stripe account id of who to pay when an order is placed for a gift card
The application fee percentage to pass to you, the connect platform, when an order is placed for a gift card
The fixed application fee to pass to you, the connect platform, when an order is placed for a gift card
Set to true to enable Ideal payments in your Gift Up! checkout
Set to true to enable Bancontact payments in your Gift Up! checkout
Set to true to enable Giropay payments in your Gift Up! checkout
Set to true to enable EPS payments in your Gift Up! checkout
Set to true to enable Multibanco payments in your Gift Up! checkout
Set to true to enable P24 payments in your Gift Up! checkout
Set to true to enable WeChat payments in your Gift Up! checkout
Set to true to enable Alipay payments in your Gift Up! checkout
Set to true to enable PayPal payments in your Gift Up! checkout
Set to true to enable Klarna payments in your Gift Up! checkout
Set to true to enable Affirm payments in your Gift Up! checkout
Set to true to enable Afterpay/Clearpay payments in your Gift Up! checkout
Set to true to enable FPX payments in your Gift Up! checkout
Set to true to enable BLIK payments in your Gift Up! checkout
Set to true to enable Cash App payments in your Gift Up! checkout
Set to true to enable GrabPay payments in your Gift Up! checkout
Set to true to enable PayNow payments in your Gift Up! checkout
Set to true to enable PromptPay payments in your Gift Up! checkout
Set to true to enable Pix payments in your Gift Up! checkout
Set to true to enable Zip payments in your Gift Up! checkout
Set to true to enable payments in your Gift Up! checkout
This will appear on your customer's card statement.
Either 'Continue' or 'WaitForApproval'
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,
"statementDescriptor": "",
"reviewAction": "Continue"
}
Gets the settings of your Stripe gateway connection.
HTTP Request
GET https://api.giftup.app/integrations/stripe/connection
Response body
Locations
An location represent a physical location where your gift cards are sold and/or redeemed. They are used for reporting purposes only.
The location object
Example item:
{
"id": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"name": "Main store"
}
Properties
Unique identifier for the location
The name of the location
List all locations
GET https://api.giftup.app/locations HTTP/2.0
Authorization: Bearer {{apikey}}
The above command returns a response body like this:
[
{
"id": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"name": "WA store"
},
{
"id": "90deec60-2685-4640-a3c8-e468c97d453f",
"name": "NY store"
}
]
List of all locations in your Gift Up! account
HTTP Request
GET https://api.giftup.app/locations
Response body
See location 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",
"orderNumber": "10152",
"createdOn": "2020-06-08T11:16:48.151Z",
"selectedRecipient": "SomeoneElse",
"purchaserEmail": "john@example.com",
"purchaserName": "John Doe",
"currency": "USD",
"revenue": 100,
"tip": 0,
"serviceFee": 0,
"discount": 0,
"shippingFee": 0,
"referrer": "",
"promotions": [
{
"promotionId": "60ef8672-aad8-4585-873c-b6944c2bb29f",
"name": "Promotion name",
"code": "BLACKFRIDAYSALE"
}
],
"customFields": [
{
"label": "Telephone",
"value": "01234 567780"
}
],
"salesTaxes": [
{
"label": "GST",
"amount": 15,
"type": "inclusive"
}
],
"notes": [
{
"id": "09666ea2-403b-4ae0-9566-729c702e8970",
"content": "My note",
"createdOn": "2020-06-08T11:18:48.151Z",
"username": "Staff name"
}
],
"metadata": {
"a key": "a value",
"another key": "another value"
},
"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/…",
}
},
"payment": {
"provider": "Stripe",
"transactionId": "ch_1HoUlaLci192ejy9tlDvIPT0"
}
}
Properties
Unique internal identifier for the order
A presentable reference number for the order
When the order was created. In UTC.
This reflects the choice made by the customer on the checkout. Either SomeoneElse, Purchaser or None
The email address of the purchaser
The name of the purchaser
The currency the order was taken in
The revenue taken for this order
The tip taken for this order
The service fee added to this order
The total discount applied to this order
The shipping fee added to this order
A string provided that reflects the origin of the order, for example a sales rep's name, or a website url
A list of promotions applied to this order
A list of custom fields collecting during this order
A list of sales taxes for this order
A list of notes added to this order
A list of key/values attached to this order
A list of links for downloading the gift card(s) in this order
An object representing payment details for this order
Order promotions
The id for the promotion
The name of the promotion
The code used to apply this promotion, if a promotion.code was needed to activate the promotion during checkout
Order custom fields
The label to describe the custom field
The value of the custom field. The type will depend on the custom field, it could be string, int or boolean
Order sales taxes
The label to describe the sales tax (e.g VAT/GST/Sales Tax etc...)
The amount collected for this sales tax
Whether the sales tax is inclusive or exclusive
Order notes
The note's content
The date/time, in UTC, when the note was created
The name of the user who added the note
Order download links
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
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
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
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
Order payment
A string representing the name of the payment provider used for this order. For example, Stripe, Square or PayPal.
The transaction Id returned to us from the payment provider when we took payment for this order.
Order metadata
A key-value data store of metadata provided to us by you.
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:
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orderNumber": "10152",
"createdOn": "2020-06-08T11:16:48.151Z",
"selectedRecipient": "SomeoneElse",
"purchaserEmail": "john@example.com",
"purchaserName": "John Doe",
"tip": 0,
"serviceFee": 0,
"discount": 20,
"referrer": "",
"revenue": 80,
"promotions": [
{
"promotionId": "60ef8672-aad8-4585-873c-b6944c2bb29f",
"name": "Promotion name",
"code": "BLACKFRIDAYSALE"
}
],
"customFields": [
{
"label": "Telephone",
"value": "01234 567780"
}
],
"salesTaxes": [
{
"label": "GST",
"amount": 15,
"type": "inclusive"
}
],
"notes": [
{
"id": "09666ea2-403b-4ae0-9566-729c702e8970",
"content": "My note",
"createdOn": "2020-06-08T11:18:48.151Z",
"username": "Staff name"
}
],
"metadata": {
"a key": "a value",
"another key": "another value"
},
"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
The id of the order to retrieve
Update an order
Note, PATCH operations must have the Content-Type header set to
application/json-patch+json
PATCH https://api.giftup.app/orders/{id} HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json-patch+json
Accept: application/json
Update the properties for an order. This endpoint supports the standard JSON patch definition. Accepts an list of patch operations.
HTTP Request
PATCH https://api.giftup.app/orders/{id}
URL Parameters
Update order paths
[
{
"op": "replace",
"path": "/purchasername",
"value": "Joe Bloggs"
},
{
"op": "replace",
"path": "/purchaseremail",
"value": "joe@bloggs.com"
},
]
The purchaser name of the order
The purchaser email address
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",
"tip": 0,
"serviceFee": 0,
"discount": 0,
"referrer": "Backoffice",
"revenue": 100,
"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,
"validFrom": null,
"validFromInDays": null,
"overrideValidFrom": false,
"sku": "MY-SKU",
"terms": "Some specific terms & conditions",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
],
"recipientDetails": {
"recipientName": "Valerie",
"recipientEmail": "val@example.com",
"message": "Happy birthday!",
"scheduledFor": "2020-06-08T11:31:31.758Z"
},
"customFields": [
{
"label": "Telephone",
"value": "01234 567780",
"showOnGiftCard": false,
"showOnRedeemApp": false
},
{
"label": "IsMember",
"value": true,
"showOnGiftCard": true,
"showOnRedeemApp": true
}
],
"salesTaxes": [
{
"label": "My state sales tax",
"amount": 15,
"type": "inclusive"
}
],
"metadata": {
"a key": "a value",
"another key": "another value"
}
}
The above command returns a 201 response when the order has been created:
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orderNumber": "10152",
"createdOn": "2020-06-08T11:16:48.151Z",
"selectedRecipient": "SomeoneElse",
"purchaserEmail": "john@example.com",
"purchaserName": "John Doe",
"tip": 0,
"serviceFee": 0,
"discount": 0,
"referrer": "Backoffice",
"revenue": 100,
"promotions": [],
"customFields": [
{
"label": "Telephone",
"value": "01234 567780"
},
{
"label": "IsMember",
"value": true
}
],
"salesTaxes": [
{
"label": "My state sales tax",
"amount": 15,
"type": "Inclusive"
}
],
"notes": [],
"metadata": {
"a key": "a value",
"another key": "another value"
},
"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
When the order was created. In UTC.
If true, Gift Up! will not send any emails for this order.
The email address of the purchaser
The name of the purchaser
The tip taken for this order
The service fee added to this order
The total discount applied to this order
The revenue taken for this order
The details for the gift cards to create.
The details for the recipient of the gift card.
A list of sales taxes for this order
Order item details
This is the definition for a gift card within the Order
Define how many of this gift card to create.
Reference an item id
quantity, and conditionally value and price, in this object are ignored
The item name, which appears as the main title on the gift card
The item description, which appears as the description on the gift card, underneath the name
The code to assign to the gift card. Must be unique.
The balance backing type of this gift card. Will be one of:
CurrencyUnits
The price charged for this gift card
id is not specified, or for Currency backed gift cards
The initial currency balance assigned to this gift card
id is not specified, or for Currency backed gift cards with Custom price types
The initial unit balance assigned to this gift card
id is not specified, or for Units backed gift cards
The equivalent value per unit unit to store on the gift card when this item is purchased (for reporting purposes only)
id is not specified, or for Units backed gift cards
The date this gift card expires. In UTC.
overrideExpiry to be set to true
Number of months from now, that this gift card expires
overrideExpiry to be set to true
Number of days from now, that this gift card expires
overrideExpiry to be set to true
Set to true to use expiresOn or expiresInMonths or expiresInDays
The date this gift card is valid from. In UTC.
overrideValidFrom to be set to true
Number of days from now, that this gift card is valid from
overrideValidFrom to be set to true
Set to true to use validFrom or validFromInDays
A private identifier for you to reference. We will include this in API calls to retrieve the gift card, and in webhooks.
Any terms & conditions you would like associated with this gift card. If a null value is passed, Gift Up will assign your default terms & conditions to the gift card.
Order recipient details
Provide this if you want a gift card to be emailed, otherwise no gift card email will be sent
The name of the recipient of the gift card
The recipient's email address
The message to the recipient
The datetime to send this gift card. In UTC.
The method of fulfilment for this order. Needs to be one of:
EmailPostNone
The shipping address definition for this order. Required if fulfilmentMethod is Post
The shipping option definition for this order. Required if fulfilmentMethod is Post
Order recipient shipping address details
The first line of the address
The second line of the address
The city line of the address
The state line of the address
The postal/zip code line of the address
The 3 character ISO country code line of this address
Order recipient shipping option details
Reference a Shipping Option id
The name of the shipping option (e.g Overnight, or 3-5 days)
id is not specified
The price of the shipping option
id is not specified
Order metadata
A key-value data store of metadata provided to us by you.
Add a note to an order
GET https://api.giftup.app/orders/{id}/notes HTTP/2.0
Authorization: Bearer {{apikey}}
Accepts: application/json
{
"content": "My new note"
}
The above command returns a 200 response if successful
Add a note to an order.
HTTP Request
POST https://api.giftup.app/orders/{id}/notes
URL Parameters
The id of the order to add a note to
Add a note properties
The content of the note. Supports line breaks.
Mark an order as posted
GET https://api.giftup.app/orders/{id}/post HTTP/2.0
Authorization: Bearer {{apikey}}
Accepts: application/json
{
"codes": [
{ "oldCode": "ABC123", "newCode": "GU-STEAK-76664" }
]
}
The above command returns a 200 response if successful
Mark a postal order as posted. Allows provisional codes to be updated.
HTTP Request
POST https://api.giftup.app/orders/{id}/post
URL Parameters
The id of the order to retrieve
Mark as posted properties
A collection of codes to update. Must include all codes in the order.
Order posted codes
The new code. Must be set.
The new code. Must be set. If you don't want to change code, make this equal oldCode.
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
The email address of the owner & main account admin
The full name of the owner & main account admin
The name of the business
The full postal address of the business
The currency code for the Gift Up! account
The country code of the account
The URL of the business' website
The IANA time zone of where the business is located
Set to true to return a new API key against this Gift Up! account
Set to true to take responsibility for billing on behalf of this Gift Up! account
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
Promotions
A promotion allows discounts to be applied on the Gift Up! checkout
The promotion object
Example item:
{
"id": "2fb047be-0bf6-496d-9b12-08d885974d50",
"name": "Free Gift Card",
"noBenefit": false,
"publishedOn": "2020-11-10T16:40:15.5923545",
"stoppedOn": null,
"benefits": {
"additionalItem": {
"item": {
"id": "192b3865-738b-450f-f9f2-08d84e8c209a",
"name": "All you can eat steak",
"backingType": "Currency",
"priceType": "Specified",
"price": 75.5000,
"value": 50.0000,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"group": null,
"description": null,
"detailsURL": null,
"stockLevel": null,
"codes": [
"ABC123",
"BCA876",
"LSK983"
],
"perOrderLimit": null,
"additionalTerms": null,
"sku": null
},
"quantity": null,
"stackThreshold": null,
"percentageDiscount": null,
"fixedDiscount": null,
"fixedPrice": null,
"receiver": "Purchaser"
},
"orderPercentageDiscount": 0.0000,
"giftCardFixedDiscount": 0.0000,
"orderFixedDiscount": null,
"giftCardExtraCredit": 0.0000,
"giftCardExtraCreditPercentage": 0.0000,
"giftCardExtraUnits": 0,
"issueAdditionalItem": true
},
"usage": {
"timesUsed": 51,
"timesUsedInGiftCards": 102,
"orderRevenue": 5983.8000,
"giftCardCurrencyBalanceIssued": 5412.0000,
"giftCardUnitBalanceIssued": 24
},
"limitations": {
"beginsOn": null,
"endsOn": null,
"limitNumberOfUses": null,
"limitNumberOfGiftCardUses": null
},
"triggers": {
"items": [
{
"id": "192b3865-738b-450f-f9f2-08d84e8c209a",
"name": "All you can eat steak",
"backingType": "Currency",
"priceType": "Specified",
"price": 75.5000,
"value": 50.0000,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"group": null,
"description": null,
"detailsURL": null,
"stockLevel": null,
"codes": [
"ABC123",
"BCA876",
"LSK983"
],
"perOrderLimit": null,
"additionalTerms": null,
"sku": null
}
],
"groups": [
"Group of Things"
],
"targetSpecificItems": true,
"minimumSpend": 10.0000,
"maximumSpend": 500.000,
"minimumQuantity": 2,
"maximumQuantity": 10,
"code": "FREEONE"
}
}
Properties
Unique identifier for the promotion
The name of the promotion
True, if the promotion offers no benefits, and is used for tracking only
The date that the promotion was published
The date that the promotion was manually stopped
Describes the benefits granted by the promotion
Tracks the usage of the promotion
Describes the conditions that will end the promotion automatically
Describes the conditions that need to be met in order for the promotion to be enabled for an order
Promotion Benefits Object
Defines an additional item available with the promotion
issueAdditionalItem is true
See additional item definition
The discount percentage to be applied to the order
The fixed discount to apply to each gift card in the order
The fixed discount to apply to the whole order
Extra currency balance to be applied to gift cards in the the order
Extra currency balance as a percentage to be applied to gift cards in the order
Extra units balance to be applied to gift cards in the order
True is an additional item is to be available in the order
Promotion Usage Object
The number of orders the promotion has been used in
The number of gift cards the promotion has been used for
targetSpecificItems is true
The order revenue taken for orders using the promotion
The amount of currency balance issued for gift cards bought using the promotion
The amount of units balance issued for gift cards bought using the promotion
Promotion Limitations Object
The promotion will automatically begin on this date
The promotion will automatically end on this date
The promotion will end once usage.timesUsed reaches this number
The promotion will end once usage.timesUsedInGiftCards reaches this number
Promotion Triggers Object
A list of item objects that the promotion applies to
targetSpecificItems is true
A list of group names that this promotion applies to
targetSpecificItems is true
True, if the promotion offers no benefits, and is used for tracking only
The minimum order spend before the promotion is triggered
The maximum order spend allowed for the promotion
The minimum number of gift cards bought for the promotion to apply
The maximum number of gift cards bought for the promotion to apply
A promo code that is required to trigger the promotion
Promotion Additional Item Object
An item object that defines the item being made available
The number of additional items
Allows for giving away x gift cards per stackThreshold
The percentage discount applied to the additional item
The fixed discount applied to the additional item
The fixed price of the additional item
Who the additional item is sent to
PurchaserRecipient
List all promotions
GET https://api.giftup.app/promotions HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
The above request returns a response body like this:
[
{
"id": "2fb047be-0bf6-496d-9b12-08d885974d50",
"name": "Free Gift Card",
"noBenefit": false,
"publishedOn": "2020-11-10T16:40:15.5923545",
"stoppedOn": null,
"benefits": {
"additionalItem": {
"item": {
"id": "192b3865-738b-450f-f9f2-08d84e8c209a",
"name": "All you can eat steak",
"backingType": "Currency",
"priceType": "Specified",
"price": 75.5000,
"value": 50.0000,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"group": null,
"description": null,
"detailsURL": null,
"stockLevel": null,
"codes": [
"ABC123",
"BCA876",
"LSK983"
],
"perOrderLimit": null,
"additionalTerms": null,
"sku": null
},
"quantity": null,
"stackThreshold": null,
"percentageDiscount": null,
"fixedDiscount": null,
"fixedPrice": null,
"receiver": "Purchaser"
},
"orderPercentageDiscount": 0.0000,
"giftCardFixedDiscount": 0.0000,
"orderFixedDiscount": null,
"giftCardExtraCredit": 0.0000,
"giftCardExtraCreditPercentage": 0.0000,
"giftCardExtraUnits": 0,
"issueAdditionalItem": true
},
"usage": {
"timesUsed": 51,
"timesUsedInGiftCards": 102,
"orderRevenue": 5983.8000,
"giftCardCurrencyBalanceIssued": 5412.0000,
"giftCardUnitBalanceIssued": 24
},
"limitations": {
"beginsOn": null,
"endsOn": null,
"limitNumberOfUses": null,
"limitNumberOfGiftCardUses": null
},
"triggers": {
"items": [
{
"id": "192b3865-738b-450f-f9f2-08d84e8c209a",
"name": "All you can eat steak",
"backingType": "Currency",
"priceType": "Specified",
"price": 75.5000,
"value": 50.0000,
"units": null,
"equivalentValuePerUnit": null,
"minimumPrice": null,
"maximumPrice": null,
"group": null,
"description": null,
"detailsURL": null,
"stockLevel": null,
"codes": [
"ABC123",
"BCA876",
"LSK983"
],
"perOrderLimit": null,
"additionalTerms": null,
"sku": null
}
],
"groups": [
"Group of Things"
],
"targetSpecificItems": true,
"minimumSpend": 10.0000,
"maximumSpend": 500.000,
"minimumQuantity": 2,
"maximumQuantity": 10,
"code": "FREEONE"
}
},
{
"id": "9095082d-bf89-4873-d210-08d880cd4b7c",
"name": "Freebie 2",
"noBenefit": false,
"publishedOn": "2020-11-04T14:24:09.5580606",
"stoppedOn": null,
"benefits": {
"additionalItem": null,
"orderPercentageDiscount": 100.0000,
"giftCardFixedDiscount": 0.0000,
"orderFixedDiscount": 0.0000,
"giftCardExtraCredit": 0.0000,
"giftCardExtraCreditPercentage": 0.0000,
"giftCardExtraUnits": 0,
"issueAdditionalItem": false
},
"usage": {
"timesUsed": 5,
"timesUsedInGiftCards": 9,
"orderRevenue": 0.0000,
"giftCardCurrencyBalanceIssued": 511.0000,
"giftCardUnitBalanceIssued": 0
},
"limitations": {
"beginsOn": "2020-12-09T00:00:00",
"endsOn": null,
"limitNumberOfUses": null,
"limitNumberOfGiftCardUses": null
},
"triggers": {
"items": [],
"groups": [
"Group of Things"
],
"targetSpecificItems": true,
"minimumSpend": null,
"maximumSpend": null,
"minimumQuantity": null,
"maximumQuantity": null,
"code": "FREEBIE"
}
}
]
Get all promotions as a list of promotion objects.
HTTP Request
GET https://api.giftup.app/promotions
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",
"eventOccuredAtLocationId": null,
"eventType": "OrderPlaced",
"reason": "",
"referrer": "",
"metadata": {},
"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",
"eventOccuredAtLocationId": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"eventType": "GiftCardCreated",
"reason": "",
"referrer": "",
"metadata": {},
"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,
"title": "All you can eat steak!"
}
},
{
"id": "9bb226d3-f286-4347-8ff9-6503586626c5",
"eventOccuredOn": "2020-06-29T12:59:30.1465461",
"eventOccuredAtLocationId": "90deec60-2685-4640-a3c8-e468c97d453f",
"eventType": "Redeemed",
"reason": "A reason…",
"referrer": "",
"metadata": {
"key": "A value"
},
"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,
"title": "All you can eat steak!"
}
}
]
Properties
Unique identifier for the event
The datetime that this event occurred
The id of the the location where the event occurred
The type of this event
One of: OrderPlaced, GiftCardCreated, CreditAdded, Redeemed, Expired, Unexpired, Voided, Reactivated
The reason this transaction occurred (supported on CreditAdded, Redeemed and Voided events).
A string provided that reflects the origin of the event, for example a sales rep's name, or a website url
A key-value data store of metadata provided to us by you (supported on CreditAdded, Redeemed, Voided and Reactivated events)
The id of the order that this transaction belongs to.
The 3-character currency code that this transaction was transacted in.
The Gift Up! fee incurred for this transaction.
The name of the user who did this event
The email address of the who did this event
Contains financial details of the order
OrderPlaced. See transaction order details
Contains financial details of the gift card
OrderPlaced event. See transaction gift card details
Transaction Order Details
The revenue taken
The service fee charged
The tip taken
The shipping fee charged
Transaction Gift Card Details
The gift card id
The code
The currency change in value by this event
Redeemed
The unit change in value by this event
Units backed gift cards
The main title of the gift card
List report transactions
GET https://api.giftup.app/reports/transactions?eventOccurredOnOrAfter=2020-01-01&eventOccurredOnOrBefore=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",
"eventOccuredAtLocationId": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"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",
"eventOccuredAtLocationId": null,
"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 via the URL parameters below.
HTTP Request
GET https://api.giftup.app/reports/transactions
URL Parameters
A UTC datetime to include only transactions that occurred on or after this date time.
A UTC datetime to include only transactions that occurred on or before this date time.
Only return events that match this.
Only return events that were generated by this user's email address
Only return events that were generated at this location id
Only return events that match this gift card code.
The number of transactions to return
The number of transactions to skip
HTTP Response
A list of transaction objects
The total number of transactions matching the filters provided
Set to true if there are more transactions after these
Get a report transaction
GET https://api.giftup.app/reports/transactions/{id} HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
The above command returns JSON structured like this:
{
"id": "d13ee30e-0994-446c-a3b1-8db44443a441",
"eventOccuredOn": "2020-06-29T12:59:25.1465461",
"eventOccuredAtLocationId": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"eventType": "OrderPlaced",
"orderId": "ce009cf1-622b-4c31-b2a6-b53334ed6f83",
"currency": "USD",
// …all other transaction properties…
}
Get a single transaction by id.
HTTP Request
GET https://api.giftup.app/reports/transactions/{id}
URL Parameters
The id of the transaction to get
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
Url of the logo shown on the hosted checkout
A short introduction text shown above the checkout on the hosted checkout
The font to use for the checkout
Font size for the checkout, in px. i.e. 16px.
Base color for the checkout
#AABBCC or rgb(50, 100, 150) color
Control whether the checkout text will be white or black
light or dark
The text to describe an optional continue button after an order has been placed on the checkout
continueLinkUrl for button to show
A url for an optional continue button after an order has been placed on the checkout
continueLinkText for button to show
A url to redirect to after an order has been placed on the checkout.
{{orderid}}, {{currency}}, {{revenue}}, {{code}}, {{sku}}, {{name}}
Custom html that will be rendered after an order has been placed on the checkout
Whether or not to show the balance checker option on the checkout
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
Whether or not to charge a service fee
The fixed element to a service fee
serviceFeeCharged is false
The percentage element to a service fee
serviceFeeCharged is false
Enable or disable tips on the checkout
If true, the user can specify their own tip value
Specify a list of string values to override the suggested tip values.
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
You can specify either:
- 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.
- A base64 encoded string representing the image. Must start with
data:image.
Light or Dark
SomeoneElse, OnlySomeoneElse, Me or OnlyMe
["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 default email settings.
HTTP Request
GET https://api.giftup.app/settings/email
Response body
Url of the logo shown on the emails sent to customers
Where the email logo should sit
One of left, middle or right
The width in pixels of the logo
The reply-to email address for emails sent to customers
The email from 'display name' as displayed in email clients
Settings for the gift card email
Settings for the receipt email
Gift card email
The subject line for the gift card email
The headline text in the gift card email
The text to display in the introduction of the gift card email
The text to display in the footer of the gift card email
A optional label for a button in the gift card email
An optional url for a button in the gift card email
The colour for the additional button
#AABBCC or rgb(50, 100, 150) color
Settings for the receipt email
left, middle or right
Receipt email
The subject line for the receipt email
The headline text in the receipt email
The text to display in the introduction of the receipt email
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 default 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
You can specify either:
- 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.
- A base64 encoded string representing the image. Must start with
data:image.
left, middle or right
left, middle or right
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,
"expiryInDays": null,
"validFromInDays": null,
"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
The default description to display on gift cards. Can be overridden when creating an item
The format of the barcode
Code128, Code39, DataMatrix, PDF417, QR
Number of months after purchase that a gift card expires
Number of days after purchase that a gift card expires
Number of days after purchase that a gift card is valid from
Show or hide the issued on date when rendering a gift card
Show or hide the balance when rendering a gift card
Show or hide the barcode when rendering a gift card
General term & conditions shared across all gift cards
The format used to generate gift card codes
@ = Random letter
# = Random number
* = Random letter/number
All other characters kept
@, # 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
PDF417, Code128, Code39, DataMatrix, QR
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
The id of the artwork
The URL of the artwork
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
You can specify either:
- 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.
- A base64 encoded string representing the image. Must start with
data:image.
If set to true, we will delete all existing artwork before replacing with this
The id of the artwork to replace
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
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
Whether fulfilment by email is enabled
Whether fulfilment by post is enabled
Whether the customer can enter a personal message when choosing a postal gift card
enableSelfFulfilledPostal is enabled
An array of shipping options presented to the purchaser
enableSelfFulfilledPostal is enabled
Shipping option
The shipping option unique identifier
The shipping option name
The price to charge the purchaser for shipping
The ascending sort order of the shipping options
The fulfilment type. Can be one of the following: Post Collect for postal or collection
Which countries are allowed for this shipping option. If empty, all countries are allowed.
Shipping option country
The country name
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,
"hideLogInRedeemApp": false,
"expiredGiftCardRedemptionDisabled": false,
"redeemLocationRestrictionEnforced": false,
"locations": [
{
"id": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"name": "Main store"
}
]
}
Properties
Unique identifier for the user
The name of the user
The email address of the user
The uploaded image of the user
The redeem pin number for the user
Set to true if the user is a dashboard admin
Set to true if the user has confirmed their email address
Set to true if the user is hidden in the redeem app
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)
Set to true if the user cannot view a gift card's history log in the redeem app
Set to true if the user cannot redeem an expired (or not yet valid) gift card
Set to true if the user cannot redeem a gift card not issued for their location(s)
A list of all locations (if any) that this user can operate in
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",
"avatarUrl": "https://…",
"pin": "1234",
"isAdministrator": true,
"hiddenInRedeemApp": false,
"disableSearchInRedeemApp": false,
"hideLogInRedeemApp": false,
"expiredGiftCardRedemptionDisabled": false,
"redeemLocationRestrictionEnforced": false
}
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,
"hideLogInRedeemApp": false,
"expiredGiftCardRedemptionDisabled": false,
"redeemLocationRestrictionEnforced": false,
"locations": [
{
"id": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"name": "Main store"
}
]
}
Invite a user to access your Gift Up! account
HTTP Request
POST https://api.giftup.app/users
Request body
See user object
Response 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,
"hideLogInRedeemApp": false,
"expiredGiftCardRedemptionDisabled": false,
"redeemLocationRestrictionEnforced": false,
"locations": [
{
"id": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"name": "Main store"
}
]
},
{
"id": "695df468-6804-4fa3-996a-22919ceb0d30",
"name": "Jenny",
"email": "jenny@juicyjoes.com",
"avatarUrl": "",
"pin": "0963",
"isAdministrator": false,
"emailConfirmed": true,
"hiddenInRedeemApp": false,
"disableSearchInRedeemApp": true,
"hideLogInRedeemApp": false,
"expiredGiftCardRedemptionDisabled": false,
"redeemLocationRestrictionEnforced": false,
"locations": []
}
]
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,
"hideLogInRedeemApp": false,
"expiredGiftCardRedemptionDisabled": false,
"redeemLocationRestrictionEnforced": false,
"locations": [
{
"id": "412f6381-02cc-4866-91f5-428a6b7db3b0",
"name": "Main store"
}
]
}
Get a user by id
HTTP Request
GET https://api.giftup.app/users/{id}
URL Parameters
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
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
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
The user's name
The pin for use with the Gift Up! redeem app
The email address of the user
Change the role of the user
administrator
Change the avatar of the user
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.
Retry logic
When we send a webhook to you, if we receive a non-200 class response code from your endpoint we will retry again after 1 second, and then back off up to retrying every 6 hours, for a maximum of 7 days before eventually giving up.
You can view the logs for all webhooks in the Gift Up! dashboard.
Payload definitions
Common properties
Standard fields included in all outbound webhook payloads:
{
// …other webhook properties…
"correlationId": "af3ae001-7e01-4490-94b8-b256195b3444",
"companyId": "44e3f564-7337-4f63-aa2f-8c5ffabe539c",
"eventType": "GiftCardCreated"
}
The payload fired to your targetUrl will always include the following extra properties:
A unique identifier to trace the event fired by Gift Up internally
The Gift Up account identifier
The event type
OrderCreated, GiftCardCreated, GiftCardRedeemed or GiftCardUpdated
GiftCardCreated webhook payload
Example
GiftCardCreatedwebhook 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 extra properties:
We prettify the initial value as a currency string. i.e. "$99.99"
We prettify the remaining value as a currency string. i.e. "$99.99"
GiftCardRedeemed webhook payload
Example
GiftCardRedeemedwebhook 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 extra properties:
The name of the user who redeemed the gift card
The email address of the user who redeemed the gift card
The currency balance redeemed off the gift card
Currency backed gift cards
The unit balance redeemed off the gift card
Units backed gift cards
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
OrderCreatedwebhook 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:
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=.
- Split the header using the
,character, this will separate the timestamp from the signature. Split each element on=, to give you key and value. - Prepare the signature to be compared. This is achieved by appending the timestamp to the end of the payload string.
- Compute a HMAC with the SHA256 hash function, using the secret you provided for the webhook.
- 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
Unique identifier for the webhook
The delivery URL for the webhook
The event type for this webhook. Can be one of the following: OrderCreated GiftCardCreated GiftCardUpdated GiftCardRedeemed
If set to true, then the webhook will only fire on test data events.
Add a webhook
POST https://api.giftup.app/hooks/{event}/subscribe 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}/subscribe
URL Parameters
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
The delivery URL for the webhook
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.
A boolean to indicate whether to fire this webhook for live or test data.
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
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
The id of the webhook to delete