{warning} This API is likely to change before the Beta period is over, please check back regularly to see the latest changes.
You can use this API endpoint to send us sales, the sale will be processed as if it was placed on Smart Gift, an order confirmation email will also be sent, so you do not have to worry about processing these yourself.
POST REQUEST (/sale)
Header: Content-Type application/json
Header: Accept application/json
Header: Smart-Auth sk_XXXXXXXXXXXXXXXXXXThe body of this request is an object representing a cart. It contains an array of items, a customer and at least a delivery with
type and price. The Payment method ID is also required, see the docs for Payment Methods for more info.
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.
The items field is an array of items (e.g vouchers) to purchase from Smart Gift. 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.
The customer field holds an object representing the customer making the purchase for this order. All of the shown fields in the below example are required with the exception of address2. This is effectively a name, email and billing address.
The delivery field expects an object with required fields of delivery_method and price. If you use an offline delivery method then you should provide the full address to ensure it is sent correctly. You may also provide a delivery date to have your order 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 as if the delivery_date value was not provided.
The totals field is an object containing total and subtotal properties, both of which are required. The total amount must perfectly match the sum of the amounts from all payments, if it does not then the order will not be processed. Assuming that the vouchers have been paid for in full within your own application, you will have identical subtotal and total amounts, and you will also have payments that equal this amount too (See next).
The payments field is an array of payment objects that represent what has been paid for the order. Payments are offset against what is owed and the total (mentioned above) must be equal to the sum of amounts of payments in this array. The amount field is the amount that has been paid and the payment_method_id references a payment method in Smart Gift that this payment should be assigned to.
Finally, you must 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.
{
"cart": {
"items": [
{
"id": "270",
"price": 150.00,
"total": 150,
"to": null,
"from": null,
"message": null,
}
],
"totals": {
"total": 150.5,
"subtotal": 150.5
},
"customer": {
"first_name": "Marty",
"last_name": "Gift",
"email": "marty.gift@smart-gift.co.uk",
"address1": "Bank Chambers",
"address2": "High Street",
"postcode": "NP11 4EY",
"town": "Newbridge",
"county": "Newport"
},
"delivery": {
"price": 0.50,
"delivery_method": 12,
"delivery_email": null,
"delivery_date": null,
"name": "Email Delivery",
"town": null,
"county": null,
"address1": null,
"address2": null,
"postcode": null,
"last_name": null,
"first_name": null,
"description": null,
},
"payments": [
{
"amount": 150.5, // (must match totals total)
"payment_method_id": 11
}
]
},
"order_id": "123"
}
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.
{
"data": {
"order_id": "oWg9LWe6G"
}
}