Common types

GraphQL types of the Sphere schema that are shared across multiple types and operations.

KeyReference

A KeyReference represents a loose reference to another resource in the same Project identified by the resource's key field. If available, the key is immutable and mandatory. KeyReferences do not support Reference Expansion.
typeId​
String​

Type of referenced resource.

key​
String​

User-defined unique and immutable key of the referenced resource.

KeyReferenceInput

Reference

A Reference represents a loose reference to another resource in the same Project identified by its id. The typeId indicates the type of the referenced resource. Each resource type has its corresponding Reference type, like ChannelReference. A referenced resource can be embedded through Reference Expansion. The expanded reference is the value of an additional obj field then.
typeId​
String​

Type of referenced resource.

id​
String​

Unique ID of the referenced resource.

ReferenceExpandable

id​
String​

ReferenceInput

typeId​
String​
id​
String​

ResourceIdentifier

Draft type to create a Reference or a KeyReference to a resource. Provide either the id or (wherever supported) the key of the resource to reference, but depending on the API endpoint the response returns either a Reference or a KeyReference. For example, the field parent of a CategoryDraft takes a ResourceIdentifier for its value while the value of the corresponding field of a Category is a Reference.
Each resource type has its corresponding ResourceIdentifier, like ChannelResourceIdentifier.
typeId​
String​
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.
key​
String​
User-defined unique identifier of the referenced resource. Required if id is absent.
id​
String​
Unique identifier of the referenced resource. Required if key is absent.

ResourceIdentifierInput

typeId​
String​
id​
String​
key​
String​

BaseMoney

type​
String​
currencyCode​
centAmount​
Long​
fractionDigits​
Int​

Money

type​
String​
currencyCode​
centAmount​
Long​
fractionDigits​
Int​
For the Money it equals to the default number of fraction digits used with the currency.

HighPrecisionMoney

Object that stores money as a fraction of the smallest indivisible unit of a specific currency.

type​
String​

Type of money used.

currencyCode​
preciseAmount​
Long​
Amount in 1 / (10 ^ fractionDigits) of a currency.
centAmount​
Long​

Amount in the smallest indivisible unit of a currency, such as:

  • Cents for EUR and USD, pence for GBP, or centime for CHF (5 CHF is specified as 500).
  • The value in the major unit for currencies without minor units, like JPY (5 JPY is specified as 5).
centAmount is represented as 64-bit integers. If this limit is exceeded, a MoneyOverflow error will be returned.
fractionDigits​
Int​

Number of digits after the decimal separator, greater than the default number of fraction digits for a currency.

Date

Time

DateTime

YearMonth

Country

Currency

CurrencyCode

Locale

LocalizedEnumValueDraft

key​
String​
label​

LocalizedString

locale​
value​
String​

LocalizedStringItemInputType

locale​
value​
String​

Address

An address represents a postal address.

id​
String​

Unique identifier of the Address.

It is not recommended to set it manually since the API overwrites this ID when creating an Address for a Customer. Use key instead and omit this field from the request to let the API generate the ID for the Address.
streetName​
String​

Name of the street.

streetNumber​
String​

Street number.

additionalStreetInfo​
String​

Further information on the street address.

postalCode​
String​

Postal code.

city​
String​

Name of the city.

region​
String​

Name of the region.

state​
String​

Name of the state, for example, Colorado.

country​

Name of the country.

company​
String​

Name of the company.

department​
String​

Name of the department.

building​
String​

Number or name of the building.

apartment​
String​

Number or name of the apartment.

pOBox​
String​

Post office box number.

additionalAddressInfo​
String​

Further information on the Address.

externalId​
String​

ID for the contact used in an external system.

key​
String​
User-defined identifier of the Address. Must be unique among the addresses in a BusinessUnit, Customer, or in the itemShippingAddresses (LineItem-specific addresses) of a Cart, Order, QuoteRequest, or Quote.
phone​
String​

Phone number of the contact.

mobile​
String​

Mobile phone number of the contact.

email​
String​

Email address of the contact.

fax​
String​

Fax number of the contact.

title​
String​

Title of the contact, for example 'Dr.'

salutation​
String​

Salutation of the contact, for example 'Mr.' or 'Ms.'

firstName​
String​

Given name (first name) of the contact.

lastName​
String​

Family name (last name) of the contact.

custom​

Custom Fields defined for the Address.

AddressDraft

Address type to be used on write methods. Optionally, use the custom field in addition to the fields of a BaseAddress.
id​
String​

Unique identifier of the Address.

It is not recommended to set it manually since the API overwrites this ID when creating an Address for a Customer. Use key instead and omit this field from the request to let the API generate the ID for the Address.
streetName​
String​

Name of the street.

streetNumber​
String​

Street number.

additionalStreetInfo​
String​

Further information on the street address.

postalCode​
String​

Postal code.

city​
String​

