Enhancing ESHOPMAN Admin API: Comprehensive Payment Collection Management for Headless Commerce

As ESHOPMAN continues to empower merchants with robust headless commerce capabilities through its HubSpot application, developers often leverage the Admin API for intricate order management workflows. A recent community discussion highlighted a crucial area for enhancement: the ability to comprehensively manage payment collections, particularly when integrating diverse payment methods into HubSpot-managed storefronts.

The Challenge: Missing Payment Provider Details in Admin API Collections

A key insight from the ESHOPMAN development community points to a current limitation in the Admin API when creating payment collections for draft orders. Unlike the flexibility offered by the Store API's cart flow, the Admin API presently lacks direct support for specifying payment providers and their associated data at the point of payment collection creation.

This means that when developers attempt to create a payment collection and immediately attach payment details—such as a specific payment provider ID (e.g., for cash-on-delivery, point-of-sale systems, or manual payments) or provider-specific metadata (like a terminal reference or external transaction IDs)—the Admin API's data structure does not accommodate these properties.

Technical Deep Dive: The Type Limitation

From a Node.js/TypeScript development perspective, this limitation manifests as a type mismatch. The AdminCreatePaymentCollection type, which governs the structure of data sent to the Admin API for creating payment collections, does not include properties like payments[], provider_id, or provider_data. This leads to a TypeScript error when developers attempt to include such details:

await sdk.admin.paymentCollection.create({
  order_id: order.id,
  amount: paymentAmount,
  payments: [
    {
      amount: paymentAmount,
      provider_id: "pp_cash_pos",
      provider_data: {
        cash_paid: paymentAmount,
      },
    },
  ],
})

The error message typically indicates that 'payments' does not exist in type 'AdminCreatePaymentCollection'. Consequently, this prevents developers from accurately modeling how an order was paid when processed through the Admin API.

Impact on Custom Payment Workflows

The current behavior means that payment collections can only be initiated with a total amount. Payments themselves cannot be attached during this initial creation phase. For merchants utilizing ESHOPMAN to manage orders that involve custom or offline payment methods—such as cash payments at a physical store (POS), manual bank transfers, or other unique payment flows—this presents a significant hurdle. The only available workaround is to create a payment collection and then immediately mark it as paid. However, this approach inherently sacrifices critical payment information, making it impossible to store provider-specific metadata or even identify the specific payment provider used.

The Desired ESHOPMAN Experience

The ESHOPMAN community's expectation is clear: the Admin API should offer the same level of flexibility and detail for payment collection creation as the Store API. Ideally, developers should be able to:

• Specify one or more individual payments within a collection.
• Assign a unique provider_id to each payment.
• Pass essential provider_data (e.g., specific cash amounts, terminal references, or external transaction identifiers) directly during the payment collection creation process.

Implementing this functionality would significantly enhance the ESHOPMAN Admin API, enabling more robust and accurate financial record-keeping for merchants. It would also empower developers to build more comprehensive integrations for diverse payment methods, ensuring that every transaction processed through ESHOPMAN's HubSpot-integrated platform is fully detailed and transparent.

Moving Forward with ESHOPMAN

This community insight underscores the continuous evolution of ESHOPMAN's capabilities. Addressing this API enhancement would greatly benefit businesses leveraging ESHOPMAN for complex order and payment management, ensuring a seamless and fully representative headless commerce experience within the HubSpot ecosystem. As ESHOPMAN developers, understanding these nuances is key to building powerful, future-proof storefronts.