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 or refunded

• subtotal (required) - The amount before fees, taxes etc. but net of discounts

• 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

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

The fee object contains

• name (required) - The name of the fee (delivery, service charge, etc.)

• amount (required) - The amount for the fee, in cents

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": 189.00,
      "subtotal": 180.00,
      "tax": 9.00,
      "fees": [
        {
          "name": "Delivery fee",
          "amount": 100
        }
      ],
      "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.

post

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.

Authorizations

Body

payload[order][line_items]arrayRequired

Line items in the order

payload[order][amount]numberRequired

Total amount of the order in cents

payload[order_source]stringRequired

Source of the order.

payload[type]stringRequired

What type of transaction occurred.

payload[merchant_pos_system]stringRequired

Type of POS system from which the order originates.

payload[external_order_guid]stringRequired

Unique identifier for the order from the external system.

payload[external_location_type]stringRequired

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

payload[external_location_id]stringRequired

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

payload[program_membership_id]stringOptional

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

payload[external_customer_id]stringOptional

External customer ID associated with the order.

payload[order][applied_discounts]arrayOptional

List of reward IDs applied to the transaction as a whole

Responses

post

HTTPcURLJavaScriptPython

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]=[]"

200

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.