Test in the GraphQL Playground
Important
The Buy with Prime API is offered as a preview and might change as we receive feedback and iterate on the interfaces. We are sharing this early documentation to help you learn about the Buy with Prime API as we write and iterate on the content.
The Buy with Prime API GraphQL playground provides developers with an interactive IDE for constructing and testing API calls. The GraphQL playground consists of a main editor window and tools that assist in forming API calls. The following list shows the tools available.
-
Documentation explorer (
): Shows a set of documentation automatically generated from the Commerce API GraphQL schema. -
History (
): Shows an updating list of your changes to the code in the main window. Choose any prior iteration to return to that state. -
GraphQL code exporter (
): Shows a non-interactive version of your current code from the main editor, along with a button to copy the code for export. -
GraphQL explorer (
): Provides an interactive list of available queries and mutations, along with their respective variables. Choosing a value in the list creates the query or mutation in your main editor. -
Re-fetch GraphQL schema (
): Triggers a refresh of the GraphQL schema used to populate the GraphQL playground, updating it to the most current version. -
Short key dialog (
): Shows keyboard shortcuts for actions in the GraphQL playground. -
Settings dialog (
): Lets you enable persistent headers, change the visual theme, or clear locally stored data.
The main editor window supports manually entered code and both queries and mutations created using the GraphQL explorer. The GraphQL playground supports tabs to edit multiple queries or mutations simultaneously. Use the execute query button to test your query against the simulated storefront.
By default, GraphQL playground API calls run against a simulated, shared storefront that only allows queries. The shared storefront doesn’t allow calls that include a mutation and responds with an error message if you attempt to include a mutation. Enter authorization details in the header to run API calls against your custom store. For details, see Use the GraphQL Playground with Your Store.
The following example response shows the error returned if you attempt to send a mutation to the simulated storefront.
Simulated store mutation response error
{
"errors": [
{
"message": "Mutations are not allowed on the shared store",
"extensions": {
"classification": {
"type": "Forbidden",
"code": 403,
"details": {},
"errorType": "Forbidden",
"errorCode": 403
}
}
}
]
}
The Buy with Prime API GraphQL playground uses a GraphiQL integration. For details, see GraphiQL & the GraphQL LSP Reference Ecosystem for building browser & IDE tools.
GraphQL schema documentation explorer
The included documentation explorer shows automatically generated content from the API’s GraphQL schema. Queries, mutations and objects available to import using the GraphQL explorer appear in the documentation explorer with brief explanations of their functionality.
Query edit history
The history panel shows a list of changes you make in the main editor window. Selecting a change returns code in the main editor window to that previous state. When selecting a previous change, your current changes remain available and you can return to that state by selecting the appropriate option in the list of changes. Select the clear option to remove all previous changes that are not marked as a favorite.
Each change includes the option to label, favorite, or delete the change.
- Edit label: Choose this option to alter the text used for this change in the list. Changes included in the list default to using the query tab’s name as their label.
- Add/Remove favorite: Choose this option to toggle the favorite status of a change. Any change marked as a favorite remains on the list after using the clear option.
- Delete from history: Choose this option to permanently delete the change from your history.
Code exporter
The code exporter panel shows a non-interactive version of the code from the main editor window, along with the code necessary to integrate it with a JavaScript platform.
Select the copy icon to copy the code shown to your local clipboard.
Interactive GraphQL explorer
The GraphQL explorer shows an interactive list of available queries, mutations and variables from the Buy with Prime API. Code imported through the explorer provides correct formatting, but you must enter any necessary values. For example, choosing the order query with orderId as the orderIdentifier creates the following query in the main editor.
query MyQuery {
order(orderIdentifier: {orderId: ""})
}
Enter a valid orderId in the provided quotation marks to complete this simple query. By selecting additional variables from the explorer, you can build more complex queries that return additional information. For example, adding lineItems with product, externalId and value selected creates the following query.
query MyQuery {
order(orderIdentifier: {orderId: ""}) {
lineItems {
product {
externalId {
value
}
}
}
}
}
Enter 322-RRQ4-6774T5 as the orderId and execute the query to see the response. This query returns a value for externalId of extproduct2.
Execute your first request with the GraphQL playground
The following steps lead you through constructing a query with the GraphQL explorer and executing it against the GraphQL playground simulated store front. The GraphQL playground includes all necessary information to target the simulated store by default. This example requires no manually entered values and returns a valid response. The response contains the first ten products in the catalog and whether or not they are eligible for Prime.
Step 1: Open the GraphQL explorer
Select the GraphQL explorer icon to open the list of available queries.
Step 2: Select the products query
Select the products query from the list to import it into the main editor window.
Step 3: Add required options to the query
Select first to define the number of products to return, starting with the first product in the catalog. The first value defaults to 10 when imported.
Select edges, followed by node to expand the list of values for the query to return. For this example, choose Product and then both id and offerPrime to return the product ID and Prime eligibility for the first ten products in the simulated store’s catalog.
Step 4: Execute the query
Select the Execute query button (
) to make an API call against the simulated store front using your constructed query.
Step 5: Parse the response
The example query produces the following response, containing the first ten product IDs in the simulated store catalog, along with their Prime eligibility.
{
"data": {
"products": {
"edges": [
{
"node": {
"id": "gam2zn0u3wfe1j",
"offerPrime": false
}
},
{
"node": {
"id": "xvss14tcfrs716",
"offerPrime": true
}
},
{
"node": {
"id": "9puqj9lgflacu1",
"offerPrime": true
}
},
{
"node": {
"id": "84xb2e3f1z9a14",
"offerPrime": true
}
},
{
"node": {
"id": "npzurve2ekv7l6",
"offerPrime": true
}
},
{
"node": {
"id": "qxrff1vmvi7811",
"offerPrime": false
}
},
{
"node": {
"id": "cb4o8ja7epb31o",
"offerPrime": true
}
},
{
"node": {
"id": "18m3tvlotzkge0",
"offerPrime": false
}
},
{
"node": {
"id": "b3w4s8vfdqdif6",
"offerPrime": true
}
},
{
"node": {
"id": "slndcy70k4hpn1",
"offerPrime": false
}
}
]
}
}
}
Additional sample queries
Use the following example queries to test functionality against the simulated storefront.
Sample query without testing data
query products {
products(first: 10) {
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
edges {
cursor
node {
id
... on Product {
id
externalId {
value
}
sku {
value
}
amazonSku {
marketplaceId
value
}
offerPrime
productDetailPageUrl
image {
displayReadyUrl
sourceUrl
}
}
}
}
}
}
Sample product query
query ProductQuery {
product(identifier: {amazonSku: {value: "B002EDAIJY"}}) {
amazonSku {
marketplaceId
}
buyability {
status
}
image {
displayReadyUrl
sourceUrl
}
representativeOfVariationGroup {
representativeProduct {
... on Product {
id
}
}
}
title {
defaultLocale
}
}
}
Sample order query
query orderquery {
order(orderIdentifier: {orderId: "322-9S2B-KXSAYH"}) {
customer {
bwpCustomerId
}
lineItems {
amount {
unit
value
}
createdAt
id
deliveryOffer {
details {
deliveryPreviewId
deliveryProvider
}
}
}
orderLinks {
displayMessage
}
payments {
details {
amount {
currencyCode
}
aliases {
aliasType
aliasId
}
}
}
}
}
Simulated store values
Use the following values for testing API calls against the shared store.
catalogFeedId- 559e42a8-9086-4268-a9c8-4461457aa046fileId- 6a7d0af6-bc62-41b9-88a4-297550c9d22cinventoryItemId- daiicqsephde80productIdentifiersku- sku2externalId- extproduct2amazonSku- B002EDAIJYproductId- j41gfl0ucpkrp2
shopperIdentitylwaAccessTokenvalue- eyJ0eXBlIjoiQUNDRVNTX1RPS0VOIiwidmFsdWUiOiJzYW5kYm94LW1vY2tlZC10ZXN0LXByaW1lLXNob3BwZXItYWNjZXNzLXRva2VuIn0=
aliasaliasType- EXTERNAL_IDaliasId- 06c1b712-099e-4295-908c-1da3456e0432
orderId- 322-RRQ4-6774T5analyticstaskId- USER_EVENTS:511a65fb-ee4d-43e1-8abd-8a4ddeef0651
Related topics
Updated 4 days ago