REST API

Every call takes your app’s access token as Authorization: Bearer and answers JSON with the result under data, as the API reference describes. Each one below names the permissions it needs; your app holds the ones a merchant granted it, from those its manifest asks for.

The OpenAPI documentCopy Anchor Link

The same calls as OpenAPI 3.1, for a code generator or an API client: https://api.storeware.ai/api/v1/openapi.json. The permissions a call needs are under x-storeware-scopes.

curl -s https://api.storeware.ai/api/v1/openapi.json -o storeware-openapi.json

More of the API is described here with each release.

ProductsCopy Anchor Link

The catalogue: products, their media and their fields.

• List products: GET /api/v1/stores/{storeId}/products
• Create a product: POST /api/v1/stores/{storeId}/products
• Count the catalogue: GET /api/v1/stores/{storeId}/products/figures
• Get a product: GET /api/v1/stores/{storeId}/products/{productId}
• Update a product: PATCH /api/v1/stores/{storeId}/products/{productId}
• Archive a product: DELETE /api/v1/stores/{storeId}/products/{productId}
• Get a product’s sales by day: GET /api/v1/stores/{storeId}/products/{productId}/sales
• Copy a product: POST /api/v1/stores/{storeId}/products/{productId}/duplicate
• List a product’s images: GET /api/v1/stores/{storeId}/products/{productId}/media
• Add an image to a product: POST /api/v1/stores/{storeId}/products/{productId}/media
• Reorder a product’s images: POST /api/v1/stores/{storeId}/products/{productId}/media/order
• Add an option to a product: POST /api/v1/stores/{storeId}/products/{productId}/options
• Rename an option: PATCH /api/v1/stores/{storeId}/options/{optionId}
• Add a value to an option: POST /api/v1/stores/{storeId}/options/{optionId}
• Rename an option value: PATCH /api/v1/stores/{storeId}/option-values/{optionValueId}
• Remove an option value: DELETE /api/v1/stores/{storeId}/option-values/{optionValueId}
• Get several listings: GET /api/v1/stores/{storeId}/products/listings
• Create a listing: POST /api/v1/stores/{storeId}/products/listings
• Change many prices at once: POST /api/v1/stores/{storeId}/products/prices
• Price and publish several listings: POST /api/v1/stores/{storeId}/products/listings/settle
• Search as an AI shopper: POST /api/v1/stores/{storeId}/search/as-ai-shopper
• List a product’s metafields: GET /api/v1/stores/{storeId}/products/{productId}/metafields
• Set a product’s metafields: PUT /api/v1/stores/{storeId}/products/{productId}/metafields
• List a product’s translations: GET /api/v1/stores/{storeId}/products/{productId}/translations
• Set a product’s translations: PUT /api/v1/stores/{storeId}/products/{productId}/translations

VariantsCopy Anchor Link

The versions of a product a shopper buys, and their options.

• Read what every variant of a product holds: GET /api/v1/stores/{storeId}/products/{productId}/variant-extras
• Update a variant: PATCH /api/v1/stores/{storeId}/variants/{variantId}
• Set a variant’s price: POST /api/v1/stores/{storeId}/variants/{variantId}/price
• List a variant’s price changes: GET /api/v1/stores/{storeId}/variants/{variantId}/price/history
• Put a price back: POST /api/v1/stores/{storeId}/variants/{variantId}/price/revert
• Set what a variant cost to buy: POST /api/v1/stores/{storeId}/variants/{variantId}/cost
• Set whether a variant sells with no stock: POST /api/v1/stores/{storeId}/variants/{variantId}/backorder
• List a variant’s images: GET /api/v1/stores/{storeId}/variants/{variantId}/media
• Show an image for a variant: POST /api/v1/stores/{storeId}/variants/{variantId}/media
• Take an image off a variant: DELETE /api/v1/stores/{storeId}/variants/{variantId}/media
• List a variant’s downloads: GET /api/v1/stores/{storeId}/variants/{variantId}/digital-assets
• Attach a download to a variant: POST /api/v1/stores/{storeId}/variants/{variantId}/digital-assets
• List a variant’s metafields: GET /api/v1/stores/{storeId}/variants/{variantId}/metafields
• Set a variant’s metafields: PUT /api/v1/stores/{storeId}/variants/{variantId}/metafields

CollectionsCopy Anchor Link

Groups of products, set by hand or by rules.

• List collections: GET /api/v1/stores/{storeId}/collections
• Create a collection: POST /api/v1/stores/{storeId}/collections
• Get a collection: GET /api/v1/stores/{storeId}/collections/{collectionId}
• Update a collection: PATCH /api/v1/stores/{storeId}/collections/{collectionId}
• Delete a collection: DELETE /api/v1/stores/{storeId}/collections/{collectionId}
• List a collection’s products: GET /api/v1/stores/{storeId}/collections/{collectionId}/products
• Add products to a collection: POST /api/v1/stores/{storeId}/collections/{collectionId}/products
• Remove a product from a collection: DELETE /api/v1/stores/{storeId}/collections/{collectionId}/products/{productId}
• List a collection’s metafields: GET /api/v1/stores/{storeId}/collections/{collectionId}/metafields
• Set a collection’s metafields: PUT /api/v1/stores/{storeId}/collections/{collectionId}/metafields
• List a collection’s translations: GET /api/v1/stores/{storeId}/collections/{collectionId}/translations
• Set a collection’s translations: PUT /api/v1/stores/{storeId}/collections/{collectionId}/translations

