diff --git a/src/_data/toc/inventory.yml b/src/_data/toc/inventory.yml index 35a816aec21..87ecf867f3b 100644 --- a/src/_data/toc/inventory.yml +++ b/src/_data/toc/inventory.yml @@ -50,6 +50,10 @@ pages: - label: Manage source selection algorithms url: /rest/modules/inventory/manage-source-selection.html + - label: In-Store Pickup + url: /rest/modules/inventory/in-store-pickup.html + exclude_versions: ["2.3"] + - label: Manage Inventory Management modules url: /extensions/inventory-management/ versionless: true diff --git a/src/_data/toc/rest-api.yml b/src/_data/toc/rest-api.yml index de36bdc86f7..4f940978e05 100644 --- a/src/_data/toc/rest-api.yml +++ b/src/_data/toc/rest-api.yml @@ -255,3 +255,8 @@ pages: - label: Manage source selection algorithms url: /rest/modules/inventory/manage-source-selection.html + + - label: In-Store Pickup + url: /rest/modules/inventory/in-store-pickup.html + exclude_versions: ["2.3"] + diff --git a/src/guides/v2.4/rest/modules/inventory/in-store-pickup.md b/src/guides/v2.4/rest/modules/inventory/in-store-pickup.md new file mode 100644 index 00000000000..9238eb7ecc0 --- /dev/null +++ b/src/guides/v2.4/rest/modules/inventory/in-store-pickup.md @@ -0,0 +1,146 @@ +--- +group: rest-api +title: In-Store Pickup +contributor_name: Oleksandr Kravchuk +contributor_link: https://github.com/swnsma +--- + +The Inventory In-Store Pickup functionality exposes an endpoint that retrieves a list of pickup locations, and another endpoint that notifies the customer that their order is ready for pickup. + +**Service names:** + +```http +inventoryInStorePickupApiGetPickupLocationsV1 +inventoryInStorePickupSalesApiNotifyOrdersAreReadyForPickupV1 +``` + +**REST endpoints:** + +```http +GET /V1/inventory/in-store-pickup/pickup-locations +POST /V1/order/notify-orders-are-ready-for-pickup +``` + +## Search for pickup locations + +The `GET /V1/inventory/in-store-pickup/pickup-locations` endpoint searches for and filters on pickup locations, allowing the shopper to quickly narrow the results. The endpoint does not require authentication. + +Search terms, filters, and other attributes are specified as query parameters in the URL. This endpoint uses a different syntax than other Magento GET calls that send `searchCriteria` parameters. Instead, the `GET /V1/inventory/in-store-pickup/pickup-locations` endpoint requires that each query parameter begins with `searchRequest`. The `scopeCode` parameter is required. All other parameters are optional. + +Name | Type | Description +--- | --- | --- +`[scopeCode]=` | String | Required. The Sales Channel code of the assigned Stock. +`[scopeType]=` | String | The Sales Channel type. The default value is `website`. +`[area][radius]=` | Int | The radius, in kilometers, to search. The Distance Priority Algorithm must be configured to search an area. This parameter must be used with `[area][searchTerm]`. +`[area][searchTerm]=` | String | The text to search, such as a city or region. This parameter must be used with `[area][radius]`. +`[filters][country][value]=` | String | Filters by the specified `country_id`. +`[filters][country][conditionType]=` | String | Optional. The default value is `eq`. +`[filters][postcode][value]=` | String | Filters by the specified `postcode`. +`[filters][postcode][conditionType]=` | String | Optional. The default value is `eq`. +`[filters][region][value]=` | String | Filters by the specified `region`. +`[filters][region][conditionType]=` | String | Optional. The default value is `eq`. +`[filters][city][value]=` | String | Filters by the specified `city`. +`[filters][city][conditionType]=` | String | Optional. The default value is `eq`. +`[filters][street][value]=` | String | Filters by the specified `street`. +`[filters][street][conditionType]=` | String | Optional. The default value is `eq`. +`[filters][name][value]=` | String | Filters by the specified display `name`. +`[filters][name][conditionType]=` | String | Optional. The default value is `eq`. +`[filters][pickupLocationCode][value]=` | String | Filters by the specified source code name. +`[filters][pickupLocationCode][conditionType]=` | String | Optional. The default value is `eq`. +`[extensionAttributes][productsInfo][0][sku]=` | String | Returns a list of products with the specified SKU that are assigned to each pickup location. Locations without all the assigned products will be filtered out. +`[extensionAttributes][productsInfo][0][extensionAttributes]=` | String | Extension point reserved for future use. +`[pageSize]=` | Int | Specifies the maximum number of items to return. +`[currentPage]=` | Int | Returns the current page. +`[sort][0][field]=` | String | Specifies the field to sort on. +`[sort][0][direction]=` | String | Specifies whether to return results in ascending (`ASC`) or descending (`DESC`) order. The default is `DESC`. + +[Search using REST endpoints]({{page.baseurl}}/rest/performing-searches.html) provides a full list of supported condition types. + +**Sample Usage:** + +`GET /rest//V1/inventory/in-store-pickup/pickup-locations` + +**Payload:** + +Define the payload as part of the `GET` request string. + +```http +searchRequest[area][radius]=1500& +searchRequest[area][searchTerm]=Austin& +searchRequest[scopeCode]=base& +searchRequest[extensionAttributes][productsInfo][0][sku]=SKU1 +``` + +**Response:** + +Magento returns Pickup Locations list, search request given and total results count. + +```json +{ + "items": [ + { + "pickup_location_code": "txspeqs", + "name": "Sport Equipment Store", + "email": "sales@company.com", + "contact_name": "Ethan Carter", + "description": "Sport Equipment Store description", + "latitude": 29.7543, + "longitude": -95.3609, + "country_id": "US", + "region_id": 57, + "region": "Texas", + "city": "Houston", + "street": "4631 Airport Blvd #125", + "postcode": "77010", + "phone": "(555) 555-5555" + } + ], + "search_request": { + "area": { + "radius": 1500, + "search_term": "Austin" + }, + "current_page": 1, + "scope_type": "website", + "scope_code": "base", + "extension_attributes": { + "products_info": [ + { + "sku": "SKU1" + } + ] + } + }, + "total_count": 1 +} +``` + +## Mark an order as ready for pickup + +The `POST /V1/order/notify-orders-are-ready-for-pickup` endpoint creates a shipment and sends an email notifying the customer that the order is ready to be picked up. +The endpoint requires appropriate permission to resource `Magento_InventoryInStorePickupApi::notify_orders_are_ready_for_pickup`. + +**Sample Usage:** + +`POST /rest//V1/order/notify-orders-are-ready-for-pickup` + +**Payload:** + +```json +{ + "orderIds": [ + 81 + ] +} +``` + +**Response:** + +Magento returns an array with success status and an array of error messages for each failed order. + +```json +{ + "successful": true, + "failed": [] +} +``` diff --git a/src/guides/v2.4/rest/modules/inventory/manage-sources.md b/src/guides/v2.4/rest/modules/inventory/manage-sources.md deleted file mode 120000 index 9de5a2e3329..00000000000 --- a/src/guides/v2.4/rest/modules/inventory/manage-sources.md +++ /dev/null @@ -1 +0,0 @@ -../../../../v2.3/rest/modules/inventory/manage-sources.md \ No newline at end of file diff --git a/src/guides/v2.4/rest/modules/inventory/manage-sources.md b/src/guides/v2.4/rest/modules/inventory/manage-sources.md new file mode 100644 index 00000000000..5f8fab8ead5 --- /dev/null +++ b/src/guides/v2.4/rest/modules/inventory/manage-sources.md @@ -0,0 +1,257 @@ +--- +group: rest-api +title: Manage sources +--- + +Sources represent locations storing and shipping available product stock. Any location with available stock and capable of order fulfillment can be added as a source. These locations can include warehouses, brick-and-mortar stores, distribution centers, and drop shippers. + +All stores begin with a default source that must remain enabled. Single Source merchants (merchants who ship all products from one location) use the default source for their single point of inventory location and shipments. Multi Source merchants create as many sources as they need to represent each location. + +You cannot rename, delete, or disable the default source. You can create, modify, enable, and disable custom sources, but you cannot rename or delete a custom source. + +Disabling a custom source has the following effects: + +* Magento ignores and does not list the source for shipment or order processing +* Stocks do not access inventory quantities from the source for aggregated inventory totals +* Order shipments cannot be assigned to disabled locations. + +{:.bs-callout-info} +Bundle and grouped products currently do not support multi-sourcing and must be assigned to the default source and default stock. + +**Service name:** + +`inventoryApiSourceRepositoryV1` + +**REST endpoints:** + +```http +POST /V1/inventory/sources +GET /V1/inventory/sources/:sourceCode +PUT /V1/inventory/sources/:sourceCode +GET /V1/inventory/sources +``` + +**SourceInterface parameters:** + +Name | Description | Type | Requirements +--- | --- | --- | --- +`source_code` | A unique identifier for the source | String | Required to create a source. This value cannot be changed with a PUT call. +`name` | A unique display name for the source. | String | Required for all POST and PUT calls +`email` | The email for the source's contact | String | Optional +`contact_name` | The name of the contact for the source | String | Optional +`enabled` | Indicates whether the source is enabled. The default value is `true`. | Boolean | Optional +`description` | A description of the source (Maximum: 1000 characters)| String | Optional +`latitude` | The latitude of the source's physical location. The value, along with the `longitude` value, could be used to determine the closest source to a customer's shipping address. | Float | Optional +`longitude` |The latitude of the source's physical location. | Float | Optional +`country_id` | The country ID of the source's physical location | String | Required for all POST and PUT calls. +`region_id` | The region ID of the state or province of the source | Integer | Optional +`region` | The region name for countries whose provinces are not defined in Magento | String | Optional +`city` | Th city in which the source is located | String | Optional +`street` | The physical street address of the source | String | Optional +`postcode` | The zip or postal code of the source's physical address | String | Required for all POST and PUT calls +`phone` | The contact's phone number | String | Optional +`fax` | The contact's fax number | String | Optional +`use_default_carrier_config` | Reserved for future use | Boolean | Optional +`carrier_code` | Reserved for future use | String | Optional +`position` | Reserved for future use | Integer | Optional + +**In-Store Pickup functionality enhance Sources with next extension attributes:** +Name | Description | Type | Requirements +`is_pickup_location_active` | Indicates whether a source can be used as a pickup location | Boolean | Optional +`frontend_name` | The pickup location name. This value is used only on the Storefront. | String | Optional +`frontend_description` | The pickup location description. It is used only on the Storefront. | String | Optional + +## Create a source + +The value of the `source_code` parameter can contain upper and lower case letters, numbers, dashes, and underscores. You use this ID when assigning stock to sources and when exporting or importing data. + +**Sample Usage:** + +`POST /rest//V1/inventory/sources` + +**Payload:** + +```json +{ + "source" : { + "name" : "Central Shipping Center", + "source_code" : "central", + "enabled" : true, + "description": "Primary source for the central region", + "latitude": "38.741320", + "longitude": "-90.363267", + "contact_name": "Harold Smith", + "email": "hsmith@example.com", + "phone": "(314) 555-1234", + "country_id" : "US", + "region_id": 36, + "city": "St. Louis", + "street": "123 Warehouse Blvd", + "postcode" : "63145", + "extension_attributes": { + "is_pickup_location_active": true, + "frontend_name": "Sport Equipment Store", + "frontend_description": "Sport Equipment Store description" + } + } +} +``` + +**Response:** + +Magento returns an empty array. + +`[]` + +## Update a source + +All PUT requests must contain the `name`, `country_id`, and `postcode` parameters. + +This example updates the contact information (`contact_name`, `email`, and `phone` parameters) of the source. + +**Sample Usage:** + +`PUT /rest//V1/inventory/sources/central` + +**Payload:** + +```json +{ + "source" : { + "name": "Central Shipping Center", + "contact_name": "Donna Milton", + "email": "dmilton@example.com", + "phone": "(314) 555-1237", + "country_id" : "US", + "postcode" : "63145" + } +} +``` + +**Response:** + +Magento returns an empty array. + +`[]` + +## Return all information about a source + +This call returns detailed information about the specified source. + +**Sample Usage:** + +`GET /rest//V1/inventory/sources/central` + +**Payload:** + +None + +**Response:** + +```json +{ + "source_code": "central", + "name": "Central Shipping Center", + "email": "dmilton@example.com", + "contact_name": "Donna Milton", + "enabled": true, + "description": "Primary source for the central region", + "latitude": 38.74132, + "longitude": -90.363267, + "country_id": "US", + "region_id": 36, + "city": "St. Louis", + "street": "123 Warehouse Blvd", + "postcode": "63145", + "phone": "(314) 555-1237", + "use_default_carrier_config": true, + "carrier_links": [] +} +``` + +## Search for sources + +The following call returns all sources that are located in the United States (`country_id` = `US`) + +See [Search using REST APIs]({{ page.baseurl }}/rest/performing-searches.html) for information about constructing a search query. + +**Sample Usage:** + +`GET /rest//V1/inventory/sources?searchCriteria[filter_groups][0][filters][0][field]=country_id&searchCriteria[filter_groups][0][filters][0][value]=US&searchCriteria[filter_groups][0][filters][0][condition_type]=eq` + +**Payload:** + +None + +**Response:** + +{% collapsible Show code sample %} + +```json +{ + "items": [ + { + "source_code": "central", + "name": "Central Shipping Center", + "email": "hsmith@example.com", + "contact_name": "Harold Smith", + "enabled": true, + "description": "Primary source for the central region", + "latitude": 38.74132, + "longitude": -90.363267, + "country_id": "US", + "region_id": 36, + "city": "St. Louis", + "street": "123 Warehouse Blvd", + "postcode": "63145", + "phone": "(314) 555-1234", + "use_default_carrier_config": true, + "carrier_links": [] + }, + { + "source_code": "default", + "name": "Default Source", + "enabled": true, + "description": "Default Source", + "latitude": 0, + "longitude": 0, + "country_id": "US", + "postcode": "00000", + "use_default_carrier_config": true, + "carrier_links": [] + }, + { + "source_code": "east", + "name": "Eastern Shipping Center", + "email": "dsimons@example.com", + "contact_name": "Daryl Simons", + "enabled": true, + "description": "Primary source for the eastern region", + "country_id": "US", + "region_id": 45, + "city": "Raleigh", + "street": "456 Shipping Center Blvd", + "postcode": "27614", + "phone": "(919) 555-8888", + "use_default_carrier_config": true, + "carrier_links": [] + } + ], + "search_criteria": { + "filter_groups": [ + { + "filters": [ + { + "field": "country_id", + "value": "US", + "condition_type": "eq" + } + ] + } + ] + }, + "total_count": 3 +} +``` + +{% endcollapsible %}