Orders
Orders are replicas of the orders generated by external software (e.g. web shops, ordering apps, POS systems, kiosks et cetera), to be used by Leat as the drivi
Orders are replicas of the orders generated by external software (e.g. web shops, ordering apps, POS systems, kiosks et cetera), to be used by Leat as the driving force behind our Loyalty, Marketing, Data and Automation tools. In the Leat dashboard, clients can setup Actions to be triggered after the successful creation of an Order in the Leat system. This can result in Leat objects such as a Points Transaction or a Prepaid Transaction.
Using Orders for Loyalty purposes requires two steps:
- Creating the Order: Replicates the Order in the Leat system.
- Processing the Order: Clients will set up their so-called Order Action in their dashboard to decide how to process the Order within the Leat system. This will usually entail converting the Order into a Points Transaction (currently the only option, to be extended in the near future).
For some integrations, it makes sense to split the two steps, and only perform the second step under certain circumstances. For most integrations, however, both steps are required. To make it easier for those, a combined Create and Process Order endpoint has been added.
New conventions
Please note: this API call uses conventions that will be used in the V4 version of our API and from this points onwards. If you're already familiar with our API, take note of the following:
- 'business_profile' instead of 'shop': This entity has already been renamed in the Leat dashboard for some time now and will be named as such in API calls.
- Refactor of Credit Receptions: As part of a larger refactor of the core of our Loyalty engine, some new entities have been introduced, whilst others have been renamed. For this particular API, this means a
points_transactionwill be returned as a result instead ofcredit_reception. - Input parameters: For previous API endpoints, input parameters like a Contact's UUID were given as
contact_uuid. In this newest endpoint, an object is expected instead.
Create And Process Order
RECOMMENDED
Creates a new Order in the Leat system and directly processes it. Returns both the Order entity itself and a result object containing the result of the Order Action as configured by the Client. Currently, the only type of Order Action supported is the creation of a Points Transaction. However, please take into account that more result types will be added in the future (e.g. Prepaid Transaction).
Note that all monetary amounts – like total_order_amount – are to be given in the currency's lowest denomination (e.g. €34,50 -> 3450).
When creating Orders, the best practice is to create the Order as completely as you can. This includes linking Products and any Leat-actions that may have been undertaken in the Order process (e.g. Reward Redemptions, Voucher Redemptions, Giftcard Transactions etc.). Some best practices to take into account:
external_identifier:This is the main identifier from your system, usually a UUID or GUID or some other. It's imperative this is unique across all Orders.order_amount, total_order_amount, total_discount_amount:These are mainly for visual and reference purposes. When Orders are using in Order Actions (to make Points Transactions, for instance), these values will be largely ignored. To account for product-specific exclusions and rules, the order amounts used in calculations and actions will be calculated using the line items, charges and discounts. Still, please ensure these match the content to prevent any confusion.line_items.external_identifier:This is the unique identifier of this line item. Another line item of the same product should have their own unique identifier.line_items.total_amount:The total amount of a line items ought to be the line items' price times the quantity, minus the discount amount. The total amount does not include the total amounts of any sub line items. They are counted separately.line_items.product:For a host of features in Leat, it's imperative the product is linked (if present). The external identifier counts as the main unique identifier of the product, which is of course static for the same product across multiple line items and orders. If no product yet exists for the external identifier, one will be created. However, to fully enable the Product filtering feature, it's highly recommended to create the entire product library, including categories, upon integration installation.line_items.sub_line_items:Line items may include sub line items, like modifiers. Note: the total amounts of the sub line items count separately from the line item's total amount. Example: a line item for a 'Pizza Margherita' with a total amount of 1200 ($12) may include a sub line item for 'Extra Cheese' with a total amount of 100 ($1), which would bring the total order amount to 1600 ($16). The $1 from the sub line item is not included in the total amount on the parent line item. Sub line items are to be linked to products in the same way as their parent line items.line_items.result:This is the 'Leat result' of this line item, if any exists. Examples of this is when a customer buys a Gift card or a Voucher. This would be reflected as a line item on the Order and the resulting Giftcard Transaction (usually created after payment has succeeded) can be linked as a result. Highly recommended to link if present.applied_discounts:If one or more discounts have been applied to the order, these should be added here. Discounts are either applied on an Order level, or on a (Sub)Line Item level. In the latter, the applied discount should also be reflected in the discount amount on the individual (sub) line item(s).applied_discounts:If one or more discounts have been applied to the order, these should be added here. Discounts are either applied on an Order level, or on a (Sub)Line Item level. In the latter, the applied discount should also be reflected in the discount amount on the individual (sub) line item(s) and/or charges. In such a case, the specific items should also be linked to the discount via the line items, sub line items and charges parameters.applied_discounts.offer:If the applied discount was the result of a Leat offer (e.g. Reward Redemption, Voucher Redemption etc.), this offer should be added to the discount. Highly recommended to link if present.charges:Charges are costs that are applied after (sub) line items. Examples include gratuity, service charges, shipping, wrapping or taxes (all of these are default Charge Definitions). In the case of taxes, there are only a few use cases in which taxes are to be included as separate charges. Most often, it's preferable to include them in the line items price instead of as separate charges. Charge Definitions are what Products are to Line Items.payments:Currently, only Leat-specific payments can be added here. Payment methods like credit card or cash are not to be sent in. If (part of) the order was paid using Leat payment methods (Giftcards, Prepaid), these should be linked here.
If you have any questions about Orders, please reach out to your partnership manager or contact us at dev@leat.com.
POST
https://api.piggy.eu/api/v3/oauth/clients/orders/create-and-processHeaders
Authorization
Accept
Bearer {{ personal_access_token }}
application/json
Input parameters
external_identifier string
required
A unique identifier from your system
reference string
optional
A human readable identifier from your system, for reference purposes only
status string
required
Status of the order
Possible values:
CREATEDOrder has just been created, not yet completed
PENDINGPending fulfilment and/or payment
COMPLETEDOrder has been completed
CANCELLEDOrder was cancelled before completion
payment_status string
required
Status of the payment of the order
Possible values:
UNPAIDPayment process has not been started
PENDINGPayment process started, pending confirmation
PAIDPayment successful
total_order_amount number
required
Total order amount, including all discounts and charges, in the currency's lowest denomination.
order_amount number
optional
Sum of total amounts of all (sub) line items – including item-based discounts – before order-based discounts and charges, in the currency's lowest denomination.
total_discount_amount number
optional
Total discount amount, in the currency's lowest denomination
currency string
optional
Order currency in ISO 4217 format; defaults to Account's default currency
paid_at string
optional
The date and time this Order was paid, in ISO 8601 format
completed_at string
optional
The date and time this Order was completed, in ISO 8601 format
contact
object
required
Contact who made the Order
uuid string
required
UUID of the Contact
business_profile
object
required
Location where the Order took place
uuid string
required
UUID of the Business Profile
line_items
array of objects
required
List of Products in this Order
external_identifier string
required
A unique identifier for this Line Item
name string
required
Name of the Line Item
quantity number
required
Quantity of the Line Item
price number
required
Price per unit of this Line Item
total_amount number
required
Total amount of this Line Item, in the currency's lowest denomination, after discounts
discount_amount number
optional
Discount amount of this Line Item, in the currency's lowest denomination
product
object
optional
Associated Product, which enables the Product filtering feature, optional but highly recommended.
external_identifier string
required
Unique identifier to identify the Product, Product will be created using external_identifier and line_item.name if not found
result
object
optional
Resulting Leat object, if applicable. Possible options: Giftcard Transaction, Prepaid Transaction and Voucher.
uuid string
required
UUID used to identify the resulting Leat object
type string
required
Type of the resulting Leat object
Possible values:
GIFTCARD_TRANSACTIONGiftcard Transaction
PREPAID_TRANSACTIONPrepaid Transaction
VOUCHERVoucher
sub_line_items
array of objects
optional
List of Sub Line Items of this Line Item
external_identifier string
required
A unique identifier for this Sub Line Item
name string
required
Name of the Sub Line Item
quantity number
required
Quantity of the Sub Line Item
price number
required
Price per unit of this Sub Line Item
total_amount number
required
Total amount of this Sub Line Item, in the currency's lowest denomination, after discounts
discount_amount number
optional
Discount amount of this Sub Line Item, in the currency's lowest denomination
product
object
optional
Associated Product, which enables the Product filtering feature, optional but highly recommended.
external_identifier string
required
Unique identifier to identify the Product, Product will be created using external_identifier and sub_line_item.name if not found
applied_discounts
array of objects
optional
List of Discounts applied to this Order
external_identifier string
required
Unique identifier to the Discount
name string
required
Name of the Discount
amount number
required
Resulting monetary discount amount in the currency's lowest denomination
type string
optional
Type of the Discount
Possible values:
PERCENTAGEFor percentage based discounts
ABSOLUTEFor absolute discounts
value number
optional
The value of either the percentage or absolute discount
applied_to string
required
Indicates if Discount is applied to Order or to one or more (Sub) Line Items
Possible values:
ORDERIndicates Discount is applied on an Order level
ORDER_LINESIndicates Discount is applied to individual Line Items, Sub Line Items, and/or Charges
line_items
array of objects
optional
List of Line Items to which this Discount was applied
external_identifier string
required
Unique identifier to the Line Item with which it's identified under line_items
sub_line_items
array of objects
optional
List of Sub Line Items to which this Discount was applied
external_identifier string
required
Unique identifier to the Sub Line Item with which it's identified under sub_line_items
charges
array of objects
optional
List of Charges to which this Discount was applied
external_identifier string
required
Unique identifier to the Charge with which it's identified under charges
offer
object
optional
Corresponding Leat Offer if applicable. Possible options: Reward Redemption, Collectable Reward Redemption and Voucher Redemption.
uuid string
required
UUID used to identify the Leat offer redemption
type string
required
Type of the Leat Offer
Possible values:
REWARD_REDEMPTIONReward Redemption
COLLECTABLE_REWARD_REDEMPTIONCollectable Reward Redemption
VOUCHER_REDEMPTIONVoucher Redemption
charges
array of objects
optional
Any charges not included as line items. E.g. gratuity, service charges or shipping
external_identifier string
required
Unique identifier to the Charge
type string
optional
deprecated
Deprecated: Please use charge_definition instead.
name string
required
A human readable reference to the charge
amount number
optional
The cost of the charge, before discounts, in the currency's lowest denomination
discount_amount number
optional
The discount amount, in the currency's lowest denomination
total_amount number
required
The total cost of the charge, after discounts, in the currency's lowest denomination
charge_definition
object
optional
The charge definition, for use in rules and exclusions. Every account has a few definitions by default, with external identifiers: SERVICE_CHARGE.
Default definitions:
SERVICE_CHARGEA service charge applied to the order
GRATUITYGratuity or tip
SHIPPINGShipping costs
WRAPPINGWrapping costs
TAXSeparate tax charges. Do not add if taxes are already included in line item total amounts.
external_identifier string
required
Unique identifier to identify the Charge Definition, Charge Definition will be created using external_identifier and charge.name if not found
payments
array of objects
optional
Any payments made for this Order using Leat objects. Note: currently accepts Giftcard Transactions and Prepaid Transactions only.
uuid string
required
UUID used to identify the Leat Payment
type string
required
Type of Leat Payment
Possible values:
GIFTCARD_TRANSACTIONGiftcard Transaction
PREPAID_TRANSACTIONPrepaid Transaction
Response Example
{
"data": {
"order": {
"uuid": "bfada889-6a69-4fcf-aed6-42933ae9084d",
"contact": {
"uuid": "12345-abcdefg-6789-yuiop",
"email": "spongebob@bikinibottom.sea"
},
"business_profile": {
"uuid": "12345-abcdefg-6789-yuiop",
"name": "HeadQuarters"
},
"external_identifier": "EXT-0012",
"reference": "Order B-2110",
"status": "COMPLETED",
"payment_status": "PAID",
"currency": "EUR",
"formatted_total_order_amount": "€ 33.31",
"order_amount": 3175,
"total_charges_amount": 381,
"total_discount_amount": 225,
"total_order_amount": 3331,
"paid_at": "2025-05-01T20:10:44+00:00",
"completed_at": "2025-05-01T20:11:03+00:00",
"line_items": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "LI_IT_11090_lkajsf",
"name": "Double Krabby Patty",
"quantity": 2,
"price": 1250,
"total_amount": 2500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
"sub_line_items": [
{
"uuid": "87a4be97-73dd-40a4",
"external_identifier": "SU_LI_IT_11090_lkajsf",
"name": "Extra Secret Sauce",
"quantity": 1,
"price": 500,
"total_amount": 500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-15-454",
"name": "Extra Secret Sauce",
}
}
]
},
{
"uuid": "187-8Dfadf3-lsdf234ds-99ass",
"external_identifier": "LI_IT_991_Ac990s",
"name": "Kelp Soda",
"quantity": 2,
"price": 450,
"total_amount": 675,
"discount_amount": 225,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
},
],
"applied_discounts": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "DISC_25_OFF_DRINKS",
"name": "25% off Drinks",
"amount": 225,
"type": "PERCENTAGE",
"value": 25,
"applied_to": "LINE_ITEM",
"line_items": [
{
"external_identifier": "LI_IT_991_Ac990s",
},
],
},
"charges": [
{
"external_identifier": "SRV_CH-12",
"type": "SERVICE_CHARGE",
"name": "Service charge: 12%",
"amount": 381,
"discount_amount": 0,
"total_amount": 0
},
],
"created_at": "2025-05-01T20:11:58+00:00",
"updated_at": "2025-05-01T20:11:58+00:00"
},
"result": {
"type": "POINTS_TRANSACTION",
"data": {
"points": 35,
"new_balance": 2267,
}
}
},
"meta": []
}Create Order
Creates a new Order in the Leat system. It does not yet process the Order, so no Points Transaction will be created just yet. Call the Process Order endpoint to convert the Order into a Points Transaction. Alternatively, use the Create and Process Order endpoint instead.
Note that all monetary amounts – like total_order_amount – are to be given in the currency's lowest denomination (e.g. €34,50 -> 3450).
When creating Orders, the best practice is to create the Order as completely as you can. This includes linking Products and any Leat-actions that may have been undertaken in the Order process (e.g. Reward Redemptions, Voucher Redemptions, Giftcard Transactions etc.). Some best practices to take into account:
external_identifier:This is the main identifier from your system, usually a UUID or GUID or some other. It's imperative this is unique across all Orders.order_amount, total_order_amount, total_discount_amount:These are mainly for visual and reference purposes. When Orders are using in Order Actions (to make Points Transactions, for instance), these values will be largely ignored. To account for product-specific exclusions and rules, the order amounts used in calculations and actions will be calculated using the line items, charges and discounts. Still, please ensure these match the content to prevent any confusion.line_items.external_identifier:This is the unique identifier of this line item. Another line item of the same product should have their own unique identifier.line_items.total_amount:The total amount of a line items ought to be the line items' price times the quantity, minus the discount amount. The total amount does not include the total amounts of any sub line items. They are counted separately.line_items.product:For a host of features in Leat, it's imperative the product is linked (if present). The external identifier counts as the main unique identifier of the product, which is of course static for the same product across multiple line items and orders. If no product yet exists for the external identifier, one will be created. However, to fully enable the Product filtering feature, it's highly recommended to create the entire product library, including categories, upon integration installation.line_items.sub_line_items:Line items may include sub line items, like modifiers. Note: the total amounts of the sub line items count separately from the line item's total amount. Example: a line item for a 'Pizza Margherita' with a total amount of 1200 ($12) may include a sub line item for 'Extra Cheese' with a total amount of 100 ($1), which would bring the total order amount to 1600 ($16). The $1 from the sub line item is not included in the total amount on the parent line item. Sub line items are to be linked to products in the same way as their parent line items.line_items.result:This is the 'Leat result' of this line item, if any exists. Examples of this is when a customer buys a Gift card or a Voucher. This would be reflected as a line item on the Order and the resulting Giftcard Transaction (usually created after payment has succeeded) can be linked as a result. Highly recommended to link if present.applied_discounts:If one or more discounts have been applied to the order, these should be added here. Discounts are either applied on an Order level, or on a (Sub)Line Item level. In the latter, the applied discount should also be reflected in the discount amount on the individual (sub) line item(s).applied_discounts:If one or more discounts have been applied to the order, these should be added here. Discounts are either applied on an Order level, or on a (Sub)Line Item level. In the latter, the applied discount should also be reflected in the discount amount on the individual (sub) line item(s) and/or charges. In such a case, the specific items should also be linked to the discount via the line items, sub line items and charges parameters.applied_discounts.offer:If the applied discount was the result of a Leat offer (e.g. Reward Redemption, Voucher Redemption etc.), this offer should be added to the discount. Highly recommended to link if present.charges:Charges are costs that are applied after (sub) line items. Examples include gratuity, service charges, shipping, wrapping or taxes (all of these are default Charge Definitions). In the case of taxes, there are only a few use cases in which taxes are to be included as separate charges. Most often, it's preferable to include them in the line items price instead of as separate charges. Charge Definitions are what Products are to Line Items.payments:Currently, only Leat-specific payments can be added here. Payment methods like credit card or cash are not to be sent in. If (part of) the order was paid using Leat payment methods (Giftcards, Prepaid), these should be linked here.
If you have any questions about Orders, please reach out to your partnership manager or contact us at dev@leat.com.
POST
https://api.piggy.eu/api/v3/oauth/clients/ordersHeaders
Authorization
Accept
Bearer {{ personal_access_token }}
application/json
Input parameters
external_identifier string
required
A unique identifier from your system
reference string
optional
A human readable identifier from your system, for reference purposes only
status string
required
Status of the order
Possible values:
CREATEDOrder has just been created, not yet completed
PENDINGPending fulfilment and/or payment
COMPLETEDOrder has been completed
CANCELLEDOrder was cancelled before completion
payment_status string
required
Status of the payment of the order
Possible values:
UNPAIDPayment process has not been started
PENDINGPayment process started, pending confirmation
PAIDPayment successful
total_order_amount number
required
Total order amount, including all discounts and charges, in the currency's lowest denomination.
order_amount number
optional
Sum of total amounts of all (sub) line items – including item-based discounts – before order-based discounts and charges, in the currency's lowest denomination.
total_discount_amount number
optional
Total discount amount, in the currency's lowest denomination
currency string
optional
Order currency in ISO 4217 format; defaults to Account's default currency
paid_at string
optional
The date and time this Order was paid, in ISO 8601 format
completed_at string
optional
The date and time this Order was completed, in ISO 8601 format
contact
object
required
Contact who made the Order
uuid string
required
UUID of the Contact
business_profile
object
required
Location where the Order took place
uuid string
required
UUID of the Business Profile
line_items
array of objects
required
List of Products in this Order
external_identifier string
required
A unique identifier for this Line Item
name string
required
Name of the Line Item
quantity number
required
Quantity of the Line Item
price number
required
Price per unit of this Line Item
total_amount number
required
Total amount of this Line Item, in the currency's lowest denomination, after discounts
discount_amount number
optional
Discount amount of this Line Item, in the currency's lowest denomination
product
object
optional
Associated Product, which enables the Product filtering feature, optional but highly recommended.
external_identifier string
required
Unique identifier to identify the Product, Product will be created using external_identifier and line_item.name if not found
result
object
optional
Resulting Leat object, if applicable. Possible options: Giftcard Transaction, Prepaid Transaction and Voucher.
uuid string
required
UUID used to identify the resulting Leat object
type string
required
Type of the resulting Leat object
Possible values:
GIFTCARD_TRANSACTIONGiftcard Transaction
PREPAID_TRANSACTIONPrepaid Transaction
VOUCHERVoucher
sub_line_items
array of objects
optional
List of Sub Line Items of this Line Item
external_identifier string
required
A unique identifier for this Sub Line Item
name string
required
Name of the Sub Line Item
quantity number
required
Quantity of the Sub Line Item
price number
required
Price per unit of this Sub Line Item
total_amount number
required
Total amount of this Sub Line Item, in the currency's lowest denomination, after discounts
discount_amount number
optional
Discount amount of this Sub Line Item, in the currency's lowest denomination
product
object
optional
Associated Product, which enables the Product filtering feature, optional but highly recommended.
external_identifier string
required
Unique identifier to identify the Product, Product will be created using external_identifier and sub_line_item.name if not found
applied_discounts
array of objects
optional
List of Discounts applied to this Order
external_identifier string
required
Unique identifier to the Discount
name string
required
Name of the Discount
amount number
required
Resulting monetary discount amount in the currency's lowest denomination
type string
optional
Type of the Discount
Possible values:
PERCENTAGEFor percentage based discounts
ABSOLUTEFor absolute discounts
value number
optional
The value of either the percentage or absolute discount
applied_to string
required
Indicates if Discount is applied to Order or to one or more (Sub) Line Items
Possible values:
ORDERIndicates Discount is applied on an Order level
ORDER_LINESIndicates Discount is applied to individual Line Items, Sub Line Items, and/or Charges
line_items
array of objects
optional
List of Line Items to which this Discount was applied
external_identifier string
required
Unique identifier to the Line Item with which it's identified under line_items
sub_line_items
array of objects
optional
List of Sub Line Items to which this Discount was applied
external_identifier string
required
Unique identifier to the Sub Line Item with which it's identified under sub_line_items
charges
array of objects
optional
List of Charges to which this Discount was applied
external_identifier string
required
Unique identifier to the Charge with which it's identified under charges
offer
object
optional
Corresponding Leat Offer if applicable. Possible options: Reward Redemption, Collectable Reward Redemption and Voucher Redemption.
uuid string
required
UUID used to identify the Leat offer redemption
type string
required
Type of the Leat Offer
Possible values:
REWARD_REDEMPTIONReward Redemption
COLLECTABLE_REWARD_REDEMPTIONCollectable Reward Redemption
VOUCHER_REDEMPTIONVoucher Redemption
charges
array of objects
optional
Any charges not included as line items. E.g. gratuity, service charges or shipping
external_identifier string
required
Unique identifier to the Charge
type string
optional
deprecated
Deprecated: Please use charge_definition instead.
name string
required
A human readable reference to the charge
amount number
optional
The cost of the charge, before discounts, in the currency's lowest denomination
discount_amount number
optional
The discount amount, in the currency's lowest denomination
total_amount number
required
The total cost of the charge, after discounts, in the currency's lowest denomination
charge_definition
object
optional
The charge definition, for use in rules and exclusions. Every account has a few definitions by default, with external identifiers: SERVICE_CHARGE.
Default definitions:
SERVICE_CHARGEA service charge applied to the order
GRATUITYGratuity or tip
SHIPPINGShipping costs
WRAPPINGWrapping costs
TAXSeparate tax charges. Do not add if taxes are already included in line item total amounts.
external_identifier string
required
Unique identifier to identify the Charge Definition, Charge Definition will be created using external_identifier and charge.name if not found
payments
array of objects
optional
Any payments made for this Order using Leat objects. Note: currently accepts Giftcard Transactions and Prepaid Transactions only.
uuid string
required
UUID used to identify the Leat Payment
type string
required
Type of Leat Payment
Possible values:
GIFTCARD_TRANSACTIONGiftcard Transaction
PREPAID_TRANSACTIONPrepaid Transaction
Response Example
{
"data": {
"uuid": "bfada889-6a69-4fcf-aed6-42933ae9084d",
"contact": {
"uuid": "12345-abcdefg-6789-yuiop",
"email": "spongebob@bikinibottom.sea"
},
"business_profile": {
"uuid": "12345-abcdefg-6789-yuiop",
"name": "HeadQuarters"
},
"external_identifier": "EXT-0012",
"reference": "Order B-2110",
"status": "COMPLETED",
"payment_status": "PAID",
"currency": "EUR",
"formatted_total_order_amount": "€ 33.31",
"order_amount": 3175,
"total_charges_amount": 381,
"total_discount_amount": 225,
"total_order_amount": 3331,
"paid_at": "2025-05-01T20:10:44+00:00",
"completed_at": "2025-05-01T20:11:03+00:00",
"line_items": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "LI_IT_11090_lkajsf",
"name": "Double Krabby Patty",
"quantity": 2,
"price": 1250,
"total_amount": 2500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
"sub_line_items": [
{
"uuid": "87a4be97-73dd-40a4",
"external_identifier": "SU_LI_IT_11090_lkajsf",
"name": "Extra Secret Sauce",
"quantity": 1,
"price": 500,
"total_amount": 500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-15-454",
"name": "Extra Secret Sauce",
}
}
]
},
{
"uuid": "187-8Dfadf3-lsdf234ds-99ass",
"external_identifier": "LI_IT_991_Ac990s",
"name": "Kelp Soda",
"quantity": 2,
"price": 450,
"total_amount": 675,
"discount_amount": 225,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
},
],
"applied_discounts": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "DISC_25_OFF_DRINKS",
"name": "25% off Drinks",
"amount": 225,
"type": "PERCENTAGE",
"value": 25,
"applied_to": "LINE_ITEM",
"line_items": [
{
"external_identifier": "LI_IT_991_Ac990s",
},
],
},
"charges": [
{
"external_identifier": "SRV_CH-12",
"type": "SERVICE_CHARGE",
"name": "Service charge: 12%",
"amount": 381,
"discount_amount": 0,
"total_amount": 0
},
],
"created_at": "2025-05-01T20:11:58+00:00",
"updated_at": "2025-05-01T20:11:58+00:00"
},
"meta": []
}Process Order
Processes an existing Order in the Leat system and returns a result object. If an Order Action was configured for the Account, then this is executed in sync and will fill the result object. An example of such a result would be a transaction containing loyalty points.
POST
https://api.piggy.eu/api/v3/oauth/clients/orders/{uuid}/processHeaders
Authorization
Accept
Bearer {{ personal_access_token }}
application/json
Input parameters
uuid string
required
The uuid of the order in your Leat system
Response Example
{
"data": {
"type": "POINTS_TRANSACTION",
"data": {
"points": 35,
"new_balance": 2267,
}
},
"meta": []
}Find Order
Use the external_identifier to find an Order.
GET
https://api.piggy.eu/api/v3/oauth/clients/orders/findHeaders
Authorization
Accept
Bearer {{ personal_access_token }}
application/json
Input parameters
external_identifier string
required
A unique identifier from your system
Response Example
{
"data": {
"uuid": "bfada889-6a69-4fcf-aed6-42933ae9084d",
"contact": {
"uuid": "12345-abcdefg-6789-yuiop",
"email": "spongebob@bikinibottom.sea"
},
"business_profile": {
"uuid": "12345-abcdefg-6789-yuiop",
"name": "HeadQuarters"
},
"external_identifier": "EXT-0012",
"reference": "Order B-2110",
"status": "COMPLETED",
"payment_status": "PAID",
"currency": "EUR",
"formatted_total_order_amount": "€ 33.31",
"order_amount": 3175,
"total_charges_amount": 381,
"total_discount_amount": 225,
"total_order_amount": 3331,
"paid_at": "2025-05-01T20:10:44+00:00",
"completed_at": "2025-05-01T20:11:03+00:00",
"line_items": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "LI_IT_11090_lkajsf",
"name": "Double Krabby Patty",
"quantity": 2,
"price": 1250,
"total_amount": 2500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
"sub_line_items": [
{
"uuid": "87a4be97-73dd-40a4",
"external_identifier": "SU_LI_IT_11090_lkajsf",
"name": "Extra Secret Sauce",
"quantity": 1,
"price": 500,
"total_amount": 500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-15-454",
"name": "Extra Secret Sauce",
}
}
]
},
{
"uuid": "187-8Dfadf3-lsdf234ds-99ass",
"external_identifier": "LI_IT_991_Ac990s",
"name": "Kelp Soda",
"quantity": 2,
"price": 450,
"total_amount": 675,
"discount_amount": 225,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
},
],
"applied_discounts": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "DISC_25_OFF_DRINKS",
"name": "25% off Drinks",
"amount": 225,
"type": "PERCENTAGE",
"value": 25,
"applied_to": "LINE_ITEM",
"line_items": [
{
"external_identifier": "LI_IT_991_Ac990s",
},
],
},
"charges": [
{
"external_identifier": "SRV_CH-12",
"type": "SERVICE_CHARGE",
"name": "Service charge: 12%",
"amount": 381,
"discount_amount": 0,
"total_amount": 0
},
],
"created_at": "2025-05-01T20:11:58+00:00",
"updated_at": "2025-05-01T20:11:58+00:00"
},
"meta": []
}Update Order
Use the uuid to update an existing Order.
PUT
https://api.piggy.eu/api/v3/oauth/clients/orders/{uuid}Headers
Authorization
Accept
Bearer {{ personal_access_token }}
application/json
Input parameters
status string
optional
Status of the order
Possible values:
CREATEDOrder has just been created, not yet completed
PENDINGPending fulfilment and/or payment
COMPLETEDOrder has been completed
CANCELLEDOrder was cancelled before completion
payment_status string
optional
Status of the payment of the order
Possible values:
UNPAIDPayment process has not been started
PENDINGPayment process started, pending confirmation
PAIDPayment successful
Response Example
{
"data": {
"uuid": "bfada889-6a69-4fcf-aed6-42933ae9084d",
"contact": {
"uuid": "12345-abcdefg-6789-yuiop",
"email": "spongebob@bikinibottom.sea"
},
"business_profile": {
"uuid": "12345-abcdefg-6789-yuiop",
"name": "HeadQuarters"
},
"external_identifier": "EXT-0012",
"reference": "Order B-2110",
"status": "COMPLETED",
"payment_status": "PAID",
"currency": "EUR",
"formatted_total_order_amount": "€ 33.31",
"order_amount": 3175,
"total_charges_amount": 381,
"total_discount_amount": 225,
"total_order_amount": 3331,
"paid_at": "2025-05-01T20:10:44+00:00",
"completed_at": "2025-05-01T20:11:03+00:00",
"line_items": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "LI_IT_11090_lkajsf",
"name": "Double Krabby Patty",
"quantity": 2,
"price": 1250,
"total_amount": 2500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
"sub_line_items": [
{
"uuid": "87a4be97-73dd-40a4",
"external_identifier": "SU_LI_IT_11090_lkajsf",
"name": "Extra Secret Sauce",
"quantity": 1,
"price": 500,
"total_amount": 500,
"discount_amount": 0,
"product": {
"external_identifier": "PR-15-454",
"name": "Extra Secret Sauce",
}
}
]
},
{
"uuid": "187-8Dfadf3-lsdf234ds-99ass",
"external_identifier": "LI_IT_991_Ac990s",
"name": "Kelp Soda",
"quantity": 2,
"price": 450,
"total_amount": 675,
"discount_amount": 225,
"product": {
"external_identifier": "PR-12-401",
"name": "Double Krabby Patty",
},
},
],
"applied_discounts": [
{
"uuid": "021as-8892k-ljkafds-98as",
"external_identifier": "DISC_25_OFF_DRINKS",
"name": "25% off Drinks",
"amount": 225,
"type": "PERCENTAGE",
"value": 25,
"applied_to": "LINE_ITEM",
"line_items": [
{
"external_identifier": "LI_IT_991_Ac990s",
},
],
},
"charges": [
{
"external_identifier": "SRV_CH-12",
"type": "SERVICE_CHARGE",
"name": "Service charge: 12%",
"amount": 381,
"discount_amount": 0,
"total_amount": 0
},
],
"created_at": "2025-05-01T20:11:58+00:00",
"updated_at": "2025-05-01T20:11:58+00:00"
},
"meta": []
}Simulate Order Result
Simulates the result of a new Order in the Leat system. Please note that the actual result may differ, as some time-based rules may be in place. Also, some rules may not be applied if the required information is missing from the payload (e.g. contact).
POST
https://api.piggy.eu/api/v3/oauth/clients/orders/simulateHeaders
Authorization
Accept
Bearer {{ personal_access_token }}
application/json
Input parameters
status string
optional
Status of the order
Possible values:
CREATEDOrder has just been created, not yet completed
PENDINGPending fulfilment
COMPLETEDWhen created
payment_status string
optional
Status of the payment of the order
Possible values:
UNPAIDPayment process has not been started
PENDINGPayment process started, pending confirmation
PAIDPayment successful
total_order_amount number
required
Total order amount, after discounts and other charges, in the currency's lowest denomination
order_amount number
optional
Total order amount, before discounts and other charges, in the currency's lowest denomination
total_discount_amount number
optional
Total discount amount, in the currency's lowest denomination
currency string
optional
Order currency in ISO 4217 format; defaults to Account's default currency
contact
object
optional
The Contact for this Order. If not given, Contact-based rules cannot be applied
uuid string
required
UUID of the Contact
business_profile
object
required
Location where the Order takes place
uuid string
required
UUID of the Business Profile
line_items
array of objects
required
List of Products in this Order
name string
required
Name of the Line Item
quantity number
required
Quantity of the Line Item
price number
required
Price per unit of this Line Item
total_amount number
required
Total amount of this Line Item, in the currency's lowest denomination
discount_amount number
optional
Discount amount of this Line Item, in the currency's lowest denomination
product
object
optional
Associated Product
uuid string
optional
UUID to the Product
external_identifier string
optional
Unique identifier to the Product with which it's registered in Leat
sub_line_items
array of objects
optional
List of Sub Line Items of this Line Item
name string
required
Name of the Sub Line Item
quantity number
required
Quantity of the Sub Line Item
price number
required
Price per unit of this Sub Line Item
total_amount number
required
Total amount of this Sub Line Item, in the currency's lowest denomination
discount_amount number
optional
Discount amount of this Sub Line Item, in the currency's lowest denomination
product
object
optional
Associated Product
uuid string
optional
UUID to the Product
external_identifier string
optional
Unique identifier to the Product with which it's registered in Leat
applied_discounts
array of objects
optional
List of Discounts applied to this Order
name string
required
Name of the Discount
amount number
required
Resulting monetary discount amount in the currency's lowest denomination
type string
optional
Type of the Discount
Possible values:
PERCENTAGEFor percentage based discounts
ABSOLUTEFor absolute discounts
value number
optional
The value of either the percentage or absolute discount
applied_to string
required
Indicates if Discount is applied to Order or to one or more (Sub) Line Items. Discounts applied on (Sub) Line Items can be excluded for the Order Simulation.
Possible values:
ORDERFor Order level discounts
LINE_ITEMSFor Line Item level discounts
SUB_LINE_ITEMSFor Sub Line Item level discounts
charges
array of objects
optional
Any charges not included as line items. E.g. gratuity, service charges or shipping
name string
required
A human readable reference to the charge
amount number
optional
The cost of the charge, before discounts, in the currency's lowest denomination
discount_amount number
optional
The discount amount, in the currency's lowest denomination
total_amount number
required
The total cost of the charge, after discounts, in the currency's lowest denomination
charge_definition
object
optional
The charge definition, for use in rules and exclusions. Every account has a few definitions by default, with external identifiers: SERVICE_CHARGE.
Default definitions:
SERVICE_CHARGEA service charge applied to the order
GRATUITYGratuity or tip
SHIPPINGShipping costs
WRAPPINGWrapping costs
TAXSeparate tax charges. Do not add if taxes are already included in line item total amounts.
uuid string
required if undefined
UUID to identify the Charge Definition
external_identifier string
required if undefined
Unique identifier to identify the Charge Definition (use for default Charge Definitions)
Response Example
{
"data": {
"type": "points_transaction",
"data" : {
"points": 35
},
},
"meta": []
}Tiers
You can now offer your Contacts an extra bonus by using Tiers. Tiers allow you to automatically assign Contacts a certain status. For example, consider Bronze,
Order Returns
Order Returns represent reversals of previously created Orders in the Leat system. They are typically generated by external systems (e.g. web shops, POS systems