Class: NewStoreApi::ShippingOptionsController

Inherits:
BaseController show all
Defined in:
lib/new_store_api/controllers/shipping_options_controller.rb

Overview

ShippingOptionsController

Constant Summary

Constants inherited from BaseController

BaseController::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseController

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseController

#initialize, #new_parameter, #new_request_builder, #new_response_handler, user_agent

Constructor Details

This class inherits a constructor from NewStoreApi::BaseController

Instance Method Details

#create_service_level_rates(body) ⇒ ResponseServiceLevelRates

🚧 BETA: This endpoint is in beta and may change.
See API Lifecycle Documentation for details.
Estimate shipping costs of all possible Service Levels for a given bag of products. ## Goal This is primarily meant for Endless Aisle orders, where a customer is waiting in front of a person to select a shipping offer with an estimate of a price and delivery time. **This endpoint allows to respond faster than `POST /shipping-options`, although possibly with less accurate results.** Then the user/customer can chose the service level of their choice. ## Requesting some Service Level Rates Follow the documentation for the request body's schema. In a nutshell, you only need to provide the recipient's address, the products to ship along with their metadata (weight / dimensions / customs / preorder…). ### Pre-order products For product that are part of a pre-order, provide both `is_preorder=True` and its `online_from` date, as shown in the schema. ## Using the Service Level Rates The responses provides a list of "service level rates", where each item of the list match a single service level, with all requested products dispatched in various fulfillment nodes, and for different prices. The **total price and currency of the option** are set in `total_price` and `total_price_currency` respectively, and should be the price and currency to show to the user/customer. Once the user/customer selected a service level, another process must follow up with generation of a real option (and pricing) to be obtained from a real carrier. ### Getting a real Option (and pricing) from a real carrier Once a user/customer selected their preferred shipping method/cost, you may generate real options using **POST /shipping-options** endpoint. The endpoint is very similar to this one, sharing a large part of its payload with the addition of the sender address. You will need to specify the Service Level ID that correspond to the user/customer's choice. ## Example 1. Get Service Level Rates URL and attributes have been trimmed to keep the example concise, please refer to the exact request body schema. ``` $ curl -d '[...2 products...], "recipient_address": {"country_code": "US", ...}' https://.../service-level-rates { "service_level_rates": [ { "service_level_id": "Standard", "total_price": "10.0", "total_price_currency": "EUR", "fulfillment_assignments": [ "StoreNYC", "products": [...1/2 product...], "DC01", "products": [...2/2 product...] ] }, { "service_level_id": "Express", "total_price": "35.8", "total_price_currency": "EUR", "fulfillment_assignments": [ "StoreNYC", "products": [...1/2 product...], "DC01", "products": [...2/2 product...] ] } ] } ``` User selects the `Express` service level, as it's more expensive but faster. You can now proceed to generate a real options that will be used to create the order in NewStore platform. You will need to generate one option for each `fulfillment_assignment`, as it requires both a Service Level **and** a **Fulfillment Node ID**. ``` $ curl -d '[...], "recipient_address": {..., "service_level": "Express", "location_id": "StoreNYC", ...}' $ curl -d '[...], "recipient_address": {..., "service_level": "Express", "location_id": "DC01", ...}' ``` Once real options are generated, capture can proceed with those. Use the `option_id` as replacement of the `shipping_option_token`. ## Details on Price and Currency selection modes
  • Service Level: by default, if nothing else is configured, then the Service Level informs the price.
  • Provider Rate Customization: if enabled by tenant and customized provider rate is set to use custom price.
  • Carrier: if a Provider Rate matching the Service Level is configured to set the price of the option. The price again obliges to different configurations, and the total shown in those attributes can be different from the addition of prices of each fulfillment_assignments.

Corner Cases

  • In case of international shipment, the resulting price might not be correct depending on the tenant's provider rates priority. This is documented in the code.
  • Should a service_level_rate host a mix of currencies, total_price and total_price_currency will be null. description here

Parameters:

Returns:



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/new_store_api/controllers/shipping_options_controller.rb', line 118

def create_service_level_rates(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/fulfillment/service-level-rates',
                                 Server::API)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('oauth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ResponseServiceLevelRates.method(:from_hash)))
    .execute
end

#create_shipping_option(body, x_audit_route_id: nil, x_audit_option_id: nil, x_dlv1_offer: nil, x_dlv1_no_prca: nil) ⇒ ResponseShippingOption

TODO: type endpoint description here description here

Parameters:

  • body (RequestShippingOption) —

    Required parameter: TODO: type

  • x_audit_route_id (String) (defaults to: nil) —

    Optional parameter: Example:

  • x_audit_option_id (String) (defaults to: nil) —

    Optional parameter: Example:

  • x_dlv1_offer (String) (defaults to: nil) —

    Optional parameter: Example:

  • x_dlv1_no_prca (String) (defaults to: nil) —

    Optional parameter: Example:

Returns:



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/new_store_api/controllers/shipping_options_controller.rb', line 142

def create_shipping_option(body,
                           x_audit_route_id: nil,
                           x_audit_option_id: nil,
                           x_dlv1_offer: nil,
                           x_dlv1_no_prca: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/fulfillment/shipping-options',
                                 Server::API)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter(x_audit_route_id, key: 'x-audit-route-id'))
               .header_param(new_parameter(x_audit_option_id, key: 'x-audit-option-id'))
               .header_param(new_parameter(x_dlv1_offer, key: 'x-dlv1-offer'))
               .header_param(new_parameter(x_dlv1_no_prca, key: 'x-dlv1-no-prca'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('oauth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ResponseShippingOption.method(:from_hash)))
    .execute
end

#show_shipping_option(option_id) ⇒ ResponseShippingOption

TODO: type endpoint description here description here

Parameters:

  • option_id (UUID | String) —

    Required parameter: TODO: type

Returns:



170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/new_store_api/controllers/shipping_options_controller.rb', line 170

def show_shipping_option(option_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/fulfillment/shipping-options/{option_id}',
                                 Server::API)
               .template_param(new_parameter(option_id, key: 'option_id')
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('oauth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ResponseShippingOption.method(:from_hash)))
    .execute
end