walmart-apimatic-sdk 0.0.1 → 0.0.5

data/lib/walmart_ap_is/apis/orders_api.rb

@@ -0,0 +1,846 @@
+# walmart_ap_is
+#
+# This file was automatically generated by APIMATIC v3.0 (
+# https://www.apimatic.io ).
+
+module WalmartApIs
+  # OrdersApi
+  class OrdersApi < BaseApi
+    # Returns orders matching the given filters. Orders are fulfilled by
+    # sellers (WFS or seller-fulfilled). Maps to Walmart OMS order queries.
+    # ### Current limitations (Phase-2 backlog)
+    # The underlying Teflon Order Lookup backend does not yet support
+    # every filter declared below. Calls using any of the following will
+    # return `400 Bad Request` with `code=FILTER_NOT_SUPPORTED` and a
+    # human-readable `message` explaining the specific rejection. Phase
+    # 2 (tracked by RCTPAPI-20960)
+    # will lift these one-by-one as Teflon adds capability.
+    # | Filter | Status today | Reason |
+    # |---|---|---|
+    # | `createdAfter`, `createdBefore` | Rejected (400) | Teflon Order Lookup
+    # does not accept date-range filters at the order level. |
+    # | `lastUpdatedAfter` | Rejected (400) | Teflon has no order-level
+    # update-date index. |
+    # | `orderStatuses` with >1 value | Rejected (400) | Teflon accepts one
+    # status per call; pass a single value or omit to match all. |
+    # | `fulfillmentTypes` | Rejected (400) | Teflon accepts one shipNodeType
+    # per call; multi-type fan-out is Phase 2. |
+    # These parameters remain in the contract (rather than being removed)
+    # so that SDKs generated today stay forward-compatible with the
+    # Phase-2 surface — your code keeps compiling, only the runtime
+    # behaviour changes when Phase 2 ships. Until then, omit them or
+    # handle the documented 400 gracefully. The `tools/loadgen-orders.sh
+    # --contract`
+    # smoke sweep exercises the rejection contract on every run.
+    # @param [DateTime] created_after Optional parameter: Filter orders created
+    # after this date-time (ISO 8601).  **Phase-2 — not yet supported.** Sending
+    # this parameter today returns `400 FILTER_NOT_SUPPORTED`; Teflon Order
+    # Lookup does not accept date-range filters at the order level. Tracked by
+    # RCTPAPI-20960. Retained in the contract so SDKs generated today stay
+    # forward-compatible.
+    # @param [DateTime] created_before Optional parameter: Filter orders created
+    # before this date-time (ISO 8601).  **Phase-2 — not yet supported.** See
+    # `createdAfter` for the rationale and the tracking ticket.
+    # @param [DateTime] last_updated_after Optional parameter: Filter orders
+    # updated after this date-time (ISO 8601).  **Phase-2 — not yet supported.**
+    # Sending this parameter today returns `400 FILTER_NOT_SUPPORTED`; Teflon
+    # Order Lookup has no order-level update-date index. Tracked by
+    # RCTPAPI-20960.
+    # @param [Array[OrderStatus]] order_statuses Optional parameter: Filter by
+    # order status.  **Phase-2 limitation:** Teflon Order Lookup accepts AT MOST
+    # ONE status per call. Passing multiple values today returns `400
+    # FILTER_NOT_SUPPORTED`; pass a single value or omit to match all.
+    # Multi-status fan-out tracked by RCTPAPI-20960.
+    # @param [Array[FulfillmentType]] fulfillment_types Optional parameter:
+    # Filter by fulfillment type.  **Phase-2 — not yet supported.** Sending this
+    # parameter today returns `400 FILTER_NOT_SUPPORTED`; Teflon accepts one
+    # shipNodeType per call and multi-type fan-out is Phase 2. Tracked by
+    # RCTPAPI-20960.
+    # @param [Integer] page_size Optional parameter: Example:100
+    # @param [String] next_token Optional parameter: TODO: type description
+    # here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_orders(created_after: nil,
+                   created_before: nil,
+                   last_updated_after: nil,
+                   order_statuses: nil,
+                   fulfillment_types: nil,
+                   page_size: 100,
+                   next_token: nil)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/orders/v4/orders',
+                                     Server::DEFAULT1)
+                   .query_param(new_parameter(created_after, key: 'createdAfter'))
+                   .query_param(new_parameter(created_before, key: 'createdBefore'))
+                   .query_param(new_parameter(last_updated_after, key: 'lastUpdatedAfter'))
+                   .query_param(new_parameter(order_statuses, key: 'orderStatuses'))
+                   .query_param(new_parameter(fulfillment_types, key: 'fulfillmentTypes'))
+                   .query_param(new_parameter(page_size, key: 'pageSize'))
+                   .query_param(new_parameter(next_token, key: 'nextToken'))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(GetFulfillmentOrderResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # TODO: type endpoint description here
+    # @param [String] purchase_order_id Required parameter: Walmart Purchase
+    # Order ID
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_order(purchase_order_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/orders/v4/orders/{purchaseOrderId}',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(GetOrderResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # TODO: type endpoint description here
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @param [AcknowledgeOrderRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def acknowledge_order(purchase_order_id,
+                          body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/orders/v4/orders/{purchaseOrderId}/acknowledge',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(AcknowledgeOrderResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # TODO: type endpoint description here
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @param [ShipOrderLinesRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def ship_order_lines(purchase_order_id,
+                         body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/orders/v4/orders/{purchaseOrderId}/shipping',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(ShipOrderLinesResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # TODO: type endpoint description here
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @param [CancelOrderLinesRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def cancel_order_lines(purchase_order_id,
+                           body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/orders/v4/orders/{purchaseOrderId}/cancel',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(CancelOrderLinesResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Walmart-specific write — no Amazon SP-API Orders v0 equivalent
+    # (Amazon refunds live in the Finance API). Mirrors
+    # gmp-orders-mono's legacy `/partner-api/{market}/v3/orders/{po}/refund`
+    # contract, simplified for the v4 surface: a flat `orderLines[]` with
+    # per-line refund amount + reason instead of the legacy three-level
+    # nesting (`orderLines → refunds → refundCharges`).
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @param [RefundOrderLinesRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def refund_order_lines(purchase_order_id,
+                           body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/orders/v4/orders/{purchaseOrderId}/refund',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(RefundOrderLinesResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Walmart-specific extension of `/shipping`. Each package carries
+    # its own tracking number, carrier, dimensions, and the order
+    # lines it covers. Maps onto FMS's existing `shipments[]` envelope
+    # (one FMS shipment per v4 package). Inspired by gmp-orders-mono's
+    # `shipOrderV2` (multiPackageShipping) operation; we hoist
+    # `packages[]` to the top level rather than nesting it under each
+    # line so the request stays self-evidently package-oriented.
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @param [MultiPackageShipRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def ship_order_multi_package(purchase_order_id,
+                                 body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/orders/v4/orders/{purchaseOrderId}/multi-package-shipping',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(MultiPackageShipResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Parity with Amazon SP-API Orders v0 `getOrderRegulatedInfo`. Returns
+    # the verification requirements that apply to an order containing
+    # regulated items (alcohol, tobacco, age-restricted goods): the
+    # required ID-verification method, the minimum buyer age, the
+    # regulated category, and any value-added services the order ships
+    # with.
+    # **Walmart OMS coverage gap (RCTPAPI-20844).** The Teflon Order
+    # Lookup response does not currently surface regulated-item
+    # metadata. Until upstream support lands (tracked separately as a
+    # follow-up to this PR), every order returns the safe default
+    # `regulatedCategory=NOT_REGULATED` with `requiredVerificationMethod=NONE`.
+    # The endpoint shape and contract are stable; only the projected
+    # values will become richer once OMS exposes the fields.
+    # @param [String] purchase_order_id Required parameter: Walmart Purchase
+    # Order ID
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_order_regulated_info(purchase_order_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/orders/v4/orders/{purchaseOrderId}/regulatedInfo',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(GetOrderRegulatedInfoResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Parity with Amazon SP-API Orders v0 `updateVerificationStatus`. The
+    # seller calls this after delivering a regulated-item order to
+    # record whether the buyer's identity / age was verified at the
+    # doorstep. An APPROVED status releases the order for settlement;
+    # REJECTED requires a `rejectionReason` and triggers downstream
+    # return-processing.
+    # Gated by the CCM-managed `orders.features.regulatedInfoEnabled`
+    # kill-switch (live-refreshable, parity with the cancel kill-switch).
+    # @param [String] purchase_order_id Required parameter: Walmart Purchase
+    # Order ID
+    # @param [UpdateVerificationStatusRequest] body Required parameter: TODO:
+    # type description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def update_verification_status(purchase_order_id,
+                                   body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::PATCH,
+                                     '/orders/v4/orders/{purchaseOrderId}/regulatedInfo',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(UpdateVerificationStatusResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Returns the SKU / quantity / item-price projection of a single
+    # purchase order. Mirrors Amazon SP-API `getOrderItems`. Not
+    # PII-restricted: only product, quantity, and price are returned.
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_order_items(purchase_order_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/orders/v4/orders/{purchaseOrderId}/items',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(GetFulfillmentOrderShipmentsResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Returns the buyer's display name, email address, and an
+    # anonymized phone (last 4 digits only). Mirrors Amazon SP-API
+    # `getOrderBuyerInfo`. PII-restricted endpoint: handlers are
+    # marked `@RestrictedData` server-side and request/response
+    # bodies must NOT be logged.
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_order_buyer_info(purchase_order_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/orders/v4/orders/{purchaseOrderId}/buyerInfo',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(GetOrderBuyerInfoResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Returns the ship-to postal address for a single purchase order.
+    # Mirrors Amazon SP-API `getOrderAddress`. PII-restricted endpoint:
+    # handlers are marked `@RestrictedData` server-side and the
+    # response body must NOT be logged.
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def get_order_address(purchase_order_id)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::GET,
+                                     '/orders/v4/orders/{purchaseOrderId}/address',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(GetOrderAddressResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Records a non-terminal shipment-lifecycle event for an order
+    # (ready for pickup, picked up, in transit, out for delivery).
+    # Use the dedicated `/deliver` endpoint for terminal delivery —
+    # it carries proof-of-delivery semantics this endpoint does not.
+    # Amazon SP-API Orders v0 `updateShipmentStatus` parity.
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @param [UpdateShipmentStatusRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def update_shipment_status(purchase_order_id,
+                               body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/orders/v4/orders/{purchaseOrderId}/shipment-status',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(UpdateShipmentStatusResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+
+    # Records the terminal `Delivered` event for one or more order
+    # lines, optionally with package-level proof-of-delivery
+    # (tracking number, package number, delivery timestamp). This is
+    # separated from `/shipment-status` because delivery is a
+    # terminal state and carries different downstream semantics
+    # (invoicing windows open, return windows start).
+    # Walmart parity from gmp-orders-mono `deliverOrder`.
+    # @param [String] purchase_order_id Required parameter: TODO: type
+    # description here
+    # @param [DeliverOrderLinesRequest] body Required parameter: TODO: type
+    # description here
+    # @return [ApiResponse] Complete http response with raw body and status code.
+    def deliver_order_lines(purchase_order_id,
+                            body)
+      @api_call
+        .request(new_request_builder(HttpMethodEnum::POST,
+                                     '/orders/v4/orders/{purchaseOrderId}/deliver',
+                                     Server::DEFAULT1)
+                   .template_param(new_parameter(purchase_order_id, key: 'purchaseOrderId')
+                                    .is_required(true)
+                                    .should_encode(true))
+                   .header_param(new_parameter('application/json', key: 'Content-Type'))
+                   .body_param(new_parameter(body)
+                                .is_required(true))
+                   .header_param(new_parameter('application/json', key: 'accept'))
+                   .body_serializer(proc do |param| param.to_json unless param.nil? end)
+                   .auth(Single.new('walletAuth')))
+        .response(new_response_handler
+                    .deserializer(APIHelper.method(:custom_type_deserializer))
+                    .deserialize_into(DeliverOrderLinesResponse.method(:from_hash))
+                    .is_api_response(true)
+                    .local_error('400',
+                                 "Bad Request.\n\nThe Phase-2 limitations described on `GET '\
+                                  '/orders/v4/orders`\nsurface here with `code'\
+                                  '=FILTER_NOT_SUPPORTED` and a human-readable\n`message` naming'\
+                                  ' the specific rejected filter. Other validation\nfailures'\
+                                  ' (malformed body, missing required field, unknown enum,\netc.)'\
+                                  ' reuse this response with their own `code` value. The `code`'\
+                                  '\nfield is intentionally an open string — new error codes can'\
+                                  ' be\nadded without a breaking spec change — but the example'\
+                                  ' below is\nthe canonical shape SDK consumers should be prepared'\
+                                  ' to handle.\n",
+                                 ErrorListErrorException)
+                    .local_error('403',
+                                 'Forbidden',
+                                 ErrorListErrorException)
+                    .local_error('404',
+                                 'Not Found',
+                                 ErrorListErrorException)
+                    .local_error('429',
+                                 'Rate limit exceeded',
+                                 ErrorListErrorException)
+                    .local_error('500',
+                                 'Internal Server Error',
+                                 ErrorListErrorException)
+                    .local_error('503',
+                                 'Service temporarily unavailable — the capability is'\
+                                  ' momentarily disabled (e.g. an operational kill-switch) or a'\
+                                  ' dependency is in maintenance. Retryable.',
+                                 ErrorListErrorException))
+        .execute
+    end
+  end
+end