Aller au contenu principal
API docs by Redocly

Storefront V1 API Specification (1.0.0)

Storefront API Support: [email protected]

Business & Store

Endpoints for retrieving business & store information

Get stores by business

Retrieve a list of stores that are currently active on storefront and owned by a business. Search results will be sorted by store id.

Authorizations:
BearerAuth
path Parameters
business_id
required
string (BusinessId) ^([1-9][0-9]*)$
Example: 123

Business id used for filtering stores

query Parameters
pagination_token
string (PaginationToken)
Example: pagination_token=pre1111

The pagination token to retrieve the previous/next page of results.

limit
integer (Limit) [ 1 .. 200 ] ^(0|[1-9][0-9]*)$
Default: 10

Specify the maximum number of items that may be returned for a single request.

should_send_store_details
boolean (ShouldSendStoreDetails)
Default: false

If true, return stores details for each store in the list. The default value is false.

Responses

Response samples

Content type
application/json
{
  • "stores": [
    ],
  • "prev_token": "239843",
  • "next_token": "239886"
}

Get stores by business group

Retrieve a list of stores that are currently active on storefront and owned by a business group. Search results will be sorted by store id.

Authorizations:
BearerAuth
path Parameters
business_group_id
required
string (BusinessGroupId) ^([1-9][0-9]*)$
Example: 123

Business group id used for filtering stores

query Parameters
pagination_token
string (PaginationToken)
Example: pagination_token=pre1111

The pagination token to retrieve the previous/next page of results.

limit
integer (Limit) [ 1 .. 200 ] ^(0|[1-9][0-9]*)$
Default: 10

Specify the maximum number of items that may be returned for a single request.

should_send_store_details
boolean (ShouldSendStoreDetails)
Default: false

If true, return stores details for each store in the list. The default value is false.

Responses

Response samples

Content type
application/json
{
  • "stores": [
    ],
  • "prev_token": "239843",
  • "next_token": "239886"
}

Get store details

Request more details about a single store given store id

Authorizations:
BearerAuth
path Parameters
store_id
required
string (StoreId) ^([1-9][0-9]*)$
Example: 123

Store id

Responses

Response samples

Content type
application/json
{
  • "id": "123",
  • "name": "Example Store",
  • "address": "123 Street Apt123, WA",
  • "phone_number": "1233333456",
  • "time_zone": "US/New York",
  • "status": {
    },
  • "store_hours": {
    },
  • "store_special_hours": {
    },
  • "minimum_order_value": 0,
  • "delivery_fee": 399,
  • "average_delivery_time": 20,
  • "average_pickup_time": 10,
  • "special_instructions_max_length": 10,
  • "should_show_delivery_fee": true,
  • "store_properties": {
    }
}

Get store menus by store id

Authorizations:
BearerAuth
path Parameters
store_id
required
string (StoreId) ^([1-9][0-9]*)$
Example: 123

Store id

Responses

Response samples

Content type
application/json
{
  • "menu": {
    }
}

Get all active store menus by store id

Authorizations:
BearerAuth
path Parameters
store_id
required
string (StoreId) ^([1-9][0-9]*)$
Example: 123

Store id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search

Endpoints for store searches

Search nearby stores by business

Search for stores that are currently active on storefront and within a specified area given business id and location. Search results can be refined by providing additional keywords and the result will be sorted by distance.

Authorizations:
BearerAuth
path Parameters
business_id
required
string (BusinessId) ^([1-9][0-9]*)$
Example: 123

Business id used for filtering stores

