checkout_sdk 2.2.1 → 2.4.0

data/lib/checkout_sdk/identities/idv_address.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Identities
+    # The applicant's address.
+    #
+    # @!attribute address_line1
+    #   The first line of the address.
+    #   [Optional]
+    #   max 250 characters
+    #   Example: 123 Main Street
+    #   @return [String]
+    # @!attribute address_line2
+    #   The second line of the address.
+    #   [Optional]
+    #   max 250 characters
+    #   Example: Apt 4B
+    #   @return [String]
+    # @!attribute city
+    #   The city or town.
+    #   [Optional]
+    #   max 50 characters
+    #   Example: London
+    #   @return [String]
+    # @!attribute state
+    #   The state, county, or province.
+    #   [Optional]
+    #   max 50 characters
+    #   Example: Greater London
+    #   @return [String]
+    # @!attribute zip
+    #   The postal or ZIP code.
+    #   [Optional]
+    #   max 50 characters
+    #   Example: SW1A 1AA
+    #   @return [String]
+    # @!attribute country
+    #   The two-letter ISO country code of the address.
+    #   [Optional]
+    #   Standard: ISO 3166-1 alpha-2 country code
+    #   max 2 characters
+    #   Example: GB
+    #   @return [String] a value of {CheckoutSdk::Common::Country}
+    class IdvAddress
+      attr_accessor :address_line1, :address_line2, :city, :state, :zip, :country
+    end
+  end
+end

data/lib/checkout_sdk/identities/idv_attempt_assets_query_filter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Identities
+    # Pagination for the attempt-assets endpoints.
+    #
+    # Separate from {IdvAttemptsQueryFilter} because the spec documents the two sets of parameters
+    # against different resources: these count assets, those count attempts.
+    #
+    # @!attribute skip
+    #   The number of assets to skip.
+    #   [Optional]
+    #   Default: 0
+    #   @return [Integer]
+    # @!attribute limit
+    #   The maximum number of assets to return.
+    #   [Optional]
+    #   Default: 10
+    #   @return [Integer]
+    class IdvAttemptAssetsQueryFilter
+      attr_accessor :skip, :limit
+    end
+  end
+end

data/lib/checkout_sdk/identities/idv_attempts_query_filter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Identities
+    # Pagination for the list-attempts endpoints.
+    #
+    # Separate from {IdvAttemptAssetsQueryFilter} because the spec documents the two sets of
+    # parameters against different resources: these count attempts, those count assets.
+    #
+    # @!attribute skip
+    #   The number of attempts to skip.
+    #   [Optional]
+    #   Default: 0
+    #   @return [Integer]
+    # @!attribute limit
+    #   The maximum number of attempts to return.
+    #   [Optional]
+    #   Default: 10
+    #   @return [Integer]
+    class IdvAttemptsQueryFilter
+      attr_accessor :skip, :limit
+    end
+  end
+end

data/lib/checkout_sdk/identities/idv_phone_number.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Identities
+    # The applicant's mobile phone number, if sharing the attempt URL via SMS.
+    #
+    # Named IdvPhoneNumber rather than PhoneNumber because
+    # {CheckoutSdk::Issuing::IssuingPhoneNumber} already exists for a different shape, and the two
+    # must not be confused.
+    #
+    # @!attribute country_code
+    #   The international phone country code. This is a dialling prefix, not an ISO country code.
+    #   [Required]
+    #   ^\+(\d+)$
+    #   Example: +33
+    #   @return [String]
+    # @!attribute number
+    #   The applicant's mobile number, without the country code.
+    #   [Required]
+    #   ^\d{1,14}$
+    #   Example: 5555550102
+    #   @return [String]
+    class IdvPhoneNumber
+      attr_accessor :country_code, :number
+    end
+  end
+end

data/lib/checkout_sdk/inventory/inventory.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'checkout_sdk/inventory/inventory_money'
+require 'checkout_sdk/inventory/inventory_adjustment_request'
+require 'checkout_sdk/inventory/inventory_reservation_item'
+require 'checkout_sdk/inventory/inventory_reservation_request'
+require 'checkout_sdk/inventory/inventory_set_levels_request'
+require 'checkout_sdk/inventory/inventory_set_product_request'
+require 'checkout_sdk/inventory/inventory_client'

