REST Resource: inventory.partners.merchants

Resource: Merchant

Info about a merchant that is on the aggregator's platform.

JSON representation
{
  "name": string,
  "merchantName": string,
  "telephone": string,
  "url": string,
  "geo": {
    object(GeoCoordinates)
  },
  "category": string,
  "numBookings30d": string,
  "taxRateBasisPoints": number,
  "taxRate": {
    object(TaxRate)
  },
  "paymentRestrictions": {
    object(PaymentRestrictions)
  },
  "paymentOption": [
    {
      object(PaymentOption)
    }
  ],
  "paymentProcessorConfig": {
    object(PaymentProcessorConfig)
  },
  "tokenizationConfig": {
    object(TokenizationConfig)
  },
  "terms": {
    object(Terms)
  },
  "brandId": string,
  "matchingHints": {
    object(MerchantMatchingHints)
  },
  "serviceAttribute": [
    {
      object(ServiceAttribute)
    }
  ]
}
Fields
name

string

The merchant resource name, which has the format of partners/{partner_id}/merchants/{merchantId}.

merchantName

string

The merchantName, telephone, url and geo are used to support matching partner inventory with merchants already present on Google Maps. This information will not be displayed.

The name of the merchant.

telephone

string

The public telephone number of the merchant including its country and area codes, e.g. +14567891234.

url

string

The url of the merchant's public website.

geo

object(GeoCoordinates)

The Geo info of the merchant, including latitude, longitude, and address.

category

string

The category of the business in aggregator's platform.

numBookings30d

string (int64 format)

Number of bookings for this merchant in the trailing 30 days.

taxRateBasisPoints
(deprecated)

number (uint32 format)

The merchant's tax rate in basis points (one hundredth of one percent). For example, if the tax rate is 7.5%, this field should be set to 750.

If this field is left unset or set to 0, the total price charged to a user for any service provided by this merchant is the exact price specified by Service.price. The service price is assumed to be exempt from or already inclusive of applicable taxes. Taxes will not be shown to the user as a separate line item.

If this field is set to any nonzero value, the total price charged to a user for any service provided by this merchant will include the service price plus the tax assessed using the tax rate provided here. Fractions of the smallest currency unit (for example, fractions of one cent) will be rounded using nearest even rounding. Taxes will be shown to the user as a separate line item.

This field is deprecated, please use taxRate instead.

taxRate

object(TaxRate)

The merchant's tax rate. If present this field overrides the deprecated taxRateBasisPoints field. An empty message (i.e. taxRate { }) will reset the applied tax rate to zero.

paymentRestrictions

object(PaymentRestrictions)

Restrictions to the payment methods this merchant accepts. We assume no restrictions exist if this field is not set.

paymentOption[]

object(PaymentOption)

Payment options available for this merchant. Services under this merchant will be able to individually limit the payment options they allow.

paymentProcessorConfig
(deprecated)

object(PaymentProcessorConfig)

Configuration for a tokenized payment processor, if the merchant has support for it.

tokenizationConfig

object(TokenizationConfig)

Configuration for a tokenized payment processor, if the merchant has support for it.

terms

object(Terms)

The specific merchant's Terms and Conditions displayed to the user when a service is being booked through Reserve with Google. In addition to these the aggregator partner's Terms and Conditions are always displayed to the user and must not be provided here.

brandId

string

An opaque string that identifies the consumer-facing brand to use when displaying partner attribution. This field allows partners with multiple consumer-facing brands to provide merchants for all brands within the same feed.

A brand consists of consumer-facing properties like the name, logo, Terms of Service, and Privacy Policy.

If there is only one consumer-facing partner brand, this field does not need to be set and can be ignored.

If the partner...

Does not have multiple consumer-facing brands? --> Ignore this field

Has Multiple Brands that are configured?

  If this field is set
    --> Associated consumer-facing brand attribution is used

  If this field is unset or the empty string
    --> Default consumer-facing brand attribution is used

Careful Note: most partners do not need to set this field. If a partner wishes to use this field, they must contact us first to configure separate brands, including the default brand.

matchingHints

object(MerchantMatchingHints)

Hints to help Google match a merchant to a place on Google Maps. Note: most partners do not need to set this field, as Google will match merchants to places on Google Maps using the information provided above. (optional)

serviceAttribute[]

object(ServiceAttribute)

Definitions for any service attributes used to describe the Services for this Merchant. (optional)

GeoCoordinates

The Geo data of a location, including latitude, longitude, and address.

JSON representation
{
  "latitude": number,
  "longitude": number,

  // Union field addresses can be only one of the following:
  "address": {
    object(PostalAddress)
  },
  "unstructuredAddress": string
  // End of list of possible types for union field addresses.
}
Fields
latitude

