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

• 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 of refunded

• 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

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

• 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

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": {
    "program_membership_id": null,
    "external_location_id": "9dedcce0-fb95-4717-923a-1193773fad59",
    "external_location_type": "ToastRestaurant",
    "external_order_guid": "c5013335-96ca-4556-bb46-dec13bf3747d",
    "merchant_pos_system": "TOAST",
    "order_source": "OTTER",
    "external_customer_id": "example-customer-id",
    "order": {
      "amount": 18900,
      "line_items": [
        {
          "tax": 200,
          "quantity": 5,
          "price": 5900,
          "external_item_guid": "639aa580-eddb-43cf-95f3-c859489da88b",
          "external_multi_location_item_id": "639aa580-eddb-43cf-95f3-c859489da88b",
          "external_group_guid": "639aa580-eddb-43cf-95f15-c859489da88b",
          "external_multi_location_group_id": "639aa580-eddb-43cf-95f3-c859489da88b",
          "applied_discounts": ["c5013335-96ca-4556-bb46-dec13bf3747d"]
        }
      ],
      "applied_discounts": ["c5013335-96ca-4556-bb46-dec13bf3747d", "bgg13335-96ca-4556-bb46-dec13bf3747d"]
    },
    "payment": {
      "provider": "Toast",
      "payment_token": "unique_id"
    }
  }
}'

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

Create an Order record.

  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.

POST/partner-api/v2/external/orders

Body

multipart/form-data

payload[order][line_items]*array of string

Line items in the order

payload[order][amount]*number

Total amount of the order in cents

payload[order_source]*string

Source of the order.

payload[type]*enum

What type of transaction occurred.

payment.createdpayment.updatedrefund.createdrefund.updated

payload[merchant_pos_system]*string

Type of POS system from which the order originates.

payload[external_order_guid]*string

Unique identifier for the order from the external system.

payload[external_location_type]*string

Type of the external location (e.g., ToastRestaurant).

payload[external_location_id]*string

Unique identifier for the location from the external system (e.g., a restaurant ID from Toast).

payload[program_membership_id]string

Program membership ID if available. Nullable field to tie the order to a specific membership.

payload[external_customer_id]string

External customer ID associated with the order.

payload[order][applied_discounts]array of string

List of reward IDs applied to the transaction as a whole

Response

200

ok

Request

JavaScriptCurlPython

const response = await fetch('/partner-api/v2/external/orders', {
    method: 'POST',
    headers: {
      "Content-Type": "multipart/form-data"
    },
    body: JSON.stringify({
      "payload[order][line_items]": [
        "text"
      ],
      "payload[order][amount]": 0,
      "payload[order_source]": "text",
      "payload[type]": "payment.created",
      "payload[merchant_pos_system]": "text",
      "payload[external_order_guid]": "text",
      "payload[external_location_type]": "text",
      "payload[external_location_id]": "text"
    }),
});
const data = await response.json();

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.