data/lib/checkout_sdk/inventory/inventory_adjustment_request.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Inventory
+    # Request body for POST /inventory/adjustments. Mirrors swagger
+    # `InventoryAdjustmentRequest`.
+    #
+    # @!attribute variant_id
+    #   @return [String] The identifier of the variant to adjust. The variant must already
+    #     exist. [Required] max 128 characters.
+    # @!attribute delta
+    #   @return [Integer] The signed change to apply to on_hand. A negative delta that would
+    #     drive on_hand below zero is rejected with a 409. Per spec, must be non-zero (not a
+    #     formal schema constraint). [Required]
+    # @!attribute reason
+    #   @return [String] A free-text reason recorded in the ledger. Must not contain personal
+    #     data. [Required] min 1 character, max 256 characters.
+    class InventoryAdjustmentRequest
+      attr_accessor :variant_id,
+                    :delta,
+                    :reason
+    end
+  end
+end

data/lib/checkout_sdk/inventory/inventory_client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Inventory
+    # Client for the Inventory API: stock levels, atomic multi-variant reservations
+    # (hold/commit/release), stock adjustments, and per-variant "product knowledge"
+    # merchandising metadata for AI agents.
+    #
+    # All 10 operations require OAuth with the agentic:inventory scope (see
+    # {CheckoutSdk::OAuthScopes::AGENTIC_INVENTORY}); unlike most domains in this SDK, there is
+    # no ApiSecretKey/ApiPublicKey fallback, so this client always authorizes with
+    # {CheckoutSdk::AuthorizationType::OAUTH} (the same pattern already used by
+    # {CheckoutSdk::Payments::GooglePayClient}).
+    #
+    # Responses are returned as Hash (OpenStruct), per this SDK's convention (see e.g.
+    # {CheckoutSdk::Balances::BalancesClient}); there are no typed InventoryLevels,
+    # InventoryReservation or InventoryProductKnowledge response classes. Error responses
+    # (404/409/422) surface as {CheckoutSdk::CheckoutApiException}; this SDK has no per-domain
+    # typed error response classes, so `InventoryErrorResponse`'s fields
+    # (request_id, error_type, error_codes, variant_id, available) are available generically via
+    # `error.error_details`, the same as every other domain.
+    #
+    # getInventoryProduct, setInventoryProduct and deleteInventoryProduct are marked Beta in the
+    # specification.
+    class InventoryClient < Client
+      INVENTORY = 'inventory'
+      ADJUSTMENTS = 'adjustments'
+      RESERVATIONS = 'reservations'
+      COMMIT = 'commit'
+      RELEASE = 'release'
+      PRODUCT = 'product'
+      private_constant :INVENTORY, :ADJUSTMENTS, :RESERVATIONS, :COMMIT, :RELEASE, :PRODUCT
+
+      # @param [ApiClient] api_client
+      # @param [CheckoutConfiguration] configuration
+      def initialize(api_client, configuration)
+        super(api_client, configuration, CheckoutSdk::AuthorizationType::OAUTH)
+      end
+
+      # Apply a signed stock adjustment to a variant's on_hand quantity, recording the reason in
+      # the ledger. Returns 201, or 200 with a Cache-Control response header on an idempotent
+      # replay; both share the InventoryLevels response schema.
+      #
+      # @param [Hash, InventoryAdjustmentRequest] adjustment_request
+      # @param [String, nil] idempotency_key Optional. Cko-Idempotency-Key request header.
+      # @return [Hash] the InventoryLevels response
+      def adjust_inventory(adjustment_request, idempotency_key = nil)
+        api_client.invoke_post(
+          build_path(INVENTORY, ADJUSTMENTS),
+          sdk_authorization,
+          adjustment_request,
+          idempotency_key
+        )
+      end
+
+      # Create an atomic multi-variant hold. Returns 201, or 200 with a Cache-Control response
+      # header on an idempotent replay; both share the InventoryReservation response schema.
+      #
+      # @param [Hash, InventoryReservationRequest] reservation_request
+      # @param [String, nil] idempotency_key Optional. Cko-Idempotency-Key request header.
+      # @return [Hash] the InventoryReservation response
+      def create_inventory_reservation(reservation_request, idempotency_key = nil)
+        api_client.invoke_post(
+          build_path(INVENTORY, RESERVATIONS),
+          sdk_authorization,
+          reservation_request,
+          idempotency_key
+        )
+      end
+
+      # Retrieve a reservation by ID.
+      #
+      # @param [String] reservation_id
+      # @return [Hash] the InventoryReservation response
+      def get_inventory_reservation(reservation_id)
+        api_client.invoke_get(build_path(INVENTORY, RESERVATIONS, reservation_id), sdk_authorization)
+      end
+
+      # Commit a held reservation, converting the hold into a permanent deduction. Takes no
+      # request body.
+      #
+      # @param [String] reservation_id
+      # @return [Hash] the InventoryReservation response
+      def commit_inventory_reservation(reservation_id)
+        api_client.invoke_post(
+          build_path(INVENTORY, RESERVATIONS, reservation_id, COMMIT),
+          sdk_authorization
+        )
+      end
+
+      # Release a held reservation, returning the reserved quantity to available stock. Takes
+      # no request body.
+      #
+      # @param [String] reservation_id
+      # @return [Hash] the InventoryReservation response
+      def release_inventory_reservation(reservation_id)
+        api_client.invoke_post(
+          build_path(INVENTORY, RESERVATIONS, reservation_id, RELEASE),
+          sdk_authorization
+        )
+      end
+
+      # Retrieve the stock levels for a variant.
+      #
+      # @param [String] variant_id
+      # @param [Boolean, nil] expand_product Optional. When true, adds `?expand=product` so the
+      #   response embeds the variant's InventoryProductKnowledge (when it exists) under
+      #   `product`.
+      # @return [Hash] the InventoryLevels response
+      def get_inventory_levels(variant_id, expand_product: false)
+        params = { expand: 'product' } if expand_product
+        api_client.invoke_get(build_path(INVENTORY, variant_id), sdk_authorization, params)
+      end
+
+      # Create or replace the stock levels for a variant.
+      #
+      # @param [String] variant_id
+      # @param [Hash, InventorySetLevelsRequest] set_levels_request
+      # @return [Hash] the InventoryLevels response
+      def set_inventory_levels(variant_id, set_levels_request)
+        api_client.invoke_put(build_path(INVENTORY, variant_id), sdk_authorization, set_levels_request)
+      end
+
+      # Retrieve the product knowledge (merchandising metadata) for a variant. Beta.
+      #
+      # @param [String] variant_id
+      # @return [Hash] the InventoryProductKnowledge response
+      def get_inventory_product(variant_id)
+        api_client.invoke_get(build_path(INVENTORY, variant_id, PRODUCT), sdk_authorization)
+      end
+
+      # Create or replace the product knowledge for a variant. Beta.
+      #
+      # @param [String] variant_id
+      # @param [Hash, InventorySetProductRequest] set_product_request
+      # @return [Hash] the InventoryProductKnowledge response
+      def set_inventory_product(variant_id, set_product_request)
+        api_client.invoke_put(build_path(INVENTORY, variant_id, PRODUCT), sdk_authorization, set_product_request)
+      end
+
+      # Delete the product knowledge for a variant. Beta. Returns 204 with no body.
+      #
+      # @param [String] variant_id
+      def delete_inventory_product(variant_id)
+        api_client.invoke_delete(build_path(INVENTORY, variant_id, PRODUCT), sdk_authorization)
+      end
+    end
+  end
+end