Name of the city.

region​
String​

Name of the region.

state​
String​

Name of the state, for example, Colorado.

country​

Name of the country.

company​
String​

Name of the company.

department​
String​

Name of the department.

building​
String​

Number or name of the building.

apartment​
String​

Number or name of the apartment.

pOBox​
String​

Post office box number.

additionalAddressInfo​
String​

Further information on the Address.

externalId​
String​

ID for the contact used in an external system.

key​
String​
User-defined identifier of the Address. Must be unique among the addresses in a BusinessUnit, Customer, or in the itemShippingAddresses (LineItem-specific addresses) of a Cart, Order, QuoteRequest, or Quote.

Custom Fields defined for the Address.

phone​
String​

Phone number of the contact.

mobile​
String​

Mobile phone number of the contact.

email​
String​

Email address of the contact.

fax​
String​

Fax number of the contact.

title​
String​

Title of the contact, for example 'Dr.'

salutation​
String​

Salutation of the contact, for example 'Mr.' or 'Ms.'

firstName​
String​

Given name (first name) of the contact.

lastName​
String​

Family name (last name) of the contact.

AddressInput

id​
String​
title​
String​
salutation​
String​
firstName​
String​
lastName​
String​
streetName​
String​
streetNumber​
String​
additionalStreetInfo​
String​
postalCode​
String​
city​
String​
region​
String​
state​
String​
country​
company​
String​
department​
String​
building​
String​
apartment​
String​
pOBox​
String​
phone​
String​
mobile​
String​
email​
String​
fax​
String​
additionalAddressInfo​
String​
externalId​
String​
key​
String​
custom​

Asset

id​
String​
Unique identifier of the Asset. Not required when importing Assets using the Import API.
key​
String​
User-defined identifier of the Asset. It is unique per Category or ProductVariant.
sources​
Array of AssetSource​
name​
String​

Name of the Asset.

nameAllLocales​
Array of LocalizedString​

Name of the Asset.

description​
String​

Description of the Asset.

descriptionAllLocales​
Array of LocalizedString​

Description of the Asset.

tags​
Array of String​

Keywords for categorizing and organizing Assets.

custom​

Custom Fields defined for the Asset.

AssetSource

Representation of an Asset in a specific format, for example a video in a certain encoding, or an image in a certain resolution.
uri​
String​

URI of the AssetSource.

key​
String​
User-defined identifier of the AssetSource. Must be unique per Asset.
dimensions​

Width and height of the AssetSource.

contentType​
String​
Indicates the type of content, for example application/pdf.

AssetDimensions

width​
Int​
height​
Int​

Image

url​
String​
URL of the image in its original size that must be unique within a single ProductVariant.
dimensions​

Dimensions of the original image.

label​
String​

Custom label for the image.

Dimensions

width​
Int​
height​
Int​

CustomFieldsCommand

typeId​
String​
typeKey​
String​
fields​
Json​
typeResId​

CustomFieldsType

typeRef​
type​
customFieldsRaw​
Array of RawCustomField​

This field contains non-typed data.

CustomFieldInput

A key-value pair representing the field name and value of one single custom field.

The value of this custom field consists of escaped JSON based on the FieldDefinition of the Type.

Examples for value:
  • FieldType String: "\"This is a string\""
  • FieldType DateTimeType: "\"2018-10-12T14:00:00.000Z\""
  • FieldType Number: "4"
  • FieldType Set with an elementType of String: "[\"This is a string\", \"This is another string\"]"
  • FieldType Reference: "{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"
name​
String​
value​
String​

The value of this custom field consists of escaped JSON based on the FieldDefinition of the Type.

Examples for value:
  • FieldType String: "\"This is a string\""
  • FieldType DateTimeType: "\"2018-10-12T14:00:00.000Z\""
  • FieldType Number: "4"
  • FieldType Set with an elementType of String: "[\"This is a string\", \"This is another string\"]"
  • FieldType Reference: "{\"id\": \"b911b62d-353a-4388-93ee-8d488d9af962\", \"typeId\": \"product\"}"

CustomFieldsDraft

typeId​
String​
typeKey​
String​
fields​
Array of CustomFieldInput​

RawCustomField

name​
String​
value​
Json​
referencedResource​
referencedResourceSet​

Initiator

isPlatformClient​
Boolean​
clientId​
String​
externalUserId​
String​
anonymousId​
String​
customerRef​
userRef​
associateRef​
attributedTo​

Attribution

clientId​
String​
source​
Can be Export, Import, IntakeAgent, ManagedCommerceMCP, ProductEnrichmentAgent, PromotionsAgent, or StarterAgent​
userRef​

AttributionSource

Export
Import
IntakeAgent
ManagedCommerceMCP
ProductEnrichmentAgent
PromotionsAgent
StarterAgent

SearchValueType

BigDecimal

Long

Json

JsonPrimitive