You can use this API endpoint to create a voucher order on Smart Gift; the sale will be processed as if it was placed on Smart Gift and an order confirmation email will also be sent if the delivery method is online, so you do not have to worry about processing these yourself.
POST REQUEST (/pos-sale)
Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXXThe body of this request takes an array of items, objects describing the customer and delivery data, and an integer
representing the payment method ID.
We also require a reference that is unique to your own system, this is appended to the company id in our system to create a unique reference.
Below we show the objects that comprise the request body in their individual parts.
A question mark following the field's type indicates that it is optional.
The items field is an array of items (or vouchers) to purchase from Smart Gift.
id: int;
price: float?;
to: String?;
from: String?;
message: String?;
code: String?;
persons: int?;
The id field is always required and the price field is always required when the id is the id of a monetary voucher. If the id of an experience voucher is provided, the price of this is calculated within Smart Gift based on the experience and the number of persons the experience is for. The persons field defaults to a value of 1 if not explicitly stated in the request. If explicitly stated (or implicitly assumed) persons is not within the vouchers minimum and maximum range for persons, an error response will be returned.
Each item, or voucher, can also be given 'to', 'from', and 'message' attributes. These are used as they would be in a letter or card, with the to and from being intended recipient and sender respectively, and the message being a message from the sender to the recipient. All of these attributes are printed on the voucher during the creation process if present. If you would like to stipulate the code that the voucher should have, you may provide the code within this object. This code must be unique and only contain alphanumeric characters, if you provide a code that is not unique or contains illegal characters, you will receive an error response.
first_name: String?;
last_name: String?;
email: String;
address1: String?;
address2: String?;
postcode: String?;
town: String?;
county: String?The customer field holds an object representing the customer making the purchase for this order. This simplified API call requires only an email address for the customer object.
method: int;
email: String?; // required if online delivery method is used
address1: String?; // required if offline delivery method is used
address2: String?;
postcode: String?; // required if offline delivery method is used
town: String?;
county: String?The delivery field expects an object with an 'always required' method field. If you use an offline delivery method then the line1 and postcode fields are required to ensure it is sent correctly. You may also provide a date to have your vouchers delivered on a certain date in the future. If the current date, a past date or an invalid date, are provided, this the order will be sent immediately. The same is true if the date field is omitted.
The payment_method field is an integer matching one of the available payment methods ni Smart Gift. You can find instructions for querying the available payment methods here.
Finally, you may provide an order_id which is a reference used to identify your order in the future. This should be unique to your integration but does not need to be globally unique or unique within Smart Gift as this will be processed before being stored in Smart Gift.
{
"items": [
{
"id": 1,
"price": 100.00,
"to": "Recipient #1",
"from": "Sender",
"message": "Here is an example voucher for you to enjoy!",
"code": "EXAMPLECODE1"
},
{
"id": 1,
"price": 100.00,
"from": "Recipient #2",
"to": "Sender",
"message": "Here is an example voucher for you to enjoy!",
"code": "EXAMPLECODE2"
}
],
"customer": {
"first_name": "John",
"last_name": "Smith",
"email": "customer@example.com",
"address1": "Bank Chambers",
"address2": "High Street",
"postcode": "NP11 4EY",
"town": "Newbridge",
"county": "Newport"
},
"delivery": {
"method": 1,
"email": "recipient@example.com",
"date": null,
"town": null,
"county": null,
"address1": null,
"address2": null,
"postcode": null,
"last_name": null,
"first_name": null
},
"payment_method": 1,
"order_id": "123"
}
Optional items can be omitted, you do not need to pass null as a value. A shortened version can be seen below to illustrate the simplicity of this API call.
{
"items": [
{
"id": 1,
"price": 100.00
}
],
"customer": {
"email": "customer@example.com",
},
"delivery": {
"method": 1,
"email": "recipient@example.com",
},
"payment_method": 1
}
This API will return the order_id of the newly created order, this may be identical to the provided order_id or it may be changed by us to maintain uniqueness of the order_id. You should use this returned value as the reference for the posted order within the Smart Gift system.
{
"message": "Order processed successfully!",
"order_reference": "SAMPLEORDERREFERENCE",
"voucher_codes": [
"EXAMPLECODE1",
"EXAMPLECODE2"
]
}