data/lib/checkout_sdk/inventory/inventory_money.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Inventory
+    # A monetary amount in an inventory product's price or sale_price. Mirrors swagger
+    # `InventoryMoney`. Used by {InventorySetProductRequest#price} and
+    # {InventorySetProductRequest#sale_price}.
+    #
+    # @!attribute amount
+    #   @return [Integer] The amount in the currency's minor unit. [Required]
+    # @!attribute currency
+    #   @return [String] The 3-letter ISO 4217 currency code. [Required] min 3 characters,
+    #     max 3 characters.
+    class InventoryMoney
+      attr_accessor :amount,
+                    :currency
+    end
+  end
+end

data/lib/checkout_sdk/inventory/inventory_reservation_item.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Inventory
+    # A single line item within an inventory reservation. Mirrors swagger
+    # `InventoryReservationItem`. Used by {InventoryReservationRequest#items} and present in the
+    # `InventoryReservation` response's `items` array (returned as a Hash, not deserialized into
+    # this class, per this SDK's response convention).
+    #
+    # @!attribute variant_id
+    #   @return [String] The identifier of the variant to reserve. The variant must already
+    #     exist. [Required] max 128 characters.
+    # @!attribute quantity
+    #   @return [Integer] The quantity to reserve. [Required] min 1.
+    class InventoryReservationItem
+      attr_accessor :variant_id,
+                    :quantity
+    end
+  end
+end

