From ac953351f074a163cd4b992d910e2625207bf2f9 Mon Sep 17 00:00:00 2001
From: Ella Nan <38847123+ellanan@users.noreply.github.com>
Date: Tue, 17 Mar 2026 16:20:55 -0400
Subject: [PATCH] feat: add failure details type in transaction

---
 .changeset/lazy-spies-laugh.md                |  6 +++
 .../src/client/types.gen.ts                   | 13 +++++
 packages/sdks/shopper/src/client/types.gen.ts | 29 ++++++++++
 packages/sdks/specs/cart_checkout.yaml        | 16 ++++++
 packages/sdks/specs/shopper.yaml              | 54 +++++++++++++++++++
 5 files changed, 118 insertions(+)
 create mode 100644 .changeset/lazy-spies-laugh.md

diff --git a/.changeset/lazy-spies-laugh.md b/.changeset/lazy-spies-laugh.md
new file mode 100644
index 00000000..e6330aab
--- /dev/null
+++ b/.changeset/lazy-spies-laugh.md
@@ -0,0 +1,6 @@
+---
+"@epcc-sdk/sdks-cart-checkout-order": patch
+"@epcc-sdk/sdks-shopper": patch
+---
+
+add failure details type in transactions
diff --git a/packages/sdks/cart-checkout-order/src/client/types.gen.ts b/packages/sdks/cart-checkout-order/src/client/types.gen.ts
index edbf5d2d..2a5fd470 100644
--- a/packages/sdks/cart-checkout-order/src/client/types.gen.ts
+++ b/packages/sdks/cart-checkout-order/src/client/types.gen.ts
@@ -1912,6 +1912,19 @@ export type TransactionResponse = {
    * The status provided by the gateway for this transaction, such as `complete` or `failed`.
    */
   status?: string
+  /**
+   * Non-PII payment failure information from the payment gateway. Only present on failed transactions where the gateway provided structured failure details.
+   */
+  failure_details?: {
+    /**
+     * Machine-readable failure or error code from the payment gateway.
+     */
+    code?: string
+    /**
+     * Human-readable failure reason or error message from the payment gateway.
+     */
+    reason?: string
+  }
   relationships?: {
     order?: {
       data?: {
diff --git a/packages/sdks/shopper/src/client/types.gen.ts b/packages/sdks/shopper/src/client/types.gen.ts
index ebff15b2..c5ce6750 100644
--- a/packages/sdks/shopper/src/client/types.gen.ts
+++ b/packages/sdks/shopper/src/client/types.gen.ts
@@ -3039,6 +3039,10 @@ export type ShippingGroupResponse = {
   order_id?: string
   shipping_type?: string
   tracking_reference?: string
+  /**
+   * An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.
+   */
+  external_ref?: string
   address?: ShippingAddress
   delivery_estimate?: DeliveryEstimate
   createdAt?: Date
@@ -3064,6 +3068,10 @@ export type CreateShippingGroupRequest = {
     type?: "shipping_group"
     shipping_type?: string
     tracking_reference?: string
+    /**
+     * An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters.
+     */
+    external_ref?: string
     shipping_price?: ShippingPriceRequest
     address?: ShippingAddress
     includes_tax?: boolean
@@ -3076,6 +3084,10 @@ export type UpdateCartShippingGroupRequest = {
     type?: "shipping_group"
     shipping_type?: string
     tracking_reference?: string
+    /**
+     * An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters.
+     */
+    external_ref?: string
     shipping_price?: ShippingPriceRequest
     address?: ShippingAddress
     includes_tax?: boolean
@@ -3882,6 +3894,19 @@ export type TransactionResponse = {
    * The status provided by the gateway for this transaction, such as `complete` or `failed`.
    */
   status?: string
+  /**
+   * Non-PII payment failure information from the payment gateway. Only present on failed transactions where the gateway provided structured failure details.
+   */
+  failure_details?: {
+    /**
+     * Machine-readable failure or error code from the payment gateway.
+     */
+    code?: string
+    /**
+     * Human-readable failure reason or error message from the payment gateway.
+     */
+    reason?: string
+  }
   relationships?: {
     order?: {
       data?: {
@@ -3988,6 +4013,10 @@ export type UpdateOrderShippingGroupRequest = {
     type?: "shipping_group"
     shipping_type?: string
     tracking_reference?: string
+    /**
+     * An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters.
+     */
+    external_ref?: string
     address?: ShippingAddress
     delivery_estimate?: DeliveryEstimate
   }
diff --git a/packages/sdks/specs/cart_checkout.yaml b/packages/sdks/specs/cart_checkout.yaml
index 4b941647..93b9e426 100644
--- a/packages/sdks/specs/cart_checkout.yaml
+++ b/packages/sdks/specs/cart_checkout.yaml
@@ -6972,6 +6972,22 @@ components:
           type: string
           examples:
             - complete
+        failure_details:
+          description: >-
+            Non-PII payment failure information from the payment gateway. Only present on
+            failed transactions where the gateway provided structured failure details.
+          type: object
+          properties:
+            code:
+              description: Machine-readable failure or error code from the payment gateway.
+              type: string
+              examples:
+                - "2"
+            reason:
+              description: Human-readable failure reason or error message from the payment gateway.
+              type: string
+              examples:
+                - This transaction has been declined.
         relationships:
           type: object
           properties:
diff --git a/packages/sdks/specs/shopper.yaml b/packages/sdks/specs/shopper.yaml
index 079832b2..9ca989fe 100644
--- a/packages/sdks/specs/shopper.yaml
+++ b/packages/sdks/specs/shopper.yaml
@@ -18766,6 +18766,17 @@ components:
           type: string
         tracking_reference:
           type: string
+        external_ref:
+          description: >-
+            An optional external ID reference for a shipping group. It can
+            contain alphanumeric characters, special characters, and spaces, and
+            is not required to be unique. The maximum allowed length is 64
+            characters. It can be used to include an external reference from a
+            separate company system.
+          type: string
+          maxLength: 64
+          examples:
+            - SG-12345
         address:
           $ref: '#/components/schemas/ShippingAddress'
         delivery_estimate:
@@ -18814,6 +18825,14 @@ components:
               type: string
             tracking_reference:
               type: string
+            external_ref:
+              description: >-
+                An optional external ID reference for a shipping group. It can
+                contain alphanumeric characters, special characters, and spaces,
+                and is not required to be unique. The maximum allowed length is
+                64 characters.
+              type: string
+              maxLength: 64
             shipping_price:
               $ref: '#/components/schemas/ShippingPriceRequest'
             address:
@@ -18836,6 +18855,14 @@ components:
               type: string
             tracking_reference:
               type: string
+            external_ref:
+              description: >-
+                An optional external ID reference for a shipping group. It can
+                contain alphanumeric characters, special characters, and spaces,
+                and is not required to be unique. The maximum allowed length is
+                64 characters.
+              type: string
+              maxLength: 64
             shipping_price:
               $ref: '#/components/schemas/ShippingPriceRequest'
             address:
@@ -20013,6 +20040,25 @@ components:
           type: string
           examples:
             - complete
+        failure_details:
+          description: >-
+            Non-PII payment failure information from the payment gateway. Only
+            present on failed transactions where the gateway provided structured
+            failure details.
+          type: object
+          properties:
+            code:
+              description: Machine-readable failure or error code from the payment gateway.
+              type: string
+              examples:
+                - '2'
+            reason:
+              description: >-
+                Human-readable failure reason or error message from the payment
+                gateway.
+              type: string
+              examples:
+                - This transaction has been declined.
         relationships:
           type: object
           properties:
@@ -20174,6 +20220,14 @@ components:
               type: string
             tracking_reference:
               type: string
+            external_ref:
+              description: >-
+                An optional external ID reference for a shipping group. It can
+                contain alphanumeric characters, special characters, and spaces,
+                and is not required to be unique. The maximum allowed length is
+                64 characters.
+              type: string
+              maxLength: 64
             address:
               $ref: '#/components/schemas/ShippingAddress'
             delivery_estimate: