Orders

The object

An order is a request to purchase or activate one or more vouchers, events or products from a properties.

You can view orders to view customer information, and what was purchased, you can create orders to generate new vouchers or event tickets and you can update existing order customer information.

Structure

At the top level the order contains key pieces of customer information such as email addresses for the purchaser and recipient, billing and delivery address, how the order is to be delivered and when.

Within an order there are rows representing the individual items (Most likely a voucher, but can be a physical item or an event ticket) the customer has ordered.

Also within an order are transactions, this represents the movement of real money. Most orders will have a single transaction, the original payment however some might have a refund, chargeback or topups that have happened later.

List orders

GET https://api.giftpro.co.uk/orders/

Returns a list of the last 50 orders with the most recently created order first. Look at the order object for more information on the response.

For viewing more orders take a look at pagination.

For more information on the various operators you can use to filter by date with view the filtering section.

Query Parameters

Name
Type
Description

domainID

int

Show orders for the specific property

orders.dateCreated[gte]

String

Add a date string to filter orders by

p

int

The page to return 

[
  {
    "orderID": 1234,,
    "domainID": 3521,
    "domainName": "Ampress Park Hotel",
    "dateCreated": "2017-09-12 11:32:41",
    "emailAddress": "customer@gmail.com",
    "currencyCode": "GBP",
    "total": 29.95,
    "delivery": 2.95,
    "...": "..."
  },
  {...}
]

Get order

GET https://api.giftpro.co.uk/orders/{orderID}/

Returns the full order object for the specified order.

Path Parameters

Name
Type
Description

orderID*

int

The order you want to return data for.

[
  {
      "orderID": 5120211,
      "domainID": 3521,
      "domainName": "Ampress Park Hotel",
      "dateCreated": "2017-09-12 11:32:41",
      "emailAddress": "customer@gmail.com",
      "currencyCode": "GBP",
      "total": 29.95,
      "delivery": 2.95,
      "paymentMethod": "Public",
      "status": "Complete",
      "customerName": "Nathan Green",
      "billingAddressLine1": "103-105 Hamilton Rd",
      "billingAddressLine2": "",
      "billingAddressLocality": "Felixstowe",
      "billingAddressCounty": "Suffolk",
      "billingAddressPostcode": "IP11 7BL",
      "billingAddressCountry": "United Kingdom",
      "deliveryName": "Mary Owen",
      "deliveryAddressLine1": "7 Templar Avenue",
      "deliveryAddressLine2": "",
      "deliveryAddressLocality": "Coventry",
      "deliveryAddressCounty": "West Midlands",
      "deliveryAddressPostcode": "CV4 9BQ",
      "deliveryAddressCountry": "United Kingdom",
      "deliveryMethodID": 5241,
      "deliveryMethodName": "Royal Mail 1st Class",
      "deliveryMethodRequiresFulfillment": true,
      "marketingOptedIn": true,
      "marketingDoubleOptedIn": false,
      "refunded": false,
      "personalTaxIdentifier": NULL
    }
]

Get order products

GET https://api.giftpro.co.uk/orders/{orderID}/rows/

Returns a list of the products that make up the order, each has its own unique rowID.

[
    {
        "rowID": 133205,
        "orderID": 51201,
        "productID": 8,
        "name": "Monetary Voucher",
        "type": "Voucher",
        "redeemCode": "1234EXAMPLECODE",
        "clientCode": "",
        "validFromDate": "2017-09-19 21:13:22",
        "redeemedDate": "",
        "expiryDate": "2018-09-19 23:59:59",
        "graceExpiryDate": "2018-10-19 23:59:59",
        "status": "Valid",
        "total": 45.00,
        "currencyCode": "GBP",
        "partiallyRedeemable" false,
        "redeemHistory": [
           {
              "eventID": 162410,
              "userID": 1,
              "domainID": "142",
              "name": "Dave Test",
              "rowID": "282631",
              "redeemedValue": "100.00",
              "location": "Restaurant",
              "status": "Redeemed",
              "lastChanged": "2018-08-02 14:28:13"
           },
           {...}
        ]
    },
    {...}
]

Create order

POST https://api.giftpro.co.uk/orders/

Creating an order requires a property to create the order within, an email address and vouchers as a minimum.

The response will contain the completed order where each voucher will now have expiries, statuses and redemption codes.

Request Body

Name
Type
Description

domainID*

int

The domainID of the property you wish to create the order for, note that the voucher must be attached to this domainID as well.

methodID*

String

Delivery method for the order, the available methodID are retrieved using the properties endpoint

email

String

The customers email address attached to the order, this is where we send order confirmation emails and other communication about the order

customerName

String

Passing the customer name is recommended as its helpful when finding the order later and providing support

billingAddress

array

We recommend passing this whenever a payment has been taken, it can be useful for providing support later. A key-value pair representing each of the 7 lines of the address. The address keys: line1 line2 locality county postcode country

deliveryAddress

array

Required based on the methodID passed, a key-value pair representing each of the 7 lines of the address. The address keys: name, line1 line2 locality county postcode country

complimentary

bool

Passing true will mean this order is processed as complimentary zero value

sendConfirmationEmail

bool

By default this is set to true. Pass false to prevent confirmation email being sent to the customers email address

paymentReferenceID

String

Provide a reference to the resulting order, this information can be retrieved later and is useful for linking together an order with data from the source system.

items*

array

List of the products in the order, each can have options and a personal message. Each item can have a personalMessage and options child attribute, within the options child attribute you should provide the selected voucher options in the form of key-value pair where the key is the optionKey returned from the voucher data and the value is the optionValue selected from within the option values.

Update order

POST https://api.giftpro.co.uk/orders/{orderID}/

Update an order with new information using the parameters specified below, parameters that are not provided are left unchanged.

The response will be the same as when issuing a GET request reflecting the updated data.

Refund order

POST https://api.giftpro.co.uk/orders/{orderID}/refund/

You can refund an order to bring the balances back to zero for both the client and the customer. Any vouchers in the order will automatically have the status changed to void and balances reduced to zero you do not need to make any additional calls. It isn't possible to delete an order entirely.

There are restrictions to be aware of, you can only refund an order that was created via API, you may only refund the entire order at once and any vouchers contained in the order must be unused. This method will return an error when called on an already-refunded order, or if any vouchers have been used with an appropriate error code which can be used for feedback purposes.

Request Body

Name
Type
Description

releaseCodes

bool (false)

Releases any clientCodes used on vouchers on the order enabling the codes to be used again in the future. Defaults to false

PreviousCategoriesNextStatuses

Last updated