data/lib/checkout_sdk/inventory/inventory_reservation_request.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Inventory
+    # Request body for POST /inventory/reservations. Mirrors swagger
+    # `InventoryReservationRequest`.
+    #
+    # @!attribute owner_type
+    #   @return [String] Free-text classification of the reservation's owner (e.g. an agent or
+    #     order type). [Required] max 64 characters.
+    # @!attribute owner_reference
+    #   @return [String] A reference identifying the specific owner, echoed back on the
+    #     reservation. [Required] max 256 characters.
+    # @!attribute items
+    #   @return [Array<InventoryReservationItem>] The variants and quantities to hold.
+    #     [Required] min 1 item, max 45 items. variant_id must be unique within the request.
+    # @!attribute ttl_seconds
+    #   @return [Integer] How long the hold stays active before it expires. [Optional]
+    #     min 60, max 3600. Default: 900.
+    class InventoryReservationRequest
+      attr_accessor :owner_type,
+                    :owner_reference,
+                    :items,
+                    :ttl_seconds
+    end
+  end
+end

data/lib/checkout_sdk/inventory/inventory_set_levels_request.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Inventory
+    # Request body for PUT /inventory/{variant_id}. Mirrors swagger
+    # `InventorySetLevelsRequest`.
+    #
+    # @!attribute on_hand
+    #   @return [Integer] The physical stock to set for the variant. [Required] min 0.
+    # @!attribute safety_stock
+    #   @return [Integer] The buffer withheld from sale. [Optional] min 0. Defaults to 0 on
+    #     create; left unchanged on update if omitted.
+    # @!attribute reason
+    #   @return [String] A free-text reason recorded in the ledger. Must not contain personal
+    #     data. [Optional] max 256 characters.
+    class InventorySetLevelsRequest
+      attr_accessor :on_hand,
+                    :safety_stock,
+                    :reason
+    end
+  end
+end

