In Store Pickup API Tutorials

Table of Contents

• Configure In-Store Pickup delivery
• Create a Pickup Location
• Search Pickup Locations
• Search Pickup Locations using GraphQL
• Place order using In-Store Pickup delivery method
• Place order using In-Store Pickup delivery method with GraphQL

In-Store Pickup API Tutorials

For more information, you can also check In-Store Pickup API references.

Configure In-Store Pickup delivery

Go to Stores > Configuration > Sales > Delivery Methods and enable In-Store Delivery.

Delivery type	Configuration name	Enabled by default?
In-Store Delivery	in_store	No

Next, configure Distance Priority algorithm provider - it is used for filtering pickup locations by distance radius.

Create a Pickup Location

The name, source_code, country_id, and postcode attributes are required for a Source creation.

city, street, and phone are required for Pickup Location additionally.

Endpoint
POST http://<host>/rest/all/V1/inventory/sources

Headers
Content-Type application/json
Authorization: Bearer <admin_token>

Payload

{
  "source": {
    "description": " Source #17",
    "source_code": "txspeqs",
    "phone": "(555) 555-5555",
    "email": "[email protected]",
    "postcode": "77010",
    "longitude": -95.383056,
    "enabled": true,
    "contact_name": "Ethan Carter",
    "latitude": 29.762778,
    "region_id": 57,
    "region": "Texas",
    "name": "Texas Sport Equipment Source #017",
    "country_id": "US",
    "city": "Houston",
    "street": "4631 Airport Blvd #125",
    "extension_attributes": {
      "is_pickup_location_active": true,
      "frontend_name": "Sport Equipment Store",
      "frontend_description": "Sport Equipment Store description"
    }
  }
}

Response
Magento returns an empty array.
[]

Search Pickup Locations

inventoryInStorePickupApiGetPickupLocationsV1 API is responsible for searching Pickup Locations. It has a wide variety of request parameters making it quite flexible:

• area (optional): for searching locations by area defined by a distance radius from the customer address
  • radius (required): search radius in KM, integer value.
  • searchTerm (required): search term string
• filters (optional) - a set of Pickup Location fields filters. Similar to regular Magento repository's filterGroups field. There are filters by:
  • country (optional)
  • postcode (optional)
  • region (optional)
  • city (optional)
  • street (optional)
  • name (optional)
  • pickupLocationCode (optional)
• pageSize (optional) - analog of Magento repository's pageSize
• currentPage (optional) - analog of Magento repository's currentPage
• scopeType (optional) - Sales Channel Type. Default value is website
• scopeCode (required) - Sales Channel code. The only one required parameter.
• sort (optional) - analog of Magento repository's sort
• extensionAttributes (optional)
  • productsInfo - list of products that be assigned to each pickup location. Locations without all the products assigned will be filtered out.
    • [0] - single product info node
      • sku (required) - product SKU
      • extensionAttributes - extension point for future customizations

Endpoint
GET http://<host>/rest/all/V1/inventory/in-store-pickup/pickup-locations/

Payload

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.

