> For the complete documentation index, see [llms.txt](https://docs.hang.com/hang-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hang.com/hang-platform/api-usage/posting-orders-through-hang.md). # 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 applicable * `external_location_id` - The identifier of the location for the order * `external_location_type` - The type of the external location * `external_order_guid` *(required)* - Unique identifier of the order from the external system * `merchant_pos_system` (*required*) - Type of system that the order originates from * `transaction_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 order * `payment.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 refunded * `refunded_amount` - The total amount refunded * `discount_amount`- The total amount discounted (check level + item level) * `subtotal` (*required*) - The amount before fees, taxes etc. but net of discounts * `status` - Check status (Open, Paid, Closed, Refunded, Voided) * `tax` (*required*) - The total tax on the order * `tip` - The total tip on the order * `applied_discounts` - The UUIDs of the discounts (if any) applied to the check at the order level * `line_items` (*required*) - An array of `line_item` objects, outlined below * `fees` - An array of `fee` objects, outlined below * `discounts` - An array of `discount` objects, outlined below The `payment` object contains * `provider` - string - The name of the payment provider used to process payments * `payment_token` - string - The unique payment identifier token returned from the payment processor. The `line_item` object contains * `tax` (*required*) - The tax for the line item * `quantity` (*required*) - Quantity of the item * `price` (*required*) - The price per unit of the item * `price_dollar` (*required*) - The price per unit of the item in dollars * `external_item_guid` (*required*) - The GUID of the item * `external_multi_location_item_id` - The multi location ID of the item, if applicable * `external_group_guid` - The GUID of the group the item belongs to, if applicable * `external_multi_location_group_id` - The multi location ID of the group, if applicable * `applied_discounts` - The UUIDs of the discounts (if any) applied at the item level * `discounts` - An array of `discount` objects, outlined below * `refunded_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 of `modifiers` 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 cents * `refunded_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 cents * `discount_name` (*required*) - The name of the discount The `modifiers` object contains * `tax` (*required*) - The tax for the line item * `quantity` (*required*) - Quantity of the item * `price` (*required*) - The price per unit of the item * `price_dollar` (*required*) - The price per unit of the item in dollars * `external_item_guid` (*required*) - The GUID of the item * `external_multi_location_item_id` - The multi location ID of the item, if applicable * `external_group_guid` - The GUID of the group the item belongs to, if applicable * `external_multi_location_group_id` - The multi location ID of the group, if applicable * `applied_discounts` - The UUIDs of the discounts (if any) applied at the item level * `discounts` - An array of `discount` objects, outlined below * `refunded_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: ```bash 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** {% openapi src="/files/y2WYkasbHcVvR9xFzLkd" path="/v2/external/orders" method="post" %} [schema\_swagger\_form\_data.json](https://2857949451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnDjUJ7LXq2gMv9rmEsrI%2Fuploads%2FgcZUOtgli8WGa6pIjlex%2Fschema_swagger_form_data.json?alt=media) {% endopenapi %} ### 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.