data/lib/checkout_sdk/inventory/inventory_set_product_request.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Inventory
+    # Request body for PUT /inventory/{variant_id}/product (Beta). Mirrors swagger
+    # `InventorySetProductRequest`, the "product knowledge" merchandising metadata used by AI
+    # agents. Shares its optional fields with the `InventoryProductKnowledge` response schema,
+    # which this SDK does not model as a class because responses are returned as Hash (see
+    # {InventoryClient}).
+    #
+    # @!attribute title
+    #   @return [String] The product title. [Required] max 512 characters.
+    # @!attribute description
+    #   @return [String] The product description. [Required] max 4000 characters.
+    # @!attribute product_url
+    #   @return [String] The URL of the product page. [Required] max 2048 characters.
+    # @!attribute image_url
+    #   @return [String] The URL of the primary product image. [Required] max 2048 characters.
+    # @!attribute additional_image_urls
+    #   @return [Array<String>] Additional product image URLs. [Optional]
+    # @!attribute video_url
+    #   @return [String] The URL of a product video. [Optional]
+    # @!attribute model_3d_url
+    #   @return [String] The URL of a 3D model of the product. [Optional]
+    # @!attribute sku
+    #   @return [String] The merchant's SKU for the variant. [Optional] max 128 characters.
+    # @!attribute gtin
+    #   @return [String] The Global Trade Item Number. [Optional]
+    # @!attribute mpn
+    #   @return [String] The Manufacturer Part Number. [Optional]
+    # @!attribute brand
+    #   @return [String] The product's brand. [Optional]
+    # @!attribute category
+    #   @return [String] The product's category. [Optional]
+    # @!attribute price
+    #   @return [InventoryMoney] The product's list price. [Optional] When set together with
+    #     sale_price, sale_price must share its currency and be less than or equal to it.
+    # @!attribute sale_price
+    #   @return [InventoryMoney] The product's discounted price. [Optional] Must share price's
+    #     currency and be less than or equal to it.
+    # @!attribute sale_price_starts_at
+    #   @return [Time] When the sale price becomes active. [Optional] Pairs with sale_price.
+    #     Format: date-time (RFC 3339).
+    # @!attribute sale_price_ends_at
+    #   @return [Time] When the sale price stops being active. [Optional] Pairs with
+    #     sale_price. Format: date-time (RFC 3339).
+    # @!attribute group_id
+    #   @return [String] Identifies a group of related variants (e.g. the same product in
+    #     different colors/sizes). [Optional] Per spec (not a formal schema constraint), when
+    #     set, color and size are both required.
+    # @!attribute group_title
+    #   @return [String] The title shared by the variant group. [Optional]
+    # @!attribute color
+    #   @return [String] The variant's color. [Optional] Required when group_id is set (spec
+    #     text, not a formal constraint).
+    # @!attribute size
+    #   @return [String] The variant's size. [Optional] Required when group_id is set (spec
+    #     text, not a formal constraint).
+    # @!attribute size_system
+    #   @return [String] The sizing system the size value uses. [Optional]
+    # @!attribute gender
+    #   @return [String] The target gender for the product. [Optional]
+    # @!attribute condition
+    #   @return [String] The product's condition. [Optional] Enum: "new" "used" "refurbished".
+    #     Exact lowercase match. Default: "new".
+    # @!attribute material
+    #   @return [String] The product's material. [Optional]
+    # @!attribute age_group
+    #   @return [String] The target age group for the product. [Optional]
+    # @!attribute length
+    #   @return [Float] The product's length. [Optional]
+    # @!attribute width
+    #   @return [Float] The product's width. [Optional]
+    # @!attribute height
+    #   @return [Float] The product's height. [Optional]
+    # @!attribute dimension_unit
+    #   @return [String] The unit used for length, width and height. [Optional]
+    # @!attribute weight
+    #   @return [Float] The product's weight. [Optional]
+    # @!attribute weight_unit
+    #   @return [String] The unit used for weight. [Optional]
+    # @!attribute expiration_date
+    #   @return [Time] The product's expiration date. [Optional] Format: date-time
+    #     (RFC 3339).
+    # @!attribute harmonized_system_code
+    #   @return [String] The Harmonized System code used for customs. [Optional]
+    # @!attribute country_of_origin
+    #   @return [String] The product's country of origin. [Optional] 2-letter ISO 3166-1
+    #     alpha-2 code.
+    # @!attribute seller_name
+    #   @return [String] The seller's name. [Optional]
+    # @!attribute seller_url
+    #   @return [String] The seller's URL. [Optional]
+    # @!attribute seller_privacy_policy
+    #   @return [String] The URL of the seller's privacy policy. [Optional]
+    # @!attribute seller_tos
+    #   @return [String] The URL of the seller's terms of service. [Optional]
+    class InventorySetProductRequest
+      attr_accessor :title,
+                    :description,
+                    :product_url,
+                    :image_url,
+                    :additional_image_urls,
+                    :video_url,
+                    :model_3d_url,
+                    :sku,
+                    :gtin,
+                    :mpn,
+                    :brand,
+                    :category,
+                    :price,
+                    :sale_price,
+                    :sale_price_starts_at,
+                    :sale_price_ends_at,
+                    :group_id,
+                    :group_title,
+                    :color,
+                    :size,
+                    :size_system,
+                    :gender,
+                    :condition,
+                    :material,
+                    :age_group,
+                    :length,
+                    :width,
+                    :height,
+                    :dimension_unit,
+                    :weight,
+                    :weight_unit,
+                    :expiration_date,
+                    :harmonized_system_code,
+                    :country_of_origin,
+                    :seller_name,
+                    :seller_url,
+                    :seller_privacy_policy,
+                    :seller_tos
+    end
+  end
+end

data/lib/checkout_sdk/issuing/card_update_headers.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Issuing
+    # The optional HTTP headers accepted when updating a card's details.
+    #
+    # Modelled as its own class rather than added to {CheckoutSdk::Common::Headers} because these
+    # two headers belong to one endpoint, and Common::Headers is shared by every client.
+    #
+    # @!attribute return_encrypted_cvv
+    #   Set to "true" to retrieve the card's encrypted credentials in the response. Requires an
+    #   RSA public key in the Encryption-Key header, otherwise the API answers 422 with error code
+    #   encryption_key_required.
+    #
+    #   A String rather than a boolean: the value is emitted verbatim as an HTTP header, and "true"
+    #   is what the spec shows.
+    #   [Optional]
+    #   Maps to HTTP header return-encrypted-cvv.
+    #   Example: "true"
+    #   @return [String]
+    # @!attribute encryption_key
+    #   The RSA public key used to encrypt returned credentials. Required when
+    #   return_encrypted_cvv is set. Provide the public key with the BEGIN PUBLIC KEY and END
+    #   PUBLIC KEY headers and any newline characters removed, encoded as Base64.
+    #   [Optional]
+    #   Maps to HTTP header Encryption-Key.
+    #   @return [String]
+    class CardUpdateHeaders
+      attr_accessor :return_encrypted_cvv, :encryption_key
+    end
+  end
+end

