# 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](https://docs.giftpro.co.uk/#retrieve-an-order) for more information on the response. For viewing more orders take a look at [pagination](/pagination.md). For more information on the various operators you can use to filter by date with view the [filtering](/filtering.md) 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 | {% tabs %} {% tab title="200 " %} ```json [ { "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, "...": "..." }, {...} ] ``` {% endtab %} {% tab title="401 Permission denied" %} {% endtab %} {% endtabs %} ## 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. | {% tabs %} {% tab title="200: OK " %} {% code lineNumbers="true" %} ```json [ { "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 } ] ``` {% endcode %} {% endtab %} {% tab title="404: Not Found " %} {% endtab %} {% endtabs %} ## 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`. {% tabs %} {% tab title="200: OK " %} ```json [ { "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" }, {...} ] }, {...} ] ``` {% endtab %} {% endtabs %} ## 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 | | recipientEmailAddress | String | The email address where the gift voucher will be sent. If specified, the recipient receives the gift voucher directly. | | 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. | {% tabs %} {% tab title="200: OK An order will be created and returned" %} {% endtab %} {% tab title="400: Bad Request " %} {% endtab %} {% tab title="401: Unauthorized " %} {% endtab %} {% endtabs %} ## 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` | {% tabs %} {% tab title="400: Bad Request " %} {% endtab %} {% tab title="200: OK " %} {% endtab %} {% tab title="401: Unauthorized " %} {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.giftpro.co.uk/reference/orders.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.