# Objects

> The resources many REST calls answer with, and every field each has.

Source: https://storeware.ai/docs/api-reference/rest/objects

## 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](https://storeware.ai/docs/api-reference/rest/app-billing#get-app-billing), [Ask the merchant to approve a one-time charge](https://storeware.ai/docs/api-reference/rest/app-billing#request-app-purchase).

## 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](https://storeware.ai/docs/api-reference/rest/app-billing#get-app-billing), [Ask the merchant to approve a plan](https://storeware.ai/docs/api-reference/rest/app-billing#request-app-subscription), [End your plan on this shop](https://storeware.ai/docs/api-reference/rest/app-billing#cancel-app-subscription).

## 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](https://storeware.ai/docs/api-reference/rest/app-billing#get-app-billing), [Report what the shop used](https://storeware.ai/docs/api-reference/rest/app-billing#record-app-usage).

## 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](https://storeware.ai/docs/api-reference/rest/collections#list-collections), [Create a collection](https://storeware.ai/docs/api-reference/rest/collections#create-collection), [Get a collection](https://storeware.ai/docs/api-reference/rest/collections#get-collection), [Update a collection](https://storeware.ai/docs/api-reference/rest/collections#update-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](https://storeware.ai/docs/api-reference/rest/customers#create-customer), [Update a customer](https://storeware.ai/docs/api-reference/rest/customers#update-customer), [Archive a customer](https://storeware.ai/docs/api-reference/rest/customers#archive-customer), [Unarchive a customer](https://storeware.ai/docs/api-reference/rest/customers#unarchive-customer), [Withdraw a customer’s marketing consent](https://storeware.ai/docs/api-reference/rest/customers#withdraw-customer-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](https://storeware.ai/docs/api-reference/rest/customers#list-customer-addresses), [Save an address for a customer](https://storeware.ai/docs/api-reference/rest/customers#add-customer-address), [Correct a customer’s saved address](https://storeware.ai/docs/api-reference/rest/customers#update-customer-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](https://storeware.ai/docs/api-reference/rest/customers#list-customers), [Get a customer](https://storeware.ai/docs/api-reference/rest/customers#get-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](https://storeware.ai/docs/api-reference/rest/variants#list-variant-digital-assets), [Attach a download to a variant](https://storeware.ai/docs/api-reference/rest/variants#attach-variant-digital-asset).

## 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](https://storeware.ai/docs/api-reference/rest/orders#list-order-downloads), [Set a download allowance](https://storeware.ai/docs/api-reference/rest/orders#set-order-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](https://storeware.ai/docs/api-reference/rest/orders#list-fulfillments), [Create a fulfillment](https://storeware.ai/docs/api-reference/rest/orders#create-fulfillment), [Record a tracking event](https://storeware.ai/docs/api-reference/rest/orders#record-tracking-event), [Take back a despatch](https://storeware.ai/docs/api-reference/rest/orders#void-fulfillment), [Correct a despatch’s tracking](https://storeware.ai/docs/api-reference/rest/orders#correct-fulfillment-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](https://storeware.ai/docs/api-reference/rest/inventory#get-inventory), [Change stock at a location](https://storeware.ai/docs/api-reference/rest/inventory#change-inventory).

## 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](https://storeware.ai/docs/api-reference/rest/products#list-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](https://storeware.ai/docs/api-reference/rest/inventory#list-locations), [Create a location](https://storeware.ai/docs/api-reference/rest/inventory#create-location), [Update a location](https://storeware.ai/docs/api-reference/rest/inventory#update-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](https://storeware.ai/docs/api-reference/rest/metafields#list-metafield-definitions), [Get a metafield definition](https://storeware.ai/docs/api-reference/rest/metafields#get-metafield-definition), [Update a metafield definition](https://storeware.ai/docs/api-reference/rest/metafields#update-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](https://storeware.ai/docs/api-reference/rest/orders#list-orders), [Get an order](https://storeware.ai/docs/api-reference/rest/orders#get-order), [Cancel an order](https://storeware.ai/docs/api-reference/rest/orders#cancel-order), [Approve or reject a held order](https://storeware.ai/docs/api-reference/rest/orders#decide-order-approval), [Record an invoice payment](https://storeware.ai/docs/api-reference/rest/orders#record-order-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](https://storeware.ai/docs/api-reference/rest/orders#get-order), [List an order’s refunds](https://storeware.ai/docs/api-reference/rest/orders#list-order-refunds), [Refund an order](https://storeware.ai/docs/api-reference/rest/orders#refund-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](https://storeware.ai/docs/api-reference/rest/orders#list-order-changes), [Open an order change](https://storeware.ai/docs/api-reference/rest/orders#open-order-change), [Confirm, decline or cancel an order change](https://storeware.ai/docs/api-reference/rest/orders#decide-order-change), [Add a line to an order change](https://storeware.ai/docs/api-reference/rest/orders#add-order-change-action), [Remove a line from an order change](https://storeware.ai/docs/api-reference/rest/orders#remove-order-change-action).