number

Latitude in degrees. (optional)

longitude

number

Longitude in degrees. (optional)

Union field addresses. Address for a location, could either be structured or unstructured. addresses can be only one of the following:
address

object(PostalAddress)

Postal address of the location, preferred.

unstructuredAddress

string

An unstructured address could also be provided as a fallback. E.g. "1600 amphitheatre parkway mountain view, ca 94043"

PaymentRestrictions

Restrictions to the payment methods this merchant accepts.

JSON representation
{
  "creditCardRestrictions": {
    object(CreditCardRestrictions)
  }
}
Fields
creditCardRestrictions

object(CreditCardRestrictions)

Restrictions to the credit cards this merchant accepts. We assume all credit cards are accepted if this field is not set. Note that the list of cards supported by CreditCardType will grow over time, meaning that leaving this empty subjects a configuration to future changes.

CreditCardRestrictions

Restrictions to the credit card types this merchant accepts.

JSON representation
{
  "creditCardType": [
    enum(CreditCardType)
  ]
}
Fields
creditCardType[]

enum(CreditCardType)

A list of supported credit cards. No credit cards are supported if empty.

CreditCardType

A credit card type.

Enums
CREDIT_CARD_TYPE_UNSPECIFIED Unused.
VISA A Visa credit card.
MASTERCARD A Mastercard credit card.
AMERICAN_EXPRESS An American Express credit card.
DISCOVER A Discover credit card.
JCB A JCB credit card.

PaymentOption

A payment option, which can be used to pay for services provided by a merchant. Payment options can be shared among multiple merchants (e.g. merchants belonging to the same chain).

JSON representation
{
  "paymentOptionId": string,
  "name": string,
  "description": string,
  "price": {
    object(Price)
  },
  "taxRate": {
    object(TaxRate)
  },
  "paymentOptionType": enum(PaymentOptionType),
  "sessionCount": string,
  "purchaseInterval": {
    object(TimeRange)
  },
  "validInterval": {
    object(TimeRange)
  },
  "validDuration": string,
  "activationType": enum(ActivationType),
  "userRestriction": {
    object(UserPurchaseRestriction)
  }
}
Fields
paymentOptionId

string

This ID is used to identify this payment option.

This ID is global to the whole aggregator, and re-using a value across multiple merchants will allow a user to pay with the corresponding payment option across those merchants.

When re-using an ID accoss multiple merchants, updating any value for a payment option under one merchant will also update any other payment option with the same ID, under a different merchant. As such, it's a best practice to have all payment options sharing the same ID, always be updated to identical values, to avoid any possibility of underministic behavior.

name

string

The name of the payment option. This can be user visible.

description

string

A description of the payment option. This can be user visible.

price

object(Price)

The price of the payment option.

taxRate

object(TaxRate)

The tax rate for this payment option. If present this field overrides the taxRate field present in the Merchant or Service. An empty message (i.e. taxRate { }) will reset the applied tax rate to zero.

paymentOptionType

enum(PaymentOptionType)

The type of this payment option. Single-use for drop-ins, multi-use for packs, and unlimited for memberships.

sessionCount

string (int64 format)

How many sessions this payment option can be used for. Valid only for multi-session / packs, where the value should be > 1.

purchaseInterval

object(TimeRange)

The payment option can be purchased within this interval.

validInterval

object(TimeRange)

The payment option can be used within this interval (e.g. special price for January 2017). If present, this overrides validDuration and activationType.

validDuration

string (Duration format)

Duration of the payment option validity (e.g. 30 day membership).

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

activationType

enum(ActivationType)

Defines how the validity start date is determined for this payment option.

userRestriction

object(UserPurchaseRestriction)

Restricts the users eligible to purchase this payment option. Can be used to restrict a promotional payment option to a subset of users. If not set, all users are eligible.

PaymentOptionType

A payment option type.

Enums
PAYMENT_OPTION_TYPE_UNSPECIFIED Unused.
PAYMENT_OPTION_SINGLE_USE Payment option can only be used once.
PAYMENT_OPTION_MULTI_USE Payment option can be used if its session count > 0.
PAYMENT_OPTION_UNLIMITED Payment option can be used within its valid time range - session count is inapplicable.

ActivationType

Defines how the validity start date is determined.

Enums
ACTIVATION_TYPE_UNSPECIFIED Unused.
ACTIVATION_ON_PURCHASE Validity starts at the time of purchase.
ACTIVATION_ON_FIRST_USE Validity starts when the payment option is used for the first time.

UserPurchaseRestriction

Restricts the users eligible to purchase a payment option.

JSON representation
{
  "newToMerchant": boolean,
  "newToPaymentOption": boolean
}
Fields
newToMerchant

