Search for a PartnerApiOrder

Bulk Search for Partner API Orders

To search for multiple partner API orders, you can make a POST request to the /v2/orders/bulk-search endpoint.

Request Parameters

The request accepts the following optional filter parameters:

• program_membership_id (String): Filter by a specific program membership ID.

• external_order_guid (String): Filter by an external order GUID.

• external_location_id (String): Filter by an external location ID.

• external_customer_id (String): Filter by an external customer ID.

• uuid (String): Filter by a specific order UUID.

• created (Hash): Filter by creation date range.

  • start (Integer): Start of the date range (epoch timestamp).

  • end (Integer): End of the date range (epoch timestamp).

• updated (Hash): Filter by update date range.

  • start (Integer): Start of the date range (epoch timestamp).

  • end (Integer): End of the date range (epoch timestamp).

• page_size (Integer): Number of results per page (max: 1000).

• page (Integer): Page number for pagination.

Example Request

curl -X POST 'https://loyalty.hang.xyz/partner-api/v2/orders/bulk-search' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "external_order_guid": "order_123",
      "external_customer_id": "customer_789",
      "created": {
        "start": 1700000000,
        "end": 1705000000
      }
    },
    "page_size": 50,
    "page": 1
  }'

Response

If successful, the API returns a 200 OK status along with the list of matching orders.

Example Response

{
  "orders": [
    {
      "id": 98765,
      "uuid": "a1b2c3d4-e5f6-7890-ab12-cd34ef56gh78",
      "external_order_guid": "order_456",
      "external_location_guid": "loc_789xyz",
      "external_customer_id": "cust_123abc",
      "payment_provider": "paypal",
      "payment_token": "tok_abcdef123456",
      "redeemed_loyalty_reward_uuids": ["reward_1", "reward_2"],
      "program_membership_id": "pm_987zyx",
      "reversed_at": null,
      "created_at": 1705000000,
      "updated_at": 1706000000,
      "raw_payload": {
        "type": "payment.completed",
        "order": {
          "tax": 2.50,
          "tip": 5.00,
          "fees": 1.25,
          "amount": 50.75,
          "subtotal": 42.00,
          "line_items": [
            {
              "tax": 1.00,
              "price": 2000,
              "quantity": 2,
              "applied_discounts": ["discount_10"],
              "external_item_guid": "item_456",
              "external_group_guid": "group_789",
              "external_multi_location_item_id": "multi_001",
              "external_multi_location_group_id": "multi_group_002"
            }
          ],
          "applied_discounts": ["discount_5"]
        },
        "payment": {
          "provider": "paypal",
          "payment_token": "tok_abcdef123456"
        },
        "order_source": "Online Checkout",
        "external_order_guid": "order_456",
        "merchant_pos_system": "Custom_POS",
        "external_customer_id": "cust_123abc",
        "external_location_id": "loc_789xyz",
        "program_membership_id": "pm_987zyx",
        "external_location_type": "franchise"
      }
    }
  ],
  "total_records": 2450
}

Error Handling

If the API encounters an error, an appropriate error message is returned. Some common errors include:

• 422 Unprocessable Entity: Invalid page_size or page values.

• 400 Bad Request: Incorrectly formatted request payload.

• 404 Not Found: No matching orders found for the provided filters.