NAV
JSON

Introduction

Base URL:

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

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

Authentication

To authorize, use this code:

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

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

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

Authorization: Bearer {{apikey}}

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

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

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:

Where:

Testing the API

To enable test mode, add the following HTTP header:

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

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

x-giftup-testmode: true

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

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


id guid
Unique identifier for the company. This is also referred to as a site id when installing a checkout.


name string
The name of the company


onboardingCompleted boolean
Have all onboarding steps been completed


canShowCheckout boolean
Have enough onboarding steps been completed to allow the checkout to render.


isCheckoutLive string
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:

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


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

An expired gift card can still be redeemed. Check hasExpired or expiredOn if this is important to you. An not yet valid gift card can still be redeemed. Check notYetValid or validFrom if this is important to you.


hasExpired boolean
Whether or not this gift card has expired, based on its expiresOn date


notYetValid boolean
Whether or not this gift card is valid, based on its validFrom date


isVoided boolean
Whether or not this gift card has been voided


code string
The gift card code


title string
The main title of the gift card


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


message string
The message included with the gift card


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


recipientName string
The recipient name on the gift card


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


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


remainingValue decimal
The currency balance remaining on this gift card

Only for Currency backed gift cards


remainingUnits integer
The units balance remaining on this gift card

Only for Units backed gift cards


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

Only for Currency backed gift cards


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

Only for Units backed gift cards


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

Only for Units backed gift cards


terms string
The terms captured when this gift card was created


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


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


expiresOn datetime
The datetime that this gift card expires

Can be null


validFrom datetime
The datetime that this gift card is valid from

Can be null


voidedOn datetime
The datetime that this gift card was voided

Can be null


order object
The order this gift card belongs to

See order definition


postalFulfilment object
Details of the postal fulfilment.

See postal fulfilment definition


emailFulfilment object
Details of the email fulfilment

See email fulfilment definition


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

See download links definition


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

See ledger entry definition

Gift card postal fulfilment


address object
The address to send this gift card to

See postal address definition


shippingOptionName string
The name of the shipping option selected.

Gift card postal address


name string
The name of the recipient


address1 string
The first line of the address


address2 string
The second line of the address


city string
The city


state string
The state


postalCode string
The postal/zip code


countryCode string
The country code

3-character ISO country code

Gift card email fulfilment


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


scheduledFor datetime
The UTC datetime that the email is requested to be sent

Will be null for immediate delivery of email

Gift card ledger entry


eventOccuredOn datetime
The datetime this event occurred


eventOccuredAtLocationId guid
The id of the the location where the event occurred


value decimal
The currency value change introduced by this event

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


units integer
The units change introduced by this event

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


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


whoName string
The name of the user who triggered this event


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


transactionId guid
The id of the report transaction object.


artworkUrl string
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


imageUrl string
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


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


appleWalletUrl string
A link that can be presented to users which will generate a downloadable gift card for Apple device wallets


googleWalletUrl string
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


code string
The gift card code

Response body


Returns a gift card object

Update a gift card

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

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

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

HTTP Request


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

URL Parameters


code string
The gift card code

Update gift card paths


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

/title string
The main title of a gift card


/expireson datetime
The gift card expiry date


/validfrom datetime
The gift card valid from date


/receipientemail string
The email address of the recipient


/recipientname string
The name of the recipient


/sku string
The SKU for this gift card


/terms string
The gift card terms

List gift cards

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

The above command returns JSON structured like this:

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

Get a list of gift cards. You can optionally provide filters via the URL parameters below.

HTTP Request


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

URL Parameters


status string
Include only gift cards in this state

If specified, must be one of active, expired, redeemed or voided


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


updatedOnOrAfter datetime
A UTC datetime to include only gift cards updated on or after this date time


orderId guid
Include only gift cards for this particular order id


sku string
Include only gift cards with this private SKU value


recipientEmail string
Include only gift cards with this recipient email address


purchaserEmail string
Include only gift cards with this purchaser email address


paymentTransactionId string
Include only gift cards where the transaction id returned by your payment provider matches this value


limit integer
The number of gift cards to return

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


offset integer
The number of gift cards to skip

0

HTTP Response


giftCards list
A list of gift card objects


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


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

Reactivate a gift card

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

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

