ultracart_api 4.0.54.rc → 4.0.55.rc

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de724f8f9a70a3142fe83ce7b16d0cf64d15ea9e683deabb18f7ce570ffa077a
-  data.tar.gz: b0e92c16cd930b980882c506bd5b288956be35256adcb89d964e59561d608154
+  metadata.gz: 243d3a3106e3395a57819fec0cfc4180771d55adfeb2b0337ccb39e6e516d731
+  data.tar.gz: 03e523e78037dbe4d2acf01c9af181fe53eacc30b554de9d44a7d062969d4986
 SHA512:
-  metadata.gz: b8004463932359b191fb9f3d7d99aec2448a35ffadeb0eede01725baa6dacc3e565dade83be7a42c38d31ee9d2db56b77115875541c5d2fa613e0703ca793d66
-  data.tar.gz: 6b8174d8c216b023457e69fde68b3adf1ff63b78e714781e9c18e6e912319ddf7c4f35240d29ccb3990fb3c1f4fb0352caceb6ea1e81e1b6198abb6dfe7cc8b1
+  metadata.gz: f87d4115dc85836f6ae24728155befc19601cbe759551d6c9775f84dbcacca318f4f8847786df0421e579a0948f79ac1e7b827e60bf17664d2f03d55cae54f7f
+  data.tar.gz: 647ab8d91ad13ca599665588c4cdb4ac3ee6d00311941e1e45dc44ffd4b5bc4b2e2273e2c08ba048adec3812bbcee7fcee6cdd1462287bd0abd79efc03882892

data/README.md

@@ -7,7 +7,7 @@ UltraCart REST API Version 2
 This SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
 - API version: 2.0.0