InventoryCopy Anchor Link

Stock at each location, and the locations themselves.

• List stock: GET /api/v1/stores/{storeId}/inventory
• List stock on its way: GET /api/v1/stores/{storeId}/inventory/incoming
• Get a variant’s stock levels: GET /api/v1/stores/{storeId}/inventory/{variantId}
• Change stock at a location: POST /api/v1/stores/{storeId}/inventory/{variantId}
• List a variant’s stock history: GET /api/v1/stores/{storeId}/inventory/{variantId}/movements
• Get a variant’s stock at every location: GET /api/v1/stores/{storeId}/inventory/{variantId}/stock
• List locations: GET /api/v1/stores/{storeId}/locations
• Create a location: POST /api/v1/stores/{storeId}/locations
• Update a location: PATCH /api/v1/stores/{storeId}/locations/{locationId}

ShippingCopy Anchor Link

The groups a shop sorts its goods into for delivery.

• List shipping classes: GET /api/v1/stores/{storeId}/shipping-classes
• Create a shipping class: POST /api/v1/stores/{storeId}/shipping-classes
• Update a shipping class: PATCH /api/v1/stores/{storeId}/shipping-classes/{classId}
• Delete a shipping class: DELETE /api/v1/stores/{storeId}/shipping-classes/{classId}

OrdersCopy Anchor Link

Orders, their payments, fulfillments, refunds and changes.

• List orders: GET /api/v1/stores/{storeId}/orders
• Get an order: GET /api/v1/stores/{storeId}/orders/{orderId}
• Cancel an order: DELETE /api/v1/stores/{storeId}/orders/{orderId}
• Correct an order’s contact details or address: PATCH /api/v1/stores/{storeId}/orders/{orderId}
• List orders waiting on a card check: GET /api/v1/stores/{storeId}/orders/authentications
• Renew a card check link: POST /api/v1/stores/{storeId}/orders/authentications/{sessionId}
• Approve or reject a held order: POST /api/v1/stores/{storeId}/orders/{orderId}/approval
• List an order’s changes: GET /api/v1/stores/{storeId}/orders/{orderId}/changes
• Open an order change: POST /api/v1/stores/{storeId}/orders/{orderId}/changes
• Get an order change: GET /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}
• Confirm, decline or cancel an order change: POST /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}
• Add a line to an order change: POST /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}/actions
• Remove a line from an order change: DELETE /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}/actions/{actionId}
• List an order’s downloads: GET /api/v1/stores/{storeId}/orders/{orderId}/downloads
• Set a download allowance: PATCH /api/v1/stores/{storeId}/orders/{orderId}/downloads
• List an order’s fulfillments: GET /api/v1/stores/{storeId}/orders/{orderId}/fulfillments
• Create a fulfillment: POST /api/v1/stores/{storeId}/orders/{orderId}/fulfillments
• Record a tracking event: POST /api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}/events
• Get what a shipping label needs: GET /api/v1/stores/{storeId}/orders/{orderId}/label-quotes
• Quote a shipping label: POST /api/v1/stores/{storeId}/orders/{orderId}/label-quotes
• List an order’s shipping labels: GET /api/v1/stores/{storeId}/orders/{orderId}/labels
• Buy a shipping label: POST /api/v1/stores/{storeId}/orders/{orderId}/labels
• Resume a shipping label purchase: POST /api/v1/stores/{storeId}/orders/{orderId}/labels/{labelId}/resume
• Void a shipping label: POST /api/v1/stores/{storeId}/orders/{orderId}/labels/{labelId}/void
• List an order’s metafields: GET /api/v1/stores/{storeId}/orders/{orderId}/metafields
• Set an order’s metafields: PUT /api/v1/stores/{storeId}/orders/{orderId}/metafields
• Add a return reason: POST /api/v1/stores/{storeId}/return-reasons
• Take back a despatch: DELETE /api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}
• Correct a despatch’s tracking: PATCH /api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}
• See what correcting an order’s details would mean: POST /api/v1/stores/{storeId}/orders/{orderId}/details/preview
• Keep an order back from being sent: POST /api/v1/stores/{storeId}/orders/{orderId}/hold
• Release an order kept back: DELETE /api/v1/stores/{storeId}/orders/{orderId}/hold
• List the tags a shop’s orders carry: GET /api/v1/stores/{storeId}/orders/facets
• Change an order’s tags: PATCH /api/v1/stores/{storeId}/orders/{orderId}/tags
• List an order’s notes: GET /api/v1/stores/{storeId}/orders/{orderId}/notes
• Add a note to an order: POST /api/v1/stores/{storeId}/orders/{orderId}/notes
• Record an invoice payment: POST /api/v1/stores/{storeId}/orders/{orderId}/payments
• List an order’s refunds: GET /api/v1/stores/{storeId}/orders/{orderId}/refunds
• Refund an order: POST /api/v1/stores/{storeId}/orders/{orderId}/refunds
• List an order’s returns: GET /api/v1/stores/{storeId}/orders/{orderId}/returns
• Open a return: POST /api/v1/stores/{storeId}/orders/{orderId}/returns