HTTP Request


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

URL Parameters


code string
The gift card code to reactivate

Request body


Example request body:

{
  "reason": "An optional reason for reactivating this gift card",
  "locationId": null,
  "metadata": {
    "key": "value"
  }
}

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


locationId guid
The location id where this event occurred at.


metadata object
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.


isRedeemed boolean
A redeemed gift card cannot be reactivated


isAlreadyActive boolean
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


code string
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"
  }
}

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


locationId guid
The location id where this event occurred at.


metadata object
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.


isRedeemed boolean
A redeemed gift card cannot be voided


isAlreadyVoided boolean
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


code string
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"
  }
}

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

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


units integer
The units to add to the gift card.

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


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


locationId guid
The location id where this event occurred at.


metadata object
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
}

transactionId string
The id of the report transaction object.


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

Only for Currency backed gift cards


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

Only for Units backed gift cards

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

{
  "isVoided": true
}

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


isVoided boolean
You cannot top up a voided gift card

Redeem a gift card

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

Will deduct the specified amount of balance from a gift card

HTTP Request


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

URL Parameters


code string
The gift card code to redeem

Request body


Example request body:

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

amount decimal
The currency amount to redeem against this gift card

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


units integer
The units to redeem off this gift card

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


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


locationId guid
The location id where this event occurred at.


metadata object
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
}

transactionId string
The id of the report transaction object.


redeemedAmount decimal
The currency amount redeemed off the gift card.

Only for Currency backed gift cards


remainingCredit decimal
The amount now available on the gift card.

Only for Currency backed gift cards


redeemedUnits integer
The units redeemed off the gift card.

Only for Units backed gift cards


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

Only for Units backed gift cards

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

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

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


wasAlreadyRedeemed boolean
The gift card has already been fully redeemed


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

Only for Currency backed gift cards


remainingCredit decimal
The remaining balance on the gift card

Only for Currency backed gift cards


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

Only for Units backed gift cards


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

Only for Units backed gift cards


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

Redeem a gift card in full

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

Will deduct all remaining balance from a gift card

HTTP Request


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

URL Parameters


code string
The gift card code to redeem

Request body


Example request body:

{
  "reason": "Used with Order 7597",
  "locationId": null,
  "metadata": {
    "ExternalOrderId": "7597"
  }
}

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


locationId guid
The location id where this event occurred at.


metadata object
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
}

transactionId string
The id of the report transaction object.


redeemedAmount decimal
The currency amount redeemed off the gift card.

Only for Currency backed gift cards


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

Only for Currency backed gift cards


redeemedUnits integer
The units redeemed off the gift card.

Only for Units backed gift cards


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

Only for Units backed gift cards

Error - 422 Unprocessable Entity


A 422 response returns JSON structured like this:

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

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


wasAlreadyRedeemed boolean
The gift card has already been fully redeemed


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

Only for Currency backed gift cards


remainingCredit decimal
The remaining balance on the gift card

Only for Currency backed gift cards


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

Only for Units backed gift cards


remainingUnits decimal
The remaining units on the gift card

Only for Units backed gift cards


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

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


code string
The gift card code to redeem

Request body


Example request body:

{
  "transactionId": "d9d587ae-fada-431c-e7af-08d885934bd4",
  "reason": "An optional reason",
  "metadata": {
    "key": "value"
  }
}

transactionId guid
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


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


metadata object
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
}

transactionId string
The id of the report transaction object representing the undo request.


amountReversed decimal
The currency amount added back the gift card.

Only for Currency backed gift cards


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

Only for Currency backed gift cards


unitsReversed integer
The units added back to the gift card.

Only for Units backed gift cards


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

Only for Units backed gift cards


alreadyReversed boolean
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.


wasAlreadyRedeemed boolean
The gift card has already been fully redeemed


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

Only for Currency backed gift cards


remainingCredit decimal
The remaining balance on the gift card

Only for Currency backed gift cards


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

Only for Units backed gift cards


remainingUnits decimal
The remaining units on the gift card

Only for Units backed gift cards


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

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"
  }
}

sourceGiftCards list
A list of gift card codes. These balance(s) will be moved to the destination gift card.


destinationGiftCard string
The destination's gift card code. This is where the balance(s) of the source gift card(s) will be moved to.