-- Package version: 4.0.54.rc
+- Package version: 4.0.55.rc
 - Build package: org.openapitools.codegen.languages.RubyClientCodegen
 For more information, please visit [http://www.ultracart.com](http://www.ultracart.com)
 
@@ -24,16 +24,16 @@ gem build ultracart_api.gemspec
 Then either install the gem locally:
 
 ```shell
-gem install ./ultracart_api-4.0.54.rc.gem
+gem install ./ultracart_api-4.0.55.rc.gem
 ```
 
-(for development, run `gem install --dev ./ultracart_api-4.0.54.rc.gem` to install the development dependencies)
+(for development, run `gem install --dev ./ultracart_api-4.0.55.rc.gem` to install the development dependencies)
 
 or publish the gem to a gem hosting service, e.g. [RubyGems](https://rubygems.org/).
 
 Finally add this to the Gemfile:
 
-    gem 'ultracart_api', '~> 4.0.54.rc'
+    gem 'ultracart_api', '~> 4.0.55.rc'
 
 ### Install from Git
 
@@ -171,6 +171,7 @@ Class | Method | HTTP request | Description
 *UltracartClient::CustomerApi* | [**get_customers_by_query**](docs/CustomerApi.md#get_customers_by_query) | **POST** /customer/customers/query | Retrieve customers by query
 *UltracartClient::CustomerApi* | [**get_customers_for_data_tables**](docs/CustomerApi.md#get_customers_for_data_tables) | **POST** /customer/customers/dataTables | Retrieve customers for DataTables plugin
 *UltracartClient::CustomerApi* | [**get_email_verification_token**](docs/CustomerApi.md#get_email_verification_token) | **POST** /customer/customers/email_verify/get_token | Create a token that can be used to verify a customer email address
+*UltracartClient::CustomerApi* | [**get_magic_link**](docs/CustomerApi.md#get_magic_link) | **PUT** /customer/customers/{customer_profile_oid}/magic_link/{storefront_host_name} | getMagicLink
 *UltracartClient::CustomerApi* | [**insert_customer**](docs/CustomerApi.md#insert_customer) | **POST** /customer/customers | Insert a customer
 *UltracartClient::CustomerApi* | [**merge_customer**](docs/CustomerApi.md#merge_customer) | **PUT** /customer/customers/{customer_profile_oid}/merge | Merge customer into this customer
 *UltracartClient::CustomerApi* | [**search_customer_profile_values**](docs/CustomerApi.md#search_customer_profile_values) | **POST** /customer/search | Searches for all matching values (using POST)
@@ -335,6 +336,7 @@ Class | Method | HTTP request | Description
 *UltracartClient::StorefrontApi* | [**get_screen_recordings_by_query**](docs/StorefrontApi.md#get_screen_recordings_by_query) | **POST** /storefront/{storefront_oid}/screen_recordings/query | Query screen recordings
 *UltracartClient::StorefrontApi* | [**get_screen_recordings_by_segment**](docs/StorefrontApi.md#get_screen_recordings_by_segment) | **POST** /storefront/{storefront_oid}/screen_recordings/segments/{screen_recording_segment_oid}/query | Get screen recordings by segment
 *UltracartClient::StorefrontApi* | [**get_store_front_pricing_tiers**](docs/StorefrontApi.md#get_store_front_pricing_tiers) | **GET** /storefront/pricing_tiers | Retrieve pricing tiers
+*UltracartClient::StorefrontApi* | [**get_store_fronts**](docs/StorefrontApi.md#get_store_fronts) | **GET** /storefront/ | Get storefronts (internal use only for security reasons)
 *UltracartClient::StorefrontApi* | [**get_thumbnail_parameters**](docs/StorefrontApi.md#get_thumbnail_parameters) | **POST** /storefront/thumbnailParameters | Get thumbnail parameters
 *UltracartClient::StorefrontApi* | [**get_transaction_email**](docs/StorefrontApi.md#get_transaction_email) | **GET** /storefront/{storefront_oid}/transaction_email/list/{email_id} | Gets a transaction email object
 *UltracartClient::StorefrontApi* | [**get_transaction_email_list**](docs/StorefrontApi.md#get_transaction_email_list) | **GET** /storefront/{storefront_oid}/transaction_email/list | Gets a list of transaction email names
@@ -667,6 +669,7 @@ Class | Method | HTTP request | Description
  - [UltracartClient::CustomerLoyalty](docs/CustomerLoyalty.md)
  - [UltracartClient::CustomerLoyaltyLedger](docs/CustomerLoyaltyLedger.md)
  - [UltracartClient::CustomerLoyaltyRedemption](docs/CustomerLoyaltyRedemption.md)
+ - [UltracartClient::CustomerMagicLinkResponse](docs/CustomerMagicLinkResponse.md)
  - [UltracartClient::CustomerMergeRequest](docs/CustomerMergeRequest.md)
  - [UltracartClient::CustomerOrdersSummary](docs/CustomerOrdersSummary.md)
  - [UltracartClient::CustomerPricingTier](docs/CustomerPricingTier.md)
@@ -1054,6 +1057,8 @@ Class | Method | HTTP request | Description
  - [UltracartClient::SovosConfig](docs/SovosConfig.md)
  - [UltracartClient::StateProvince](docs/StateProvince.md)
  - [UltracartClient::StepWaiting](docs/StepWaiting.md)
+ - [UltracartClient::StoreFront](docs/StoreFront.md)
+ - [UltracartClient::StoreFrontsResponse](docs/StoreFrontsResponse.md)
  - [UltracartClient::TaxCity](docs/TaxCity.md)
  - [UltracartClient::TaxCountry](docs/TaxCountry.md)
  - [UltracartClient::TaxCountryCode](docs/TaxCountryCode.md)
@@ -1182,6 +1187,7 @@ Not every change is committed to every SDK.
 
 | Version | Date | Comments |
 | --: | :-: | --- |
+| 4.0.55-RC | 08/12/2022 | internal code to allow merchant login as customer |
 | 4.0.54-RC | 08/11/2022 | fix entry_dts type on gift certificate ledger |
 | 4.0.53-RC | 08/10/2022 | conversation event refactoring |
 | 4.0.52-RC | 08/05/2022 | conversation adjustments for ES integration |

data/docs/CustomerApi.md

@@ -16,6 +16,7 @@ All URIs are relative to *https://secure.ultracart.com/rest/v2*
 | [**get_customers_by_query**](CustomerApi.md#get_customers_by_query) | **POST** /customer/customers/query | Retrieve customers by query |
 | [**get_customers_for_data_tables**](CustomerApi.md#get_customers_for_data_tables) | **POST** /customer/customers/dataTables | Retrieve customers for DataTables plugin |
 | [**get_email_verification_token**](CustomerApi.md#get_email_verification_token) | **POST** /customer/customers/email_verify/get_token | Create a token that can be used to verify a customer email address |
+| [**get_magic_link**](CustomerApi.md#get_magic_link) | **PUT** /customer/customers/{customer_profile_oid}/magic_link/{storefront_host_name} | getMagicLink |
 | [**insert_customer**](CustomerApi.md#insert_customer) | **POST** /customer/customers | Insert a customer |
 | [**merge_customer**](CustomerApi.md#merge_customer) | **PUT** /customer/customers/{customer_profile_oid}/merge | Merge customer into this customer |
 | [**search_customer_profile_values**](CustomerApi.md#search_customer_profile_values) | **POST** /customer/search | Searches for all matching values (using POST) |
@@ -959,6 +960,79 @@ end
 - **Accept**: application/json
 
 
+## get_magic_link
+
+> <CustomerMagicLinkResponse> get_magic_link(customer_profile_oid, storefront_host_name)
+
+getMagicLink
+
+Retrieves a magic link to allow a merchant to login as a customer.  This method is a PUT call intentionally. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'ultracart_api'
+require 'json'
+require 'yaml'
+require_relative '../constants' # https://github.com/UltraCart/sdk_samples/blob/master/ruby/constants.rb
+
+# This example is based on our samples_sdk project, but still contains auto-generated content from our sdk generators.
+# As such, this might not be the best way to use this object.
+# Please see https://github.com/UltraCart/sdk_samples for working examples.
+
+api = UltracartClient::CustomerApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)
+customer_profile_oid = 56 # Integer | The customer_profile_oid of the customer.
+storefront_host_name = 'storefront_host_name_example' # String | The storefront to log into.
+
+begin
+  # getMagicLink
+  result = api_instance.get_magic_link(customer_profile_oid, storefront_host_name)
+  p result
+rescue UltracartClient::ApiError => e
+  puts "Error when calling CustomerApi->get_magic_link: #{e}"
+end
+```
+
+#### Using the get_magic_link_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<CustomerMagicLinkResponse>, Integer, Hash)> get_magic_link_with_http_info(customer_profile_oid, storefront_host_name)
+
+```ruby
+begin
+  # getMagicLink
+  data, status_code, headers = api_instance.get_magic_link_with_http_info(customer_profile_oid, storefront_host_name)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <CustomerMagicLinkResponse>
+rescue UltracartClient::ApiError => e
+  puts "Error when calling CustomerApi->get_magic_link_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **customer_profile_oid** | **Integer** | The customer_profile_oid of the customer. |  |
+| **storefront_host_name** | **String** | The storefront to log into. |  |
+
+### Return type
+
+[**CustomerMagicLinkResponse**](CustomerMagicLinkResponse.md)
+
+### Authorization
+
+[ultraCartOauth](../README.md#ultraCartOauth), [ultraCartSimpleApiKey](../README.md#ultraCartSimpleApiKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+
 ## insert_customer
 
 > <CustomerResponse> insert_customer(customer, opts)

data/docs/CustomerMagicLinkResponse.md

@@ -0,0 +1,26 @@
+# UltracartClient::CustomerMagicLinkResponse
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **error** | [**Error**](Error.md) |  | [optional] |
+| **metadata** | [**ResponseMetadata**](ResponseMetadata.md) |  | [optional] |
+| **success** | **Boolean** | Indicates if API call was successful | [optional] |
+| **url** | **String** | URL | [optional] |
+| **warning** | [**Warning**](Warning.md) |  | [optional] |
+
+## Example
+
+```ruby
+require 'ultracart_api'
+
+instance = UltracartClient::CustomerMagicLinkResponse.new(
+  error: null,
+  metadata: null,
+  success: null,
+  url: null,
+  warning: null
+)
+```
+

data/docs/StoreFront.md

@@ -0,0 +1,38 @@
+# UltracartClient::StoreFront
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **host_alias1** | **String** |  | [optional] |
+| **host_alias2** | **String** |  | [optional] |
+| **host_alias3** | **String** |  | [optional] |
+| **host_alias4** | **String** |  | [optional] |
+| **host_alias5** | **String** |  | [optional] |
+| **host_name** | **String** |  | [optional] |
+| **locked** | **Boolean** |  | [optional] |
+| **merchant_id** | **String** |  | [optional] |
+| **redirect_aliases** | **Boolean** |  | [optional] |
+| **storefront_oid** | **Integer** |  | [optional] |
+| **unlock_password** | **String** |  | [optional] |
+
+## Example
+
+```ruby
+require 'ultracart_api'
+
+instance = UltracartClient::StoreFront.new(
+  host_alias1: null,
+  host_alias2: null,
+  host_alias3: null,
+  host_alias4: null,
+  host_alias5: null,
+  host_name: null,
+  locked: null,
+  merchant_id: null,
+  redirect_aliases: null,
+  storefront_oid: null,
+  unlock_password: null
+)
+```
+

data/docs/StoreFrontsResponse.md

@@ -0,0 +1,26 @@
+# UltracartClient::StoreFrontsResponse
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **error** | [**Error**](Error.md) |  | [optional] |
+| **metadata** | [**ResponseMetadata**](ResponseMetadata.md) |  | [optional] |
+| **store_fronts** | [**Array<StoreFront>**](StoreFront.md) |  | [optional] |
+| **success** | **Boolean** | Indicates if API call was successful | [optional] |
+| **warning** | [**Warning**](Warning.md) |  | [optional] |
+
+## Example
+
+```ruby
+require 'ultracart_api'
+
+instance = UltracartClient::StoreFrontsResponse.new(
+  error: null,
+  metadata: null,
+  store_fronts: null,
+  success: null,
+  warning: null
+)
+```
+

data/docs/StorefrontApi.md

@@ -105,6 +105,7 @@ All URIs are relative to *https://secure.ultracart.com/rest/v2*
 | [**get_screen_recordings_by_query**](StorefrontApi.md#get_screen_recordings_by_query) | **POST** /storefront/{storefront_oid}/screen_recordings/query | Query screen recordings |
 | [**get_screen_recordings_by_segment**](StorefrontApi.md#get_screen_recordings_by_segment) | **POST** /storefront/{storefront_oid}/screen_recordings/segments/{screen_recording_segment_oid}/query | Get screen recordings by segment |
 | [**get_store_front_pricing_tiers**](StorefrontApi.md#get_store_front_pricing_tiers) | **GET** /storefront/pricing_tiers | Retrieve pricing tiers |
+| [**get_store_fronts**](StorefrontApi.md#get_store_fronts) | **GET** /storefront/ | Get storefronts (internal use only for security reasons) |
 | [**get_thumbnail_parameters**](StorefrontApi.md#get_thumbnail_parameters) | **POST** /storefront/thumbnailParameters | Get thumbnail parameters |
 | [**get_transaction_email**](StorefrontApi.md#get_transaction_email) | **GET** /storefront/{storefront_oid}/transaction_email/list/{email_id} | Gets a transaction email object |
 | [**get_transaction_email_list**](StorefrontApi.md#get_transaction_email_list) | **GET** /storefront/{storefront_oid}/transaction_email/list | Gets a list of transaction email names |
@@ -7380,6 +7381,72 @@ end
 - **Accept**: application/json
 
 
+## get_store_fronts
+
+> <StoreFrontsResponse> get_store_fronts
+
+Get storefronts (internal use only for security reasons)
+
+### Examples
+
+```ruby
+require 'time'
+require 'ultracart_api'
+require 'json'
+require 'yaml'
+require_relative '../constants' # https://github.com/UltraCart/sdk_samples/blob/master/ruby/constants.rb
+
+# This example is based on our samples_sdk project, but still contains auto-generated content from our sdk generators.
+# As such, this might not be the best way to use this object.
+# Please see https://github.com/UltraCart/sdk_samples for working examples.
+
+api = UltracartClient::StorefrontApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)
+
+begin
+  # Get storefronts (internal use only for security reasons)
+  result = api_instance.get_store_fronts
+  p result
+rescue UltracartClient::ApiError => e
+  puts "Error when calling StorefrontApi->get_store_fronts: #{e}"
+end
+```
+
+#### Using the get_store_fronts_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<StoreFrontsResponse>, Integer, Hash)> get_store_fronts_with_http_info
+
+```ruby
+begin
+  # Get storefronts (internal use only for security reasons)
+  data, status_code, headers = api_instance.get_store_fronts_with_http_info
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <StoreFrontsResponse>
+rescue UltracartClient::ApiError => e
+  puts "Error when calling StorefrontApi->get_store_fronts_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+This endpoint does not need any parameter.
+
+### Return type
+
+[**StoreFrontsResponse**](StoreFrontsResponse.md)
+
+### Authorization
+
+[ultraCartBrowserApiKey](../README.md#ultraCartBrowserApiKey), [ultraCartOauth](../README.md#ultraCartOauth), [ultraCartSimpleApiKey](../README.md#ultraCartSimpleApiKey)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+
 ## get_thumbnail_parameters
 
 > <ThumbnailParametersResponse> get_thumbnail_parameters(thumbnail_parameters)

data/lib/ultracart_api/api/customer_api.rb

@@ -928,6 +928,76 @@ module UltracartClient
       return data, status_code, headers
     end
 
+    # getMagicLink
+    # Retrieves a magic link to allow a merchant to login as a customer.  This method is a PUT call intentionally. 
+    # @param customer_profile_oid [Integer] The customer_profile_oid of the customer.
+    # @param storefront_host_name [String] The storefront to log into.
+    # @param [Hash] opts the optional parameters
+    # @return [CustomerMagicLinkResponse]
+    def get_magic_link(customer_profile_oid, storefront_host_name, opts = {})
+      data, _status_code, _headers = get_magic_link_with_http_info(customer_profile_oid, storefront_host_name, opts)
+      data
+    end
+
+    # getMagicLink
+    # Retrieves a magic link to allow a merchant to login as a customer.  This method is a PUT call intentionally. 
+    # @param customer_profile_oid [Integer] The customer_profile_oid of the customer.
+    # @param storefront_host_name [String] The storefront to log into.
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(CustomerMagicLinkResponse, Integer, Hash)>] CustomerMagicLinkResponse data, response status code and response headers
+    def get_magic_link_with_http_info(customer_profile_oid, storefront_host_name, opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: CustomerApi.get_magic_link ...'
+      end
+      # verify the required parameter 'customer_profile_oid' is set
+      if @api_client.config.client_side_validation && customer_profile_oid.nil?
+        fail ArgumentError, "Missing the required parameter 'customer_profile_oid' when calling CustomerApi.get_magic_link"
+      end
+      # verify the required parameter 'storefront_host_name' is set
+      if @api_client.config.client_side_validation && storefront_host_name.nil?
+        fail ArgumentError, "Missing the required parameter 'storefront_host_name' when calling CustomerApi.get_magic_link"
+      end
+      # resource path
+      local_var_path = '/customer/customers/{customer_profile_oid}/magic_link/{storefront_host_name}'.sub('{' + 'customer_profile_oid' + '}', CGI.escape(customer_profile_oid.to_s)).sub('{' + 'storefront_host_name' + '}', CGI.escape(storefront_host_name.to_s))
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      header_params['X-UltraCart-Api-Version'] = @api_client.select_header_api_version()
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'CustomerMagicLinkResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ultraCartOauth', 'ultraCartSimpleApiKey']
+
+      new_options = opts.merge(
+        :operation => :"CustomerApi.get_magic_link",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:PUT, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: CustomerApi#get_magic_link\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
     # Insert a customer
     # Insert a customer on the UltraCart account. 
     # @param customer [Customer] Customer to insert

data/lib/ultracart_api/api/storefront_api.rb

@@ -6894,6 +6894,62 @@ module UltracartClient
       return data, status_code, headers
     end
 
+    # Get storefronts (internal use only for security reasons)
+    # @param [Hash] opts the optional parameters
+    # @return [StoreFrontsResponse]
+    def get_store_fronts(opts = {})
+      data, _status_code, _headers = get_store_fronts_with_http_info(opts)
+      data
+    end
+
+    # Get storefronts (internal use only for security reasons)
+    # @param [Hash] opts the optional parameters
+    # @return [Array<(StoreFrontsResponse, Integer, Hash)>] StoreFrontsResponse data, response status code and response headers
+    def get_store_fronts_with_http_info(opts = {})
+      if @api_client.config.debugging
+        @api_client.config.logger.debug 'Calling API: StorefrontApi.get_store_fronts ...'
+      end
+      # resource path
+      local_var_path = '/storefront/'
+
+      # query parameters
+      query_params = opts[:query_params] || {}
+
+      # header parameters
+      header_params = opts[:header_params] || {}
+      header_params['X-UltraCart-Api-Version'] = @api_client.select_header_api_version()
+      # HTTP header 'Accept' (if needed)
+      header_params['Accept'] = @api_client.select_header_accept(['application/json'])
+
+      # form parameters
+      form_params = opts[:form_params] || {}
+
+      # http body (model)
+      post_body = opts[:debug_body]
+
+      # return_type
+      return_type = opts[:debug_return_type] || 'StoreFrontsResponse'
+
+      # auth_names
+      auth_names = opts[:debug_auth_names] || ['ultraCartBrowserApiKey', 'ultraCartOauth', 'ultraCartSimpleApiKey']
+
+      new_options = opts.merge(
+        :operation => :"StorefrontApi.get_store_fronts",
+        :header_params => header_params,
+        :query_params => query_params,
+        :form_params => form_params,
+        :body => post_body,
+        :auth_names => auth_names,
+        :return_type => return_type
+      )
+
+      data, status_code, headers = @api_client.call_api(:GET, local_var_path, new_options)
+      if @api_client.config.debugging
+        @api_client.config.logger.debug "API called: StorefrontApi#get_store_fronts\nData: #{data.inspect}\nStatus code: #{status_code}\nHeaders: #{headers}"
+      end
+      return data, status_code, headers
+    end
+
     # Get thumbnail parameters
     # @param thumbnail_parameters [ThumbnailParametersRequest] Thumbnail Parameters
     # @param [Hash] opts the optional parameters