2. Endpoint Mapping

Understand which REST endpoints map to the equivalent GraphQL queries and mutations.

Introduction

In this section we map the existing REST API endpoints to their GraphQL equivalents, we do this by grouping the REST endpoints as follows:

Adverts

Use-caseRESTGraphQL
List adverts without filtersGET /api/v2/client/advertsallAdverts
- Example
List adverts with filtersGET /api/v2/client/adverts?sku=VALUEadvertsWhere
- Example
Get a single advertGET /api/v2/client/adverts/1node (advert)
- Example
Get a single advert with additional resourcesGET /api/v2/client/adverts/1?include=variants,shipping_parcelnode (advert)
- Example
Create an advertPOST /api/v2/client/advertsadvertUpsert
- Example
Update an advertPUT /api/v2/client/adverts/1advertUpsert
- Example
Resubmit a rejected advert for vettingPUT /api/v2/client/adverts/1/resubmit_for_vettingadvertVettingResubmit
- Example
Deleting an advertDELETE /api/v2/client/adverts/1advertDelete
- Example

Brands

Use-caseRESTGraphQL
Listing brandsGET /api/v2/brandsbrands
- Example
Search for a brandGET /api/v2/brands/search?name=GiantbrandSearch
- Example

Images

Use-caseRESTGraphQL
List an adverts imagesGET /api/v2/client/adverts/1/imagesnode (advert)
- Example
List a variants imagesGET /api/v2/client/variants/1/imagesnode (variant)
- Example
Showing a single imageGET /api/v2/client/adverts/1/images/1node (image)
- Example
Adding an image to an advertPOST /api/v2/client/adverts/1/imagesadvertUpsert
- Example
Adding an image to a variantPOST /api/v2/client/variants/1/imagesadvertUpsert
- Example
Updating an adverts imagePUT /api/v2/client/adverts/1/images/1advertUpsert
- Example
Updating a variants imagePUT /api/v2/client/variants/1/images/1variantUpdate
- Example
Deleting an adverts imageDELETE /api/v2/client/adverts/1/images/1advertUpsert
- Example
Deleting a variants imageDELETE /api/v2/client/variants/1/images/1variantUpdate
- Example

Documents

Use-caseRESTGraphQL
Listing an adverts documentsGET /api/v2/client/adverts/1/documentsnode (advert)
- Example
Showing a single documentGET /api/v2/client/adverts/1/documents/1node (document)
- Example
Adding a documentPOST /api/v2/client/adverts/1/documentsadvertUpsert
- Example
Updating a documentPUT /api/v2/client/adverts/1/documents/1advertUpsert
- Example
Deleting a documentDELETE /api/v2/client/adverts/1/documents/1advertUpsert
- Example

Inventory (multi-store)

Use-caseRESTGraphQL
Listing a variants inventoryGET /api/v2/client/variants/1/inventoriesnode (variant)
Example
Updating a variants inventoryPUT /api/v2/client/variants/1/inventoriesNot currently supported
Deleting an inventory recordDELETE /api/v2/client/variants/1/inventories/1Not currently supported

Invoices (Orders)

Use-caseRESTGraphQL
Listing invoices no filtersGET /api/v2/client/invoicesinvoices
Example
Listing invoices with filtersGET /api/v2/client/invoices?updated_since=2015-11-10T00:00:00Z&status=sentinvoices
Example
Listing invoices with additional resourcesGET /api/v2/client/invoices?include=line_items,customerinvoices
Example
Show an individual invoiceGET /api/v2/client/invoices/1node (invoice)
Example
Sending an invoicePUT /api/v2/client/invoices/1/sentshipmentCreate
Example
Readying an invoicePUT /api/v2/client/invoices/1/readyNot currently supported
Marking an invoice as collectedPUT /api/v2/client/invoices/1/collectedNot currently supported

Shipments

Use-caseRESTGraphQL
Listing shipmentsGET /api/v2/client/invoices/:invoice_id/shipmentsnode (invoice)
Example
Showing shipmentsGET /api/v2/client/invoices/:invoice_id/shipments/:shipment_idnode (invoice)
Example
Creating a shipmentPOST /api/v2/client/invoices/:invoice_id/shipmentsshipmentCreate
Example
Updating a shipmentPUT /api/v2/client/invoices/:invoice_id/shipments/:shipment_idshipmentUpdate
Example

Shipping Profiles

Use-caseRESTGraphQL
Listing shipping profilesGET /api/v2/shipping_profilesshippingProfiles
Example
Getting a variants shipping profileGET /api/v2/client/variants/1?include=shipping_profilenode (variant)
Example

Taxons

