Posting Orders Through Hang
The Orders API allows partners to post transactions to Hang via the Partner API. These orders can be tied to users via a program membership to accrue points based on spend and process redemptions of rewards, or can be used without a program membership to store a historical record of orders. This API is intended for orders outside of platforms that Hang already integrates with (Square, Toast, etc.) as those orders are automatically processed.
Request Parameters
The top level parameter is payload
The payload
object contains
program_membership_id
- The Id of the Program Membership if applicableexternal_location_id
- The identifier of the location for the orderexternal_location_type
- The type of the external locationexternal_order_guid
(required) - Unique identifier of the order from the external systemmerchant_pos_system
(required) - Type of system that the order originates fromtransaction_date
(required) - date transaction was made in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"refunded_date
- date transaction was refunded in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"voided_date
- date transaction was voided in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"updated_date
- date transaction was voided in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"type
(required) - The type of orderpayment.created
payment.updated
refund.created
refund.updated
order_source
(required) - The source of the order (for example your company's name)order
(required) - The contents of the order, outlined below
The order
object contains
amount
(required) - The total amount spent or refundedrefunded_amount
- The total amount refundeddiscount_amount
- The total amount discounted (check level + item level)subtotal
(required) - The amount before fees, taxes etc. but net of discountsstatus
- Check status (Open, Paid, Closed, Refunded, Voided)tax
(required) - The total tax on the ordertip
- The total tip on the orderapplied_discounts
- The UUIDs of the discounts (if any) applied to the check at the order levelline_items
(required) - An array ofline_item
objects, outlined belowfees
- An array offee
objects, outlined belowdiscounts
- An array ofdiscount
objects, outlined below
The payment
object contains
provider
- string - The name of the payment provider used to process paymentspayment_token
- string - The unique payment identifier token returned from the payment processor.
The line_item
object contains
tax
(required) - The tax for the line itemquantity
(required) - Quantity of the itemprice
(required) - The price per unit of the itemprice_dollar
(required) - The price per unit of the item in dollarsexternal_item_guid
(required) - The GUID of the itemexternal_multi_location_item_id
- The multi location ID of the item, if applicableexternal_group_guid
- The GUID of the group the item belongs to, if applicableexternal_multi_location_group_id
- The multi location ID of the group, if applicableapplied_discounts
- The UUIDs of the discounts (if any) applied at the item leveldiscounts
- An array ofdiscount
objects, outlined belowrefunded_date
- date line item was refunded in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"voided_date
- date line item was voided in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"updated_date
- date line item was update in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"modifiers
- An array ofmodifiers
objects, outlined below
The fee
object contains
name
(required) - The name of the fee (delivery, service charge, etc.)amount
(required) - The amount for the fee, in centsrefunded_amount
(required) - The amount for the fee, in cents
The discount
object contains
discount_id
(required) - The name of the fee (delivery, service charge, etc.)discount_amount
(required) - The amount for the fee, in centsdiscount_name
(required) - The name of the discount
The modifiers
object contains
tax
(required) - The tax for the line itemquantity
(required) - Quantity of the itemprice
(required) - The price per unit of the itemprice_dollar
(required) - The price per unit of the item in dollarsexternal_item_guid
(required) - The GUID of the itemexternal_multi_location_item_id
- The multi location ID of the item, if applicableexternal_group_guid
- The GUID of the group the item belongs to, if applicableexternal_multi_location_group_id
- The multi location ID of the group, if applicableapplied_discounts
- The UUIDs of the discounts (if any) applied at the item leveldiscounts
- An array ofdiscount
objects, outlined belowrefunded_date
- date line item modifier was refunded in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"voided_date
- date line item modifier was voided in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"updated_date
- date line item modifier was update in UTC, ISO 8601 format "2024-11-21T16:53:18.681+0000"
Example Request
Here's an example of a valid POST
request to the orders endpoint:
curl -X POST 'https://loyalty.hang.xyz/partner-api/v2/external/orders' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"payload": {
"order_source": "Source POS",
"external_order_guid": "order guid",
"merchant_pos_system": "merchant pos (toast, square etc)",
"external_customer_id": "customer_id",
"external_location_id": "restuarant_guid",
"program_membership_id": "pm_uuid",
"external_location_type": null,
"transaction_date": "2024-11-21T16:53:18.681+0000",
"voided_date": "2024-11-21T16:53:18.681+0000",
"refunded_date": "2024-11-21T16:53:18.681+0000",
"updated_date": "2024-11-21T16:53:18.681+0000",
"order": {
"tax": 0.86,
"tip": 0.0,
"fees": null,
"amount": 13.85,
"refund_amount": 1.25,
"subtotal": 12.99,
"discount_amount": 13.00,
"status": "OPEN",
"line_items": [
{
"tax": 0,
"price": 1299,
"price_dollar": 12.99,
"quantity": 1,
"external_item_guid": "uuid",
"external_group_guid": null,
"external_multi_location_item_id": "uuid",
"external_multi_location_group_id": null,
"applied_discounts": [],
"discounts": [
{
"discount_id": "uuid",
"discount_amount": 3.00,
"discount_name": "$3 off the item"
}
],
"voided_date": "2024-11-21T16:53:18.681+0000",
"refunded_date": "2024-11-21T16:53:18.681+0000",
"updated_date": "2024-11-21T16:53:18.681+0000"
"modifiers": [
{
"tax": 0,
"price": 1299,
"price_dollar": 12.99,
"quantity": 1,
"external_item_guid": "uuid",
"external_group_guid": null,
"external_multi_location_item_id": "uuid",
"external_multi_location_group_id": null,
"applied_discounts": [],
"discounts": [
{
"discount_id": "uuid",
"discount_amount": 1.00,
"discount_name": "Free modifier"
}
],
"voided_date": "2024-11-21T16:53:18.681+0000",
"refunded_date": "2024-11-21T16:53:18.681+0000",
"updated_date": "2024-11-21T16:53:18.681+0000"
}
]
}
],
"applied_discounts": ["uuid"],
"discounts": [
{
"discount_id": "uuid",
"discount_amount": 10.00,
"discount_name": "$10 off full check"
}
]
},
"payment": {
"provider": "Fiserve/Chase/Fluidpay",
"payment_token": "HIDDEN"
}
}
}'
Example Response
Success
{
status: 'success',
message: 'Order created successfully.'
}
Failure
On failure, a response will be returned with error messages outlining the cause of the error.
Posting Orders
This endpoint receives orders from external systems. It requires a comprehensive payload that includes details about the order, such as the items purchased, applicable taxes, discounts, and the source and POS system of the order. It can optionally link the order to a program membership if the program_membership_id is provided.
Line items in the order
Total amount of the order in cents
Source of the order.
What type of transaction occurred.
Type of POS system from which the order originates.
Unique identifier for the order from the external system.
Type of the external location (e.g., ToastRestaurant).
Unique identifier for the location from the external system (e.g., a restaurant ID from Toast).
Program membership ID if available. Nullable field to tie the order to a specific membership.
External customer ID associated with the order.
List of reward IDs applied to the transaction as a whole
POST /partner-api/v2/external/orders HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 388
"payload[order][line_items]=[]&payload[order][amount]=1&payload[order_source]='text'&payload[type]='text'&payload[merchant_pos_system]='text'&payload[external_order_guid]='text'&payload[external_location_type]='text'&payload[external_location_id]='text'&payload[program_membership_id]='text'&payload[external_customer_id]='text'&payload[order][applied_discounts]=[]"
ok
No content
Error Handling
The API provides error messages for guidance in case of issues. This assists in rapid resolution and smooth operation.
Parameters and Responses
Each endpoint requires specific parameters. For full details on request parameters and expected responses, please refer to the individual endpoint documentation in our API reference.
Last updated