reason string
The reason for transferring the balance(s). Will appear in the gift card history log.


locationId guid
The location id where this event occurred at.


metadata object
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
}

transferredCredit decimal
The currency balance moved to the destination gift card.

Only for Currency backed gift cards


transferredUnits integer
The units moved to the destination gift card.

Only for 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


id guid
Unique identifier for the item


name string
The name of the item


description string
The description of the item


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

Currency


priceType string
The price type of this item. Will be one of:

Only relevant if the backingType is of type Currency
Specified


price decimal
The price to charge the purchaser

Required if the backingType is Currency & priceType is Specified, or backingType is Units


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

Required for Currency backed gift cards


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

Required for Units backed gift cards


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

Required for Units backed gift cards


minimumPrice decimal
The minimum price the customer can enter when buying this custom value item

Can be set if the backingType is Currency and priceType is Custom


maximumPrice decimal
The maximum price the customer can enter when buying this custom value item

Can be set if the backingType is Currency and priceType is Custom


availableFrom datetime
The scheduled datetime that the customer can buy this item on your checkout. In UTC.

Can be null


overrideValidFrom boolean
Whether or not this item overrides the default valid from.


validFrom datetime
The datetime that gift cards created from this item will be valid from. In UTC.

Can be null


validFromInDays decimal
The number of days after creation that gift cards created from this item will be valid from. In UTC.

Can be null


overrideExpiry boolean
Whether or not this item overrides the default expiry.


expiresOn datetime
The datetime that gift cards created from this item will expire. In UTC.

Can be null


expiresOnInMonths integer
The number of months after creation that gift cards created from this item will expire. In UTC.

Can be null


expiresOnInDays decimal
The number of days after creation that gift cards created from this item will expire. In UTC.

Can be null


availableUntil datetime
The scheduled datetime that the customer can no longer buy this item on your checkout. In UTC.

Can be null


group string
The item group name this item is part of.

When creating an item, if the item is to exist in a group, only specify either a Group or a Group Id, not both.


groupId guid
The item group id this item is part of.

When creating an item, if the item is to exist in a group, only specify either a Group or a Group Id, not both.


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

Must be a fully qualified, absolute URL, if specified


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


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


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


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


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

Create a new item

POST https://api.giftup.app/items  HTTP/2.0
Authorization: Bearer {{apikey}}
Accept: application/json
Content-Type: application/json
{
  "name": "All you can eat steak",
  "description": "Can be used in any of our restaurants",
  "backingType": "Currency",
  "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


id guid
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 codes collection using commands add and remove combined 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 use 0 e.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.

/name string
The name of the item


/description string
The description of the item


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


/price decimal
The price to charge the purchaser


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


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


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


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


/stocklevel integer
An integer defining the stock level available to purchase


/perorderlimit integer
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


id guid
The id of the item to retrieve

Delete an item

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

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

Delete an item by id.

HTTP Request


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

URL Parameters


id guid
The id of the item to delete

List all items

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

The above command returns a response body like this:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "All you can eat steak",
    "description": "Can be used in any of our restaurants",
    "backingType": "Currency",
    "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


groupId guid
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


id guid
Unique identifier for the group


name string
The name of the group


description string
The description of the group


sortOrder integer
The sort order for how the groups appear in the checkout (ascending)

0


autoExpand boolean
Whether to expand the items by default in this group on the checkout

false

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


See item group object

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


id guid
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
  }
]

/name string
The name of the item group


/description string
The description of the item group


/autoExpand string
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


id guid
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


id guid
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


livePublicKey string
Your Stripe live publishable API key

Must start with pk_live_


liveSecretKey string
Your Stripe live secret API key

Must start with sk_live_ or rk_live_


testPublicKey string
Your Stripe test publishable API key

We will use our test keys if nothing provided


testSecretKey string
Your Stripe test secret API key

We will use our test keys if nothing provided


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

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


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

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


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

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


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

false


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

false


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

false


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

false


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

false


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

false


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

false


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

false


enablePayPal boolean
Set to true to enable PayPal payments in your Gift Up! checkout

false


enableKlarna boolean
Set to true to enable Klarna payments in your Gift Up! checkout

false