Use-caseRESTGraphQL
List TaxonsGET /api/v2/taxonstaxon
Example
Search for TaxonsGET /api/v2/taxons/search?name=HybridtaxonSearch
Example
Get Taxon Option ValuesGET /api/v2/taxons/bikesnode (taxon)
Example

Multi-store memberships

Use-caseRESTGraphQL
List the members of a multi-storeGET /api/v2/client/multi_store_membershipsNot currently supported

Variants

Use-caseRESTGraphQL
Listing variants without filtersGET /api/v2/client/variantsallAdverts
Example
Listing variants with filtersGET /api/v2/client/variants?external_id=VALUEvariantsWhere
Example
Listing an adverts variantsGET /api/v2/client/adverts/1/variantsnode (advert)
Example
Get a single variantGET /api/v2/client/variants/1node (variant)
Example
Get a single variant with additional resourcesGET /api/v2/client/variants/1?include=shipping_parcel,shipping_profilenode (variant)
Example
Creating a variantPOST /api/v2/client/adverts/1/variantsadvertUpsert
Example
Updating a variantPUT /api/v2/client/adverts/1/variants/1 or
PUT /api/v2/client/variants/1
variantUpdate
Example
Updating count on hand for many variantsPOST /api/v2/client/variants/stock_on_handNot currently supported
Deleting a variantDELETE /api/v2/client/adverts/1/variants/2 or
DELETE /api/v2/client/variants/2
variantDelete
Example

Examples

allAdverts - List Adverts without filters

query {
	allAdverts {
		nodes {
			__typename
			... on Advert {
				legacyId
				updatedAt
				title
				seller {
					businessName
				}
			}
			... on UnpublishedAdvert {
				legacyId
				updatedAt
				details {
					title
					seller {
						businessName
					}
				}
			}
			... on DeletedAdvert {
				legacyId
				id
				updatedAt
			}
		}
	}
}

advertsWhere - List Adverts with filters

query {
	advertsWhere(variantSkus: ["VALUE"]) {
		totalCount
		nodes {
			__typename
			id
			legacyId
			title
			published
			online
			displayable
			vetted
			requiresVetting
			vettingRejected
			variants {
				nodes {
					id
					countOnHand
				}
			}
		}
	}
}

node (advert) - Get an individual advert

query {
	node(id: "QWR2ZXJ0LTEwMDA3MDczNA==") {
		... on Advert {
			id
			legacyId
			title
			lowestOriginalPrice
			lowestPrice
			variants {
				nodes {
					legacyId
					sku
					label
					countOnHand
				}
			}
		}
	}
}

advertUpsert - Create an advert

