REST
Objects
The resources many REST calls answer with, and every field each has.
AppPurchase
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
name | string | |
amountMinor | integer | |
currency | string | The shop’s billing currency. Every amount here is in its minor unit: cents, pence, paise. One of usd, gbp, eur, inr. |
test | boolean | True when no money moves. |
status | string | One of pending, accepted, declined, expired. |
createdAt | string (date-time) | |
confirmationUrl | string or null | Where the merchant approves it, while it waits. Send them there. |
Used by Get your app’s billing on this shop, Ask the merchant to approve a one-time charge.
AppSubscription
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
plan | string | The plan’s key in your manifest’s [[billing.plans]]. |
name | string | |
status | string | pending waits for the merchant; active, past_due and frozen are in force; scheduled starts when the current period ends. One of pending, active, past_due, frozen, scheduled, canceled, declined, expired. |
amountMinor | integer | What each period costs. |
currency | string | The shop’s billing currency. Every amount here is in its minor unit: cents, pence, paise. One of usd, gbp, eur, inr. |
interval | string | One of month, year. |
test | boolean | True when no money moves. |
trialEndsAt | string (date-time) or null | |
currentPeriodStart | string (date-time) or null | |
currentPeriodEnd | string (date-time) or null | |
cancelAtPeriodEnd | boolean | |
createdAt | string (date-time) | |
confirmationUrl | string or null | Where the merchant approves it, while it waits. Send them there. |
usageCapMinor | integer or null | The most a period’s usage may come to, for a plan that charges by use. |
usageTerms | string or null | How usage is priced, in your words. |
Used by Get your app’s billing on this shop, Ask the merchant to approve a plan, End your plan on this shop.
AppUsage
| Field | Type | Description |
|---|---|---|
capMinor | integer | The most this period’s usage may come to. |
usedMinor | integer | What has been reported so far this period. |
terms | string or null | How usage is priced, in your words. |
Used by Get your app’s billing on this shop, Report what the shop used.
Collection
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
title | string | |
handle | string | |
description | string or null | |
parentId | string (uuid) or null | |
seoTitle | string or null | |
seoDescription | string or null | |
kind | string | One of manual, automatic. |
rules | array of object | What an automatic collection matches. Empty on a manual one. Up to 10 items. |
rules[].field | string | One of title, product_type, vendor, tag, price. |
rules[].operator | string | One of equals, not_equals, contains, starts_with, ends_with, greater_than, less_than. |
rules[].value | string | 1 to 200 characters. |
rules[].currency | string | Matches ^[A-Z]{3}$. |
sortOrder | string | One of manual, title_asc, title_desc, created_desc, price_asc, price_desc. |
filterable | boolean | |
publishedAt | string (date-time) or null | |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by List collections, Create a collection, Get a collection, Update a collection.
Customer
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
email | string | |
firstName | string or null | |
lastName | string or null | |
phone | string or null | |
accountType | string | guest until they first sign in with their email, then registered. One of guest, registered, business. |
acceptsMarketing | boolean | Whether they agreed to be emailed. Only the customer can give it; withdraw it with withdrawCustomerMarketingConsent. |
defaultAddress | object or null | |
defaultAddress.name | string | |
defaultAddress.line_one | string | |
defaultAddress.line_two | string | |
defaultAddress.city | string | |
defaultAddress.state | string | A code where the country has them, such as CA. |
defaultAddress.country | string | Two letters, such as GB. |
defaultAddress.postal_code | string | |
tags | array of string | The merchant’s labels. |
taxExempt | boolean | They pay no tax. |
taxExemptionReference | string or null | Why they are exempt: a VAT number, a resale certificate. |
note | string or null | The merchant’s own note. Never shown to the customer. |
verifiedAt | string (date-time) or null | When they last signed in with this email. Cleared when the email is changed, until they sign in again. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
archivedAt | string (date-time) or null | When they were archived. Lists leave archived customers out unless asked. |
Used by Create a customer, Update a customer, Archive a customer, Unarchive a customer, Withdraw a customer’s marketing consent.
CustomerSavedAddress
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
customerId | string (uuid) | |
address | object | |
address.name | string | |
address.line_one | string | |
address.line_two | string | |
address.city | string | |
address.state | string | A code where the country has them, such as CA. |
address.country | string | Two letters, such as GB. |
address.postal_code | string | |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by List a customer’s saved addresses, Save an address for a customer, Correct a customer’s saved address.
CustomerSummary
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
email | string | |
firstName | string or null | |
lastName | string or null | |
phone | string or null | |
accountType | string | guest until they first sign in with their email, then registered. One of guest, registered, business. |
acceptsMarketing | boolean | Whether they agreed to be emailed. Only the customer can give it; withdraw it with withdrawCustomerMarketingConsent. |
defaultAddress | object or null | |
defaultAddress.name | string | |
defaultAddress.line_one | string | |
defaultAddress.line_two | string | |
defaultAddress.city | string | |
defaultAddress.state | string | A code where the country has them, such as CA. |
defaultAddress.country | string | Two letters, such as GB. |
defaultAddress.postal_code | string | |
tags | array of string | The merchant’s labels. |
taxExempt | boolean | They pay no tax. |
taxExemptionReference | string or null | Why they are exempt: a VAT number, a resale certificate. |
note | string or null | The merchant’s own note. Never shown to the customer. |
verifiedAt | string (date-time) or null | When they last signed in with this email. Cleared when the email is changed, until they sign in again. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
archivedAt | string (date-time) or null | When they were archived. Lists leave archived customers out unless asked. |
orderCount | integer | Orders that were not cancelled. |
spentAmount | integer | What they have spent, in minor units: charged less refunded, over orders not cancelled. |
lastOrderAt | string (date-time) or null | When they last ordered. |
Used by List customers, Get a customer.
DigitalAsset
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
variantId | string (uuid) | |
storeId | string (uuid) | |
storagePath | string | Where the file is kept, from its upload ticket. |
fileName | string | The name a buyer’s download is saved under. |
sizeBytes | number or null | |
downloadLimit | number or null | How many times each buyer may download it. Null is no limit. |
createdAt | string (date-time) |
Used by List a variant’s downloads, Attach a download to a variant.
DownloadGrant
| Field | Type | Description |
|---|---|---|
lineItemId | string (uuid) | |
assetId | string (uuid) | |
fileName | string | |
sizeBytes | integer or null | |
downloadCount | integer | |
downloadLimit | integer or null | Null means unlimited. |
downloadsRemaining | integer or null | Null when unlimited. |
firstDownloadedAt | string (date-time) or null | |
lastDownloadedAt | string (date-time) or null | |
available | boolean | False when the order does not entitle anyone, or the allowance is spent. |
unavailableReason | string or null | Why not, in English, for the customer. |
unavailable | string or null | One of unpaid, canceled, refunded, exhausted. |
Used by List an order’s downloads, Set a download allowance.
Fulfillment
| Field | Type | Description |
|---|---|---|
fulfillment | object | |
fulfillment.id | string (uuid) | |
fulfillment.orderId | string (uuid) | |
fulfillment.storeId | string (uuid) | |
fulfillment.locationId | string (uuid) or null | |
fulfillment.type | string | One of shipping, pickup, digital. |
fulfillment.status | string | One of pending, processing, shipped, in_transit, out_for_delivery, ready_for_pickup, delivered, failed, canceled. |
fulfillment.carrier | string or null | |
fulfillment.trackingNumber | string or null | |
fulfillment.trackingUrl | string or null | |
fulfillment.destination | object or null | Where it is going. |
fulfillment.destination.name | string | |
fulfillment.destination.line_one | string | |
fulfillment.destination.line_two | string | |
fulfillment.destination.city | string | |
fulfillment.destination.state | string | |
fulfillment.destination.country | string | |
fulfillment.destination.postal_code | string | |
fulfillment.estimatedDeliveryEarliest | string (date-time) or null | |
fulfillment.estimatedDeliveryLatest | string (date-time) or null | |
fulfillment.digitalAccessUrl | string or null | |
fulfillment.digitalLicenseKey | string or null | |
fulfillment.digitalExpiresAt | string (date-time) or null | |
fulfillment.description | string or null | |
fulfillment.supplierConnectionId | string (uuid) or null | |
fulfillment.supplierOrderId | string or null | |
fulfillment.actorType | string or null | Who recorded it. One of staff, customer, plugin, agent, system. |
fulfillment.actorId | string or null | |
fulfillment.createdAt | string (date-time) | |
fulfillment.updatedAt | string (date-time) | |
events | array of object | Where it has got to, newest first. |
events[].id | string (uuid) | |
events[].fulfillmentId | string (uuid) | |
events[].storeId | string (uuid) | |
events[].type | string | One of processing, shipped, in_transit, out_for_delivery, ready_for_pickup, delivered, failed_attempt, returned. |
events[].occurredAt | string (date-time) | |
events[].description | string or null | |
events[].location | string or null | |
events[].sourceKey | string or null | The carrier’s name for the scan. Null for one a person recorded. |
events[].createdAt | string (date-time) | |
lineItems | array of object | The order’s lines it carries, and how many of each. |
lineItems[].lineItemId | string (uuid) | |
lineItems[].quantity | integer |
Used by List an order’s fulfillments, Create a fulfillment, Record a tracking event, Take back a despatch, Correct a despatch’s tracking.
InventoryLevel
| Field | Type | Description |
|---|---|---|
variantId | string (uuid) | |
locationId | string (uuid) | |
storeId | string (uuid) | |
onHand | number | What is on the shelf. |
reserved | number | Held for orders placed and not yet sent. |
available | integer | On hand less reserved: what can still be sold. |
updatedAt | string (date-time) |
Used by Get a variant’s stock levels, Change stock at a location.
Listing
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
title | string | |
status | string | One of draft, active, archived. |
description | string or null | HTML. |
productType | string or null | |
variants | integer | How many variants it has. More than one means options, each with its own price. |
price | object or null | Its price in the shop’s currency, when it has one variant and that is priced. |
price.amount | integer | In the currency’s minor units, such as pence. |
price.currency | string | An ISO 4217 code, such as GBP. |
madeToOrder | boolean | Whether it keeps selling with none in stock. |
pictures | array of object | Its first three pictures, the cover first, sized for a small tile. |
pictures[].id | string (uuid) | |
pictures[].url | string or null |
Used by Get several listings.
Location
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
name | string | |
isDefault | boolean | Orders take their stock from the default location. A shop has one. |
address | object or null | Where a carrier collects from. Null until somebody gives one. |
address.name | string | |
address.company | string | |
address.line_one | string | |
address.line_two | string | |
address.city | string | |
address.state | string | |
address.country | string | Two letters, such as GB. |
address.postal_code | string | |
address.phone | string | |
address.email | string | |
addressValidatedAt | string (date-time) or null | When a carrier last agreed the address exists. Null is unchecked. |
kind | string | supplier stock is refreshed from the supplier and cannot be changed here. One of own, supplier. |
supplierConnectionId | string (uuid) or null | The supplier that stocks it. Null for the shop’s own. |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by List locations, Create a location, Update a location.
MetafieldDefinition
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
pluginId | string (uuid) or null | The app whose manifest declares it. Null for the shop’s own field. |
ownerType | string | The kind of record it hangs on. One of product, variant, collection, customer, order, store. |
namespace | string | custom unless said. Namespaces starting app_ belong to apps. |
key | string | |
name | string | The merchant’s label for it. |
description | string or null | |
type | string | One of single_line_text, multi_line_text, integer, decimal, boolean, date, url. |
isList | boolean | Holds a list of values rather than one. |
validations | object | The rules every value is checked against. |
validations.min | number | |
validations.max | number | |
validations.minLength | integer | |
validations.maxLength | integer | |
validations.choices | array of string | The only values it may hold. |
validations.scale | integer | Digits after the point, for decimal. |
storefrontVisible | boolean | Shoppers may see it. Never true on a customer or an order. |
searchFacet | boolean | Shoppers can narrow search by it. |
position | number | Where it sits among the fields for its kind of record, lowest first. |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by List metafield definitions, Get a metafield definition, Update a metafield definition.
Order
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
sessionId | string (uuid) or null | |
customerId | string (uuid) or null | |
buyerProven | boolean | Whether the basket named a known customer when the order was placed. False for an order filed under an email address someone typed. |
orderNumber | string | The number the shop and the buyer know it by, without the #. |
customerNote | string or null | What the shopper wrote at checkout. |
status | string | One of created, confirmed, manual_review, processing, shipped, delivered, canceled. |
currency | string | |
locale | string or null | The language the shopper was reading the shop in. Null when the shop never knew. |
buyerEmail | string | |
buyerFirstName | string or null | |
buyerLastName | string or null | |
buyerPhone | string or null | |
shippingAddress | object or null | |
shippingAddress.name | string | |
shippingAddress.line_one | string | |
shippingAddress.line_two | string | |
shippingAddress.city | string | |
shippingAddress.state | string | |
shippingAddress.country | string | |
shippingAddress.postal_code | string | |
billingAddress | object or null | |
billingAddress.name | string | |
billingAddress.line_one | string | |
billingAddress.line_two | string | |
billingAddress.city | string | |
billingAddress.state | string | |
billingAddress.country | string | |
billingAddress.postal_code | string | |
fulfillmentOption | object or null | The delivery the shopper chose, by name. Null on older orders. |
fulfillmentOption.type | string | One of shipping, digital, pickup, local_delivery. |
fulfillmentOption.id | string | |
fulfillmentOption.title | string | |
fulfillmentOption.description | string | |
fulfillmentOption.carrier | string | |
fulfillmentOption.earliest_delivery_time | string | |
fulfillmentOption.latest_delivery_time | string | |
fulfillmentOption.amount | integer | Minor units. |
subtotalAmount | number | The goods, before discounts, in minor units of currency (1999 is 19.99). Every amount on an order is in minor units. |
discountAmount | number | Everything discounts took off, including any taken off delivery. |
fulfillmentAmount | number | Delivery, after any discount on it. |
taxAmount | number | Tax, including any on delivery. |
fulfillmentTaxAmount | number | The part of taxAmount charged on delivery. |
fulfillmentDiscountAmount | number | The part of discountAmount that came off delivery. |
companyId | string (uuid) or null | The trade account it was placed against, if any. |
priceListId | string (uuid) or null | |
paymentTermsNetDays | number or null | Days to pay, for an order placed on account. Null when paid at checkout. |
dueAt | string (date-time) or null | When an order on account falls due. |
purchaseOrderNumber | string or null | |
totalAmount | number | What the order came to at checkout. Refunds and edits never change it; they are counted in refundedAmount and changeAmount. |
refundedAmount | number | Refunded so far. |
changeAmount | number | The net of every confirmed change, signed: positive means the customer owes more. |
creditAppliedAmount | number | The part of the total paid with store credit. |
taxCalculationId | string or null | |
taxTransactionId | string or null | |
discountId | string (uuid) or null | |
discountCode | string or null | |
tags | array of string | Labels the shop put on the order. Staff only, never shown to a shopper. |
heldAt | string (date-time) or null | When the shop kept this order back from being sent. Null when it may go. |
heldBy | string or null | Who kept it back. |
holdReason | string or null | Why it was kept back. Staff only, never shown to a shopper. |
origin | string | Which door placed it. One of storefront, agent, admin, plugin, imported, subscription. |
agentId | string or null | The AI agent that placed it, when one did. |
conversationId | string (uuid) or null | |
referralId | string (uuid) or null | |
adLinkId | string (uuid) or null | |
placedAt | string (date-time) | |
canceledAt | string (date-time) or null | |
subscriptionId | string (uuid) or null | The subscription that produced it. Null for a one time purchase. |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by List orders, Get an order, Cancel an order, Approve or reject a held order, Record an invoice payment.
OrderAdjustment
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
orderId | string (uuid) | |
storeId | string (uuid) | |
type | string | One of refund, partial_refund, store_credit, return, exchange, cancellation, dispute, chargeback. |
status | string | A refund is pending while the money moves, then completed or failed. One of pending, completed, failed. |
amount | number | In minor units of the order’s currency. |
currency | string or null | |
reason | string or null | |
description | string or null | |
providerRefundId | string or null | The payment provider’s id for the refund, when one was sent. |
evidenceDueBy | string (date-time) or null | On a dispute: when the answer is due. |
feeAmount | number or null | On a dispute: what it cost, in minor units of feeCurrency. Null until the payment provider states it. |
feeCurrency | string or null | On a dispute: the currency of feeAmount. |
taxReversalId | string or null | |
actorType | string or null | Who issued it. Null for a refund the payment provider reported. One of staff, customer, plugin, agent, system. |
actorId | string or null | |
occurredAt | string (date-time) | |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by Get an order, List an order’s refunds, Refund an order.
OrderChange
| Field | Type | Description |
|---|---|---|
change | object | |
change.id | string (uuid) | |
change.storeId | string (uuid) | |
change.orderId | string (uuid) | |
change.kind | string | One of edit, return, exchange, claim. |
change.status | string | One of pending, confirmed, declined, canceled. |
change.reason | string or null | |
change.note | string or null | |
change.deltaSubtotalAmount | number | |
change.deltaDiscountAmount | number | |
change.deltaFulfillmentAmount | number | |
change.deltaTaxAmount | number | |
change.deltaTotalAmount | number | What the change came to, signed and in minor units: positive means the customer owes more. Zero until it is confirmed, as are the other deltas. |
change.currency | string | |
change.adjustmentId | string (uuid) or null | The refund it made, when it gave money back. |
change.paymentId | string (uuid) or null | |
change.actorType | string or null | One of staff, customer, plugin, agent, system. |
change.actorId | string or null | |
change.createdAt | string (date-time) | |
change.updatedAt | string (date-time) | |
change.confirmedAt | string (date-time) or null | |
change.declinedAt | string (date-time) or null | |
change.canceledAt | string (date-time) or null | |
actions | array of object | |
actions[].id | string (uuid) | |
actions[].storeId | string (uuid) | |
actions[].changeId | string (uuid) | |
actions[].action | string | One of item_add, item_quantity, item_remove, shipping_add, shipping_remove. |
actions[].lineItemId | string (uuid) or null | |
actions[].variantId | string (uuid) or null | |
actions[].quantityDelta | number | Signed. Negative takes units off the line. |
actions[].unitAmount | number | Minor units. |
actions[].amount | number | Minor units. |
actions[].details | any | |
actions[].createdAt | string (date-time) |
Used by List an order’s changes, Open an order change, Confirm, decline or cancel an order change, Add a line to an order change, Remove a line from an order change.
OrderLineItem
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
orderId | string (uuid) | |
storeId | string (uuid) | |
variantId | string (uuid) or null | |
productId | string (uuid) or null | |
title | string | The product’s title when it was bought. |
variantTitle | string or null | The variant’s title when it was bought. |
productHandle | string or null | |
sku | string or null | |
imageUrl | string or null | |
quantityOrdered | number | |
quantityShipped | number | Units sent. |
quantityRefunded | number | Units whose money went back. |
quantityReturned | number | Units that came back, whatever the shopper got for them. |
unitAmount | number | One unit, in minor units of the order’s currency. |
subtotalAmount | number | Every unit on the line, before its discount and tax. |
priceListId | string (uuid) or null | |
listUnitAmount | number or null | What one unit costs at the shop’s own price, when a price list priced this line. Null otherwise. |
discountAmount | number | The line’s share of the discounts. |
taxAmount | number | The line’s tax. |
sellingPlanId | string (uuid) or null | |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by Get an order, Approve or reject a held order.
OrderNote
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
orderId | string (uuid) | |
storeId | string (uuid) | |
body | string | |
actorType | string | Who wrote it. One of staff, system, agent, plugin. |
actorId | string | |
createdAt | string (date-time) |
Used by List an order’s notes, Add a note to an order.
PayoutSummary
| Field | Type | Description |
|---|---|---|
connected | boolean | False for a shop with no payment account yet. |
live | boolean | False when the balance and the list could not be read just now. They are then empty, and failure is still current. |
balance | object | |
balance.available | array of object | Ready to be sent, per currency. |
balance.available[].amount | integer | In the currency’s minor unit: cents, pence, paise. |
balance.available[].currency | string | Lower case, such as gbp. |
balance.pending | array of object | Still clearing, per currency. |
balance.pending[].amount | integer | In the currency’s minor unit: cents, pence, paise. |
balance.pending[].currency | string | Lower case, such as gbp. |
payouts | array of object | The latest ten, newest first. |
payouts[].id | string | |
payouts[].amount | integer | In the currency’s minor unit. |
payouts[].currency | string | |
payouts[].arrivalDate | string (date-time) | When the bank should have it, or did. |
payouts[].status | string | paid, pending, in_transit, canceled or failed. |
payouts[].failureCode | string or null | Why it failed, as a code such as account_closed, when it did. |
nextArrival | string (date-time) or null | The earliest arrival among those on their way, or null when none is. |
failure | object or null | The last failure on record, while no later payout has arrived. |
failure.at | string (date-time) | |
failure.code | string or null |
Used by Read the shop’s balance and payouts.
PriceChange
| Field | Type | Description |
|---|---|---|
id | number | Pass as historyId to put back the price from before this change. |
storeId | string (uuid) | |
variantId | string (uuid) | |
currency | string | |
amount | number | The new price, in minor units. |
previousAmount | number or null | The price before. Null for the variant’s first price. |
compareAtAmount | number or null | |
previousCompareAtAmount | number or null | |
actorType | string | One of staff, customer, plugin, agent, system. |
actorId | string or null | |
reason | string or null | Why it moved, where known, such as revert for a change put back. One of merchant, import, bulk, proposal, revert. |
proposalId | string (uuid) or null | |
createdAt | string (date-time) |
Used by List a variant’s price changes.
Product
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
title | string | |
handle | string | The product’s address on the shop front: /products/\{handle\}. |
description | string or null | |
status | string | Only an active product is on sale. One of draft, active, archived. |
productType | string or null | |
vendor | string or null | |
tags | array of string | |
seoTitle | string or null | |
seoDescription | string or null | |
isGiftCard | boolean | Buying it buys a gift card worth the variant’s price. |
pinnedCopy | array of string | Fields whose wording is the merchant’s own, which automatic copy leaves alone. |
publishedAt | string (date-time) or null | When it first went on sale. Putting it on sale again does not move it. |
enrichmentStatus | string | One of none, queued, ready, failed. |
indexedAt | string (date-time) or null | |
indexedEnrichmentId | string (uuid) or null | |
indexedBackends | array of string | |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
archivedAt | string (date-time) or null | When it was archived. Lists leave archived products out unless asked. |
Used by List a collection’s products.
ProductDetail
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
title | string | |
handle | string | The product’s address on the shop front: /products/\{handle\}. |
description | string or null | |
status | string | Only an active product is on sale. One of draft, active, archived. |
productType | string or null | |
vendor | string or null | |
tags | array of string | |
seoTitle | string or null | |
seoDescription | string or null | |
isGiftCard | boolean | Buying it buys a gift card worth the variant’s price. |
pinnedCopy | array of string | Fields whose wording is the merchant’s own, which automatic copy leaves alone. |
publishedAt | string (date-time) or null | When it first went on sale. Putting it on sale again does not move it. |
enrichmentStatus | string | One of none, queued, ready, failed. |
indexedAt | string (date-time) or null | |
indexedEnrichmentId | string (uuid) or null | |
indexedBackends | array of string | |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
archivedAt | string (date-time) or null | When it was archived. Lists leave archived products out unless asked. |
options | array of object | |
options[].id | string (uuid) | |
options[].name | string | |
options[].position | integer | |
options[].values | array of string | Its values, in order. |
options[].valueRows | array of object | The same values with their ids, for renaming or removing one. |
options[].valueRows[].id | string (uuid) | |
options[].valueRows[].value | string | |
options[].valueRows[].position | integer | |
variants | array of object | |
variants[].id | string (uuid) | |
variants[].title | string | Its option values joined, such as S / Navy, unless set by hand. |
variants[].sku | string or null | |
variants[].barcode | string or null | |
variants[].weightGrams | integer or null | |
variants[].hsCode | string or null | The tariff code customs is told abroad. |
variants[].countryOfOrigin | string or null | Two letters, such as US. |
variants[].requiresShipping | boolean | |
variants[].isDigital | boolean | |
variants[].position | integer | |
variants[].continueSelling | boolean | Whether it keeps selling once its stock is zero. |
variants[].taxClassId | string (uuid) or null | The shop’s own tax rate it is sold at. Null is the standard one. |
variants[].shippingClassId | string (uuid) or null | The delivery group it belongs to, which decides the rates it can go by. |
variants[].cost | object or null | What one cost to buy. Null means unknown, not free. |
variants[].cost.amount | integer | In the currency’s minor units, such as pence. |
variants[].cost.currency | string | An ISO 4217 code, such as GBP. |
variants[].prices | array of object | |
variants[].prices[].currency | string | |
variants[].prices[].amount | integer | |
variants[].prices[].compareAtAmount | integer or null | The higher price shown struck through beside it. |
Used by Create a product, Get a product, Update a product, Copy a product, Add an option to a product, Rename an option, Add a value to an option, Rename an option value, Remove an option value, Create a listing.
ProductFigures
| Field | Type | Description |
|---|---|---|
notLive | integer | Drafts, not yet on sale. |
outOfStock | integer | Products nobody can buy: every version keeps a count and none is left. filter=out_of_stock lists them. |
neverRead | integer | Products the shop has never read. filter=never_read lists them. |
sold30Days | object or null | The last thirty days. Null without analytics:read. filter=sold_30d lists them. |
sold30Days.products | integer | How many products were on an order. |
sold30Days.units | integer | How many of them were ordered. |
Used by Count the catalogue.
ProductMedia
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
storagePath | string or null | |
sourceUrl | string or null | |
storageProvider | string | One of supabase, r2. |
mimeType | string | |
sizeBytes | number or null | |
width | number or null | |
height | number or null | |
alt | string or null | |
mirrorClaimedAt | string (date-time) or null | |
mirrorAttempts | number | |
mirrorFailedAt | string (date-time) or null | |
createdAt | string (date-time) | |
url | string | Where the image is served. |
position | integer | Its place in the order, from 0. |
Used by List a product’s images, Add an image to a product, List a variant’s images.
ProductRow
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
title | string | |
handle | string | The product’s address on the shop front: /products/\{handle\}. |
description | string or null | |
status | string | Only an active product is on sale. One of draft, active, archived. |
productType | string or null | |
vendor | string or null | |
tags | array of string | |
seoTitle | string or null | |
seoDescription | string or null | |
isGiftCard | boolean | Buying it buys a gift card worth the variant’s price. |
pinnedCopy | array of string | Fields whose wording is the merchant’s own, which automatic copy leaves alone. |
publishedAt | string (date-time) or null | When it first went on sale. Putting it on sale again does not move it. |
enrichmentStatus | string | One of none, queued, ready, failed. |
indexedAt | string (date-time) or null | |
indexedEnrichmentId | string (uuid) or null | |
indexedBackends | array of string | |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
archivedAt | string (date-time) or null | When it was archived. Lists leave archived products out unless asked. |
thumbnail | string or null | Its first picture, sized for a row. Null when it has none. |
price | object or null | Null when no version has a price in the shop’s currency. |
price.min | integer | The cheapest version, in the currency’s minor units. |
price.max | integer | The dearest version, in the same units. |
price.currency | string | The shop’s own currency. |
stock | object | What is left of it. |
stock.available | integer | What is left to sell, over every location and every version that counts. |
stock.tracked | boolean | False when no version keeps a count: each sells on with none left, or is a download. |
stock.sellsOn | boolean | True when at least one version sells on with none left, or is a download, so the product can still be bought at nought. |
Used by List products.
ProductSales
| Field | Type | Description |
|---|---|---|
units | array of integer | 30 entries, one per day, oldest first. |
revenue | integer | What those units were sold for in the shop’s own currency, in minor units. Sales taken in another currency count as units and are left out of this figure. |
currency | string or null | The shop’s currency, or null when nothing sold in it. |
Used by Get a product’s sales by day.
Return
| Field | Type | Description |
|---|---|---|
request | object | |
request.id | string (uuid) | |
request.storeId | string (uuid) | |
request.orderId | string (uuid) | |
request.customerId | string (uuid) or null | |
request.returnNumber | string | |
request.status | string | One of requested, approved, declined, in_transit, partially_received, received, resolved, canceled. |
request.reasonId | string (uuid) or null | |
request.reasonNote | string or null | |
request.resolution | string or null | One of refund, store_credit, exchange. |
request.locationId | string (uuid) or null | |
request.carrier | string or null | |
request.trackingNumber | string or null | |
request.trackingUrl | string or null | |
request.labelUrl | string or null | |
request.adjustmentId | string (uuid) or null | |
request.orderChangeId | string (uuid) or null | |
request.creditEntryId | string (uuid) or null | |
request.exchangeSessionId | string (uuid) or null | |
request.exchangeOrderId | string (uuid) or null | |
request.estimatedRefundAmount | number | Minor units, as every amount on a return is. |
request.restockingFeeAmount | number | |
request.shippingRefundAmount | number | |
request.currency | string | |
request.origin | string | One of storefront, agent, admin, plugin, imported. |
request.agentId | string or null | |
request.requestedAt | string (date-time) | |
request.approvedAt | string (date-time) or null | |
request.declinedAt | string (date-time) or null | |
request.inTransitAt | string (date-time) or null | |
request.receivedAt | string (date-time) or null | |
request.resolvedAt | string (date-time) or null | |
request.canceledAt | string (date-time) or null | |
request.windowOverriddenAt | string (date-time) or null | |
request.merchantNote | string or null | |
request.declineReason | string or null | |
request.decidedVia | string or null | One of policy, mandate. |
request.mandateHeldBecause | string or null | |
request.createdAt | string (date-time) | |
request.updatedAt | string (date-time) | |
lines | array of object | |
lines[].returnId | string (uuid) | |
lines[].lineItemId | string (uuid) | |
lines[].storeId | string (uuid) | |
lines[].quantityRequested | number | |
lines[].quantityApproved | number | |
lines[].quantityReceived | number | |
lines[].quantityRestocked | number | |
lines[].quantityClaimed | number | |
lines[].reasonId | string (uuid) or null | |
lines[].reasonNote | string or null | |
lines[].disposition | string or null | One of restock, damaged, discard, quarantine, return_to_vendor. |
lines[].inspectedAt | string (date-time) or null | |
lines[].refundAmount | number | |
lines[].taxRefundAmount | number | |
lines[].restockingFeeAmount | number | |
lines[].createdAt | string (date-time) | |
lines[].updatedAt | string (date-time) | |
lines[].title | string | |
lines[].variantTitle | string or null | |
lines[].sku | string or null | |
lines[].imageUrl | string or null | |
reason | object or null | |
reason.id | string (uuid) | |
reason.storeId | string (uuid) | |
reason.code | string | One of wrong_size, wrong_item_sent, damaged_in_transit, defective, not_as_described, looks_different_to_photo, quality_below_expectation, arrived_late, changed_mind, other. |
reason.label | string | |
reason.refundsShipping | boolean | |
reason.waivesRestockingFee | boolean | |
reason.requiresReturn | boolean | |
reason.defaultDisposition | string | One of restock, damaged, discard, quarantine, return_to_vendor. |
reason.position | number | |
reason.shopAdded | boolean | |
reason.archivedAt | string (date-time) or null | |
reason.createdAt | string (date-time) | |
reason.updatedAt | string (date-time) |
Used by List an order’s returns, Open a return.
ShippingClass
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
name | string | |
slug | string | Stable across renames. What a later import matches on. |
description | string or null | A note for the merchant. Shoppers do not see it. |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by Create a shipping class, Update a shipping class.
ShippingClassRow
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
storeId | string (uuid) | |
name | string | |
slug | string | Stable across renames. What a later import matches on. |
description | string or null | A note for the merchant. Shoppers do not see it. |
createdAt | string (date-time) | |
updatedAt | string (date-time) | |
variantCount | integer | How many variants are in it. |
rateCount | integer | How many delivery rates name it. |
Used by List shipping classes.
ShippingLabel
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
orderId | string (uuid) | |
fulfillmentId | string (uuid) or null | The despatch it is for. |
returnId | string (uuid) or null | The return it brings back. |
direction | string | One of outbound, return. |
status | string | One of reserved, action_required, authorized, purchasing, purchased, void_pending, voided, failed, canceled. |
livemode | boolean | |
payOnUse | boolean | A return label charged only if a carrier scans it. |
carrier | string | |
carrierName | string | |
serviceToken | string | |
serviceName | string | |
estimatedDays | integer or null | |
trackingNumber | string or null | |
trackingUrl | string or null | |
trackingStatus | string or null | |
labelUrl | string or null | The label to print, once it is bought. |
commercialInvoiceUrl | string or null | |
amount | integer | The carrier’s price, in minor units. |
currency | string | |
charge | object or null | What the card was charged, in minor units. |
charge.status | string | One of pending, action_required, authorized, captured, canceled, failed, owed. |
charge.postage | integer | |
charge.fee | integer | |
charge.total | integer | |
charge.refunded | integer | |
parcel | object | |
parcel.packageId | string (uuid) | |
parcel.packageName | string | |
parcel.lengthMm | integer | |
parcel.widthMm | integer | |
parcel.heightMm | integer | |
parcel.weightGrams | integer | |
lines | array of object | |
lines[].lineItemId | string (uuid) | |
lines[].quantity | integer | |
failure | string or null | |
createdAt | string (date-time) | |
purchasedAt | string (date-time) or null | |
voidedAt | string (date-time) or null | |
clientSecret | string | Present only while the bank wants the cardholder to confirm the charge. |
Used by List an order’s shipping labels, Buy a shipping label, Resume a shipping label purchase, Void a shipping label.
Variant
| Field | Type | Description |
|---|---|---|
id | string (uuid) | |
productId | string (uuid) | |
storeId | string (uuid) | |
title | string | Its option values joined, such as S / Navy, unless set by hand. |
sku | string or null | |
barcode | string or null | |
position | number | |
weightGrams | number or null | |
lengthMm | number or null | |
widthMm | number or null | |
heightMm | number or null | |
hsCode | string or null | The tariff code customs is told when it is posted abroad. |
countryOfOrigin | string or null | Two letters, such as US. |
shippingClassId | string (uuid) or null | The delivery group it belongs to, which decides the rates it can go by. |
lowStockThreshold | number or null | |
taxClassId | string (uuid) or null | The shop’s own tax rate it is sold at. Null is the standard one. |
orderMinimum | number or null | |
orderMaximum | number or null | |
orderIncrement | number or null | |
costAmount | number or null | What one cost to buy, in minor units of costCurrency. Null means unknown. |
costCurrency | string or null | |
requiresShipping | boolean | |
isDigital | boolean | |
continueSelling | boolean | Whether it keeps selling once its stock is zero. |
createdAt | string (date-time) | |
updatedAt | string (date-time) |
Used by Update a variant.
VariantExtras
| Field | Type | Description |
|---|---|---|
variantId | string (uuid) | |
levels | array of InventoryLevel | Its stock at every location holding it. |
assets | array of DigitalAsset | The files it delivers, oldest first. |
images | array of ProductMedia | Its own pictures, in order. |
metafields | array of object | |
metafields[].definitionId | string (uuid) | |
metafields[].namespace | string | |
metafields[].key | string | |
metafields[].label | string | The merchant’s name for the field. |
metafields[].type | string | single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types. |
metafields[].isList | boolean | |
metafields[].storefrontVisible | boolean | |
metafields[].searchFacet | boolean | |
metafields[].position | integer | |
metafields[].value | any | The value, or a list of values when isList. |
metafields[].displayValue | string | The value as one line of text, lists joined. |
metafields[].source | string | Who set it: the merchant, an import, or an app’s slug. |
Used by Read what every variant of a product holds.
Error
What every call answers when it fails, with a status of 400 or more. See Errors.
| Field | Type | Description |
|---|---|---|
error | object | |
error.type | string | What went wrong, for a program: not_found, validation_failed. |
error.message | string | What went wrong, for a person. |
error.fields | map of array of string | On 422: each field that is wrong, and what is wrong with it. |
error.requiredScopes | array of string | On 403: the permissions the call needed. |
requestId | string | Quote it when asking for help. |