enableAffirm boolean
Set to true to enable Affirm payments in your Gift Up! checkout

false


enableAfterpayClearpay boolean
Set to true to enable Afterpay/Clearpay payments in your Gift Up! checkout

false


enableFpx boolean
Set to true to enable FPX payments in your Gift Up! checkout

false


enableBlik boolean
Set to true to enable BLIK payments in your Gift Up! checkout

false


enableCashApp boolean
Set to true to enable Cash App payments in your Gift Up! checkout

false


enableGrabPay boolean
Set to true to enable GrabPay payments in your Gift Up! checkout

false


enablePayNow boolean
Set to true to enable PayNow payments in your Gift Up! checkout

false


enablePromptPay boolean
Set to true to enable PromptPay payments in your Gift Up! checkout

false


enablePix boolean
Set to true to enable Pix payments in your Gift Up! checkout

false


enableZip boolean
Set to true to enable Zip payments in your Gift Up! checkout

false


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

false


statementDescriptor string
This will appear on your customer's card statement.


reviewAction string
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


See Stripe connection object

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


id guid
Unique identifier for the location


name string
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


id guid
Unique internal identifier for the order


orderNumber string
A presentable reference number for the order


createdOn datetime
When the order was created. In UTC.


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


purchaserEmail string
The email address of the purchaser


purchaserName string
The name of the purchaser


currency string
The currency the order was taken in


revenue decimal
The revenue taken for this order


tip decimal
The tip taken for this order


serviceFee decimal
The service fee added to this order


discount decimal
The total discount applied to this order


shippingFee decimal
The shipping fee added to this order


referrer string
A string provided that reflects the origin of the order, for example a sales rep's name, or a website url


promotions list
A list of promotions applied to this order

See Order - Promotions properties


customFields list
A list of custom fields collecting during this order

See Order - Custom fields properties


salesTaxes list
A list of sales taxes for this order

See Order - Sales tax properties


notes list
A list of notes added to this order

See Order - notes properties


metadata list
A list of key/values attached to this order

See Metadata properties


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

See Order - Download links properties


payment object
An object representing payment details for this order

See Order - Payment properties

Order promotions


promotionId guid
The id for the promotion


name string
The name of the promotion


code string
The code used to apply this promotion, if a promotion.code was needed to activate the promotion during checkout

Order custom fields


label string
The label to describe the custom field


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

Order sales taxes


label string
The label to describe the sales tax (e.g VAT/GST/Sales Tax etc...)


amount decimal
The amount collected for this sales tax


type string
Whether the sales tax is inclusive or exclusive

Order notes


content string
The note's content


createdOn datetime
The date/time, in UTC, when the note was created


username string
The name of the user who added the note


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


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


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


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

Order payment


provider string
A string representing the name of the payment provider used for this order. For example, Stripe, Square or PayPal.


transactionId string
The transaction Id returned to us from the payment provider when we took payment for this order.

Order metadata


metadata object
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


id guid
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


id string The id or order number of the order

Update order paths


[
{
  "op": "replace",
  "path": "/purchasername",
  "value": "Joe Bloggs"
},
{
  "op": "replace",
  "path": "/purchaseremail",
  "value": "joe@bloggs.com"
},
]

/purchasername string
The purchaser name of the order


/purchaseremail string
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


orderDate datetime
When the order was created. In UTC.

now


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

false


purchaserEmail string
The email address of the purchaser


purchaserName string
The name of the purchaser


tip decimal
The tip taken for this order

If set, must be a positive number


serviceFee decimal
The service fee added to this order

If set, must be a positive number


discount decimal
The total discount applied to this order

If set, must be a positive number


revenue decimal
The revenue taken for this order

If set, must be a positive number


itemDetails list
The details for the gift cards to create.

See Order - Item properties


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

See Order - Recipient properties


salesTaxes list
A list of sales taxes for this order

See Order - Sales tax properties

Order item details

This is the definition for a gift card within the Order


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

Must be at least 1, and not more than 1000


id guid
Reference an item id

If specified, all other properties apart from quantity, and conditionally value and price, in this object are ignored


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


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


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

Gift Up! generates code according to your account code format


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


price decimal
The price charged for this gift card

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


value decimal
The initial currency balance assigned to this gift card

0 Required if id is not specified, or for Currency backed gift cards with Custom price types


units integer
The initial unit balance assigned to this gift card

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


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

Required if id is not specified, or for Units backed gift cards


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

Requires overrideExpiry to be set to true


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

Requires overrideExpiry to be set to true


expiresInDays decimal
Number of days from now, that this gift card expires

Requires overrideExpiry to be set to true


overrideExpiry boolean
Set to true to use expiresOn or expiresInMonths or expiresInDays

false


validFrom datetime
The date this gift card is valid from. In UTC.

Requires overrideValidFrom to be set to true


validFromInDays decimal
Number of days from now, that this gift card is valid from

Requires overrideValidFrom to be set to true


overrideValidFrom boolean
Set to true to use validFrom or validFromInDays

false


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


terms string
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.


customFields list A list of custom fields for this order

See Order - Custom fields properties

Order recipient details

Provide this if you want a gift card to be emailed, otherwise no gift card email will be sent


recipientName string
The name of the recipient of the gift card


recipientEmail string
The recipient's email address


message string
The message to the recipient


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


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

Email


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

See Shipping Address properties


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

See Shipping Option properties

Order recipient shipping address details


address1 string
The first line of the address


address2 string
The second line of the address


city string
The city line of the address


state string
The state line of the address


postalCode string
The postal/zip code line of the address


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

The country code for your account

Order recipient shipping option details


id guid
Reference a Shipping Option id

If specified, all other properties in this object are ignored


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

Required if id is not specified


price decimal
The price of the shipping option

Required if id is not specified

Order metadata


metadata object
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


id guid
The id of the order to add a note to

Add a note properties


content string
The content of the note. Supports line breaks.

Must be no more than 500 characters in length.

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


id guid
The id of the order to retrieve

Mark as posted properties


codes list
A collection of codes to update. Must include all codes in the order.

See codes update definition


Order posted codes


oldCode string
The new code. Must be set.


newCode string
The new code. Must be set. If you don't want to change code, make this equal oldCode.

Must be at least 3 characters, and not already be in use.

Partners

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

Provision a Gift Up! account

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

The above command returns JSON structured like this:

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

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

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

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

HTTP Request


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

Payload


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

Must be a valid email address


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


companyName string
The name of the business


address string
The full postal address of the business


currency string
The currency code for the Gift Up! account

Must be a valid 3-character currency code


countryCode string
The country code of the account

Must be a valid 3-character ISO country code


websiteUrl string
The URL of the business' website

Must be a fully qualified, absolute URL


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

Must be a valid IANA time zone

UTC


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

false


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

false

Ping

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

GET

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

The above command returns a response body like this:

pong

Returns pong in the response body.

HTTP Request


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

POST

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

The above command returns a response body like this:

EXAMPLE

Returns whatever you post to it, as the response body

HTTP Request


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

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


id guid
Unique identifier for the promotion


name string
The name of the promotion


noBenefit boolean
True, if the promotion offers no benefits, and is used for tracking only


publishedOn datetime
The date that the promotion was published


stoppedOn datetime
The date that the promotion was manually stopped


benefits object
Describes the benefits granted by the promotion

See benefits definition


usage object
Tracks the usage of the promotion

See usage definition


limitations object
Describes the conditions that will end the promotion automatically

See limitations definition


triggers object
Describes the conditions that need to be met in order for the promotion to be enabled for an order

See triggers definition


Promotion Benefits Object


additionalItem object
Defines an additional item available with the promotion

Only used if issueAdditionalItem is true
See additional item definition


orderPercentageDiscount decimal
The discount percentage to be applied to the order


giftCardFixedDiscount decimal
The fixed discount to apply to each gift card in the order


orderFixedDiscount decimal
The fixed discount to apply to the whole order


giftCardExtraCredit decimal
Extra currency balance to be applied to gift cards in the the order


giftCardExtraCreditPercentage decimal
Extra currency balance as a percentage to be applied to gift cards in the order


giftCardExtraUnits integer
Extra units balance to be applied to gift cards in the order


issueAdditionalItem boolean
True is an additional item is to be available in the order


Promotion Usage Object


timesUsed integer
The number of orders the promotion has been used in