query Parameters
lat
required
string (Latitude) ^(\+|-)?(?:90(?:(?:\.0{1,7})?)|(?:[0-9]|[1-8]...
Example: lat=-32.1234537

latitude

lon
required
string (Longitude) ^(\+|-)?(?:180(?:(?:\.0{1,7})?)|(?:[0-9]|[1-9...
Example: lon=-156.1234538

longitude

limit
integer (Limit) [ 1 .. 200 ] ^(0|[1-9][0-9]*)$
Default: 10

Specify the maximum number of items that may be returned for a single request.

open_at
string (OpenAt) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: open_at=2018-08-22T17:20:28Z or 2018-08-22T17:20:28.123Z

If specified, only stores that are open for business at the specified time are returned. Possible values is future UTC timestamp in ISO-8601 format within seven days from current time.

is_pickup
boolean (IsPickup)
Default: true

If true, return stores based on store pick up radius. Otherwise, return stores based on delivery radius. The default value is true.

search_radius
integer (StoreRadius) [ 1 .. 100000 ]
Default: 1000

Define the distance in meters within which to return store results. The default value is 1000. Search radius is only applicable to pick ups.

should_send_store_details
boolean (ShouldSendStoreDetails)
Default: false

If true, return stores details for each store in the list. The default value is false.

Responses

Response samples

Content type
application/json
{
  • "stores": [
    ]
}

Search nearby stores by business group

Search for stores that are currently active on storefront and within a specified area given business group id and location. Search results can be refined by providing additional keywords and the result will be sorted by distance.

Authorizations:
BearerAuth
path Parameters
business_group_id
required
string (BusinessGroupId) ^([1-9][0-9]*)$
Example: 123

Business group id used for filtering stores

query Parameters
lat
required
string (Latitude) ^(\+|-)?(?:90(?:(?:\.0{1,7})?)|(?:[0-9]|[1-8]...
Example: lat=-32.1234537

latitude

lon
required
string (Longitude) ^(\+|-)?(?:180(?:(?:\.0{1,7})?)|(?:[0-9]|[1-9...
Example: lon=-156.1234538

longitude

limit
integer (Limit) [ 1 .. 200 ] ^(0|[1-9][0-9]*)$
Default: 10

Specify the maximum number of items that may be returned for a single request.

open_at
string (OpenAt) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...
Example: open_at=2018-08-22T17:20:28Z or 2018-08-22T17:20:28.123Z

If specified, only stores that are open for business at the specified time are returned. Possible values is future UTC timestamp in ISO-8601 format within seven days from current time.

is_pickup
boolean (IsPickup)
Default: true

If true, return stores based on store pick up radius. Otherwise, return stores based on delivery radius. The default value is true.

search_radius
integer (StoreRadius) [ 1 .. 100000 ]
Default: 1000

Define the distance in meters within which to return store results. The default value is 1000. Search radius is only applicable to pick ups.

should_send_store_details
boolean (ShouldSendStoreDetails)
Default: false

If true, return stores details for each store in the list. The default value is false.

Responses

Response samples

Content type
application/json
{
  • "stores": [
    ]
}

Address

Endpoints for address related information

Get address suggestions for an input string

Retrieve a list of address suggestions based on the user input and optional geographic bounds.

Authorizations:
BearerAuth
query Parameters
integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$
Example: integration_id=987654

business id, business group id or store id

integration_type
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"
Example: integration_type=store

business id, business group id or store id

input
required
string
lat
string (Latitude) ^(\+|-)?(?:90(?:(?:\.0{1,7})?)|(?:[0-9]|[1-8]...
Example: lat=-32.1234537

latitude

lon
string (Longitude) ^(\+|-)?(?:180(?:(?:\.0{1,7})?)|(?:[0-9]|[1-9...
Example: lon=-156.1234538

longitude

country_code
string (CountryCode) ^[A-Z]{2}$
Example: country_code=US

ISO 3166-1 alpha-2 country code

search_radius
integer [ 1 .. 100000 ]

Define the distance in meters within which to return results. Results outside of the defined area may still be displayed.

language
string (Language) ^[a-z]{2}$
Example: language=en

ISO 639-1 language code

Responses

Response samples

Content type
application/json
{
  • "suggestions": [
    ]
}

Get address details with an id

Request more details about an address given an id

Authorizations:
BearerAuth
query Parameters
integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$
Example: integration_id=987654

business id, business group id or store id

integration_type
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"
Example: integration_type=store

business id, business group id or store id

source_place_id
required
string
country_code
string (CountryCode) ^[A-Z]{2}$
Example: country_code=US

ISO 3166-1 alpha-2 country code

Responses

Response samples

Content type
application/json
{
  • "address": {
    }
}

Get list of addresses with latitude and longitude

Find addresses closest to a location on the map

Authorizations:
BearerAuth
query Parameters
integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$
Example: integration_id=987654

business id, business group id or store id

integration_type
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"
Example: integration_type=store

business id, business group id or store id

lat
required
string (Latitude) ^(\+|-)?(?:90(?:(?:\.0{1,7})?)|(?:[0-9]|[1-8]...
Example: lat=-32.1234537

latitude

lon
required
string (Longitude) ^(\+|-)?(?:180(?:(?:\.0{1,7})?)|(?:[0-9]|[1-9...
Example: lon=-156.1234538

longitude

language
string (Language) ^[a-z]{2}$
Example: language=en

ISO 639-1 language code

Responses

Response samples

Content type
application/json
{
  • "addresses": [
    ]
}

Get or create address details with a full qualified address string.

Get or create address details based on a formatted_address, e.g. "1234 Main St., Sacramento, CA 95814"

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain formatted address, integration id and type.

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

formatted_address
required
string

Short displayable address

country_code
string (CountryCode) ^[A-Z]{2}$

Country code in ISO 3166-1 alpha-2 format

Responses

Request samples

Content type
application/json
{
  • "integration_id": "987654",
  • "integration_type": "store",
  • "formatted_address": "303 2nd Street, San Francisco, CA, USA",
  • "country_code": "US"
}

Response samples

Content type
application/json
{
  • "address": {
    }
}

Loyalty

Endpoints for loyalty related resources

Get loyalty account balance of the user Deprecated

Authorizations:
BearerAuth
query Parameters
external_user_id
required
string (ExternalUserId) ^([a-zA-Z1-9][a-zA-Z0-9]*)$
Example: external_user_id=asAZ123

External User id, user identifier of the external loyalty provider

provider
required
string (Provider)
Enum: "paytronix" "spendgo"
Example: provider=spendgo

loyalty provider of the user

provider_environment
required
string (ProviderEnvironment)
Enum: "prod" "staging"
Example: provider_environment=staging

which environment of the loyalty provider needs to be used.

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$
Example: integration_id=987654

business id, business group id or store id

provider_reference_id
required
string (ProviderReferenceId) ^([a-zA-Z1-9][:_a-zA-Z0-9]*)$
Example: provider_reference_id=123:12

merchant id or any other id which loyalty provider uses to uniquely identify the business/merchant.

Responses

Response samples

Content type
application/json
{
  • "balance": "1234"
}

Get loyalty member profile of the user

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

session_id
required
string (SessionId)

id of the application session

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

get_loyalty_info
boolean (GetLoyaltyInfo)
Default: false

if true, return loyalty account information for the user.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "integration_id": "987654",
  • "integration_type": "store",
  • "get_loyalty_info": false
}

Response samples

Content type
application/json
{
  • "profile": {
    }
}

Revoke a user's session with the loyalty provider

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

session_id
required
string (SessionId)

id of the application session

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "integration_id": "987654",
  • "integration_type": "store"
}

Delete a user's account.

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

session_id
required
string (SessionId)

id of the application session

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "integration_id": "987654",
  • "integration_type": "store"
}

Retrieve a user's session info with the loyalty provider

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

session_id
required
string (SessionId)

id of the application session

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "integration_id": "987654",
  • "integration_type": "store"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

Get QR code for user loyalty account.

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

required
object (LoyaltyUserSessionRequest)
store_id
required
string (StoreId) ^([1-9][0-9]*)$

Unique ID for the store.

width
integer (Width) [ 1 .. 1024 ]
Default: 256

expected width of the qr code

height
integer (Height) [ 1 .. 1024 ]
Default: 256

expected height of the qr code

Responses

Request samples

Content type
application/json
{
  • "session": {
    },
  • "store_id": "123",
  • "width": 300,
  • "height": 300
}

Response samples

Content type
application/json
{
  • "qr_code": "string"
}

Retrieve user loyalty rewards.

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

session_id
required
string (SessionId)

id of the application session

store_id
required
string (StoreId) ^([1-9][0-9]*)$

Unique ID for the store.

Responses

Request samples

Content type
application/json
{
  • "integration_id": "987654",
  • "integration_type": "store",
  • "session_id": "string",
  • "store_id": "123"
}

Check a user in to earn loyalty points for visiting a store location.

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

required
object (LoyaltyUserSessionRequest)
store_id
required
string (StoreId) ^([1-9][0-9]*)$

Unique ID for the store.

latitude
string (Latitude) ^(\+|-)?(?:90(?:(?:\.0{1,7})?)|(?:[0-9]|[1-8]...
longitude
string (Longitude) ^(\+|-)?(?:180(?:(?:\.0{1,7})?)|(?:[0-9]|[1-9...

Responses

Request samples

Content type
application/json
{
  • "session": {
    },
  • "store_id": "123",
  • "latitude": -32.1234537,
  • "longitude": -156.1234538
}

Response samples

Content type
application/json
{
  • "earned_reward": {
    }
}

Redeem a customer's loyalty reward in store.

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

required
object (LoyaltyUserSessionRequest)
promotion_id
required
string

Unique identifier for the reward

Responses

Request samples

Content type
application/json
{
  • "session": {
    },
  • "promotion_id": "2d3eddf8-2723-434d-81d5-920eac66a61c"
}

Response samples

Content type
application/json
{
  • "applied_redemption": [
    ],
  • "rejected_redemption": [
    ]
}

JWT

Endpoints for JWT resources

Create JWT for the integration_id which could be business, business group or store id

Create JWT for a onboarded integration id.

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain integration_id.

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

Responses

Request samples

Content type
application/json
{
  • "integration_id": "987654",
  • "integration_type": "store"
}

Response samples

Content type
application/json
{
  • "jwt": "string",
  • "expires_in": 0
}

Order

Endpoints for order resources

Create storefront order session from external cart.

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain menu ids, menu item ids and other relevant details needed in external cart.

store_id
required
string
menu_id
required
string
fulfillment_type
required
string (FulfillmentType)
Enum: "delivery" "pickup"
required
Array of objects (ExternalCartItem)
object (DeliveryDetails)
scheduled_time
string^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

UTC Timestamp in ISO-8601 format

Responses

Request samples

Content type
application/json
{
  • "store_id": "string",
  • "menu_id": "string",
  • "fulfillment_type": "pickup",
  • "items": [
    ],
  • "delivery_details": {
    },
  • "scheduled_time": "2018-08-22T17:20:28Z or 2018-08-22T17:20:28.123Z"
}

Response samples

Content type
application/json
{
  • "order_session_id": "string",
  • "checkout_url": "string"
}

Create cart from order session.

Authorizations:
BearerAuth
Request Body schema: application/json

Internal use only. request body which should contain all the relevant details needed to create cart from order session.

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

order_session_id
required
string
session_id
required
string (SessionId)

id of the application session

consumer_id
required
string (ConsumerId) ^([1-9][0-9]*)$

Unique ID for a doordash consumer.

should_delete_existing_carts
boolean (ShouldDeleteExistingCarts)
Default: true

Responses

Request samples

Content type
application/json
{
  • "integration_id": "987654",
  • "integration_type": "store",
  • "order_session_id": "string",
  • "session_id": "string",
  • "consumer_id": "123",
  • "should_delete_existing_carts": true
}

Response samples

Content type
application/json
{
  • "cart_id": "string"
}

Get order history of a consumer

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should contain user's identification details.

session_id
required
string (SessionId)

id of the application session

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "integration_id": "987654",
  • "integration_type": "store"
}

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Get order status given a order id

Authorizations:
BearerAuth
Request Body schema: application/json

request body which should integration id, type and order id.

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

order_id
required
string

unique id for this order

Responses

Request samples

Content type
application/json
{
  • "integration_id": "987654",
  • "integration_type": "store",
  • "order_id": "string"
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

App

Endpoints for mobile app related information

Get minimum application version required for the mobile apps to operate

Authorizations:
BearerAuth
query Parameters
app_platform
required
string (AppPlatform)
Enum: "android" "ios"
Example: app_platform=android

operating system like android or ios.

integration_id
string (IntegrationId) ^([1-9][0-9]*)$
Example: integration_id=987654

business id, business group id or store id

Responses

Response samples

Content type
application/json
{
  • "version": "1234"
}

Get app metadata for the mobile apps to operate

Authorizations:
BearerAuth
query Parameters
integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$
Example: integration_id=987654

business id, business group id or store id

integration_type
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"
Example: integration_type=store

business id, business group id or store id

Responses

Response samples

Content type
application/json
{}

Menu Item

Get store menu item.

Get store menu item

Authorizations:
BearerAuth
path Parameters
store_id
required
string (StoreId) ^([1-9][0-9]*)$
Example: 123

Store id

Request Body schema: application/json

request body which should contain item id

item_id
required
string
menu_id
required
string
integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

session_id
string (SessionId)

id of the application session

fulfillment_type
string (FulfillmentType)
Enum: "delivery" "pickup"
cursor
string

Responses

Request samples

Content type
application/json
{
  • "item_id": "string",
  • "menu_id": "string",
  • "integration_id": "987654",
  • "integration_type": "store",
  • "session_id": "string",
  • "fulfillment_type": "pickup",
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "code": "validation_error",
  • "message": "Request validation failed.",
  • "errors": "Missing business/store id."
}

Menu V2

Get store menu v2.

Get store menu v2

Authorizations:
BearerAuth
path Parameters
store_id
required
string (StoreId) ^([1-9][0-9]*)$
Example: 123

Store id

Request Body schema: application/json

request body which should contain store id

integration_id
required
string (IntegrationId) ^([1-9][0-9]*)$

Unique ID for the business, business group or store.

integration_type
required
string (IntegrationType)
Default: "business"
Enum: "BUSINESS" "BUSINESS_GROUP" "STORE"

Type of the integration id

session_id
string (SessionId)

id of the application session

menu_id
string
fulfillment_type
string (FulfillmentType)
Enum: "delivery" "pickup"
country_code
string (CountryCode) ^[A-Z]{2}$

Country code in ISO 3166-1 alpha-2 format

Responses

Request samples

Content type
application/json
{
  • "integration_id": "987654",
  • "integration_type": "store",
  • "session_id": "string",
  • "menu_id": "string",
  • "fulfillment_type": "pickup",
  • "country_code": "US"
}

Response samples

Content type
application/json
{
  • "store_header": {
    },
  • "primary_menu": { }
}