Introduction

Base URL:

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

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

Authentication

To authorize, use this code:

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

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

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

Authorization: Bearer {{apikey}}

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

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

Controlling display name

You can pass a header of x-giftup-displayname to override the display name used in API calls.

Content types

Specify payload and response content-types in each request:

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

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

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

Response codes

HTTP status code summary:

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

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

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

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

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

Specifying dates

Specify requests using our format requirements:

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

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

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

• yyyy-MM-dd e.g. "2020-07-30"
• yyyy-MM-dd HH:mm e.g. "2020-07-30 16:35"
• yyyy-MM-dd HH:mm:ss e.g. "2020-07-30 16:35:06"
• yyyy-MM-ddTHH:mm:ss.fffffffK e.g. "2020-07-30T16:35:06.0000000" / "2020-07-30T16:35:06.0000000Z"
• yyyy-MM-ddTHH:mm:ss.fffK e.g. "2020-07-30T16:35:06.000" / "2020-07-30T16:35:06.000Z"
• yyyy-MM-ddTHH:mm:ssK e.g. "2020-07-30T16:35:06" / "2020-07-30T16:35:06-07:00"
• yyyy-MM-ddTHH:mmK e.g. "2020-07-30T16:35" / "2020-07-30T16:35Z"
• Round-trip date/time pattern e.g. "2009-06-15T13:45:30.0000000-07:00"
• RFC1123 pattern e.g. "Mon, 15 Jun 2009 20:45:30 GMT"

Where:

• yyyy is the 4 digit year
• MM is the 2 digit month
• dd is the 2 digit day of the month
• HH is the 2 digit hours, in 24 hour notation
• mm is the 2 digit minutes
• ss is the 2 digit seconds
• fff is the 3 digit milliseconds
• K is the time zone information specifier. E.g. Z for UTC (aka Zulu), or -07:00, -0700 for the offset in hours

Testing the API

To enable test mode, add the following HTTP header:

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

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

x-giftup-testmode: true

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

Rate limits

Request throughput per API key:

Sustained: 5 requests per second
Burst (example): 10 requests per second for up to 5 minutes

The Gift Up API use a leaky bucket algorithm to manage requests. This algorithm lets your app make an large amount of requests in infrequent bursts over time. This model ensures that apps that manage API calls responsibly will always have room in their buckets to make a burst of requests if needed.

The general throughput target for any given API key is 5 requests per second for a sustained period. We do not guarantee these limits, but we aim to achieve this throughput.

If you are using our API beyond these limits we will slow down your calls to us by up to several seconds, and eventually for more severe cases, we will block your API key being used for several minutes by returning a HTTP 429 response.

Metadata

Example: Adding metadata to an order:

POST https://api.giftup.app/orders HTTP/2.0
Authorization: Bearer {{apikey}}
Content-Type: application/json
Accepts: application/json

{  
  "orderDate": "2020-06-08T11:31:31.758Z",
  "revenue": 100,
  // …all other order properties…
  "metadata": {
    "a key": "a value",
    "another key": "another value"
  }
}

Orders and some Report transactions have a metadata parameter. You can use this parameter to attach key-value data to these Gift Up! objects.

You can specify up to 20 keys, and the value can be any type supported by the JSON spec, including string, boolean, object, array, number etc…

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on an Order object. Metadata is not used by Gift Up! and won't be seen by your customers.

Companies

A company is also known as a Gift Up account. Multiple users can have access to a single Gift Up company.

The company object

Example item:

{
  "id": "cd6228d8-8ed6-4264-b28a-eb5a5736e81e",
  "name": "Juicy Joes Steakhouse",
  "currency": "GBP",
  "onboardingCompleted": true,
  "canShowCheckout": true,
  "isCheckoutLive": true
}

Properties

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:

• Active a gift card that has a positive balance and is not voided or expired
• Expired a gift card that has a positive balance, is not voided but has expired based on its expiredOn date
• Not Yet Valid a gift card that has a positive balance, is not voided but is yet to become valid based on the validFrom date
• Redeemed a gift card that has a zero balance
• Voided a gift card that has a positive balance and has been voided

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

The gift card object

Example gift card:

{
  "canBeRedeemed": true,
  "hasExpired": false,
  "notYetValid": false,
  "isVoided": false,
  "code": "ABC123",
  "title": "All you can eat steak!",
  "subTitle": "For use at any Juicy Joes restaurant",
  "message": "Happy Birthday! Dad",
  "fulfilledOn": "2020-06-10T15:02:18.786Z",
  "recipientName": "Dad",
  "recipientEmail": "bob.bloggs@example.com",
  "backingType": "Currency",
  "remainingValue": 100,
  "remainingUnits": null,
  "initialValue": 100,
  "initialUnits": null,
  "equivalentValuePerUnit": null,
  "terms": "Can only be used on Saturdays",
  "sku": "STEAK-8",
  "expiresOn": "2020-06-10T15:02:17.786Z",
  "validFrom": null,
  "voidedOn": "2020-06-10T15:02:17.786Z",
  "fulfilledBy": "Email",
  "order": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "orderNumber": "10152",
    "createdOn": "2020-06-10T15:02:17.786Z",
    "selectedRecipient": "SomeoneElse",
    "purchaserEmail": "joe.bloggs@example.com",
    "purchaserName": "Joe Bloggs",
    "tip": 0,
    "serviceFee": 0,
    "shippingFee": 0,
    "currency": "USD",
    "revenue": 50,
    "customFields": [
      {
        "label": "Telephone",
        "value": "202-555-0191"
      }
    ],
    "salesTaxes": [
      {
        "label": "Sales Tax",
        "amount": 20,
        "type": "exclusive"
      }
    ],
    "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:

• Currency
• Units

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.

Gift card download links

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
• Units

Currency

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

• Specified
• Custom

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

Order download links

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:

• Currency
• Units

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