timesUsedInGiftCards integer
The number of gift cards the promotion has been used for

Only used if targetSpecificItems is true


orderRevenue decimal
The order revenue taken for orders using the promotion


giftCardCurrencyBalanceIssued decimal
The amount of currency balance issued for gift cards bought using the promotion


giftCardUnitBalanceIssued integer
The amount of units balance issued for gift cards bought using the promotion


Promotion Limitations Object


beginsOn datetime
The promotion will automatically begin on this date

null


endsOn datetime
The promotion will automatically end on this date

null


limitNumberOfUses integer
The promotion will end once usage.timesUsed reaches this number

null


limitNumberOfGiftCardUses decimal
The promotion will end once usage.timesUsedInGiftCards reaches this number

null


Promotion Triggers Object


items list
A list of item objects that the promotion applies to

Only used if targetSpecificItems is true


groups list
A list of group names that this promotion applies to

Only used if targetSpecificItems is true


targetSpecificItems boolean
True, if the promotion offers no benefits, and is used for tracking only


minimumSpend decimal
The minimum order spend before the promotion is triggered

null


maximumSpend decimal
The maximum order spend allowed for the promotion

null


minimumQuantity integer
The minimum number of gift cards bought for the promotion to apply

null


maximumQuantity integer
The maximum number of gift cards bought for the promotion to apply

null


code string
A promo code that is required to trigger the promotion

null


Promotion Additional Item Object


item list
An item object that defines the item being made available


quantity integer
The number of additional items


stackThreshold integer
Allows for giving away x gift cards per stackThreshold


percentageDiscount decimal
The percentage discount applied to the additional item

null


fixedDiscount decimal
The fixed discount applied to the additional item

null


fixedPrice decimal
The fixed price of the additional item

null


receiver string
Who the additional item is sent to

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


id guid
Unique identifier for the event


eventOccurredOn datetime
The datetime that this event occurred


eventOccuredAtLocationId guid
The id of the the location where the event occurred


eventType string
The type of this event

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


reason string
The reason this transaction occurred (supported on CreditAdded, Redeemed and Voided events).


referrer string
A string provided that reflects the origin of the event, for example a sales rep's name, or a website url


metadata object
A key-value data store of metadata provided to us by you (supported on CreditAdded, Redeemed, Voided and Reactivated events)


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


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


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


whoName string
The name of the user who did this event

Can be null (for event triggered by your customers)


whoEmail string
The email address of the who did this event

Can be null (for event triggered by your customers)


orderDetails object
Contains financial details of the order

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


giftCard object
Contains financial details of the gift card

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


Transaction Order Details


income decimal
The revenue taken


serviceFee decimal
The service fee charged


tip decimal
The tip taken


shippingFee decimal
The shipping fee charged


Transaction Gift Card Details


id string
The gift card id


code string
The code


valueChange decimal
The currency change in value by this event

Will be negative for Redeemed


unitChange integer
The unit change in value by this event

Only for Units backed gift cards


title string
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


eventOccurredOnOrAfter datetime
A UTC datetime to include only transactions that occurred on or after this date time.


eventOccurredOnOrBefore datetime
A UTC datetime to include only transactions that occurred on or before this date time.


events string
Only return events that match this.

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


users string
Only return events that were generated by this user's email address

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


locations string
Only return events that were generated at this location id

Can be specified multiple times e.g. …/reports/transactions?locations=412f6381-02cc-4866-91f5-428a6b7db3b0&locations=636fc5f2-7eed-4bd7-8897-f0e6cbe4a63f


code string
Only return events that match this gift card code.


limit integer
The number of transactions to return

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


offset integer
The number of transactions to skip

0

HTTP Response


transactions list
A list of transaction objects


total integer
The total number of transactions matching the filters provided


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

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


id guid
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


logoUrl string
Url of the logo shown on the hosted checkout


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


fontFamily string
The font to use for the checkout


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

A px based CSS font definition


themeColor string
Base color for the checkout

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


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

Must be one of either light or dark


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

Must specify in combination with continueLinkUrl for button to show


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

Must specify in combination with continueLinkText for button to show


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

Supports placeholder replacement of the following properties:

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


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

Script tags are not allowed


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


defaultFor string
Controls who the gift card is for by default