data/lib/checkout_sdk/issuing/issuing.rb

@@ -9,6 +9,7 @@ require 'checkout_sdk/issuing/oob_authentication_request'
 require 'checkout_sdk/issuing/issuing_phone_number'
 require 'checkout_sdk/issuing/issuing_address'
 require 'checkout_sdk/issuing/update_cardholder_request'
+require 'checkout_sdk/issuing/card_update_headers'
 require 'checkout_sdk/issuing/update_card_request'
 
 # Simulations

data/lib/checkout_sdk/issuing/issuing_client.rb

@@ -85,13 +85,21 @@ module CheckoutSdk
         api_client.invoke_get(build_path(ISSUING, CARDS, card_id), sdk_authorization)
       end
 
+      # Update the details of an issued card. Only the fields for which you provide values are
+      # updated.
+      #
       # @param [String] card_id
       # @param [Hash, UpdateCardRequest] update_card_request
-      def update_card(card_id, update_card_request)
+      # @param [CardUpdateHeaders, nil] headers the optional return-encrypted-cvv and
+      #   Encryption-Key HTTP headers. Setting return_encrypted_cvv without encryption_key returns
+      #   a 422 with error code encryption_key_required.
+      # @return [OpenStruct] the update response, carrying encrypted_cvv when requested
+      def update_card(card_id, update_card_request, headers = nil)
         api_client.invoke_patch(
           build_path(ISSUING, CARDS, card_id),
           sdk_authorization,
-          update_card_request
+          update_card_request,
+          headers
         )
       end
 

data/lib/checkout_sdk/issuing/update_card_request.rb

@@ -5,23 +5,48 @@ module CheckoutSdk
     # Request body for PATCH /issuing/cards/{cardId}.
     #
     # @!attribute reference
+    #   Your reference.
+    #   [Optional]
+    #   max 256 characters
+    #   Example: X-123456-N11
     #   @return [String]
     # @!attribute metadata
+    #   The user's metadata.
+    #   [Optional]
     #   @return [Hash{String => String}]
     # @!attribute expiry_month
+    #   The card's expiration month.
+    #   [Optional]
+    #   min 1, max 12
+    #   Example: 5
     #   @return [Integer]
     # @!attribute expiry_year
+    #   The card's expiration year.
+    #   [Optional]
+    #   min 4 characters, max 4 characters
+    #   Example: 2025
     #   @return [Integer]
-    # @!attribute activation_date
-    #   @return [String] ISO-8601 date scheduling the card's activation. Supported formats:
-    #     date only `yyyy-mm-dd` (treated as midnight UTC) or date with round hour
-    #     `yyyy-mm-ddTHH:mmZ` / `yyyy-mm-ddTHH:mm±HH:mm`. Maps swagger `IssuingActivationDate`.
+    # @!attribute scheduled_activation_date
+    #   Date scheduling the card's first activation. Only applies to the initial activation of a
+    #   card. Two formats are supported: date only (yyyy-MM-dd, treated as midnight UTC), or date
+    #   with round hour (yyyy-MM-ddTHH:mmZ in UTC, or yyyy-MM-ddTHH:mm+HH:mm with offset). Only
+    #   round hours are allowed when a time is provided (HH:00). The value must be at least the
+    #   next round hour after the request time.
+    #
+    #   Renamed from activation_date by the 2026-09-02 spec, which also removed the
+    #   IssuingActivationDate schema this attribute used to cite.
+    #   [Optional]
+    #   Example: 2026-06-01T10:00Z
+    #   @return [String]
     # @!attribute revocation_date
-    #   @return [String] Date for the card to be automatically revoked, in the form `yyyy-mm-dd`.
-    #     Must be after the current date. Maps swagger `IssuingRevocationDate`.
+    #   Date scheduling the card's automatic revocation.
+    #   [Optional]
+    #   Format: yyyy-MM-dd (time is midnight UTC)
+    #   Example: 2027-03-12
+    #   @return [String]
     class UpdateCardRequest
       attr_accessor :reference, :metadata, :expiry_month, :expiry_year,
-                    :activation_date, :revocation_date
+                    :scheduled_activation_date, :revocation_date
     end
   end
 end