Navigating Buy-Get Promotion Updates: Resolving Admin API Validation Challenges in ESHOPMAN

Understanding ESHOPMAN Promotion Management Challenges

Managing promotions effectively is crucial for any e-commerce platform, and ESHOPMAN provides robust tools for storefronts deployed via HubSpot CMS. Developers often interact with the ESHOPMAN Admin API to programmatically create and update promotions, ensuring dynamic and flexible campaign management. However, a recent community discussion highlighted a specific challenge when attempting to update 'buyget' promotions through the PATCH /admin/promotions/{id} endpoint.

The core issue revolved around a validation conflict that made it impossible to update existing 'buyget' promotions. This 'double-bind' scenario presented two mutually exclusive errors, depending on the payload sent to the Admin API:

Attempt 1 — Without buy_rules in the payload:

{
  "application_method": {
    "allocation": "each",
    "max_quantity": 10000,
    "target_type": "items",
    "value": 100,
    "buy_rules_min_quantity": 4,
    "type": "percentage",
    "currency_code": "eur",
    "apply_to_quantity": 2
  },
  "status": "inactive",
  "type": "buyget"
}
→ {"type":"invalid_data","message":"Invalid request: Buyget promotions require at least one buy rule and quantities to be defined"}

This error indicated that 'buyget' promotions require 'buy rules' to be defined, even for an update operation where these rules might already exist in the database.

Attempt 2 — Including buy_rules in the application_method:

{
  "application_method": {
    "allocation": "each",
    "max_quantity": 10000,
    "target_type": "items",
    "value": 100,
    "buy_rules_min_quantity": 4,
    "type": "percentage",
    "currency_code": "eur",
    "buy_rules": [
      {
        "values": ["variant_01KGGKYNS442TBAJ0167T7TENG"],
        "operator": "eq",
        "attribute": "items.variant.id"
      }
    ],
    "apply_to_quantity": 2
  },
  "status": "inactive",
  "type": "buyget"
}
→ {"type":"invalid_data","message":"Invalid request: Unrecognized fields: 'buy_rules'"}

In this second attempt, the API rejected the request because the buy_rules field was considered 'unrecognized'.

The Root Cause: A Validation Double-Bind

A deeper look into ESHOPMAN's internal validation logic, specifically the schema definitions for Admin API requests, revealed the core problem:

• The AdminUpdateApplicationMethod schema, which governs updates to promotion application methods, was configured to be 'strict'. Crucially, it did not include buy_rules as an allowed field. Therefore, any payload containing buy_rules was rejected as having 'unrecognized fields'.
• Concurrently, a promotion refinement rule, applied to both creation and update operations, explicitly checked that application_method.buy_rules.length > 0 whenever the promotion type was 'buyget'. In the context of an update payload, if buy_rules was absent (due to the strict schema), this refinement would always fail, leading to the first error message.

This created an impossible situation for developers: the update schema rejected buy_rules, yet a separate validation rule required it.

// Excerpt of ESHOPMAN's AdminUpdateApplicationMethod schema (simplified)
exports.AdminUpdateApplicati
  value: z.number().optional(),
  max_quantity: z.number().nullish(),
  currency_code: z.string().nullish(),
  type: z.nativeEnum(ApplicationMethodType).optional(),
  target_type: z.nativeEnum(ApplicationMethodTargetType).optional(),
  allocation: z.nativeEnum(ApplicationMethodAllocation).optional(),
  apply_to_quantity: z.number().nullish(),
  buy_rules_min_quantity: z.number().nullish()
  // <-- 'buy_rules' is missing here, and .strict() blocks it
}).strict();

// Excerpt of ESHOPMAN's promoRefinement logic (simplified)
const promoRefinement = (promo) => {
  if (promo.type === PromotionType.BUYGET) {
    return (appMethod?.buy_rules?.length ?? 0) > 0 // <-- always 0 in update context if schema is strict
      && appMethod?.apply_to_quantity !== undefined
      && appMethod?.buy_rules_min_quantity !== undefined;
  }
  return true;
};

Proposed Solution and Best Practice for ESHOPMAN Developers

The community discussion led to a clear path forward. To resolve this double-bind, the AdminUpdateApplicationMethod schema needs to be updated to optionally include buy_rules. This would allow developers to pass buy_rules in their update payloads without triggering the 'unrecognized fields' error, satisfying the promotion refinement rule.

Minimal Fix: Add buy_rules as an optional field to the AdminUpdateApplicationMethod schema:

exports.AdminUpdateApplicati
  // ...existing fields...
  buy_rules: z.array(AdminCreatePromotionRule).optional() // <-- Add this line
}).strict();

Alternatively, the refinement logic could be adjusted to not strictly require buy_rules in a PATCH payload if the promotion already exists and has these rules persisted. However, modifying the schema is often a more direct and robust solution for API consistency.

This insight is crucial for ESHOPMAN developers working with the Admin API, especially those building custom integrations or tools for promotion management within their HubSpot-powered storefronts. Understanding such validation nuances ensures smoother development workflows and prevents unexpected API errors.