Valid settings are:

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


serviceFeeCharged boolean
Whether or not to charge a service fee


serviceFeeFixed decimal
The fixed element to a service fee

Has no effect if serviceFeeCharged is false


serviceFeePercentage decimal
The percentage element to a service fee

Has no effect if serviceFeeCharged is false


tipsEnabled boolean
Enable or disable tips on the checkout


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


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

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

Update checkout settings

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

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

Update your checkout settings.

HTTP Request


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

Update checkout settings paths


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

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

Definitions for the following properties are available above

/logoUrl string
You can specify either:

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

/introductionText string


/fontFamily string


/fontSize string


/themeColor string


/backgroundColor string

Must be either Light or Dark


/continueLinkText string


/continueLinkUrl string

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


/redirectUrl string


/additionalCustomHtml string


/showBalanceChecker boolean


/defaultFor string

Must be either SomeoneElse, OnlySomeoneElse, Me or OnlyMe


/serviceFeeCharged boolean


/serviceFeeFixed decimal

Must be at least 0


/serviceFeePercentage decimal

Must be between 0 and 100


/tipsEnabled boolean


/allowCustomTipValues boolean


/overrideTipValues list

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

Get email settings

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

The above command returns a response body like this:

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

Get your default email settings.

HTTP Request


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

Response body


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


logoAlignment string
Where the email logo should sit

One of left, middle or right


logoWidth integer
The width in pixels of the logo


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


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

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


giftCardEmail object
Settings for the gift card email

See Gift card email


receiptEmail object
Settings for the receipt email

See Receipt email

Gift card email


subjectLine string
The subject line for the gift card email


title string
The headline text in the gift card email


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


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


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


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


buttonColour string
The colour for the additional button

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


buttonAlignment string
Settings for the receipt email

One of left, middle or right

Receipt email


subjectLine string
The subject line for the receipt email


title string
The headline text in the receipt email


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


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

Update email settings

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

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

Update your 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

/logourl string
You can specify either:

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

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


/logowidth integer


/fromemail string


/fromname string


/giftcardemail/subjectline string


/giftcardemail/title string


/giftcardemail/introtext string


/giftcardemail/footertext string


/giftcardemail/buttonlabel string


/giftcardemail/buttonurl string


/giftcardemail/buttoncolour string


/giftcardemail/buttonalignment string

Must be one of left, middle or right


/receiptemail/subjectline string


/receiptemail/title string


/receiptemail/introtext string


/receiptemail/footertext string

Get gift card settings

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

The above command returns a response body like this:

{
    "defaultDescription": "For use at Juicy Joe's",
    "barcodeFormat": "PDF417",
    "expiryInMonths": 12,
    "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


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


barcodeFormat string
The format of the barcode

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


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

null


expiryInDays decimal
Number of days after purchase that a gift card expires

null


validFromInDays decimal
Number of days after purchase that a gift card is valid from

null


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


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


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


generalTerms string
General term & conditions shared across all gift cards


codeFormat string
The format used to generate gift card codes

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

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

Update gift card settings

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

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

Update your gift card settings.

HTTP Request


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

Update gift card settings paths


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

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

Definitions for the following properties are available above

/defaultdescription string


/barcodeformat string

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


/expiryinmonths integer

Must be at least 1, can be null


/expiryindays decimal

Must be at least 1, can be null


/validfromindays decimal

Must be at least 0, can be null


/showissuedondate boolean


/showbalance boolean


/showbarcode boolean


/generalterms string


/codeformat string

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

List gift card artwork

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

The above command returns a response body like this:

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

Get a list of your your uploaded gift card artwork.

HTTP Request


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

Response body


id string
The id of the artwork


url string
The URL of the artwork


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

Upload gift card artwork

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

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

Upload some new gift card artwork.

HTTP Request


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

Request body


url string
You can specify either:

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

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

false


replaceArtworkId string
The id of the artwork to replace

blank

Delete gift card artwork

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

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

Delete one of your uploaded gift card artwork.

HTTP Request


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

URL Parameters


id guid
The id of the artwork to delete

Get shipping settings

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

The above command returns a response body like this:

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

Get your shipping settings.

HTTP Request


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

Response body


enableDigitalFulfilment boolean
Whether fulfilment by email is enabled


enableSelfFulfilledPostal boolean
Whether fulfilment by post is enabled


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

Only relevant if enableSelfFulfilledPostal is enabled


postalShippingOptions list
An array of shipping options presented to the purchaser

Only relevant if enableSelfFulfilledPostal is enabled See shipping option definition

Shipping option


id guid
The shipping option unique identifier


name string
The shipping option name


price decimal
The price to charge the purchaser for shipping


sortOrder integer
The ascending sort order of the shipping options


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


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

See shipping option country definition

Shipping option country


name string
The country name


isoCode string
The 3 character ISO country code

Users

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

The user object

Example item:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Joe",
  "email": "joe@juicyjoes.com",
  "avatarUrl": "https://…",
  "pin": "1234",
  "isAdministrator": true,
  "emailConfirmed": true,
  "hiddenInRedeemApp": false,
  "disableSearchInRedeemApp": false,
  "hideLogInRedeemApp": false,
  "expiredGiftCardRedemptionDisabled": false,
  "redeemLocationRestrictionEnforced": false,
  "locations": [
    {
      "id": "412f6381-02cc-4866-91f5-428a6b7db3b0",
      "name": "Main store"
    }
  ]
}