mutation {
	advertUpsert(
		input: {
			attributes: {
				brandId: "QnJhbmQtNA=="
				taxonId: "VGF4b24tMjc4"
				title: "GlocalMe 4G Wireless Hot Spot"
				description: "WiFi Hotspot powered by 4G"
				price: "49.99"
				attemptAutoPublish: true
				images: [
					{
						sourceUrl: "https://example.com/router.jpg"
					}
				]
				productFeatures: 
					["Fast charge", "Light weight", "4G compatible"]
				advertOptionValues: [
					{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
				]
				variants: [
					{
						countOnHand: 1000
						variantOptionValues: [
							{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
						]
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

advertsUpsert - Update an advert

mutation {
	advertUpsert(
		input: {
			advertId: "QWR2ZXJ0LTEwMDA3MDczMA=="
			attributes: {
				price: "29.99"
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

advertVettingResubmit - Resubmit a rejected advert for vetting

mutation {
	advertVettingResubmit(input: 
		{ 
			advertIds: ["QWR2ZXJ0LTEwMDAwMjU3OA=="]
		}) {
		adverts {
			nodes {
				id
				vetted
				vettingRejected
				vettingRejectedReason
				requiresVetting
			}
		}
	}
}

advertDelete - Delete an advert

mutation{
	advertDelete(input: {
		id: "QWR2ZXJ0LTEwMDAxMzAyNg=="	
	})
	{
		status
		advert{
			id
			legacyId
		}
		errors{
			field
			messages
		}
	}
}

brands - List brands

query
{
	brands{
		nodes
		{
			id
			name
			slug
		}
	}
}

brandSearch - Search for a Brand

query{
	brandSearch(keyword: "Giant")
	{
		nodes{
			id
			name
		}
	}
}

node (advert) - List an adverts images

query {
	node(id: "QWR2ZXJ0LTEwMDA3MDczNA==") {
		... on Advert {
			id
			legacyId
			images{
				nodes{
					url
					alt
					id
				}
			}
		}
	}
}

node (variant) - List a variants images

query {
	node(id: "VmFyaWFudC03ODAyOA==") {
		... on Variant {
			id
			legacyId
			images{
				nodes{
					url
					alt
					id
				}
			}
		}
	}
}

node (image) - Showing a single image

query {
	node(id: "SW1hZ2UtMjg0OTQw") {
		... on Image {
			url
			alt
		}
	}
}

advertUpsert - Adding an image to an advert

mutation {
	advertUpsert(
		input: {
			attributes: {
				brandId: "QnJhbmQtNA=="
				taxonId: "VGF4b24tMjc4"
				title: "GlocalMe 4G Wireless Hot Spot"
				description: "WiFi Hotspot powered by 4G"
				price: "49.99"
				attemptAutoPublish: true
				images: [
					{
						sourceUrl: "https://example.com/router.jpg"
					}
				]
				productFeatures: 
					["Fast charge", "Light weight", "4G compatible"]
				advertOptionValues: [
					{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
				]
				variants: [
					{
						countOnHand: 1000
						variantOptionValues: [
							{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
						]
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

advertUpsert - Adding an image to a variant

mutation {
	advertUpsert(
		input: {
			attributes: {
				brandId: "QnJhbmQtNA=="
				taxonId: "VGF4b24tMjc4"
				title: "GlocalMe 4G Wireless Hot Spot"
				description: "WiFi Hotspot powered by 4G"
				price: "49.99"
				attemptAutoPublish: true
				images: [
					{
						sourceUrl: "https://example.com/router.jpg"
					}
				]
				productFeatures: 
					["Fast charge", "Light weight", "4G compatible"]
				advertOptionValues: [
					{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
				]
				variants: [
					{
						countOnHand: 1000
						variantOptionValues: [
							{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
						]
						images:[
							{
								sourceUrl: "https://example.com/router2.jpg"
							}
						]
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

advertUpsert - Updating an adverts image

mutation {
	advertUpsert(
		input: {
			advertId: "QWR2ZXJ0LTEwMDA3MDczMA=="
			attributes: {
				images: [
					{
						imageId: "SW1hZ2UtMjg0OTQw"
						sourceUrl: "https://example.com/router3.jpg"
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

variantUpdate - Updating a variants image

mutation{
	variantUpdate(
		input:
		{
			variantId: "VmFyaWFudC03ODAyOA=="
			attributes: {
				images: [
					{
						imageId: "SW1hZ2UtMjg0OTQw"
						sourceUrl: "https://example.com/router4.jpg"
					}
				]
			}
		})
	{
		variant{
			id
		}
		errors{
			field
			messages
		}
	}
}

advertUpsert - Delete an adverts image

mutation {
	advertUpsert(
		input: {
			advertId: "QWR2ZXJ0LTEwMDA3NzY5MA=="
			attributes: {
				images: [
					{
						imageId: "SW1hZ2UtMzA1MTAy"
						sourceUrl: null
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

variantUpdate - Delete a variants image

mutation{
	variantUpdate(
		input:
		{
			variantId: "VmFyaWFudC03ODAyOA=="
			attributes: {
				images: [
					{
						imageId: "SW1hZ2UtMjg0OTQw"
						sourceUrl: null
					}
				]
			}
		})
	{
		variant{
			id
		}
		errors{
			field
			messages
		}
	}
}

node (advert) - Listing an adverts documents

query {
	node(id: "QWR2ZXJ0LTEwMDA3NzY5MA==") {
		... on Advert {
			id
			legacyId
			documents{
				nodes{
					filename
					url
					id
				}
			}
		}
	}
}

node (advertDocument) - Showing a single document

query {
	node(id: "QWR2ZXJ0RG9jdW1lbnQtMzA1MTAz") {
		... on AdvertDocument {
			id
			url
			filename
		}
	}
}

advertUpsert - Adding a document to an advert

mutation {
	advertUpsert(
		input: {
			attributes: {
				brandId: "QnJhbmQtNA=="
				taxonId: "VGF4b24tMjc4"
				title: "GlocalMe 4G Wireless Hot Spot"
				description: "WiFi Hotspot powered by 4G"
				price: "49.99"
				attemptAutoPublish: true
				documents: [
					{
						sourceUrl: "https://example.com/router.pdf"
					}
				]
				
				variants: [
					{
						countOnHand: 1000
						variantOptionValues: [
							{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
						]
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

advertUpsert - Updating an adverts document

mutation {
	advertUpsert(
		input: {
			advertId: "QWR2ZXJ0LTEwMDA3MDczMA=="
			attributes: {
				documents: [
					{
						documentId: "QWR2ZXJ0RG9jdW1lbnQtMzA1MTAz"
						sourceUrl: "https://example.com/router3.pdf"
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

advertUpsert - Deleting an adverts document

mutation {
	advertUpsert(
		input: {
			advertId: "QWR2ZXJ0LTEwMDA3NzY5MA=="
			attributes: {
				documents: [
					{
						documentId: "QWR2ZXJ0RG9jdW1lbnQtMzA1MTAz"
						sourceUrl: "https://example.com/router3.pdf"
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

node (variant) - Listing a variants inventory

query {
	node(id: "VmFyaWFudC0xNTIwMw==") {
		... on Variant {
			id
			legacyId
			countOnHand
			inventories{
				nodes{
					price{amount}
					salePrice{amount}
					infiniteQuantity
					countOnHand
					seller{
						id
						legacyId
						businessName
					}
					
				}
			}
			
		}
	}
}

invoices - Listing invoices with no filters

query {
	invoices{
		nodes
		{
			id
			legacyId
			shippingCostCents
			paidAt
			statusFlags
			discountCents
			subtotalCents
			totalCents
			seller{
				legacyId
			}
			metadata{
				key
				value
			}
		}
	}
}

invoices - Listing invoices with filters

query {
	invoices(filters: {updatedSince: "2023-05-16" }){
		nodes
		{
			id
			legacyId
			shippingCostCents
			paidAt
			statusFlags
			discountCents
			subtotalCents
			totalCents
			seller{
				legacyId
			}
			metadata{
				key
				value
			}
		}
	}
}

invoices - Listing invoices with additional resources

query {
	invoices(filters: {updatedSince: "2023-05-16" }){
		nodes
		{
			id
			legacyId
			shippingCostCents
			paidAt
			statusFlags
			discountCents
			subtotalCents
			totalCents
			seller{
				legacyId
			}
			metadata{
				key
				value
			}
			lineItems{
				id
				quantity
			}
			shipments{
				id
				dispatchedAt
				carrier
			}
		}
	}
}

node (invoice) - Show an individual invoice

query {
	node(id: "SW52b2ljZS0xMzIxOA==") {
		... on Invoice {
			id
			legacyId
			shippingCostCents
			paidAt
			statusFlags
			discountCents
			subtotalCents
			totalCents
			seller{
				legacyId
			}
			metadata{
				key
				value
			}
			lineItems{
				id
				quantity
			}
			shipments{
				id
				dispatchedAt
				carrier
			}
		}
	}
}

shipmentCreate - Send an invoice

mutation {
	shipmentCreate(
		input: {
			invoiceId: "SW52b2ljZS0xMDQyMQ=="
			dispatchedAt: "2023-06-07"
			note: "Dispatched within SLA"
			postageCarrierId: "U2hpcG1lbnRDYXJyaWVyLTY5"
			trackingNumber: "12234"
			shippedItems: [
				{ lineItemId: "TGluZUl0ZW0tNDk5", 
					quantity: 1 
				}]
		}
	) {
		errors {
			field
			messages
		}
		shipment {
			id
			createdAt
		}
	}
}

node (invoice) - Listing shipments on an invoice

query {
	node(id: "SW52b2ljZS0xMzIxOA==") {
		... on Invoice {
			id
			shipments{
				id
				dispatchedAt
				carrier
				trackingLink
				trackingNumber
				note
			}
		}
	}
}

node (shipment) - Show an individual shipment

query {
	node(id: "U2hpcG1lbnQtNzM1") {
		... on Shipment {
			id
			id
			dispatchedAt
			carrier
			trackingLink
			trackingNumber
			note
		}
	}
}

shipmentCreate - Create a shipment

mutation {
	shipmentCreate(
		input: {
			invoiceId: "SW52b2ljZS0xMDQyMQ=="
			dispatchedAt: "2023-06-07"
			note: "Dispatched within SLA"
			postageCarrierId: "U2hpcG1lbnRDYXJyaWVyLTY5"
			trackingNumber: "12234"
			shippedItems: [
				{ lineItemId: "TGluZUl0ZW0tNDk5", 
					quantity: 1 
				}]
		}
	) {
		errors {
			field
			messages
		}
		shipment {
			id
			createdAt
		}
	}
}

shipmentUpdate - Update a shipment

mutation {
	shipmentUpdate(
		input: { 
			shipmentId: "U2hpcG1lbnQtMzc4OTYz", 
			trackingNumber: "66666" }
	) {
		errors {
			field
			messages
		}
		shipment {
			trackingNumber
		}
	}
}

shippingProfiles - Listing shipping profiles

query d{
	shippingProfiles{
		nodes{
			id
			name
			legacyId
			description	
		}
	}
}

node (variant) - Getting a variants shipping profile

query {
	node(id: "VmFyaWFudC03ODAyOA==") {
		... on Variant {
			id
			shippingProfile{
				id
				legacyId
			}
		}
	}
}

taxons - Listing taxons

query{
	taxons{
		nodes{
			treeName
			displayName
			urlSlug
			id
		}
	}
}

taxonSearch - Search Taxons

query{
	taxonSearch(searchValue: "BBQ")
	{
		nodes
		{
			treeName
			displayName
			urlSlug
			id
		}
	}
}

node (taxon) - Obtaining option types and values

query {
	node(id: "VGF4b24tMTc4") {
		... on Taxon {
			id
			treeName
			taxonType
			prototype{
				optionTypes{
					nodes{
						name
						id
						appliedTo
						fieldType
						optional
						presentation
						optionValues{
							nodes{
								id
								name
								displayName
							}
						}
					}
				}
			}
		}
	}
}

allAdverts - List variants no filters

query {
	allAdverts {
		nodes {
			__typename
			... on Advert {
				variants {
					nodes {
						countOnHand
						sku
						barcode
						lowestOriginalPrice
						lowestPrice
						maxPurchaseQuantity
						minPurchaseQuantity
					}
				}
			}
			... on UnpublishedAdvert {
				details {
					variants {
						nodes {
							countOnHand
							sku
							barcode
							lowestOriginalPrice
							lowestPrice
							maxPurchaseQuantity
							minPurchaseQuantity
						}
					}
				}
			}
			... on DeletedAdvert {
				legacyId
				id
				updatedAt
			}
		}
	}
}

variantsWhere - List variants with filters

query {
	variantsWhere(
		variantFilters: 
		{skus: ["sku-1", "sku-2"]}) {
		nodes {
			countOnHand
			sku
			barcode
			lowestOriginalPrice
			lowestPrice
			maxPurchaseQuantity
			minPurchaseQuantity
		}
	}
}

node (advert) - Listing an adverts variants

query {
	node(id: "QWR2ZXJ0LTEwMDA3MDcyOQ==") {
		... on Advert {
			variants {
				nodes {
					countOnHand
					sku
					barcode
					lowestOriginalPrice
					lowestPrice
					maxPurchaseQuantity
					minPurchaseQuantity
				}
			}
		}
	}
}

node (variant) - Get a single variant

query {
	node(id: "VmFyaWFudC03ODAyMw==") {
		... on Variant {
			id
			countOnHand
			sku
			barcode
			lowestOriginalPrice
			lowestPrice
			maxPurchaseQuantity
			minPurchaseQuantity
		}
	}
}

node (variant) - Get a single variant with additional resources

query {
	node(id: "VmFyaWFudC03ODAyMw==") {
		... on Variant {
			id
			countOnHand
			sku
			barcode
			lowestOriginalPrice
			lowestPrice
			maxPurchaseQuantity
			minPurchaseQuantity
			shippingParcel{
				length
			}
		}
	}
}

advertUpsert - Creating a variant

mutation {
	advertUpsert(
		input: {
			attributes: {
				brandId: "QnJhbmQtNA=="
				taxonId: "VGF4b24tMjc4"
				title: "GlocalMe 4G Wireless Hot Spot"
				description: "WiFi Hotspot powered by 4G"
				price: "49.99"
				attemptAutoPublish: true
				images: [
					{
						sourceUrl: "https://example.com/router.jpg"
					}
				]
				productFeatures: 
					["Fast charge", "Light weight", "4G compatible"]
				advertOptionValues: [
					{ optionValueId: "T3B0aW9uVmFsdWUtNzM2" }
				]
				variants: [
					{
						countOnHand: 1000
						variantOptionValues: [
							{ optionValueId: "T3B0aW9uVmFsdWUtNzMy" }
						]
					}
				]
			}
		}
	) {
		status
		advert {
			id
			legacyId
		}
		errors {
			field
			messages
		}
	}
}

variantUpdate - Updating a variant

mutation {
	variantUpdate(
		input: {
			variantId: "VmFyaWFudC03ODAyMw=="
			attributes: 
			{ 
				countOnHand: 78, 
				sku: "SKU-1234", 
				salePrice: 201 }
		}
	) {
		variant {
			id
		}
		errors {
			field
			messages
		}
	}
}

variantDelete - Deleting a variant

mutation {
	variantDelete(input: 
		{ id: "VmFyaWFudC03ODAyMw==" }) {
		variant {
			countOnHand
		}
		errors {
			field
			messages
		}
	}
}