Called when a purchase is created or updated.
This is a type of Webhook Integration event. It will be called when a purchase is created or updated.
Here is an example of a payload sent by the webhook endpoint:
{
"venue": {
"id": 4,
"name": "Fake Venue",
"slug": "fake-venue"
},
"purchase": {
"id": 1374,
"reference": "p_wDX4oMuamxyQIaeGP2",
"status": "paid",
"created_at": "2024-08-27T15:32:49.000Z",
"fullyPaidAt": "2024-08-27T15:33:15.000Z",
"confirmedAt": "2024-08-27T15:32:50.000Z",
"total": 1225,
"totalPaid": 1225,
"tax": {
"ADDITIVE": {},
"INCLUSIVE": {
"VAT 20": 204
}
},
"user": {
"id": 12194,
"email": "[email protected]",
"confirmed": true,
"telephone": null,
"firstName": "John",
"lastName": "Smith",
"created_at": "2024-02-02T11:11:56.000Z",
"blocked": false,
"balances": []
},
"lineItems": [
{
"type": "product",
"reference": "li_QKslMCEvP7Hd3jqTx",
"price": 225,
"basePrice": 250,
"discountedPrice": 225,
"group": "li_UPwmRFIrX9Jn4wwpr",
"descriptor": "Americano",
"tax": {
"ADDITIVE": {},
"INCLUSIVE": {
"VAT 20": 37
}
},
"category": "product>americano",
"notes": "",
"quantity": 1,
"status": "confirmed",
"appliedDiscounts": {
"11": 25
}
},
{
"type": "booking",
"reference": "li_UPwmRFIrX9Jn4wwpr",
"price": 1000,
"basePrice": 1000,
"discountedPrice": 1000,
"group": "li_UPwmRFIrX9Jn4wwpr",
"descriptor": "Booking #521919",
"tax": {
"ADDITIVE": {},
"INCLUSIVE": {
"VAT 20": 167
}
},
"category": "bay>1 hour",
"notes": "",
"quantity": 1,
"status": "confirmed",
"appliedDiscounts": {},
"booking": {} // {...}
}
],
"payments": [
{
"id": 1271,
"amount": 1250,
"status": "complete",
"reference": "expos_KOXkD2vAIk4qwmohJgqyVrN83",
"descriptor": "POS payment.",
"chargeType": {
"id": 2,
"name": "POS",
"type": "EXTERNAL"
}
}
],
"discounts": [
{
"id": 11,
"name": "Gold Member bar discount"
}
]
}
}
Standard Fields
Here is a quick breakdown of some of the less obvious fields on the user object:
- id - Unique integer id for this purchase.
- reference - Unique alphanumeric id for this purchase.
- status - The payment status - one of paid, unpaid, part_paid, overpaid, voided or draft.
- source - Where this payment originated. Will be one of:
- customer - Made by a customer directly, IE from an online checkout.
- admin - Made by a staff member from the admin panel.
- system - Automatically generated, such as for an automatic membership payment.
- total - Total payable price of this purchase, as a lowest currency denomination integer.
- totalPaid - Similar to the above, but a total of the payments made against the purchase.
- created_at - The date this purchase was created. In the case of a customer created purchase, this may somewhat predate the actual date of sale, as a customer's basket may be created some time before they finally transact.
- confirmedAt - The date this purchase transitioned out of draft state. For an admin created purchase this will likely be very shortly after the created_at date.
- fullyPaidAt - The date that this purchase's status transitioned to paid.
Line Items
The most important part of the purchase is the line items added to it. Line items can have various types, such as product, booking or top-up.
Depending on the type of line item, the properties available may be slightly different.
[
{
"type": "product",
"reference": "li_QKslMCEvP7Hd3jqTx",
"price": 225,
"basePrice": 250,
"discountedPrice": 225,
"group": "li_UPwmRFIrX9Jn4wwpr",
"descriptor": "Americano",
"tax": {
"ADDITIVE": {},
"INCLUSIVE": {
"VAT 20": 37
}
},
"category": "product>americano",
"notes": "",
"quantity": 1,
"status": "confirmed",
"appliedDiscounts": {
"11": 25
}
},
{
"type": "booking",
"reference": "li_UPwmRFIrX9Jn4wwpr",
"price": 1000,
"basePrice": 1000,
"discountedPrice": 1000,
"group": "li_UPwmRFIrX9Jn4wwpr",
"descriptor": "Booking #521919",
"tax": {
"ADDITIVE": {},
"INCLUSIVE": {
"VAT 20": 167
}
},
"category": "bay>1 hour",
"notes": "",
"quantity": 1,
"status": "confirmed",
"appliedDiscounts": {},
"booking": {} // {...}
}
]
General Line Item Fields
Some fields are standard to all line item types. For example:
- type - The type of the line item.
- price - Along with other price fields such as basePrice and discountedPrice.
- group - Whether the line item was added as part of a group. For example extras on a booking. These line items would have a group value that equals the reference of the line item they are parented to.
- descriptor - A short readable description of what the line item was.
- tax - An object summarising the tax applied to this line item.
- category - The reporting category configured on the main item that this line item relates to. For example the product or the bay option.
- status - Will be either confirmed or voided. Voided items are not for payment and their values will be excluded from any totals.
- appliedDiscounts - An object where the keys are the id of the discount applied, and the value is the integer cash amount that has been discounted. Details of the discounts applied to the purchase can be found under discounts.
Booking Line Items
Booking line items will have a related booking field, which gives some more information about what was purchased.
There are currently two kinds of bookings, bay bookings and course bookings. They have different fields and reference different objects in the system.
Here are some example booking fields on line items for bookings of each type:
Bay Bookings
// {... booking:
{
"id": 521920,
"type": "bay",
"start": "2024-08-28T12:00:00.000Z",
"status": "confirmed",
"created_at": "2024-08-28T11:36:31.000Z",
"playerOptions": [
{
"id": 3,
"name": "Child",
"subtitle": "Under 16",
"quantity": 1
},
{
"id": 8,
"name": "Adult",
"subtitle": "16 +",
"quantity": 1
}
],
"end": "2024-08-28T12:30:00.000Z",
"range": {
"id": 1
},
"bay": {
"id": 61,
"ref": "6"
},
"bayOption": {
"id": 175,
"name": "30 Mins",
"duration": 1,
"subtitle": "50 Balls Included"
}
}
// ...}
Course Bookings
// {... booking:
{
"id": 521921,
"type": "course",
"start": "2024-08-29T09:18:00.000Z",
"status": "confirmed",
"created_at": "2024-08-28T11:36:31.000Z",
"playerOptions": [
{
"id": 1,
"name": "Adult",
"subtitle": "Weekday Price",
"quantity": 1
}
],
"course": {
"id": 1,
"name": "Fruity Fairway"
},
"courseOption": {
"id": 3,
"name": "18 Holes",
"duration": 120
},
"loop1": "2024-08-29T11:30:00.000Z",
"loop2": null
}
// ...}
Payments
Payments, as expected, are created whenever a customer transacts. Each one will have a chargeType which gives information about the kind of payment and the source of the funds. Particularly important is the chargeType's type. This will be a broader category that tells you where the money came from.
[
{
"id": 1271,
"amount": 1250,
"status": "complete",
"reference": "expos_KOXkD2vAIk4qwmohJgqyVrN83",
"descriptor": "POS payment.",
"chargeType": {
"id": 2,
"name": "POS",
"type": "EXTERNAL"
}
}
]
Some payments may have a negative value - these are refunds. They also will have their own charge type, which helps to explain how the funds were returned to the customer.
Discounts
Discounts are added in the discounts array on the purchase object. It will show the list of all discounts applied to the purchase.
{
//...
"discounts": [
{
"id": 11,
"name": "Gold Member bar discount"
}
]
//...
}
If you want to see exactly what discount was applied per line item, you can check the appliedDiscounts field on that item.
{
//...
lineItems: [
{
"type": "product",
"reference": "li_QKslMCEvP7Hd3jqTx",
"price": 225,
"basePrice": 250,
"discountedPrice": 225,
"group": "li_UPwmRFIrX9Jn4wwpr",
"descriptor": "Americano",
"tax": {
"ADDITIVE": {},
"INCLUSIVE": {
"VAT 20": 37
}
},
"category": "product>americano",
"notes": "",
"quantity": 1,
"status": "confirmed",
"appliedDiscounts": {
"11": 25
}
},
//...
]
//...
}
In this instance, the discount with id 11 has been added to this line item, and it has discounted £0.25 from the Americano purchased. This is reflected in the discountedPrice.