PaymentsCopy Anchor Link

What the shop holds, and the money sent to its bank.

• Read the shop’s balance and payouts: GET /api/v1/stores/{storeId}/payments/payouts

CustomersCopy Anchor Link

The shop’s customers and what is kept about them.

• List customers: GET /api/v1/stores/{storeId}/customers
• Create a customer: POST /api/v1/stores/{storeId}/customers
• List the tags and countries customers have: GET /api/v1/stores/{storeId}/customers/facets
• Get a customer: GET /api/v1/stores/{storeId}/customers/{customerId}
• Update a customer: PATCH /api/v1/stores/{storeId}/customers/{customerId}
• List a customer’s saved addresses: GET /api/v1/stores/{storeId}/customers/{customerId}/addresses
• Save an address for a customer: POST /api/v1/stores/{storeId}/customers/{customerId}/addresses
• Correct a customer’s saved address: PATCH /api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}
• Remove a customer’s saved address: DELETE /api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}
• Make a saved address the default: POST /api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}/default
• Archive a customer: POST /api/v1/stores/{storeId}/customers/{customerId}/archive
• Unarchive a customer: POST /api/v1/stores/{storeId}/customers/{customerId}/unarchive
• Withdraw a customer’s marketing consent: DELETE /api/v1/stores/{storeId}/customers/{customerId}/marketing-consent
• List a customer’s metafields: GET /api/v1/stores/{storeId}/customers/{customerId}/metafields
• Set a customer’s metafields: PUT /api/v1/stores/{storeId}/customers/{customerId}/metafields
• List the trade accounts a customer buys for: GET /api/v1/stores/{storeId}/customers/{customerId}/companies
• Get a customer’s store credit: GET /api/v1/stores/{storeId}/customers/{customerId}/store-credit
• Give a customer store credit: POST /api/v1/stores/{storeId}/customers/{customerId}/store-credit
• Get what the shop remembers about a customer: GET /api/v1/stores/{storeId}/customers/{customerId}/memory
• Make the shop forget what a customer told it: POST /api/v1/stores/{storeId}/customers/{customerId}/memory

MetafieldsCopy Anchor Link

The typed fields a shop and its apps keep on records.

• List metafield definitions: GET /api/v1/stores/{storeId}/metafield-definitions
• Get a metafield definition: GET /api/v1/stores/{storeId}/metafield-definitions/{definitionId}
• Update a metafield definition: PATCH /api/v1/stores/{storeId}/metafield-definitions/{definitionId}
• Delete a metafield definition: DELETE /api/v1/stores/{storeId}/metafield-definitions/{definitionId}
• List the shop’s metafields: GET /api/v1/stores/{storeId}/metafields
• Set the shop’s metafields: PUT /api/v1/stores/{storeId}/metafields

App billingCopy Anchor Link

What a shop pays your app: plans, one time charges and use.

• Get your app’s billing on this shop: GET /api/v1/app-billing
• Ask the merchant to approve a plan: POST /api/v1/app-billing/subscriptions
• End your plan on this shop: POST /api/v1/app-billing/subscriptions/{subscriptionId}/cancel
• Ask the merchant to approve a one-time charge: POST /api/v1/app-billing/purchases
• Report what the shop used: POST /api/v1/app-billing/usage
• Credit the shop: POST /api/v1/app-billing/credits

App settingsCopy Anchor Link

What a merchant set for your app, and pictures your components show.

• Get what the merchant set for your app: GET /api/v1/app/settings
• Put a picture on Storeware for your components: POST /api/v1/app/assets

App automationsCopy Anchor Link

Triggers your app fires into a shop’s automations, and the menu they are built from.

• Fire one of your automation triggers: POST /api/v1/app/events
• Get what this shop’s automations may be made of: GET /api/v1/stores/{storeId}/automations/vocabulary

ObjectsCopy Anchor Link

What many calls answer with is described once, on Objects: AppPurchase, AppSubscription, AppUsage, Collection, Customer, CustomerSavedAddress, CustomerSummary, DigitalAsset, DownloadGrant, Fulfillment, InventoryLevel, Listing, Location, MetafieldDefinition, Order, OrderAdjustment, OrderChange, OrderLineItem, OrderNote, PayoutSummary, PriceChange, Product, ProductDetail, ProductFigures, ProductMedia, ProductRow, ProductSales, Return, ShippingClass, ShippingClassRow, ShippingLabel, Variant, VariantExtras.