---
title: "Tutorial: Setting up an in-store pickup configuration"
slug: "tutorial-setting-up-an-in-store-pickup-configuration"
tags: ["Associate App", "shipping", "in-store pickup", "customer", "platform", "stock on hand", "inventory", "onboarding", "store fulfillment", "routing", "tutorial", "api", "omnichannel manager "]
updated: 2026-05-04T14:01:56Z
published: 2026-05-04T14:01:56Z
canonical: "docs.newstore.com/tutorial-setting-up-an-in-store-pickup-configuration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial: Setting up an in-store pickup configuration

The aim of this tutorial is to set up `in-store pickup` for an imaginary business based in New York City that has 2 stores.

## Prerequisites

When you set up a store, regardless of transfer orders, in-store pickup, or any orders routed via NewStore, you have to create this key pair once for generating shipping option tokens.

> [!NOTE]
> Important
> 
> Before getting started with this tutorial, ensure that you understand how routing works at NewStore. See [About order routing](/v1/docs/about-order-routing#routing).
> 
> We assume that you have an authentication token stored in the `AUTH_TOKEN` variable. Retrieve one with the following call:
> 
> ```plaintext
> export AUTH_TOKEN=$(curl -s <url>/v0/token -d \
> "grant_type=password&username=<myusername>&password=<mypassword>" | jq -r.access_token)
> ```

## Creating the stores

Before we can think of placing orders, we must set up our business's stores. To prepare a store for in-store pickup orders, we must **provide accurate geo coordinates** of the store during its creation, using the `latitude` and `longitude` properties. The geo coordinates of a store are at the core of the in-store pickup routing.

1. Create the first store using the example provided in [Tutorial: Setting up a store](/v1/docs/tutorial-setting-up-a-store#tuto-create-store).
2. Create a second store with a different address using the following payload:

```json
{
  "active_status": true,
  "business_hours": [
    {
      "from_time": "09:00",
      "to_time": "20:00",
      "weekday": 0
    },
    {
      "from_time": "09:00",
      "to_time": "20:00",
      "weekday": 2
    },
    {
      "from_time": "09:00",
      "to_time": "20:00",
      "weekday": 3
    },
    {
      "from_time": "09:00",
      "to_time": "20:00",
      "weekday": 4
    },
    {
      "from_time": "09:00",
      "to_time": "20:00",
      "weekday": 5
    },
    {
      "from_time": "09:00",
      "to_time": "20:00",
      "weekday": 6
    }
  ],
  "division_name": "US",
  "pricebook": "price-us",
  "gift_wrapping": false,
  "label": "002_US_XYZ_Street",
  "tax_included": true,
  "phone_number": "202-555-2946",
  "physical_address": {
    "address_line_1": "33 XYZ Street",
    "city": "New York",
    "country_code": "US",
    "latitude": 40.711219,
    "longitude": -73.806230,
    "state": "NY",
    "zip_code": "11422"
  },
  "shipping_address": {
    "address_line_1": "33 XYZ Street",
    "city": "New York",
    "country_code": "US",
    "state": "NY",
    "zip_code": "11422"
  },
  "store_id": "store2_NYC",
  "timezone": "America/New_York"
}
```

## Adding inventory

We have created 2 stores, let's import products that they will sell. To learn how to import master data, see [Tutorial: Importing products](/v1/docs/tutorial-importing-products#tuto-import-product). Ensure you import stock for both stores during the [stock import step](/v1/docs/tutorial-importing-stock-information#creating-stock-data).

## Enabling in-store pickup

Our stores are ready to process orders but they are not ready to process **in-store pickup** orders. To enable in-store pickup, we must use the [in-store pickup config](https://docs.newstore.net/api/integration/store-fulfillment/in_store_pickup_api) API.

1. Let's create the in-store pickup config using the [create pickup config](https://docs.newstore.net/api/integration/store-fulfillment/in_store_pickup_api#operation/CreatePickupConfig) method.

This method allows us to set global options, which apply to all stores, and store-specific options. In our situation, we have defined 2 stores respectively identified by `store1_NYC` and `store2_NYC`.

Let's choose the display name that will appear during fulfillment for in-store pickup orders. It must be as clear as possible to ensure that associates can identify the in-store pickup order. Let's use `In-store pickup`.

Create a `data.json` file and paste the following body in it:

```json
{
  "global": {
    "display_name": "In-store pickup",
    "grace_period": 0,
    "default_search_radius": 5
  },
  "stores": {
    "store1_NYC": {
      "delivery_time": "Available now",
      "delivery_time_if_not_available": "Pick up in 5-6 days",
      "cost": {
        "price": 0,
        "tax_code": "FR",
        "currency_code": "USD"
      }
    },
    "store2_NYC": {
      "delivery_time": "Available now",
      "delivery_time_if_not_available": "Pick up in 5-6 days",
      "cost": {
        "price": 10,
        "tax_code": "FR",
        "currency_code": "USD"
      }
    }
  }
}
```
2. Call the [create pickup config](https://docs.newstore.net/api/integration/store-fulfillment/in_store_pickup_api#operation/CreatePickupConfig) method:

```plaintext
curl -X POST "https://dodici.x.newstore.net/v0/d/in_store_pickup_config" \
     -H "Authorization: Bearer $AUTH_TOKEN" \
     -d @data.json
```

> [!TIP]
> Note
> 
> You can get a token using the call at the top of [the page](/v1/docs/tutorial-setting-up-an-in-store-pickup-configuration#tuto-instorepickup).

The stores now support in-store pickup orders. We can start creating in-store pickup orders.

## Retrieving stores that can fulfill an order

In our case, let's imagine the following workflow:

1. The customer adds items to a cart and proceeds to checkout.
2. The customer provides their address.
3. Our website automatically displays a list of stores near this address
4. The customer selects a store and pays.
5. We create the order in NewStore.

To implement this workflow:

1. Once we have a cart of items created by the customer and the customer's address, our E-commerce platform must call the [Get in-store pickup options](https://docs.newstore.net/api/integration/store-fulfillment/in_store_pickup_api#operation/GetIn-StorePickupOptions) method.

This method takes a reference location's coordinates. The reference location is the address provided by our customer.

Let's assume that we have a cart with one item to be delivered to Manhattan in New York City, we can use the following payload saved in the `data.json` file:

```json
{
   "location": {
     "geo": {
       "latitude": 40.817027,
       "longitude": -73.952452
     }
   },
   "bag": [
    {
       "product_id": "6050673",
       "quantity": 1
     }
   ],
   "options": {
     "search_radius": 30,
     "show_stores_without_atp": false
   }
}
```

> [!TIP]
> Note
> 
> The search radius is in kilometers.

1. Call the [Get in-store pickup options](https://docs.newstore.net/api/integration/store-fulfillment/in_store_pickup_api#operation/GetIn-StorePickupOptions) method:

```plaintext
curl -X POST "https://dodici.x.newstore.net/v0/d/in_store_pickup_options" \
     -H "Authorization: Bearer $AUTH_TOKEN" \
     -d @data.json
```

The method returns an `options` array that contains all the stores in the search radius defined in the request, ordered by proximity to the reference location. Each store contains a `shipping_offer_token` that is required to request the fulfillment of our order.

In our case, let's assume that the customer selects `store1_NYC`. We can now route the order to this store.
2. Our E-commerce platform can create the order using the [create order](https://docs.newstore.net/api/integration/order-management/order_injection_api) method. In the request, provide the shipping offer token we retrieved in the previous steps, in the `shipping_offer_token` property.

> [!TIP]
> Note
> 
> For `in-store pickup` orders, a shipping offer token does not expire.

The order is open. After the grace period set in the in-store config is complete, the order is sent to the `store1_NYC` store.

If there is enough inventory, it is assigned to an associate that can fulfill the order. If there is insufficient inventory, the order is put [On Hold](/v1/docs/monitoring-orders#nom-onhold). We must import inventory and reroute the order. It will get routed to the same store. An associate can also route the order manually to another store using NewStore Omnichannel Manager. See [Managing On Hold orders with insufficient inventory](/v1/docs/monitoring-orders#managing-on-hold-orders-with-insufficient-inventory).

## Printing documents for the in-store pickup order

To print documents for the in-store pickup order, use the [Create documents to print config](https://docs.newstore.net/api/integration/inventory-management/packages_api#operation/documentsToPrint) method, and add the following sample payload to specify invoices to be printed in the store:

```json
{
 "default": {
   "in_store_pickup": [
     {
       "document_type": "invoice",
       "number_of_copies": 1,
       "printer_type": "document_printer"
     },
   ],
  }
 }
```

For more information on configuring documents to print during order fulfillment, see [Configuring documents for print in a store or warehouse](/v1/docs/configuring-documents-for-print-in-a-store-or-warehouse#config-notif-docs).

**Related topics**

- [Tutorial: Importing products](/v1/docs/tutorial-importing-products#tuto-import-product)
- [Tutorial: Setting up a store](/v1/docs/tutorial-setting-up-a-store#tuto-create-store)
- [About order routing](/v1/docs/about-order-routing#routing)
- [Get in-store pickup options](https://docs.newstore.net/api/integration/store-fulfillment/in_store_pickup_api#operation/GetIn-StorePickupOptions)
- [In-store pickup config](https://docs.newstore.net/api/integration/store-fulfillment/in_store_pickup_api)