Regalo API

The Regalo API is a simple API allowing the redemption of vouchers.

Authorisation

Most endpoints in the Regalo API will require the Authorization HTTP header.

Authorisation: bearer wH2MXKTwh58kC2oXeY6UlsDxJk3cyPYa1sA1clEZvBihwdRZQW51CHsiwenP

Failing to do so will cause the following error:

{
  "errors" : [
      {
        "message" : "Unauthorized."
      }
  ]
}

Personal authorisation api tokens are available for users with API access. These can be found in the user section of the Regalo admin panel (https://app.reaglo.gifts). Make sure the users have the appropriate role and access to the appropriate shops so they are authorised to use the required API endpoints.

Additional HTTP Headers

All requests require the Accept header to be set to application/json.

Accept: application/json

Any POST requests using json also require the Content-Type header to be set to application/json.

Content-Type: application/json

Shops ¶

View available shops, view and redeem vouchers.

Shop List ¶

Get shops
GET`/shops`

Return a list of shops the authorised user has access to.

Example URI

GET https://api.regalo.gifts/api/shops

Request

HideShow

Headers

Accept: application/json
Authorization: Bearer {api_token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 2,
      "name": "The Swan Hotel & Spa",
      "enabled": true,
      "created_at": {
        "date": "2017-10-12 09:55:07.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      },
      "updated_at": {
        "date": "2017-10-12 09:55:07.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      }
    },
    {
      "id": 3,
      "name": "The Royal Hotel",
      "enabled": true,
      "created_at": {
        "date": "2017-10-12 09:55:03.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      },
      "updated_at": {
        "date": "2017-10-13 16:55:21.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      }
    }
  ]
}

Venues ¶

Get venues
GET`/shops/{shopId}/venues`

Return a list of venues (only used for multi-venue setup).

Example URI

GET https://api.regalo.gifts/api/shops/shopId/venues

URI Parameters

HideShow

shopId: integer (required)
The unique identifier of a shop

Request

HideShow

Headers

Accept: application/json
Authorization: Bearer {api_token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 1,
      "name": "Ross, Rogers and Owen",
      "address_line_1": "441 Carole Points",
      "address_line_2": "Flat 62",
      "town": "South Shannon",
      "county": "West Yorkshire",
      "postcode": "I62 9GR",
      "latitude": "-10.87457900",
      "longitude": "-41.58685000",
      "email_address": "benjamin.butler@young.com",
      "telephone_number": "5400941",
      "website_url": "https://www.richards.com/voluptatem-nihil-et-molestias-sapiente-temporibus",
      "created_at": {
        "date": "2019-02-08 05:12:42.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      },
      "updated_at": {
        "date": "2019-02-08 05:12:42.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      }
    },
    {
      "id": 2,
      "name": "Lloyd Inc",
      "address_line_1": "Studio 40n\nDavis Road",
      "address_line_2": "Studio 01",
      "town": "Sabrinachester",
      "county": "Carmarthenshire",
      "postcode": "VO2 9BP",
      "latitude": "11.36247900",
      "longitude": "77.58880500",
      "email_address": "jasmine66@bailey.com",
      "telephone_number": "57972393",
      "website_url": "http://www.hughes.com/expedita-occaecati-est-architecto-placeat-beatae-et",
      "created_at": {
        "date": "2019-02-08 05:12:42.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      },
      "updated_at": {
        "date": "2019-02-08 05:12:42.000000",
        "timezone_type": 3,
        "timezone": "Europe/London"
      }
    }
  ]
}

Vouchers ¶

Get voucher
GET`/shops/{shopId}/vouchers/{voucherId}`

Get existing voucher.

Example URI

GET https://api.regalo.gifts/api/shops/shopId/vouchers/voucherId

URI Parameters

HideShow

shopId: integer (required)
The unique identifier of a shop
voucherId: integer (required)
The unique identifier of a voucher (5 letter code)

Request

HideShow

Headers

Accept: application/json
Authorization: Bearer {api_token}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": {
    "id": "1ZQI8",
    "code": "1ZQI8",
    "package_name": "Gift Voucher",
    "price_option_name": "",
    "price": "100.00",
    "post_and_packaging": "0.00",
    "total": "100.00",
    "is_monetary": true,
    "terms_and_conditions": "This voucher features a unique reference ID code, may only be redeemed once, may not be exchanged for cash or replaced if lost. Vouchers are non-transferable. All reservations must be booked prior to arrival. Please quote the gift voucher ID reference when making your reservation. Terms & Conditions are subject to change.",
    "delivery_type": "Email",
    "delivery_status": "Dispatched",
    "message": null,
    "expiry": {
      "date": "2020-02-02 23:59:59.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    },
    "status": "Valid",
    "usable": true,
    "refunded": false,
    "logs": [
      {
        "id": 29,
        "title": "Dispatched",
        "log": "Voucher dispatched by email.",
        "user_name": "Regalo Fulfilment Service",
        "user_super_admin": false,
        "created_at": {
          "date": "2019-02-02 16:06:14.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      },
      {
        "id": 31,
        "title": "Partially Redeemed",
        "log": "Voucher Partially Redeemed.\n\nRedemption Date:\n02/02/2019\n\nRedemption Value:\n£95.00",
        "user_name": "Regalo Admin",
        "user_super_admin": true,
        "created_at": {
          "date": "2019-02-02 16:06:53.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      },
      {
        "id": 33,
        "title": "Partially Redeemed",
        "log": "Voucher Partially Redeemed.\n\nRedemption Date:\n02/02/2019\n\nRedemption Value:\n£1.00",
        "user_name": "Tenant Admin",
        "user_super_admin": false,
        "created_at": {
          "date": "2019-02-02 17:18:17.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      }
    ],
    "redemptions": [
      {
        "id": 448,
        "voucher_id": "1ZQI8",
        "type": "Partial",
        "date": {
          "date": "2019-02-02 00:00:00.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        },
        "value": "95.00",
        "venue": null,
        "created_at": {
          "date": "2019-02-02 16:06:53.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      },
      {
        "id": 449,
        "voucher_id": "1ZQI8",
        "type": "Partial",
        "date": {
          "date": "2019-02-02 00:00:00.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        },
        "value": "1.00",
        "venue": null,
        "created_at": {
          "date": "2019-02-02 17:18:17.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      }
    ],
    "redemption_status": "Partially Redeemed",
    "unredeemed": "4.00",
    "redeemed": "96.00",
    "is_partially_redeemable": true,
    "notes": null,
    "created_at": {
      "date": "2019-02-02 16:06:06.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    },
    "updated_at": {
      "date": "2019-02-02 17:18:17.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    }
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    {
      "message": "Voucher does not exist."
    }
  ]
}

Create full redemption ¶

Create a full redemption
POST`/shops/{shopId}/vouchers/{voucherId}/redemptions/full`

Redeem a voucher in full.

Example URI

POST https://api.regalo.gifts/api/shops/shopId/vouchers/voucherId/redemptions/full

URI Parameters

HideShow

shopId: integer (required)
The unique identifier of a shop
voucherId: integer (required)
The unique identifier of a voucher (5 letter code)

Request

HideShow

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer {api_token}

Body

{
  "date": "28/01/2019",
  "venue": 10
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "The date the redemption dd/mm/yyyy"
    },
    "venue": {
      "type": "integer",
      "description": "The id of the venue, only required for multi-venue setups"
    }
  },
  "required": [
    "date"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": {
    "id": 5,
    "voucher_id": "NVM18",
    "type": "Full",
    "date": {
      "date": "2019-02-02 00:00:00.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    },
    "value": "100.00",
    "venue": null,
    "created_at": {
      "date": "2019-02-08 05:33:32.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    }
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    {
      "message": "Voucher does not exist."
    }
  ]
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    {
      "message": "Voucher is not usable."
    }
  ]
}

Create partial redemption ¶

Create a partial redemption
POST`/shops/{shopId}/vouchers/{voucherId}/redemptions/partial`

Partially redeem a voucher (can only be used for monetary vouchers if enabled).

Example URI

POST https://api.regalo.gifts/api/shops/shopId/vouchers/voucherId/redemptions/partial

URI Parameters

HideShow

shopId: integer (required)
The unique identifier of a shop
voucherId: integer (required)
The unique identifier of a voucher (5 letter code)

Request

HideShow

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer {api_token}

Body

{
    "date": "28/01/2019",
    "value" 5.50
    "venue": 10
}

Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "date": {
            "type": "string",
            "description": "The date the redemption dd/mm/yyyy"
        },
        "value": {
            "type": "number",
            "description": "The value of the redemption"
        },
        "venue": {
            "type": "integer",
            "description": "The id of the venue, only required for multi-venue setups"
        }
    },
    "required":["date", "value"]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": {
    "id": 6,
    "voucher_id": "QCI0T",
    "type": "Partial",
    "date": {
      "date": "2019-02-02 00:00:00.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    },
    "value": 5.5,
    "venue": null,
    "created_at": {
      "date": "2019-02-08 06:05:41.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    }
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    {
      "message": "Voucher does not exist."
    }
  ]
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    {
      "message": "Voucher is not usable."
    }
  ]
}

Update voucher notes ¶

Update a voucher's notes
PUT`/shops/{shopId}/vouchers/{voucherId}/notes`

This will overwrite any notes saved on the voucher.

Example URI

PUT https://api.regalo.gifts/api/shops/shopId/vouchers/voucherId/notes

URI Parameters

HideShow

shopId: integer (required)
The unique identifier of a shop
voucherId: integer (required)
The unique identifier of a voucher (5 letter code)

Request

HideShow

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer {api_token}

Body

{
  "notes": "Updated by epos using Tom"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "notes": {
      "type": "string",
      "description": "Notes for the voucher"
    }
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": {
    "id": "1ZQI8",
    "code": "1ZQI8",
    "package_name": "Gift Voucher",
    "price_option_name": "",
    "price": "100.00",
    "post_and_packaging": "0.00",
    "total": "100.00",
    "is_monetary": true,
    "terms_and_conditions": "This voucher features a unique reference ID code, may only be redeemed once, may not be exchanged for cash or replaced if lost. Vouchers are non-transferable. All reservations must be booked prior to arrival. Please quote the gift voucher ID reference when making your reservation. Terms & Conditions are subject to change.",
    "delivery_type": "Email",
    "delivery_status": "Dispatched",
    "message": null,
    "expiry": {
      "date": "2020-02-02 23:59:59.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    },
    "status": "Valid",
    "usable": true,
    "refunded": false,
    "logs": [
      {
        "id": 29,
        "title": "Dispatched",
        "log": "Voucher dispatched by email.",
        "user_name": "Regalo Fulfilment Service",
        "user_super_admin": false,
        "created_at": {
          "date": "2019-02-02 16:06:14.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      },
      {
        "id": 31,
        "title": "Partially Redeemed",
        "log": "Voucher Partially Redeemed.\n\nRedemption Date:\n02/02/2019\n\nRedemption Value:\n£95.00",
        "user_name": "Regalo Admin",
        "user_super_admin": true,
        "created_at": {
          "date": "2019-02-02 16:06:53.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      },
      {
        "id": 33,
        "title": "Partially Redeemed",
        "log": "Voucher Partially Redeemed.\n\nRedemption Date:\n02/02/2019\n\nRedemption Value:\n£1.00",
        "user_name": "Tenant Admin",
        "user_super_admin": false,
        "created_at": {
          "date": "2019-02-02 17:18:17.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      }
    ],
    "redemptions": [
      {
        "id": 448,
        "voucher_id": "1ZQI8",
        "type": "Partial",
        "date": {
          "date": "2019-02-02 00:00:00.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        },
        "value": "95.00",
        "venue": null,
        "created_at": {
          "date": "2019-02-02 16:06:53.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      },
      {
        "id": 449,
        "voucher_id": "1ZQI8",
        "type": "Partial",
        "date": {
          "date": "2019-02-02 00:00:00.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        },
        "value": "1.00",
        "venue": null,
        "created_at": {
          "date": "2019-02-02 17:18:17.000000",
          "timezone_type": 3,
          "timezone": "Europe/London"
        }
      }
    ],
    "redemption_status": "Partially Redeemed",
    "unredeemed": "4.00",
    "redeemed": "96.00",
    "is_partially_redeemable": true,
    "notes": "Updated by epos using Tom",
    "created_at": {
      "date": "2019-02-02 16:06:06.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    },
    "updated_at": {
      "date": "2019-02-02 17:18:17.000000",
      "timezone_type": 3,
      "timezone": "Europe/London"
    }
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    {
      "message": "Voucher does not exist."
    }
  ]
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    {
      "message": "Notes exceeds max length."
    }
  ]
}

Authorisation ¶

Additional HTTP Headers ¶

Shops ¶

Shop List ¶

Get shopsGET/shops

Example URI

Headers

Headers

Body

Venues ¶

Get venuesGET/shops/{shopId}/venues

Example URI

Headers

Headers

Body

Vouchers ¶

Get voucherGET/shops/{shopId}/vouchers/{voucherId}

Example URI

Headers

Headers

Body

Headers

Body

Create full redemption ¶

Create a full redemptionPOST/shops/{shopId}/vouchers/{voucherId}/redemptions/full

Example URI

Headers

Body

Schema

Headers

Body

Headers

Body

Headers

Body

Create partial redemption ¶

Create a partial redemptionPOST/shops/{shopId}/vouchers/{voucherId}/redemptions/partial

Example URI

Headers

Body

Schema

Headers

Body

Headers

Body

Headers

Body

Update voucher notes ¶

Update a voucher's notesPUT/shops/{shopId}/vouchers/{voucherId}/notes

Example URI

Headers

Body

Schema

Headers

Body

Headers

Body

Headers

Body

Authorisation

Additional HTTP Headers

Get shops
GET`/shops`

Get venues
GET`/shops/{shopId}/venues`

Get voucher
GET`/shops/{shopId}/vouchers/{voucherId}`

Create a full redemption
POST`/shops/{shopId}/vouchers/{voucherId}/redemptions/full`

Create a partial redemption
POST`/shops/{shopId}/vouchers/{voucherId}/redemptions/partial`

Update a voucher's notes
PUT`/shops/{shopId}/vouchers/{voucherId}/notes`