{
  "items": [
    {
      "pickup_location_code": "txspeqs",
      "name": "Sport Equipment Store",
      "email": "[email protected]",
      "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
}

Search Pickup Locations using GraphQL

Magento GraphQl schema was extended to support the search of Pickup Locations on frontend application. To do so, you can use the pickupLocations query type. Schema of the query supports the most number of filters as an API endpoint. Currently, search by SKU assignment is not supported in GraphQl.

Payload

{
  pickupLocations(
    area:{
      radius: 1500
      search_term: "Austin:US"
    }
    pageSize: 1
    currentPage: 1
    sort: {distance: ASC}
  ) {
    items {
      pickup_location_code
      name
      email
      fax
      description
      latitude
      longitude
      country_id
      region_id
      region
      city
      street
      postcode
      phone
    },
    total_count
    page_info {
      page_size
      current_page
      total_pages
    }
  }
}

Response

{
  "data": {
    "pickupLocations": {
      "items": [
        {
          "pickup_location_code": "txspeqs",
          "name": "Sport Equipment Store",
          "email": "[email protected]",
          "fax": null,
          "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"
        }
      ],
      "total_count": 1,
      "page_info": {
        "page_size": 1,
        "current_page": 1,
        "total_pages": 1
      }
    }
  }
}

Place order using the In-Store Pickup delivery method

First of all, Configure In-Store Pickup delivery, Create a Pickup Location and proceed with steps 1-8 (except setting delivery method) described in the Order Processing with Inventory Management tutorial.

Find a pickup location suitable for placing the order with. For example, let it be 'Sport Equipment Store' with code txspeqs.

Set the In-Store Pickup Delivery method, and the pickup location code.

Endpoint

POST <host>/rest/us/V1/carts/mine/shipping-information (see step 8)

Payload

{
    "addressInformation": {
        "shipping_address": {
            "countryId": "US",
            "regionId": 57,
            "regionCode": "TX",
            "region": "Texas",
            "street": [
                "4631 Airport Blvd #125"
            ],
            "telephone": "(555) 555-5555",
            "postcode": "77010",
            "city": "Houston",
            "firstname": "Sport Equipment Store",
            "lastname": "Store",
            "saveInAddressBook": 0,
            "extension_attributes": {
                "pickup_location_code": "txspeqs"
            }
        },
        "billing_address": {
            "region": "New York",
            "region_id": 43,
            "region_code": "NY",
            "country_id": "US",
            "street": [
                "123 Oak Ave"
            ],
            "postcode": "10577",
            "city": "Purchase",
            "firstname": "Jane",
            "lastname": "Doe",
            "email": "[email protected]",
            "telephone": "512-555-1111"
        },
        "shipping_method_code": "pickup",
        "shipping_carrier_code": "in_store",
        "extension_attributes": {}
    }
}

The rest of the steps are the same as for regular order placing & processing.

Place order using In-Store Pickup delivery method with GraphQL

Generally, steps almost the same as how to place In-Store Pickup order: you need to have pickup locations and configured In-Store Pickup delivery method. To pass initial steps, you can follow the GraphQl Checkout Tutorial. The only difference is in Step #4. In-Store Pickup method extends schema of ShippingAddressInput and provide possibility to pass pickup location code together with address data.

GraphQl Schema

input ShippingAddressInput {
    customer_address_id: Int
    address: CartAddressInput
    customer_notes: String
    pickup_location_code: String
}

Payload

mutation {
  setShippingAddressesOnCart(
    input: {
      cart_id: "{ CART_ID }"
      shipping_addresses: [
        {
          address: {
            firstname: "John"
            lastname: "Doe"
            company: "Company Name"
            street: ["320 N Crescent Dr", "Beverly Hills"]
            city: "Los Angeles"
            region: "CA"
            postcode: "90210"
            country_code: "US"
            telephone: "123-456-0000"
            save_in_address_book: false
          },
          pickup_location_code: "txspeqs"
        }
      ]
    }
  ) {
    cart {
      shipping_addresses {
        firstname
        lastname
        company
        street
        city
        region {
          code
          label
        }
        postcode
        telephone
        country {
          code
          label
        },
        pickup_location_code
      }
    }
  }
}

Response Postcode, street, city, region, and country will be replaced in shipping address with pickup location address. The pickup location code will be displayed in the response.

{
  "data": {
    "setShippingAddressesOnCart": {
      "cart": {
        "shipping_addresses": [
          {
            "firstname": "John",
            "lastname": "Doe",
            "company": "Company Name",
            "street": [
              "4631 Airport Blvd #125"
            ],
            "city": "Houston",
            "region": {
              "code": "TX",
              "label": "Texas"
            },
            "postcode": "77010",
            "telephone": "123-456-0000",
            "country": {
              "code": "US",
              "label": "US"
            },
            "pickup_location_code": "txspeqs"
          }
        ]
      }
    }
  }
}

Mark Order as Ready for Pickup

Send an email to the customer that the order is ready to be picked up and create a shipment.

Endpoint
POST http://<host>/rest/all/V1/order/notify-orders-are-ready-for-pickup

Headers
Content-Type application/json
Authorization: Bearer <admin_token>

Payload

{
  "orderIds": [
    81
  ]
}

Response

Magento returns an array with success status and an array of error messages for each failed order.

{
  "successful": true,
  "failed": []
}