Properties


id guid
Unique identifier for the user


name string
The name of the user


email string
The email address of the user


avatarUrl string
The uploaded image of the user

If inviting or updating a user, you can provide a URL or a base64 encoded image


pin string
The redeem pin number for the user


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


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


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


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


hideLogInRedeemApp boolean
Set to true if the user cannot view a gift card's history log in the redeem app


expiredGiftCardRedemptionDisabled boolean
Set to true if the user cannot redeem an expired (or not yet valid) gift card


redeemLocationRestrictionEnforced boolean
Set to true if the user cannot redeem a gift card not issued for their location(s)


locations array
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


id guid
The id of the user to retrieve

Response body


See user object

Delete a user

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

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

Delete a user by id

HTTP Request


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

URL Parameters


id guid
The id of the user to delete

Update a user

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

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

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

HTTP Request


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

URL Parameters


id guid
The id of the user to update

Update user paths


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

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

/name string
The user's name


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


/email string
The email address of the user


/role string
Change the role of the user

Can be either blank/null or administrator


/avatarUrl string
Change the avatar of the user

Can be either a URL or a base64 encoded image

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:


correlationId guid
A unique identifier to trace the event fired by Gift Up internally


companyId guid
The Gift Up account identifier


eventType string
The event type

Can be one of OrderCreated, GiftCardCreated, GiftCardRedeemed or GiftCardUpdated


GiftCardCreated webhook payload

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

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

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


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


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


GiftCardRedeemed webhook payload

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

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

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


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


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


redeemedAmount decimal
The currency balance redeemed off the gift card

Only for Currency backed gift cards


unitsRedeemed integer
The unit balance redeemed off the gift card

Only for Units backed gift cards


occurredOn datetime
When the redemption event occurred. In UTC.


GiftCardUpdated webhook payload

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

OrderCreated webhook payload

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

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

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


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

Verifying calls are made by Gift Up!

Example request:

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

Verifying secret in C#

var request = HttpContext.Request;

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

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

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

var requestBody = request.Content.ReadAsStringAsync();

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

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

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

Verifying secret in node/js

const crypto = require("crypto"); 

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

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

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

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

Verifying secret in Ruby/Rails

def signature_valid? 

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

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

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

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

end

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

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

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

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

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

The webhook object

Example webhook:

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

Properties


id guid
Unique identifier for the webhook


url string
The delivery URL for the webhook


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


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

Add a webhook

POST https://api.giftup.app/hooks/{event}/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


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

Request body


targetUrl string
The delivery URL for the webhook


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

blank


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

false

List all webhooks

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

The above command returns a response body like this:

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

Retrieve all webhooks on an account

HTTP Request


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

Response body


A list of webhook objects

Get a webhook

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

The above command returns a response body like this:

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

Retrieve a webhook by id.

HTTP Request


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

URL Parameters


id string
The id of the webhook to retrieve

Response body


The webhook object

Delete a webhook

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

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

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

HTTP Request


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

URL Parameters


id string
The id of the webhook to delete