## 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](https://storeware.ai/docs/api-reference/rest/orders#get-order), [Approve or reject a held order](https://storeware.ai/docs/api-reference/rest/orders#decide-order-approval).

## 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](https://storeware.ai/docs/api-reference/rest/orders#list-order-notes), [Add a note to an order](https://storeware.ai/docs/api-reference/rest/orders#add-order-note).

## 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](https://storeware.ai/docs/api-reference/rest/payments#get-payout-summary).

## 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](https://storeware.ai/docs/api-reference/rest/variants#list-variant-price-history).

## 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](https://storeware.ai/docs/api-reference/rest/collections#list-collection-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](https://storeware.ai/docs/api-reference/rest/products#create-product), [Get a product](https://storeware.ai/docs/api-reference/rest/products#get-product), [Update a product](https://storeware.ai/docs/api-reference/rest/products#update-product), [Copy a product](https://storeware.ai/docs/api-reference/rest/products#duplicate-product), [Add an option to a product](https://storeware.ai/docs/api-reference/rest/products#add-product-option), [Rename an option](https://storeware.ai/docs/api-reference/rest/products#rename-option), [Add a value to an option](https://storeware.ai/docs/api-reference/rest/products#add-option-value), [Rename an option value](https://storeware.ai/docs/api-reference/rest/products#rename-option-value), [Remove an option value](https://storeware.ai/docs/api-reference/rest/products#remove-option-value), [Create a listing](https://storeware.ai/docs/api-reference/rest/products#create-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](https://storeware.ai/docs/api-reference/rest/products#get-product-figures).

## 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](https://storeware.ai/docs/api-reference/rest/products#list-product-media), [Add an image to a product](https://storeware.ai/docs/api-reference/rest/products#add-product-media), [List a variant’s images](https://storeware.ai/docs/api-reference/rest/variants#list-variant-media).

## 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](https://storeware.ai/docs/api-reference/rest/products#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](https://storeware.ai/docs/api-reference/rest/products#get-product-sales).

## 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](https://storeware.ai/docs/api-reference/rest/orders#list-order-returns), [Open a return](https://storeware.ai/docs/api-reference/rest/orders#request-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](https://storeware.ai/docs/api-reference/rest/shipping#create-shipping-class), [Update a shipping class](https://storeware.ai/docs/api-reference/rest/shipping#update-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](https://storeware.ai/docs/api-reference/rest/shipping#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](https://storeware.ai/docs/api-reference/rest/orders#list-shipping-labels), [Buy a shipping label](https://storeware.ai/docs/api-reference/rest/orders#buy-shipping-label), [Resume a shipping label purchase](https://storeware.ai/docs/api-reference/rest/orders#resume-shipping-label), [Void a shipping label](https://storeware.ai/docs/api-reference/rest/orders#void-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](https://storeware.ai/docs/api-reference/rest/variants#update-variant).

## VariantExtras

| Field | Type | Description |
| --- | --- | --- |
| `variantId` | string (uuid) |  |
| `levels` | array of [InventoryLevel](https://storeware.ai/docs/api-reference/rest/objects#inventorylevel) | Its stock at every location holding it. |
| `assets` | array of [DigitalAsset](https://storeware.ai/docs/api-reference/rest/objects#digitalasset) | The files it delivers, oldest first. |
| `images` | array of [ProductMedia](https://storeware.ai/docs/api-reference/rest/objects#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](https://storeware.ai/docs/api-reference/rest/variants#get-variant-extras).

## Error

What every call answers when it fails, with a status of 400 or more. See [Errors](https://storeware.ai/docs/api-reference#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. |