boolean

A payment option that can only be purchased by users who have never purchased from the same merchant before.

newToPaymentOption

boolean

A payment option that can only be purchased by users who have never purchased the same payment option before.

PaymentProcessorConfig

A configuration for a payment processor, setup on a per Merchant basis.

JSON representation
{
  "processor": enum(Processor),
  "publicKey": string,
  "version": string
}
Fields
processor

enum(Processor)

Defines the payment processor partner this configuration applies to.

publicKey

string

The key used to identify this merchant with the payment processor.

For Stripe, refer to: https://stripe.com/docs/dashboard#api-keys For Braintree, refer to: https://articles.braintreepayments.com/control-panel/important-gateway-credentials

version

string

The API version number sent to the payment processor along with payment requests.

Processor

Defines a specific payment processor partner.

Enums
PROCESSOR_UNSPECIFIED Unused
PROCESSOR_STRIPE A configuration for payments with Stripe.
PROCESSOR_BRAINTREE A configuration for payments with Braintree.

TokenizationConfig

A configuration for payment-processor tokenization, set up on a per-Merchant basis.

JSON representation
{
  "tokenizationParameter": {
    string: string,
    ...
  },
  "billingInformationFormat": enum(BillingInformationFormat)
}
Fields
tokenizationParameter

map (key: string, value: string)

A tokenization configuration will typically have one tokenizationParameter whose key is "gateway" and whose value is the name of the processor.

The rest of the parameters are dependent on the processor. See Google Pay's documentation for further information.

Braintree example: tokenizationParameter { key: "gateway" value: "braintree" } tokenizationParameter { key: "braintree:apiVersion" value: "v1" } tokenizationParameter { key: "braintree:sdkVersion" value: "2.30.0" } tokenizationParameter { key: "braintree:merchantId" value: "abcdef" } tokenizationParameter { key: "braintree:clientKey" value: "production_xxx_yyy" }

Stripe example: tokenizationParameter { key: "gateway" value: "stripe" } tokenizationParameter { key: "stripe:version" value: "2018-02-28" } tokenizationParameter { key: "stripe:publishableKey" value: "pk_1234" }

Adyen example: tokenizationParameter { key: "gateway" value: "adyen" } tokenizationParameter { key: "gatewayMerchantId" value: "yourId" }

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

billingInformationFormat

enum(BillingInformationFormat)

Include in the payment token the user's billing information as entered into Google Pay with their FOP (see above). Leaving the field empty is equivalent to specifying MIN.

BillingInformationFormat

How much of the Billing Address to require of the user and include in the token. The enum values correspond to parameters in the Google Pay API (see https://developers.google.com/pay/api/web/reference/object#BillingAddressParameters).

Enums
BILLING_INFORMATION_FORMAT_UNSPECIFIED Not specified. Defaults to MIN.
MIN name, country code, and postal code (Google Pay default setting).
FULL name, street address, locality, region, country code, and postal code.

Terms

A set of rules and guidelines that are displayed to the user in order to make a booking through Reserve with Google.

JSON representation
{
  "url": string,
  "text": string
}
Fields
url

string

Optionally, the URL to the Terms and Conditions.

text

string

The text to be displayed to the user.

MerchantMatchingHints

Hints used to help Google match a merchant to a place on Google Maps.

JSON representation
{
  "placeId": string
}
Fields
placeId

string

The Place ID for a place in the Google Places database and on Google Maps. See https://developers.google.com/places/place-id for more about Place IDs.

ServiceAttribute

Service attributes are partner-defined categories that describe the Services for a Merchant. For example, a bank may define an "Account Type" service attribute with possible values of "Personal" and "Business", while a hair salon may define a "Service Type" service attribute with possible values of "Haircut", "Color", and "Style".

JSON representation
{
  "attributeId": string,
  "attributeName": string,
  "value": [
    {
      object(Value)
    }
  ]
}
Fields
attributeId

string

An identifier that uniquely identifies this service attribute among others for the same merchant, e.g. "account-type".

attributeName

string

A user-visible name for this attribute, e.g. "Account Type".

value[]

object(Value)

All possible values for this service attribute.

Value

Represents a possible value for a particular service attribute.

JSON representation
{
  "valueId": string,
  "valueName": string
}
Fields
valueId

string

An identifier that uniquely identifies this value among others for this service attribute, e.g. "personal".

valueName

string

A user-visible name for the value, e.g. "Personal".

Methods

create

Creates a new Merchant managed by the specified aggregator, and returns it.

delete

Deletes an existing Merchant managed by the specified aggregator.

patch

Updates an existing Merchant managed by the specified aggregator, and returns it.