Developer docs

API v1 and fixed commerce SDK

Public reference for ReTale integrators: generated OpenAPI operations, TypeScript client usage, checkout-safe idempotency, pagination, error envelopes, tenant scoping, and generated storefront boundaries.

Start at the quickstart, then verify the same contracts in API reference before wiring storefront actions.

OpenAPI sourceopenapi/v1.yaml

API version0.1.0

Operations341

Idempotent mutations14

Entry points

Move to the right surface for your next decision

Merchant execution

Use the signup flow when you are evaluating catalog, payments, and storefront rollout.

Start a store

SDK integration

Read install and usage steps for both public catalog + merchant-scoped calls.

Jump to quickstart

Compliance evidence

Open trust, security, and policy pages for public statements before procurement or legal review.

View trust posture

SDK quickstart

Install, configure, and call fixed commerce flows

Install packages

npm install @retale/api-client @retale/commerce-sdk

Use @retale/api-client for typed REST calls and @retale/commerce-sdk for generated storefront commerce surfaces.

Configure base URL

import { createRetaleClient } from "@retale/api-client";
import { createCommerceSdk } from "@retale/commerce-sdk";

const api = createRetaleClient({
  baseUrl: process.env.NEXT_PUBLIC_RETALE_API_URL ?? "http://localhost:4100/api/v1",
  publishableKey: process.env.NEXT_PUBLIC_RETALE_PUBLISHABLE_KEY
});

export const commerce = createCommerceSdk(api);

Local examples target http://localhost:4100/api/v1. Public storefront calls scope by storeSlug; merchant calls scope by storeId plus a merchant session token.

Checkout mutation with idempotency and errors

import { ApiClientError } from "@retale/api-client";

try {
  const checkout = await commerce.checkout.create({
    storeSlug: "demo-store",
    cartId: "cart_123",
    idempotencyKey: "checkout-cart_123-attempt_1"
  });

  await commerce.checkout.initiateGatewayPayment({
    storeSlug: "demo-store",
    checkoutId: checkout.id,
    returnUrl: "http://localhost:4102/checkout/return",
    cancelUrl: "http://localhost:4102/cart",
    idempotencyKey: "payment-session-cart_123-attempt_1"
  });
} catch (error) {
  if (error instanceof ApiClientError) {
    console.error(error.status, error.code, error.requestId, error.details);
  }
  throw error;
}

Retryable cart, checkout, payment, loyalty, and order mutations should pass a stable idempotencyKey. Non-2xx responses throw ApiClientError with status, code, message, requestId, and optional details.

Pagination

const page = await api.listProducts("demo-store", {
  limit: 24,
  offset: 48,
  sort: "best_selling"
});

console.log(page.items, page.limit, page.offset, page.total);

List endpoints return items, limit, offset, and total. Keep UI paging state explicit so generated storefronts can render stable catalog and review views.

Generated from OpenAPI

API reference

This operation index is generated from openapi/v1.yaml. Run npm run developer-docs:check to verify the checked-in docs artifact still matches the OpenAPI contract.

Storefront API80 Merchant Admin API252 Provider Webhooks6 Platform API3

Storefront API

Slug-scoped catalog, cart, checkout, account, content, loyalty, membership, and review endpoints.

80 operations

GET/stores/{storeSlug}/account/addresses

List saved customer addresses

Operation: listStorefrontCustomerAddresses
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Saved customer addressesCustomerAddress[]

POST/stores/{storeSlug}/account/addresses

Create a saved customer address

Operation: createStorefrontCustomerAddress
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerAddressRequest

Responses

201Address savedCustomerAddress

PATCH/stores/{storeSlug}/account/addresses/{addressId}

Update a saved customer address

Operation: updateStorefrontCustomerAddress
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
addressIdpathrequiredstring

Request body

Required: CustomerAddressPatchRequest

Responses

200Address updatedCustomerAddress

DELETE/stores/{storeSlug}/account/addresses/{addressId}

Delete a saved customer address

Operation: deleteStorefrontCustomerAddress
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
addressIdpathrequiredstring

Responses

204Address deleted

POST/stores/{storeSlug}/account/content-comments

Submit a content comment for moderation

Operation: submitContentComment
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: ContentCommentSubmissionRequest

Responses

201Content comment submittedContentComment

POST/stores/{storeSlug}/account/login

Create a storefront customer session

Operation: loginStorefrontCustomer
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerLoginRequest

Responses

200Customer session createdCustomerSessionResponse

POST/stores/{storeSlug}/account/logout

Revoke the current storefront customer session

Operation: logoutStorefrontCustomer
Audience: Generated storefronts and customer experiences
Access: CustomerSession
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

204Customer session revoked
401Missing or invalid customer sessionErrorResponse

GET/stores/{storeSlug}/account/loyalty

Get the authenticated customer's loyalty account

Operation: getAccountLoyalty
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Loyalty account projectionLoyaltyAccount

GET/stores/{storeSlug}/account/loyalty/ledger

List the authenticated customer's loyalty ledger entries

Operation: listAccountLoyaltyLedger
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Loyalty ledger entriesLoyaltyLedgerListResponse

PUT/stores/{storeSlug}/account/marketing-consent

Update current customer marketing consent

Operation: updateStorefrontCustomerMarketingConsent
Audience: Generated storefronts and customer experiences
Access: CustomerSession
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerMarketingConsentRequest

Responses

200Updated customer profileCustomer

GET/stores/{storeSlug}/account/me

Get the current storefront customer profile

Operation: getStorefrontCustomerProfile
Audience: Generated storefronts and customer experiences
Access: CustomerSession
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Current customer profileCustomer
401Missing or invalid customer sessionErrorResponse

PATCH/stores/{storeSlug}/account/me

Update the current storefront customer profile

Operation: updateStorefrontCustomerProfile
Audience: Generated storefronts and customer experiences
Access: CustomerSession
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerProfilePatchRequest

Responses

200Updated customer profileCustomer
401Missing or invalid customer sessionErrorResponse

POST/stores/{storeSlug}/account/membership-billing-subscriptions/{membershipBillingSubscriptionId}/plan/{membershipPlanId}

Change a recurring membership subscription plan with proration

Operation: changeMembershipBillingPlan
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
membershipBillingSubscriptionIdpathrequiredstring
membershipPlanIdpathrequiredstring

Request body

Optional: MembershipSubscriptionChangeRequest

Responses

200Membership plan changed and proration recorded when applicableMembershipBillingPlanChangeResponse

GET/stores/{storeSlug}/account/memberships

List memberships for the authenticated customer

Operation: listAccountMemberships
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Customer membershipsCustomerMembership[]

POST/stores/{storeSlug}/account/memberships/{customerMembershipId}/cancel

Cancel a customer membership

Operation: cancelMembership
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
customerMembershipIdpathrequiredstring

Request body

Optional: object

Responses

200Customer membership cancelledCustomerMembership

POST/stores/{storeSlug}/account/memberships/{membershipPlanId}/join

Join a published membership plan

Operation: joinMembershipPlan
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
membershipPlanIdpathrequiredstring

Request body

Optional: CustomerMembershipJoinRequest

Responses

200Customer membershipCustomerMembership

POST/stores/{storeSlug}/account/memberships/{membershipPlanId}/subscriptions

Create a gateway-backed recurring membership subscription

Operation: subscribeToMembershipPlan
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
membershipPlanIdpathrequiredstring

Request body

Required: MembershipSubscriptionCreateRequest

Responses

201Membership and recurring billing subscription createdMembershipBillingSubscriptionResponse
409Gateway, membership, or payment source is not in a subscribable stateErrorResponse

GET/stores/{storeSlug}/account/orders

List customer order history for a storefront account

Operation: listStorefrontCustomerOrders
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
customerIdqueryoptionalstring
emailqueryoptionalstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Customer-scoped order historyOrderListResponse

POST/stores/{storeSlug}/account/password-reset

Request a one-time customer password reset token

Operation: requestStorefrontCustomerPasswordReset
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerPasswordResetRequest

Responses

202Password reset request acceptedobject

POST/stores/{storeSlug}/account/password-reset/complete

Complete a customer password reset and revoke existing sessions

Operation: completeStorefrontCustomerPasswordReset
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerPasswordResetCompleteRequest

Responses

204Password reset completed

GET/stores/{storeSlug}/account/payment-methods

List tokenized customer payment methods

Operation: listStorefrontCustomerPaymentMethods
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Tokenized payment methodsCustomerPaymentMethod[]

POST/stores/{storeSlug}/account/payment-methods

Save a tokenized customer payment method reference

Operation: saveStorefrontCustomerPaymentMethod
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerPaymentMethodRequest

Responses

201Payment method savedCustomerPaymentMethod

DELETE/stores/{storeSlug}/account/payment-methods/{paymentMethodId}

Delete a tokenized customer payment method reference

Operation: deleteStorefrontCustomerPaymentMethod
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
paymentMethodIdpathrequiredstring

Responses

204Payment method deleted

POST/stores/{storeSlug}/account/reviews

Submit a verified-purchase product review

Operation: submitProductReview
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: ProductReviewSubmissionRequest

Responses

201Review submitted for moderation or rejected by abuse controlsProductReview
409Purchase verification, duplicate, or abuse limit failedErrorResponse

POST/stores/{storeSlug}/account/signup

Create a storefront customer account and session

Operation: signupStorefrontCustomer
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: CustomerSignupRequest

Responses

201Customer account and session createdCustomerSessionResponse

POST/stores/{storeSlug}/cart-recoveries

Restore a cart from a recovery link

Operation: recoverStorefrontCart
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: object

Responses

200The cart, restoredCartReopenResult

POST/stores/{storeSlug}/carts

Create a storefront cart

Operation: createStorefrontCart
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Optional: CartCreateRequest

Responses

201Cart created or idempotently returnedCart

GET/stores/{storeSlug}/carts/{cartId}

Get a storefront cart by ID

Operation: getStorefrontCart
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring

Responses

200Cart detailCart
404Cart not found in this storeErrorResponse

POST/stores/{storeSlug}/carts/{cartId}/checkout

Create a checkout session and reserve inventory

Operation: createStorefrontCheckout
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Optional: CheckoutCreateRequest

Responses

201Checkout created with inventory reservedCheckoutSession
409Cart expired or inventory unavailableErrorResponse

PUT/stores/{storeSlug}/carts/{cartId}/customer

Attach guest or authenticated customer context to a cart

Operation: attachStorefrontCartCustomer
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: CheckoutCustomer

Responses

200Customer context attachedCart

PUT/stores/{storeSlug}/carts/{cartId}/customer/addresses

Attach saved customer addresses to a cart

Operation: attachStorefrontCartCustomerAddress
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: AttachCustomerAddressToCartRequest

Responses

200Saved addresses attached to cart customer contextCart

POST/stores/{storeSlug}/carts/{cartId}/discounts

Apply a discount code to a cart

Operation: applyStorefrontCartDiscount
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: CartDiscountRequest

Responses

200Discount appliedCart

DELETE/stores/{storeSlug}/carts/{cartId}/discounts/{code}

Take a discount code off a cart

Operation: removeStorefrontCartDiscount
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
codepathrequiredstring
Idempotency-Keyheaderrequiredstring

Responses

200Code removed and totals recalculatedCart

POST/stores/{storeSlug}/carts/{cartId}/lines

Add a variant to a storefront cart

Operation: addStorefrontCartLine
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: CartLineAddRequest

Responses

200Cart updatedCart

PATCH/stores/{storeSlug}/carts/{cartId}/lines/{lineId}

Update a cart line quantity

Operation: updateStorefrontCartLine
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
lineIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: CartLineUpdateRequest

Responses

200Cart line updatedCart

DELETE/stores/{storeSlug}/carts/{cartId}/lines/{lineId}

Remove a cart line

Operation: removeStorefrontCartLine
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
lineIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Responses

200Cart line removedCart

POST/stores/{storeSlug}/carts/{cartId}/loyalty-redemptions

Reserve loyalty points and return a cart discount line

Operation: redeemLoyaltyPointsForCart
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: LoyaltyRedemptionRequest

Responses

201Loyalty redemption reserved for checkoutLoyaltyRedemptionResponse

GET/stores/{storeSlug}/carts/{cartId}/membership-perks

Evaluate active membership perks for a cart

Operation: evaluateMembershipPerks
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring

Responses

200Membership perks applicable to the cartMembershipPerkEvaluation

POST/stores/{storeSlug}/carts/{cartId}/reopen

Bring back a cart left at checkout

Operation: reopenStorefrontCart
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring

Responses

200The cart, open againCartReopenResult

PUT/stores/{storeSlug}/carts/{cartId}/shipping

Select a shipping option for checkout

Operation: selectStorefrontCartShipping
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: CartShippingSelectionRequest

Responses

200Shipping selectedCart

GET/stores/{storeSlug}/carts/{cartId}/shipping-options

The shipping options this cart is offered

Operation: listStorefrontCartShippingOptions
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
cartIdpathrequiredstring

Responses

200Shipping optionsCartShippingOptionList

GET/stores/{storeSlug}/catalog

Public catalog placeholder

Operation: listStoreCatalog
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Store catalog responsePublicCatalogResponse
404Store not foundErrorResponse

GET/stores/{storeSlug}/checkouts/{checkoutId}

Get a checkout session by ID

Operation: getStorefrontCheckout
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring

Responses

200Checkout session detailCheckoutSession
404Checkout session not found in this storeErrorResponse

GET/stores/{storeSlug}/checkouts/{checkoutId}/age-check

Whether this checkout needs an age check, and where it stands

Operation: getStorefrontCheckoutAgeCheck
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring

Responses

200The checkout's age checkStorefrontAgeCheck

POST/stores/{storeSlug}/checkouts/{checkoutId}/age-check

Check the shopper's age for this checkout

Operation: checkStorefrontCheckoutAge
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring

Request body

Required: object

Responses

200The checkout's age check, after checkingStorefrontAgeCheck
503The age check couldn't be made; nothing can be paid until it isErrorResponse

POST/stores/{storeSlug}/checkouts/{checkoutId}/order

Finalize a checkout into an order

Operation: finalizeStorefrontCheckoutOrder
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Optional: OrderFinalizeRequest

Responses

201Order created, checkout completed, and inventory committedOrderFinalizationResponse

GET/stores/{storeSlug}/checkouts/{checkoutId}/payment-status

Where a card payment has got to

Operation: getStorefrontCardPaymentProgress
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring

Responses

200Payment progressCardPaymentProgress

POST/stores/{storeSlug}/checkouts/{checkoutId}/payments/card

Start (or resume) card payment through the store's payment provider

Operation: startStorefrontCardPayment
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring

Responses

200What the Payment Element needsCardPaymentStart
409The store is not taking card payments right nowErrorResponse

POST/stores/{storeSlug}/checkouts/{checkoutId}/payments/card/authorize-net

Pay a checkout through the store's own Authorize.net account

Operation: payStorefrontCheckoutWithAuthorizeNet
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring

Request body

Required: object

Responses

200How the payment wentAuthorizeNetPaymentOutcome
400The token is missing or not an Accept.js tokenErrorResponse
409The store is not taking card payments through Authorize.netErrorResponse

POST/stores/{storeSlug}/checkouts/{checkoutId}/payments/confirm

Confirm checkout payment with a gateway token or saved payment method

Operation: confirmGatewayCheckoutPayment
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Required: GatewayCheckoutPaymentConfirmRequest

Responses

200Payment authorization resultGatewayCheckoutPaymentConfirmResponse

POST/stores/{storeSlug}/checkouts/{checkoutId}/payments/session

Create a hosted or tokenized payment session through the configured gateway

Operation: initiateGatewayCheckoutPayment
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Uses Idempotency-Key

Parameters

storeSlugpathrequiredstring
checkoutIdpathrequiredstring
Idempotency-Keyheaderrequiredstring

Request body

Optional: GatewayCheckoutPaymentSessionRequest

Responses

200Gateway payment session createdGatewayCheckoutPaymentSessionResponse

GET/stores/{storeSlug}/collections

List published collections for a storefront

Operation: listPublicCollections
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger
qqueryoptionalstring
sortqueryoptionalPublicCollectionSortOrder

Responses

200Published collections visible to generated storefrontsPublicCollectionListResponse
404Store not foundErrorResponse

GET/stores/{storeSlug}/collections/{handle}

Get a published collection and paginated products

Operation: listPublicCollectionProducts
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
handlepathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger
qqueryoptionalstring
vendorqueryoptionalstring
brandqueryoptionalstring
tagqueryoptionalstring[]
minPricequeryoptionalstring
maxPricequeryoptionalstring
sortqueryoptionalstring | PublicProductSortOrder
filterqueryoptionalobject

Responses

200Collection metadata and visible productsPublicCollectionProductsResponse
404Collection not found or unpublishedErrorResponse

GET/stores/{storeSlug}/content

List published pages and blog posts for a storefront

Operation: listPublicContentEntries
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
typequeryoptionalContentEntryType
tagqueryoptionalstring
categoryqueryoptionalstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Published content entries visible to generated storefrontsPublicContentEntryListResponse

GET/stores/{storeSlug}/content/{entryId}/comments

List approved comments for a content entry

Operation: listPublicContentComments
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
entryIdpathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Approved content commentsPublicContentCommentListResponse

GET/stores/{storeSlug}/content/{type}/{slug}

Get one published content entry by type and slug

Operation: getPublicContentEntry
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
typepathrequiredContentEntryType
slugpathrequiredstring

Responses

200Published content entryPublicContentEntry
404Content not found or not yet publishedErrorResponse

GET/stores/{storeSlug}/filters

What a shopper can filter this store's products on

Operation: listStorefrontFilters
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200The filterable fieldsobject

POST/stores/{storeSlug}/guests

Create a guest checkout identity

Operation: createStorefrontGuestIdentity
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: GuestIdentityCreateRequest

Responses

201Guest identity createdGuestIdentity

POST/stores/{storeSlug}/guests/{guestId}/convert

Convert a guest identity into a customer account

Operation: convertStorefrontGuestIdentity
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
guestIdpathrequiredstring

Request body

Required: GuestConvertRequest

Responses

201Guest converted to a customer account and sessionCustomerSessionResponse

GET/stores/{storeSlug}/head

The store's name, home page search listing and business details, for every storefront page's head (NOR-987 / NOR-988)

Operation: getPublicStoreHead
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200The store's headobject
404Store not foundErrorResponse

GET/stores/{storeSlug}/indexnow-key

The store's IndexNow key, which the storefront serves at /<key>.txt on the store's domain

Operation: getStoreIndexNowKey
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200The keyobject
404Store not foundErrorResponse

POST/stores/{storeSlug}/invoices/pay

The checkout an invoice is paid through (NOR-919)

Operation: payDraftInvoice
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: DraftInvoiceToken

Responses

200The checkout to payobject

POST/stores/{storeSlug}/invoices/view

The order a draft order's invoice link shows (NOR-919)

Operation: getDraftInvoice
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: DraftInvoiceToken

Responses

200The draft, as agreedDraftInvoice

POST/stores/{storeSlug}/marketing/unsubscribe

Record a tokenized customer marketing unsubscribe

Operation: unsubscribeStorefrontMarketing
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: StorefrontMarketingUnsubscribeRequest

Responses

200Marketing opt-out recordedMarketingOptOutResponse

POST/stores/{storeSlug}/memberships/access

Evaluate member-only access for a product or collection

Operation: evaluateMembershipAccess
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Request body

Required: MembershipAccessCheckRequest

Responses

200Membership access decisionMembershipAccessDecision

GET/stores/{storeSlug}/menus/{handle}

A storefront menu, resolved to labels and addresses (NOR-878)

Operation: getPublicMenu
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
handlepathrequiredstring

Responses

200The menuPublicMenu
404No menu with this handleErrorResponse

GET/stores/{storeSlug}/orders/{orderId}

Get a single order for its owning customer or guest

Operation: getStorefrontOrder
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
orderIdpathrequiredstring
emailqueryoptionalstring

Responses

200Order detailOrder
404Order not found for this store, or not owned by the requesting customer/guestErrorResponse

GET/stores/{storeSlug}/pages/{handle}

A storefront page as its sections, resolved for rendering (NOR-967 / NOR-969)

Operation: getPublicStorePage
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
handlepathrequiredstring

Responses

200The pagePublicStorePage
404No such pageErrorResponse

GET/stores/{storeSlug}/products

List published products for a storefront

Operation: listPublicProducts
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger
qqueryoptionalstring
vendorqueryoptionalstring
brandqueryoptionalstring
tagqueryoptionalstring[]
minPricequeryoptionalstring
maxPricequeryoptionalstring
sortqueryoptionalPublicProductSortOrder
collectionqueryoptionalstring
wherequeryoptionalstring[]

Responses

200Published products visible to generated storefrontsPublicProductListResponse
404Store not foundErrorResponse

GET/stores/{storeSlug}/products/{handle}

Get one published product by handle

Operation: getPublicProductByHandle
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
handlepathrequiredstring

Responses

200Published product detailPublicProduct
404Product not found or unpublishedErrorResponse

GET/stores/{storeSlug}/products/{handle}/related

Other published products from the collections this product is in (stored membership)

Operation: listPublicRelatedProducts
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
handlepathrequiredstring
limitqueryoptionalinteger

Responses

200Related products; empty when the product is in no published collectionobject
404Product not found or unpublishedErrorResponse

GET/stores/{storeSlug}/products/{handle}/reviews

List approved reviews for a published product

Operation: listPublicProductReviews
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
handlepathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Approved product reviews visible to the storefrontPublicProductReviewListResponse

GET/stores/{storeSlug}/products/{handle}/reviews/summary

Get aggregate rating for a published product

Operation: getPublicProductReviewSummary
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
handlepathrequiredstring

Responses

200Product review aggregateProductReviewSummary

GET/stores/{storeSlug}/purchasing

Whether this store can take an order right now

Operation: getStorePurchasing
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Purchasing availabilityStorePurchasing

GET/stores/{storeSlug}/redirects

Where an old address now lives -- for a product whose web address was changed

Operation: resolveStorefrontRedirect
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
pathqueryrequiredstring

Responses

200The redirectobject
404No redirect from that pathErrorResponse

GET/stores/{storeSlug}/resolve-path

What the storefront should do with a path (NOR-828 / NOR-872)

Operation: resolveStorefrontPath
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
pathqueryrequiredstring
searchqueryoptionalstring
referrerqueryoptionalstring

Responses

200The decisionobject

GET/stores/{storeSlug}/robots.txt

Storefront robots directives

Operation: getStoreRobots
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Robots directives
404Store not foundErrorResponse

GET/stores/{storeSlug}/sitemap.xml

The store's sitemap index (NOR-986) over one file per kind, for published, indexable resources

Operation: getStoreSitemap
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200XML sitemap
404Store not foundErrorResponse

GET/stores/{storeSlug}/sitemaps/{kind}

One kind's sitemap file (products, collections, pages or blogs), as the store's own domain serves it

Operation: getStoreSitemapByKind
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring
kindpathrequiredstring

Responses

200XML sitemap (urlset)
404Store or sitemap kind not foundErrorResponse

GET/stores/{storeSlug}/tax-display

Get storefront tax display settings

Operation: getStorefrontTaxDisplaySettings
Audience: Generated storefronts and customer experiences
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeSlugpathrequiredstring

Responses

200Storefront tax display modeStorefrontTaxDisplaySettings
404Store not foundErrorResponse

Merchant Admin API

Store ID-scoped operations for catalog, inventory, orders, settings, generation, and growth workflows.

252 operations

POST/merchant/invitations/accept

Accept a store staff invitation for the current merchant user

Operation: acceptStoreStaffInvitation
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: AcceptStaffInvitationRequest

Responses

200Active store context and permissionsResolvedMerchantAccess
401Missing session or invalid invitation tokenErrorResponse

GET/merchant/legal-acceptance

Whether the signed-in merchant has agreed to the current Terms of Service and Privacy Policy

Operation: readLegalAcceptance
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Responses

200Each document's current version and what the merchant last agreed toLegalAcceptanceStatus

POST/merchant/legal-acceptance

Record agreement to the current Terms of Service and Privacy Policy

Operation: acceptLegalDocuments
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: LegalVersions

Responses

200Recorded, with the version and the timeLegalAcceptanceStatus
400Missing, or not the current version (LEGAL_ACCEPTANCE_REQUIRED / LEGAL_VERSION_OUTDATED)ErrorResponse

POST/merchant/login

Create a merchant session

Operation: loginMerchant
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Request body

Required: MerchantLoginRequest

Responses

200Merchant session createdMerchantSessionResponse
401Invalid merchant credentialsErrorResponse
403Merchant cannot access requested active storeErrorResponse

POST/merchant/logout

Revoke the current merchant session

Operation: logoutMerchant
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Responses

204Merchant session revoked
401Missing or invalid merchant sessionErrorResponse

POST/merchant/oauth/{provider}/callback

Complete a Google or Apple sign-in and create a merchant session

Operation: completeMerchantOAuth
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

providerpathrequiredstring

Request body

Required: MerchantOAuthCallbackRequest

Responses

200Merchant session createdMerchantOAuthSessionResponse
400The provider did not vouch for an email addressErrorResponse
401The code or ID token could not be verifiedErrorResponse
409An email/password account already holds this addressErrorResponse

POST/merchant/oauth/{provider}/start

Begin a Google or Apple sign-in

Operation: startMerchantOAuth
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

providerpathrequiredstring

Responses

200Authorization URL for the providerMerchantOAuthStartResponse
404Provider is not configuredErrorResponse

GET/merchant/oauth/providers

List the identity providers a merchant can sign up or log in with

Operation: listMerchantOAuthProviders
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Responses

200Configured providersMerchantOAuthProvidersResponse

POST/merchant/onboarding

Initialize a merchant store from a business preset

Operation: completeMerchantOnboarding
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: CompleteOnboardingRequest

Responses

201Initialized store and active owner contextOnboardingResponse
400Invalid onboarding requestErrorResponse

POST/merchant/onboarding/classify

Guess the business type and default switches from the merchant's own words

Operation: classifyOnboardingDescription
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: ClassifyOnboardingDescriptionRequest

Responses

200The guess, in plain words, with the merchant's own words behind itOnboardingClassificationResponse
429Too many classification requestsErrorResponse

GET/merchant/onboarding/draft

The landing-page answer Step 1 of onboarding pre-fills from

Operation: readOnboardingDraft
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Responses

200The carried answer, or nullOnboardingDraftResponse

POST/merchant/onboarding/drafts

Park the landing-page answer before the visitor has an account

Operation: createOnboardingDraft
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Request body

Required: CreateOnboardingDraftRequest

Responses

201Draft parkedOnboardingDraftCreatedResponse
400Empty answerErrorResponse
429Too many drafts from this clientErrorResponse

POST/merchant/onboarding/drafts/claim

Bind a parked landing-page answer to the signed-in account and return its text

Operation: claimOnboardingDraft
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: ClaimOnboardingDraftRequest

Responses

200The carried answer, or nullOnboardingDraftResponse

GET/merchant/onboarding/progress

Where the signed-in merchant is in the four onboarding steps

Operation: readOnboardingProgress
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Responses

200The merchant's onboarding progressOnboardingProgressResponse

POST/merchant/onboarding/progress/building

Step 4 -- record the first website build so it can be followed later

Operation: recordOnboardingBuild
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: OnboardingBuildRequest

Responses

200The saved progressOnboardingProgressResponse
400An answer that cannot be usedErrorResponse
409An earlier step is not done yet, or the store already existsErrorResponse

POST/merchant/onboarding/progress/business-type

Step 2 -- the merchant picks a different business type

Operation: chooseOnboardingBusinessType
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: OnboardingBusinessTypeRequest

Responses

200The saved progressOnboardingProgressResponse
400An answer that cannot be usedErrorResponse
409An earlier step is not done yet, or the store already existsErrorResponse

POST/merchant/onboarding/progress/complete

Create the store from the saved onboarding answers

Operation: completeOnboardingFromProgress
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: object

Responses

201The store that was created, or the one already createdobject
409A step is not done yetErrorResponse

POST/merchant/onboarding/progress/description

Step 1 -- save the merchant's own description and classify it

Operation: saveOnboardingDescription
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: OnboardingDescriptionRequest

Responses

200The saved progressOnboardingProgressResponse
400An answer that cannot be usedErrorResponse
409An earlier step is not done yet, or the store already existsErrorResponse

POST/merchant/onboarding/progress/details

Step 3 -- business name, location and (with booking on) booking address mode

Operation: saveOnboardingDetails
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: OnboardingDetailsRequest

Responses

200The saved progressOnboardingProgressResponse
400An answer that cannot be usedErrorResponse
409An earlier step is not done yet, or the store already existsErrorResponse

POST/merchant/onboarding/progress/features

Step 2 -- the switches as the merchant left them

Operation: saveOnboardingFeatures
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Request body

Required: OnboardingFeaturesRequest

Responses

200The saved progressOnboardingProgressResponse
400An answer that cannot be usedErrorResponse
409An earlier step is not done yet, or the store already existsErrorResponse

POST/merchant/password-reset/complete

Complete a merchant password reset

Operation: completeMerchantPasswordReset
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Request body

Required: PasswordResetCompleteRequest

Responses

204Merchant password reset completed
401Password reset token is invalid or expiredErrorResponse

POST/merchant/password-reset/request

Request a merchant password reset token

Operation: requestMerchantPasswordReset
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Request body

Required: PasswordResetRequest

Responses

202Password reset request acceptedPasswordResetRequestResponse
400Invalid password reset requestErrorResponse

POST/merchant/signup

Create a merchant account and session

Operation: signupMerchant
Audience: Merchant admin app and trusted integrations
Access: Public or provider verified
Idempotency: Not required by contract

Request body

Required: MerchantSignupRequest

Responses

201Merchant account and session createdMerchantSessionResponse
400Invalid signup requestErrorResponse

GET/merchant/stores

List stores available to the current merchant session

Operation: listMerchantStores
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Responses

200Store switcher options for the merchantStoreSwitcherResponse
401Missing or invalid merchant sessionErrorResponse

GET/merchant/stores/{storeId}/abandoned-checkouts

Carts left at checkout with an email (NOR-899), newest first

Operation: listAbandonedCheckouts
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The abandoned checkoutsobject

GET/merchant/stores/{storeId}/abandoned-checkouts/{cartId}

One abandoned cart, as it stood (NOR-899)

Operation: getAbandonedCheckout
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
cartIdpathrequiredstring

Responses

200The cart at the prices the shopper was offeredAbandonedCheckoutDetail

GET/merchant/stores/{storeId}/ai-providers

List this store's AI provider keys, masked

Operation: listAiProviderKeys
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Masked AI provider keys for the active tenantAiProviderKeysResponse
403Merchant role cannot view store settingsErrorResponse

PUT/merchant/stores/{storeId}/ai-providers/{provider}

Save or replace this store's API key for one AI provider

Operation: saveAiProviderKey
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredAiProviderId

Request body

Required: AiProviderKeyRequest

Responses

200Masked AI provider keys after the saveAiProviderKeysResponse
400The key, model, or address was rejectedErrorResponse
403Merchant role cannot update store settingsErrorResponse

DELETE/merchant/stores/{storeId}/ai-providers/{provider}

Remove this store's API key for one AI provider

Operation: deleteAiProviderKey
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredAiProviderId

Responses

200Masked AI provider keys after the removalAiProviderKeysResponse
400No key was saved for that providerErrorResponse
403Merchant role cannot update store settingsErrorResponse

POST/merchant/stores/{storeId}/ai-providers/{provider}/check

Send one small request through the key to confirm it works

Operation: checkAiProviderKey
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredAiProviderId

Responses

200The outcome of the check, plus the refreshed masked listAiProviderKeyCheckResponse
403Merchant role cannot update store settingsErrorResponse

GET/merchant/stores/{storeId}/audit-events

List append-only audit events for a store

Operation: listStoreAuditEvents
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
actorUserIdqueryoptionalstring
resourceTypequeryoptionalstring
resourceIdqueryoptionalstring
actionqueryoptionalstring
occurredFromqueryoptionalstring
occurredToqueryoptionalstring
limitqueryoptionalinteger

Responses

200Tenant-scoped audit event historyAuditEventListResponse
403Merchant role cannot view audit historyErrorResponse

GET/merchant/stores/{storeId}/bookings

Everything the Bookings page shows except appointments

Operation: getBookingsWorkspace
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200DoneBookingsWorkspace
400Not accepted, with the reason in plain wordsErrorResponse

GET/merchant/stores/{storeId}/bookings/appointments

Appointments, optionally within a range, for one person, or in one status

Operation: listAppointments
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Doneobject
400Not accepted, with the reason in plain wordsErrorResponse

POST/merchant/stores/{storeId}/bookings/appointments

Book an appointment

Operation: bookAppointment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201DoneAppointment
400Not accepted, with the reason in plain wordsErrorResponse

GET/merchant/stores/{storeId}/bookings/appointments/{appointmentId}

One appointment

Operation: getAppointment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
appointmentIdpathrequiredstring

Responses

200DoneAppointment
400Not accepted, with the reason in plain wordsErrorResponse

PATCH/merchant/stores/{storeId}/bookings/appointments/{appointmentId}

Reschedule, reassign, or change status, payment or notes

Operation: updateAppointment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
appointmentIdpathrequiredstring

Request body

Required: object

Responses

200DoneAppointment
400Not accepted, with the reason in plain wordsErrorResponse

POST/merchant/stores/{storeId}/bookings/appointments/{appointmentId}/on-the-way

Send the "On the way" message now

Operation: sendOnTheWay
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
appointmentIdpathrequiredstring

Responses

200Doneobject
400Not accepted, with the reason in plain wordsErrorResponse

PUT/merchant/stores/{storeId}/bookings/messages/{kind}

Save one message template

Operation: saveBookingMessage
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
kindpathrequiredstring

Request body

Required: object

Responses

200Done
400Not accepted, with the reason in plain wordsErrorResponse

PUT/merchant/stores/{storeId}/bookings/rules

Save the store's booking rules and time zone

Operation: saveBookingRules
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

200Done
400Not accepted, with the reason in plain wordsErrorResponse

POST/merchant/stores/{storeId}/bookings/services

Add a service

Operation: createBookingService
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201Doneobject
400Not accepted, with the reason in plain wordsErrorResponse

PATCH/merchant/stores/{storeId}/bookings/services/{serviceId}

Edit a service

Operation: updateBookingService
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
serviceIdpathrequiredstring

Request body

Required: object

Responses

200Doneobject
400Not accepted, with the reason in plain wordsErrorResponse

DELETE/merchant/stores/{storeId}/bookings/services/{serviceId}

Delete a never-booked service

Operation: deleteBookingService
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
serviceIdpathrequiredstring

Responses

204Done
400Not accepted, with the reason in plain wordsErrorResponse

POST/merchant/stores/{storeId}/bookings/services/{serviceId}/archive

Archive or restore a service

Operation: archiveBookingService
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
serviceIdpathrequiredstring

Request body

Required: object

Responses

200Done
400Not accepted, with the reason in plain wordsErrorResponse

PUT/merchant/stores/{storeId}/bookings/staff/{staffUserId}/availability

Replace one person's working windows

Operation: saveStaffAvailability
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
staffUserIdpathrequiredstring

Request body

Required: object

Responses

200Done
400Not accepted, with the reason in plain wordsErrorResponse

POST/merchant/stores/{storeId}/bookings/staff/{staffUserId}/time-off

Add time off for one person

Operation: addStaffTimeOff
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
staffUserIdpathrequiredstring

Request body

Required: object

Responses

201Doneobject
400Not accepted, with the reason in plain wordsErrorResponse

DELETE/merchant/stores/{storeId}/bookings/time-off/{timeOffId}

Remove time off

Operation: removeStaffTimeOff
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
timeOffIdpathrequiredstring

Responses

204Done
400Not accepted, with the reason in plain wordsErrorResponse

GET/merchant/stores/{storeId}/business-profile

Get the store's business profile

Operation: getStoreBusinessProfile
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Store business profileStoreBusinessProfile

PUT/merchant/stores/{storeId}/business-profile

Save part of the store's business profile

Operation: saveStoreBusinessProfile
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: StoreBusinessProfileRequest

Responses

200Business profile savedStoreBusinessProfile
400A value that cannot be storedErrorResponse

POST/merchant/stores/{storeId}/business-profile/complete

Check every field and mark the business profile complete

Operation: completeStoreBusinessProfile
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: StoreBusinessProfileRequest

Responses

200Business profile completeStoreBusinessProfile
400One or more fields need another lookErrorResponse

GET/merchant/stores/{storeId}/collections

List tenant-scoped product collections

Operation: listMerchantCollections
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Tenant-scoped admin collectionsAdminCollectionListResponse

POST/merchant/stores/{storeId}/collections

Create a manual or rule-based product collection

Operation: createMerchantCollection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: CollectionCreateRequest

Responses

201Collection created and audit event writtenCollectionMutationResponse

GET/merchant/stores/{storeId}/collections/{collectionId}

One collection, with the menus that link to it (NOR-870 / NOR-877)

Operation: getMerchantCollection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Responses

200The collection
404Not this store's collectionErrorResponse

PATCH/merchant/stores/{storeId}/collections/{collectionId}

Update collection metadata, publishing state, sort order, or rules

Operation: updateMerchantCollection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Request body

Required: CollectionUpdateRequest

Responses

200Collection updated and audit event writtenCollectionMutationResponse

DELETE/merchant/stores/{storeId}/collections/{collectionId}

Delete a collection; menu items pointing at it go with it

Operation: deleteMerchantCollection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Responses

200Deleted, with the menus it was removed fromobject

POST/merchant/stores/{storeId}/collections/{collectionId}/archive

Archive a collection and remove it from public collection responses

Operation: archiveMerchantCollection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Responses

200Collection archived and audit event writtenCollectionMutationResponse

GET/merchant/stores/{storeId}/collections/{collectionId}/filters

A collection's own filters, or null for the store's (NOR-939)

Operation: getCollectionFilterSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Responses

200The filtersobject

PUT/merchant/stores/{storeId}/collections/{collectionId}/filters

A collection's own filters, replacing the store's for it alone; facets null goes back (NOR-939)

Operation: saveCollectionFilterSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Request body

Required: object

Responses

200The filtersobject

PUT/merchant/stores/{storeId}/collections/{collectionId}/products

Replace manual collection product membership and order

Operation: replaceManualCollectionProducts
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Request body

Required: CollectionProductsReplaceRequest

Responses

200Collection membership replaced and audit event writtenCollectionRefreshResponse

POST/merchant/stores/{storeId}/collections/{collectionId}/promote-filtered-view

Turn a filtered view of this collection into a draft collection of its own (NOR-940)

Operation: promoteFilteredView
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Request body

Required: object

Responses

201The filtersobject

POST/merchant/stores/{storeId}/collections/{collectionId}/refresh

Re-evaluate a rule-based collection and refresh membership

Operation: refreshRuleBasedCollection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
collectionIdpathrequiredstring

Responses

200Rule collection refreshed and audit event written when membership changedCollectionRefreshResponse

POST/merchant/stores/{storeId}/collections/preview

Preview why products match or miss a rule-based collection

Operation: previewCollectionRules
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: CollectionRuleSet

Responses

200Product-level rule preview resultsCollectionRulePreviewResponse

POST/merchant/stores/{storeId}/collections/refresh

Re-run every smart collection against the catalogue, once, at the end of a bulk edit

Operation: refreshSmartCollections
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200How many smart collections were re-run, and how many changedobject
403The signed-in user may not change the catalogueErrorResponse

GET/merchant/stores/{storeId}/content

List CMS pages and blog posts for merchant management

Operation: listMerchantContentEntries
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
typequeryoptionalContentEntryType
statusqueryoptionalContentEntryStatus
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Merchant content entriesContentEntryListResponse

POST/merchant/stores/{storeId}/content

Create a CMS page or blog post

Operation: createContentEntry
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: ContentEntryRequest

Responses

201Content entry createdContentEntryMutationResponse

GET/merchant/stores/{storeId}/content-comments

List content comments for moderation

Operation: listMerchantContentComments
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
entryIdqueryoptionalstring
statusqueryoptionalContentCommentStatus
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Content commentsContentCommentListResponse

POST/merchant/stores/{storeId}/content-comments/{commentId}/moderate

Approve, reject, hide, or return a content comment to pending

Operation: moderateContentComment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
commentIdpathrequiredstring

Request body

Required: ContentCommentModerationRequest

Responses

200Content comment moderatedContentCommentMutationResponse

PATCH/merchant/stores/{storeId}/content/{entryId}

Update a CMS page or blog post

Operation: updateContentEntry
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
entryIdpathrequiredstring

Request body

Required: ContentEntryRequest

Responses

200Content entry updatedContentEntryMutationResponse

GET/merchant/stores/{storeId}/customer-segments

List saved customer segments

Operation: listCustomerSegments
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
statusqueryoptionalCustomerSegmentStatus
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Customer segment listCustomerSegmentListResponse

POST/merchant/stores/{storeId}/customer-segments

Create a customer segment

Operation: createCustomerSegment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: CustomerSegmentRequest

Responses

201Customer segment createdCustomerSegment

PATCH/merchant/stores/{storeId}/customer-segments/{segmentId}

Update a customer segment

Operation: updateCustomerSegment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
segmentIdpathrequiredstring

Request body

Required: CustomerSegmentPatchRequest

Responses

200Customer segment updatedCustomerSegment

DELETE/merchant/stores/{storeId}/customer-segments/{segmentId}

Delete a customer segment

Operation: deleteCustomerSegment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
segmentIdpathrequiredstring

Responses

204Customer segment deleted

GET/merchant/stores/{storeId}/customer-segments/{segmentId}/customers

List customers matching a saved segment

Operation: listCustomerSegmentMatches
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
segmentIdpathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Matching customers with reasonsCustomerSegmentPreviewResponse

POST/merchant/stores/{storeId}/customer-segments/preview

Preview an unsaved customer segment definition

Operation: previewCustomerSegment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: CustomerSegmentPreviewRequest

Responses

200Segment preview with customer match reasonsCustomerSegmentPreviewResponse

POST/merchant/stores/{storeId}/customers/{customerId}/loyalty-adjustments

Manually adjust a customer loyalty balance with an audited ledger entry

Operation: adjustCustomerLoyaltyPoints
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
customerIdpathrequiredstring

Request body

Required: LoyaltyAdjustmentRequest

Responses

200Loyalty account adjustedLoyaltyMutationResponse

POST/merchant/stores/{storeId}/customers/{customerId}/loyalty-bonuses

Issue an idempotent configured loyalty bonus

Operation: issueLoyaltyBonus
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
customerIdpathrequiredstring

Request body

Required: LoyaltyBonusRequest

Responses

200Loyalty bonus issued or idempotently returnedLoyaltyMutationResponse

GET/merchant/stores/{storeId}/discounts

List discounts and promotions

Operation: listDiscounts
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
statusqueryoptionalDiscountStatus
triggerqueryoptionalDiscountTrigger
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Discount listDiscountListResponse

POST/merchant/stores/{storeId}/discounts

Create a discount or automatic promotion

Operation: createDiscount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: DiscountRequest

Responses

201Discount createdDiscount

GET/merchant/stores/{storeId}/discounts/{discountId}

One discount, with its status worked out now

Operation: getDiscount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
discountIdpathrequiredstring

Responses

200The discountDiscount

PATCH/merchant/stores/{storeId}/discounts/{discountId}

Update a discount or automatic promotion

Operation: updateDiscount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
discountIdpathrequiredstring

Request body

Required: DiscountPatchRequest

Responses

200Discount updatedDiscount

DELETE/merchant/stores/{storeId}/discounts/{discountId}

Delete a discount or automatic promotion

Operation: deleteDiscount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
discountIdpathrequiredstring

Responses

204Discount deleted
409NOR-914. The discount has been used, so it can't be deleted; disable it instead. Orders that used it still name it.ErrorResponse

GET/merchant/stores/{storeId}/domain-setup

The store's own domain, step by step (NOR-842 / NOR-843)

Operation: getCustomDomainSetup
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Whether connecting is open here, and the domain in progress or liveCustomDomainSetup

POST/merchant/stores/{storeId}/domain-setup

Connect a domain the merchant owns

Operation: connectCustomDomain
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201Connected; the records to add come back with itCustomDomainSetup
409Another store has it, this store already has one, or connecting isn't openErrorResponse

POST/merchant/stores/{storeId}/domain-setup/{domainId}/check

Check ownership, the certificate and where each spelling points now

Operation: checkCustomDomain
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
domainIdpathrequiredstring

Responses

200The domain after the checkCustomDomainSetup

POST/merchant/stores/{storeId}/domain-setup/{domainId}/nameservers

Read every record on the domain for a nameserver move (NOR-843)

Operation: prepareNameserverMove
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
domainIdpathrequiredstring

Responses

200The records to carry, old beside newCustomDomainSetup

POST/merchant/stores/{storeId}/domain-setup/{domainId}/nameservers/confirm

Carry every record into ReTale's DNS and return the nameservers to switch to

Operation: confirmNameserverMove
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
domainIdpathrequiredstring

Request body

Required: object

Responses

200Carried; the nameservers are in `domain.nameserverPlan.nameservers`CustomDomainSetup
409The move would drop mail, or wasn't confirmedErrorResponse

POST/merchant/stores/{storeId}/domain-setup/{domainId}/ttl

Record that the merchant lowered their TTL ahead of the switch (NOR-845)

Operation: confirmCustomDomainTtl
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
domainIdpathrequiredstring

Request body

Required: object

Responses

200RecordedCustomDomainSetup

POST/merchant/stores/{storeId}/domain-setup/platform-address/check

Look at the store's platform address again now (NOR-1024)

Operation: checkPlatformAddress
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The setup, with the platform address just checkedCustomDomainSetup

POST/merchant/stores/{storeId}/domains/{domainId}/activate

Switch the store onto its custom domain -- the same as Go live (NOR-844)

Operation: activateCustomDomain
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
domainIdpathrequiredstring

Responses

200The store is live on its domainGoLiveView
409A check still failsErrorResponse

POST/merchant/stores/{storeId}/domains/{domainId}/disable

Disable an active custom domain

Operation: disableCustomDomain
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
domainIdpathrequiredstring

Responses

200Custom domain disabledDomainLifecycleResponse

POST/merchant/stores/{storeId}/domains/{domainId}/verify

Check a custom domain's ownership record, certificate and live DNS (NOR-842)

Operation: verifyCustomDomain
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
domainIdpathrequiredstring

Responses

200The domain as it stands after the checkCustomDomainSetup

POST/merchant/stores/{storeId}/domains/custom

Create a custom-domain verification intent

Operation: createCustomDomainIntent
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: CustomDomainIntentRequest

Responses

201Custom-domain verification intent createdCustomDomainIntentResponse
409Custom domain is unavailableErrorResponse

POST/merchant/stores/{storeId}/domains/platform-subdomain

Reserve a platform subdomain for a store

Operation: reservePlatformSubdomain
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: PlatformSubdomainRequest

Responses

201Platform subdomain reservedPlatformSubdomainResponse
409Platform subdomain is unavailableErrorResponse

GET/merchant/stores/{storeId}/draft-orders

Every draft order, converted ones included, newest first (NOR-921)

Operation: listDraftOrders
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The draftsobject

POST/merchant/stores/{storeId}/draft-orders

Start a draft -- empty, for a customer, or copied from an order (NOR-917 / NOR-922)

Operation: createDraftOrder
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201The draft as it now standsDraftOrderView

GET/merchant/stores/{storeId}/draft-orders/{draftId}

One draft, with its invoice link when one is out

Operation: getDraftOrder
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Responses

200The draft as it now standsDraftOrderView

PATCH/merchant/stores/{storeId}/draft-orders/{draftId}

The address, shipping, tax, PO number and note (NOR-918)

Operation: updateDraftOrderDetails
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Request body

Required: object

Responses

200The draft as it now standsDraftOrderView

DELETE/merchant/stores/{storeId}/draft-orders/{draftId}

Delete a draft that hasn't converted -- it never had an order number to give back

Operation: deleteDraftOrder
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Responses

200Deletedobject

POST/merchant/stores/{storeId}/draft-orders/{draftId}/convert

Convert to an order, once (NOR-920)

Operation: convertDraftOrder
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Request body

Required: object

Responses

200The draft as it now standsDraftOrderView

PUT/merchant/stores/{storeId}/draft-orders/{draftId}/customer

Who the order is for, or nobody yet (a null customerId)

Operation: setDraftOrderCustomer
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Request body

Required: object

Responses

200The draft as it now standsDraftOrderView

POST/merchant/stores/{storeId}/draft-orders/{draftId}/discounts

A discount code, judged as checkout judges one, or the merchant's own with a reason

Operation: addDraftOrderDiscount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Request body

Required: object

Responses

200The draft as it now standsDraftOrderView

DELETE/merchant/stores/{storeId}/draft-orders/{draftId}/discounts/{index}

Take a discount off

Operation: removeDraftOrderDiscount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring
indexpathrequiredinteger

Responses

200The draft as it now standsDraftOrderView

POST/merchant/stores/{storeId}/draft-orders/{draftId}/invoice

The invoice link to copy and send (NOR-919)

Operation: issueDraftInvoice
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Responses

200The draft, with its linkDraftOrderView

POST/merchant/stores/{storeId}/draft-orders/{draftId}/lines

Add a product at today's price (`variantId`) or a custom line (`custom`)

Operation: addDraftOrderLine
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring

Request body

Required: object

Responses

200The draft as it now standsDraftOrderView

PATCH/merchant/stores/{storeId}/draft-orders/{draftId}/lines/{lineId}

Change a line's quantity or price (NOR-918)

Operation: updateDraftOrderLine
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring
lineIdpathrequiredstring

Request body

Required: object

Responses

200The draft as it now standsDraftOrderView

DELETE/merchant/stores/{storeId}/draft-orders/{draftId}/lines/{lineId}

Remove a line

Operation: removeDraftOrderLine
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
draftIdpathrequiredstring
lineIdpathrequiredstring

Responses

200The draft as it now standsDraftOrderView

GET/merchant/stores/{storeId}/draft-orders/matches

The editor's pickers -- products by name or SKU, customers by name or email (NOR-918)

Operation: findDraftOrderMatches
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productsqueryoptionalstring
customersqueryoptionalstring

Responses

200What matchedobject

PATCH/merchant/stores/{storeId}/fulfillments/{fulfillmentId}

Update carrier, tracking, and shipment status

Operation: updateMerchantFulfillmentTracking
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
fulfillmentIdpathrequiredstring

Request body

Required: FulfillmentTrackingUpdateRequest

Responses

200Fulfillment tracking updatedFulfillmentMutationResponse

POST/merchant/stores/{storeId}/fulfillments/{fulfillmentId}/cancel

Cancel an uncompleted fulfillment without mutating payment or inventory records

Operation: cancelMerchantFulfillment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
fulfillmentIdpathrequiredstring

Request body

Optional: FulfillmentCancelRequest

Responses

200Fulfillment canceled and rollup recalculatedFulfillmentMutationResponse

POST/merchant/stores/{storeId}/fulfillments/{fulfillmentId}/complete

Mark a fulfillment delivered

Operation: completeMerchantFulfillment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
fulfillmentIdpathrequiredstring

Responses

200Fulfillment completedFulfillmentMutationResponse

GET/merchant/stores/{storeId}/go-live

The go-live checks, run now (NOR-844)

Operation: getGoLive
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Every check, whether the store can go live, and the launch if it hasGoLiveView

POST/merchant/stores/{storeId}/go-live

Switch the store onto its own domain

Operation: goLive
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200LiveGoLiveView
409A check still failsErrorResponse

POST/merchant/stores/{storeId}/go-live/acknowledgements

Go ahead without fixing a soft check; recorded with who, when and how many problems

Operation: acknowledgeGoLiveCheck
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

200AcknowledgedGoLiveView

POST/merchant/stores/{storeId}/integration-requests

Ask for an app ReTale doesn't have (NOR-906). Kept exactly as typed.

Operation: requestIntegration
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201Logged. Nothing is promised.object

GET/merchant/stores/{storeId}/integrations

The apps connected to this store (NOR-904) -- several at once

Operation: listStoreIntegrations
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Every connection, with how it is doing. No credential is ever returned.object

GET/merchant/stores/{storeId}/integrations/{integrationId}/deliveries

What was sent to one app, and what came back (NOR-903)

Operation: getIntegrationSendLog
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
integrationIdpathrequiredstring

Responses

200The most recent deliveries, newest first, with every attemptobject

POST/merchant/stores/{storeId}/inventory/adjustments

Apply an audited inventory ledger adjustment

Operation: adjustInventory
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: InventoryAdjustmentRequest

Responses

201Inventory adjustment applied with ledger and audit eventsInventoryAdjustmentResponse

GET/merchant/stores/{storeId}/inventory/alerts

List inventory alerts for a store

Operation: listInventoryAlerts
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
statusqueryoptionalInventoryAlertStatus

Responses

200Inventory alertsobject

POST/merchant/stores/{storeId}/inventory/alerts/{alertId}/acknowledge

Acknowledge an open inventory alert and write an audit event

Operation: acknowledgeInventoryAlert
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
alertIdpathrequiredstring

Responses

200Inventory alert acknowledgedInventoryAlert

GET/merchant/stores/{storeId}/inventory/locations

The store's active stock locations, default first

Operation: listMerchantInventoryLocations
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Locationsobject

POST/merchant/stores/{storeId}/inventory/locations

Create an inventory location for a store

Operation: createInventoryLocation
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: InventoryLocationCreateRequest

Responses

201Inventory location createdInventoryLocation
403Merchant role cannot write inventory dataErrorResponse

PUT/merchant/stores/{storeId}/inventory/policy

Configure default low-stock and out-of-stock inventory policy for a store

Operation: configureStoreInventoryPolicy
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: InventoryPolicyRequest

Responses

200Store inventory policy updated and auditedInventoryPolicy

POST/merchant/stores/{storeId}/inventory/reservations

Create a concurrency-safe checkout inventory reservation

Operation: reserveInventory
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: InventoryReservationRequest

Responses

201Inventory reserved for checkoutInventoryReservation
409Requested inventory is unavailableErrorResponse

POST/merchant/stores/{storeId}/inventory/reservations/{reservationId}/commit

Commit an active reservation as sold inventory

Operation: commitInventoryReservation
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
reservationIdpathrequiredstring

Request body

Optional: object

Responses

200Reservation committedInventoryReservation

POST/merchant/stores/{storeId}/inventory/reservations/{reservationId}/release

Release an active inventory reservation back to available stock

Operation: releaseInventoryReservation
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
reservationIdpathrequiredstring

Responses

200Reservation releasedInventoryReservation

POST/merchant/stores/{storeId}/inventory/reservations/expired

Release all expired active reservations for a store

Operation: releaseExpiredInventoryReservations
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Expired reservations releasedobject

POST/merchant/stores/{storeId}/inventory/returns

Return sold inventory to stock through ledger entries

Operation: returnInventoryToStock
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: InventoryReturnRequest

Responses

201Inventory returned to stockobject

PUT/merchant/stores/{storeId}/inventory/variants/{variantId}/policy

Configure variant-specific inventory thresholds and out-of-stock policy

Operation: configureVariantInventoryPolicy
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
variantIdpathrequiredstring

Request body

Required: InventoryPolicyRequest

Responses

200Variant inventory policy updated and auditedInventoryPolicy

POST/merchant/stores/{storeId}/invitations

Invite a staff member to a store

Operation: inviteStoreStaff
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: InviteStaffRequest

Responses

201Staff invitation createdStaffInvitationResponse
403Merchant role cannot invite staffErrorResponse

PUT/merchant/stores/{storeId}/lifecycle-automations/{type}

Update a lifecycle automation template and settings

Operation: updateLifecycleAutomationSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
typepathrequiredLifecycleAutomationType

Request body

Required: LifecycleAutomationSettingsRequest

Responses

200Automation settings updatedLifecycleAutomationSettings

POST/merchant/stores/{storeId}/lifecycle-automations/{type}/preview

Preview a rendered lifecycle automation template

Operation: previewLifecycleAutomationTemplate
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
typepathrequiredLifecycleAutomationType

Request body

Required: LifecycleAutomationPreviewRequest

Responses

200Rendered template previewLifecycleAutomationTemplate

GET/merchant/stores/{storeId}/lifecycle-automations/deliveries

List lifecycle automation delivery records

Operation: listLifecycleAutomationDeliveries
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
typequeryoptionalLifecycleAutomationType
statusqueryoptionalLifecycleAutomationDeliveryStatus
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Automation delivery recordsLifecycleAutomationDeliveryListResponse

GET/merchant/stores/{storeId}/loyalty-settings

Get loyalty earning, redemption, tier, expiration, and refund settings

Operation: getLoyaltyProgramSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Loyalty program settingsLoyaltyProgramSettings

PATCH/merchant/stores/{storeId}/loyalty-settings

Update loyalty earning, redemption, tier, expiration, and refund settings

Operation: updateLoyaltyProgramSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: LoyaltyProgramSettingsRequest

Responses

200Loyalty program settings updatedLoyaltyProgramSettings

GET/merchant/stores/{storeId}/marketing/campaigns

List marketing campaigns

Operation: listMarketingCampaigns
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
statusqueryoptionalMarketingCampaignStatus
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Marketing campaignsMarketingCampaignListResponse

POST/merchant/stores/{storeId}/marketing/campaigns

Create a draft or scheduled marketing campaign

Operation: createMarketingCampaign
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: MarketingCampaignRequest

Responses

201Marketing campaign createdMarketingCampaign

PATCH/merchant/stores/{storeId}/marketing/campaigns/{campaignId}

Update a draft or scheduled marketing campaign

Operation: updateMarketingCampaign
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
campaignIdpathrequiredstring

Request body

Required: MarketingCampaignRequest

Responses

200Marketing campaign updatedMarketingCampaign

POST/merchant/stores/{storeId}/marketing/campaigns/{campaignId}/send

Send a campaign through the configured delivery provider

Operation: sendMarketingCampaign
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
campaignIdpathrequiredstring

Responses

200Campaign send resultsMarketingCampaignSendResponse

POST/merchant/stores/{storeId}/marketing/campaigns/send-due

Send scheduled campaigns that are due for the store

Operation: sendDueMarketingCampaigns
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Due campaign send resultsMarketingCampaignSendResponse[]

PUT/merchant/stores/{storeId}/marketing/consents

Set email or SMS marketing consent for a customer

Operation: setMarketingConsent
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: MarketingConsentRequest

Responses

200Consent updatedMarketingConsentMutationResponse

POST/merchant/stores/{storeId}/marketing/opt-outs

Record an unsubscribe, opt-out keyword, or suppression event

Operation: recordMarketingOptOut
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: MarketingOptOutRequest

Responses

200Suppression recordedMarketingOptOutResponse

GET/merchant/stores/{storeId}/media/upload-settings

Whether product photo uploads are set up, and the size and types they accept

Operation: getMerchantMediaUploadSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Upload settingsMediaUploadSettings

POST/merchant/stores/{storeId}/media/uploads

A presigned form for uploading one product photo straight to storage

Operation: createMerchantMediaUpload
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: MediaUploadRequest

Responses

201The upload formMediaUploadTicket
400Not an accepted photo type, empty, or over the size limitErrorResponse
409Photo uploads are not set up for this deploymentErrorResponse

PATCH/merchant/stores/{storeId}/members/{userId}

Change a store staff member role

Operation: changeStoreStaffRole
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
userIdpathrequiredstring

Request body

Required: ChangeStaffRoleRequest

Responses

204Staff member role changed
403Merchant role cannot change this staff memberErrorResponse

DELETE/merchant/stores/{storeId}/members/{userId}

Remove a staff member from a store

Operation: removeStoreStaff
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
userIdpathrequiredstring

Responses

204Staff member removed
403Merchant role cannot remove this staff memberErrorResponse

PUT/merchant/stores/{storeId}/membership-access-rules

Upsert member-only product or collection access rule

Operation: upsertMembershipAccessRule
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: MembershipAccessRuleRequest

Responses

200Membership access ruleMembershipAccessRule

POST/merchant/stores/{storeId}/membership-billing-subscriptions/{membershipBillingSubscriptionId}/cancel

Cancel a recurring membership subscription through the configured gateway

Operation: cancelMembershipBillingSubscription
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
membershipBillingSubscriptionIdpathrequiredstring

Request body

Optional: MembershipSubscriptionCancelRequest

Responses

200Subscription cancellation recordedMembershipBillingSubscriptionResponse

POST/merchant/stores/{storeId}/membership-billing-subscriptions/{membershipBillingSubscriptionId}/retry

Retry a failed recurring membership payment

Operation: retryMembershipBillingPayment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
membershipBillingSubscriptionIdpathrequiredstring

Request body

Optional: MembershipBillingRetryRequest

Responses

200Retry result recorded and dunning state updatedMembershipBillingSubscriptionResponse

GET/merchant/stores/{storeId}/membership-plans

List membership plans

Operation: listMembershipPlans
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
statusqueryoptionalMembershipPlanStatus
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Membership plansMembershipPlanListResponse

POST/merchant/stores/{storeId}/membership-plans

Create a membership plan

Operation: createMembershipPlan
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: MembershipPlanRequest

Responses

201Membership plan createdMembershipPlan

PATCH/merchant/stores/{storeId}/membership-plans/{membershipPlanId}

Update a membership plan

Operation: updateMembershipPlan
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
membershipPlanIdpathrequiredstring

Request body

Required: MembershipPlanPatchRequest

Responses

200Membership plan updatedMembershipPlan

POST/merchant/stores/{storeId}/membership-plans/{membershipPlanId}/archive

Archive a membership plan

Operation: archiveMembershipPlan
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
membershipPlanIdpathrequiredstring

Responses

200Membership plan archivedMembershipPlan

GET/merchant/stores/{storeId}/menus

The store's menus (NOR-877)

Operation: listStoreMenus
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Main menu and Footer menu first, then the rest by nameobject

POST/merchant/stores/{storeId}/menus

Add a menu

Operation: createStoreMenu
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201The new, empty menuMenuDetail

GET/merchant/stores/{storeId}/menus/{menuId}

One menu and its items, plus a rebuilt website's proposal if one is waiting

Operation: getStoreMenu
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
menuIdpathrequiredstring

Responses

200The menuMenuDetail

PUT/merchant/stores/{storeId}/menus/{menuId}

Rename a menu and/or replace its items (marks it as edited, NOR-878)

Operation: saveStoreMenu
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
menuIdpathrequiredstring

Request body

Required: object

Responses

200The saved menuMenuDetail
400An item points at nothing in this store, nests too deep, or has an address that isn't oneErrorResponse

DELETE/merchant/stores/{storeId}/menus/{menuId}

Delete a menu the merchant made (Main menu and Footer menu can't be)

Operation: deleteStoreMenu
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
menuIdpathrequiredstring

Responses

200Deletedobject

POST/merchant/stores/{storeId}/menus/{menuId}/proposal/accept

Take the rebuilt website's menu in place of this one

Operation: acceptMenuProposal
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
menuIdpathrequiredstring

Responses

200The menu, now the proposalMenuDetail

POST/merchant/stores/{storeId}/menus/{menuId}/proposal/dismiss

Keep this menu and drop the rebuilt website's proposal

Operation: dismissMenuProposal
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
menuIdpathrequiredstring

Responses

200The menu, unchangedMenuDetail

GET/merchant/stores/{storeId}/menus/link-check

Menu items that open nothing on the website, and published collections no menu links to (NOR-879)

Operation: getMenuLinkReport
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The report, menu by menuobject

GET/merchant/stores/{storeId}/menus/targets

What a menu item can point at -- the store's collections, products and pages

Operation: listMenuTargetChoices
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Choices for the editor's pickersobject

GET/merchant/stores/{storeId}/metafields

The store's custom product fields (NOR-936), with how many products use each

Operation: listMetafieldDefinitions
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The definitionsobject

POST/merchant/stores/{storeId}/metafields

Add a custom product field (NOR-936)

Operation: createMetafieldDefinition
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: MetafieldDefinitionInput

Responses

201Created; the key is derived from the nameobject

PATCH/merchant/stores/{storeId}/metafields/{definitionId}

Rename, re-list, hide or show a custom field. Never rewrites a value.

Operation: updateMetafieldDefinition
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
definitionIdpathrequiredstring

Request body

Required

Responses

200Savedobject
409The change would rewrite or orphan values products holdErrorResponse

DELETE/merchant/stores/{storeId}/metafields/{definitionId}

Delete a custom field no product uses. One with values is hidden instead (409).

Operation: deleteMetafieldDefinition
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
definitionIdpathrequiredstring

Responses

200Deletedobject

POST/merchant/stores/{storeId}/modules

Enable additional vertical modules on an already-onboarded store

Operation: enableVerticalModules
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: EnableVerticalModulesRequest

Responses

200Updated enabled modules and generator contextEnableVerticalModulesResponse
403Merchant role cannot enable modulesErrorResponse

GET/merchant/stores/{storeId}/orders

List tenant-scoped orders for merchant administration

Operation: listMerchantOrders
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
statusqueryoptionalOrderStatus
customerIdqueryoptionalstring
paymentProviderqueryoptionalstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Tenant-scoped admin orders, each with its delivery, label and return statusAdminOrderListResponse

GET/merchant/stores/{storeId}/orders/{orderId}

Get an order detail with immutable lines and timeline

Operation: getMerchantOrder
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Responses

200Order detailOrder

PATCH/merchant/stores/{storeId}/orders/{orderId}

Transition order status and append audit and timeline entries

Operation: transitionMerchantOrderStatus
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: OrderStatusTransitionRequest

Responses

200Order status changedOrderMutationResponse
409Invalid status transitionErrorResponse

GET/merchant/stores/{storeId}/orders/{orderId}/edit-locks

What the order page can change now, and why not (NOR-892)

Operation: getMerchantOrderEditLocks
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Responses

200The locksobject

PUT/merchant/stores/{storeId}/orders/{orderId}/email

Correct the order's contact email; always editable, recorded in its history (NOR-892)

Operation: updateMerchantOrderEmail
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: object

Responses

200Saved; changed is false when the email was already that oneobject
400Not an email addressErrorResponse

GET/merchant/stores/{storeId}/orders/{orderId}/fulfillments

One order's shipments, cancelled ones included

Operation: listMerchantOrderFulfillments
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Responses

200The order's shipmentsobject
404Order not found for this storeErrorResponse

POST/merchant/stores/{storeId}/orders/{orderId}/fulfillments

Create a partial or full order fulfillment

Operation: createMerchantOrderFulfillment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: FulfillmentCreateRequest

Responses

201Fulfillment created and order fulfillment rollup updatedFulfillmentMutationResponse
409Invalid fulfillment allocation or order stateErrorResponse

POST/merchant/stores/{storeId}/orders/{orderId}/notes

Add an internal order note and append audit and timeline entries

Operation: addMerchantOrderNote
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: OrderNoteRequest

Responses

201Order note addedOrderMutationResponse

GET/merchant/stores/{storeId}/orders/{orderId}/payment

An order's card payment, as the provider that took it recorded it

Operation: getMerchantOrderPayment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Responses

200The order's paymentobject

POST/merchant/stores/{storeId}/orders/{orderId}/payment-capture

Charge a card that was only held at checkout

Operation: captureMerchantOrderPayment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Responses

200Capturedobject
400Not capturableErrorResponse

POST/merchant/stores/{storeId}/orders/{orderId}/payment-refunds

Refund an order through the provider that took its payment

Operation: refundMerchantOrderPayment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: object

Responses

200Refund sentobject
400Not refundable as askedErrorResponse

POST/merchant/stores/{storeId}/orders/{orderId}/refunds

Record a payment-gateway refund result

Operation: recordMerchantRefund
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: RefundCreateRequest

Responses

201Refund result recordedRefundMutationResponse

POST/merchant/stores/{storeId}/orders/{orderId}/returns

Create a return request for order lines

Operation: createMerchantReturnRequest
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: ReturnRequestCreateRequest

Responses

201Return requestedReturnRequestMutationResponse

POST/merchant/stores/{storeId}/orders/{orderId}/tags

Add tags to an order (additive; existing tags are kept) and append an audit entry

Operation: addMerchantOrderTags
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: OrderTagsRequest

Responses

200The order with its tags in metadata.tagsOrder
400No usable tag, a tag over 40 characters, or more than 20 tags on the orderErrorResponse

PUT/merchant/stores/{storeId}/orders/{orderId}/tags

Replace an order's tags, recording what was added and removed in its history (NOR-892)

Operation: replaceMerchantOrderTags
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
orderIdpathrequiredstring

Request body

Required: object

Responses

200The order's tags nowobject
400A tag over 40 characters, or more than 20 tagsErrorResponse

GET/merchant/stores/{storeId}/pages

The website's pages that hold sections (NOR-967)

Operation: listStorePages
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The page, after the changeStorePageList

GET/merchant/stores/{storeId}/pages/{pageHandle}

One page's sections, with a rebuild's proposals

Operation: getStorePage
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring

Responses

200The page, after the changeStorePageDetail

PUT/merchant/stores/{storeId}/pages/{pageHandle}/order

Move sections -- a change of positions, never a rebuild

Operation: reorderPageSections
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring

Request body

Required: object

Responses

200The page, after the changeStorePageDetail

POST/merchant/stores/{storeId}/pages/{pageHandle}/proposal/accept

Take the rebuilt website's arrangement of this page (NOR-968)

Operation: acceptPageProposal
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring

Responses

200The page, after the changeStorePageDetail

POST/merchant/stores/{storeId}/pages/{pageHandle}/proposal/dismiss

Keep this page's arrangement and drop the rebuild's

Operation: dismissPageProposal
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring

Responses

200The page, after the changeStorePageDetail

POST/merchant/stores/{storeId}/pages/{pageHandle}/sections

Add a section; its settings are checked against its type's fields

Operation: addPageSection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring

Request body

Required: object

Responses

201The page, after the changeStorePageWriteResult

PUT/merchant/stores/{storeId}/pages/{pageHandle}/sections/{sectionId}

Change a section's settings; the first change makes it the merchant's

Operation: updatePageSection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring
sectionIdpathrequiredstring

Request body

Required: object

Responses

200The page, after the changeStorePageWriteResult

DELETE/merchant/stores/{storeId}/pages/{pageHandle}/sections/{sectionId}

Take a section off the page (the header and footer can only be hidden)

Operation: deletePageSection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring
sectionIdpathrequiredstring

Responses

200The page, after the changeStorePageDeleteResult

POST/merchant/stores/{storeId}/pages/{pageHandle}/sections/{sectionId}/move

Move a section up or down one place

Operation: movePageSection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring
sectionIdpathrequiredstring

Request body

Required: object

Responses

200The page, after the changeStorePageDetail

POST/merchant/stores/{storeId}/pages/{pageHandle}/sections/{sectionId}/proposal/accept

Take the rebuild's version of a section the merchant changed

Operation: acceptPageSectionProposal
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring
sectionIdpathrequiredstring

Responses

200The page, after the changeStorePageDetail

POST/merchant/stores/{storeId}/pages/{pageHandle}/sections/{sectionId}/proposal/dismiss

Keep the merchant's section and drop the rebuild's version

Operation: dismissPageSectionProposal
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring
sectionIdpathrequiredstring

Responses

200The page, after the changeStorePageDetail

POST/merchant/stores/{storeId}/pages/{pageHandle}/sections/{sectionId}/restore

Put a section removed this session back where it was (NOR-975)

Operation: restorePageSection
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring
sectionIdpathrequiredstring

Responses

200The page, after the changeStorePageDetail

PUT/merchant/stores/{storeId}/pages/{pageHandle}/sections/{sectionId}/visibility

Show or hide a section; hiding keeps its settings

Operation: setPageSectionVisibility
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
pageHandlepathrequiredstring
sectionIdpathrequiredstring

Request body

Required: object

Responses

200The page, after the changeStorePageDetail

GET/merchant/stores/{storeId}/pages/choices

What a section can point at -- collections, products, pages, photos and menus

Operation: listSectionChoices
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The page, after the changeSectionChoices

GET/merchant/stores/{storeId}/payment-gateway-settings

Get store payment gateway settings

Operation: getPaymentGatewaySettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Store payment gateway settingsStorePaymentGatewaySettings

PATCH/merchant/stores/{storeId}/payment-gateway-settings

Update store payment gateway settings

Operation: updatePaymentGatewaySettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: StorePaymentGatewaySettingsRequest

Responses

200Store payment gateway settings updatedStorePaymentGatewaySettings

POST/merchant/stores/{storeId}/payment-gateway-settings/test

Test configured payment gateway health

Operation: testPaymentGateway
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Payment gateway healthPaymentProviderHealth

GET/merchant/stores/{storeId}/payment-providers

Which payment provider takes this store's payments

Operation: getPaymentProviders
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Payment providersPaymentProviders

POST/merchant/stores/{storeId}/payment-providers/{provider}/connect

Verify, save and activate a provider's credentials

Operation: connectPaymentProvider
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredstring

Request body

Required: PaymentProviderCredentials

Responses

200Payment providersPaymentProviders
400Missing fields, or the provider rejected themErrorResponse
503The provider could not be reached; nothing was savedErrorResponse

DELETE/merchant/stores/{storeId}/payment-providers/{provider}/credentials

Delete a disconnected provider's saved credentials

Operation: removePaymentProviderCredentials
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredstring

Responses

200Payment providersPaymentProviders

POST/merchant/stores/{storeId}/payment-providers/{provider}/disconnect

Stop taking payments through a provider

Operation: disconnectPaymentProvider
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredstring

Request body

Required: object

Responses

200Payment providersPaymentProviders
400Not confirmedErrorResponse

PATCH/merchant/stores/{storeId}/payment-providers/{provider}/settings

When a provider takes the money

Operation: updatePaymentProviderSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredstring

Request body

Required: object

Responses

200Payment providersPaymentProviders

POST/merchant/stores/{storeId}/payment-providers/{provider}/test

Check a provider's credentials without saving them

Operation: testPaymentProvider
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
providerpathrequiredstring

Request body

Required: PaymentProviderCredentials

Responses

200The credentials workobject
400Missing fields, or the provider rejected themErrorResponse
503The provider could not be reached; nothing was savedErrorResponse

POST/merchant/stores/{storeId}/payment-providers/retale_payments/activate

Switch the store back to ReTale Payments

Operation: activateRetalePayments
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Payment providersPaymentProviders

GET/merchant/stores/{storeId}/payments-account

Get the store's ReTale Payments account status

Operation: getStorePaymentAccount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Payments account statusStorePaymentAccount

POST/merchant/stores/{storeId}/payments-account

Create the store's payments account from its finished business profile

Operation: createStorePaymentAccount
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Payments accountStorePaymentAccount
400The business profile is not finishedErrorResponse
409ReTale Payments is not open yetErrorResponse

POST/merchant/stores/{storeId}/payments/{paymentTransactionId}/capture

Capture an authorized payment transaction

Operation: capturePayment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
paymentTransactionIdpathrequiredstring

Request body

Optional: PaymentOperationRequest

Responses

200Capture transactionPaymentTransaction

POST/merchant/stores/{storeId}/payments/{paymentTransactionId}/refund

Refund a captured payment transaction

Operation: refundPayment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
paymentTransactionIdpathrequiredstring

Request body

Required: PaymentOperationRequest

Responses

200Refund transactionPaymentTransaction

POST/merchant/stores/{storeId}/payments/{paymentTransactionId}/void

Void an authorized payment transaction

Operation: voidPayment
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
paymentTransactionIdpathrequiredstring

Request body

Optional: PaymentOperationRequest

Responses

200Void transactionPaymentTransaction

POST/merchant/stores/{storeId}/payments/reconciliation

Reconcile ReTale payment transactions against a gateway report

Operation: reconcilePayments
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: PaymentReconciliationRequest

Responses

200Payment reconciliation recordsPaymentReconciliationResponse

GET/merchant/stores/{storeId}/product-imports

This store's ten most recent product imports

Operation: listProductImports
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Recent importsobject

POST/merchant/stores/{storeId}/product-imports

Import products from a CSV, in the background

Operation: startProductImport
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

202QueuedProductImport
400The file can't be imported, with the reason in plain wordsErrorResponse

GET/merchant/stores/{storeId}/product-imports/{importId}

One product import's progress and results

Operation: getProductImport
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
importIdpathrequiredstring

Responses

200The importProductImport

GET/merchant/stores/{storeId}/product-imports/{importId}/failed-rows

The rows that couldn't be imported, as CSV, each with its reason

Operation: getProductImportFailedRows
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
importIdpathrequiredstring

Responses

200The original header plus an "Import error" column, and each failed row as it was in the fileobject

GET/merchant/stores/{storeId}/products

List tenant-scoped products for merchant administration

Operation: listMerchantProducts
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Tenant-scoped admin productsAdminProductListResponse
403Merchant cannot view this store catalogErrorResponse

POST/merchant/stores/{storeId}/products

Create a product with variants, media, pricing, and publishing state

Operation: createMerchantProduct
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: ProductCreateRequest

Responses

201Product created and audit event writtenProductMutationResponse
400Product validation failedErrorResponse
403Merchant role cannot write catalog dataErrorResponse

GET/merchant/stores/{storeId}/products/{productId}

One tenant-scoped product, with its stock summary, for the admin product page

Operation: getMerchantProduct
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring

Responses

200The productAdminProductListItem
404No such product in this storeErrorResponse

PATCH/merchant/stores/{storeId}/products/{productId}

Update product fields and replace variants or media

Operation: updateMerchantProduct
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring
deferCollectionRefreshqueryoptionalstring

Request body

Required: ProductUpdateRequest

Responses

200Product updated and audit event writtenProductMutationResponse
404Product not found in active storeErrorResponse

POST/merchant/stores/{storeId}/products/{productId}/archive

Archive a product and remove it from public catalog responses

Operation: archiveMerchantProduct
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring
deferCollectionRefreshqueryoptionalstring

Responses

200Product archived and audit event writtenProductMutationResponse

POST/merchant/stores/{storeId}/products/{productId}/duplicate

Duplicate a product as a draft with store-unique handle and SKUs

Operation: duplicateMerchantProduct
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring

Responses

201Draft product copy created and audit event writtenProductMutationResponse

GET/merchant/stores/{storeId}/products/{productId}/metafields

A product's custom field values, by key (NOR-936)

Operation: getProductMetafields
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring

Responses

200The definitions and this product's valuesProductMetafields

PUT/merchant/stores/{storeId}/products/{productId}/metafields

Save a product's custom field values. Each is checked; if any is refused, none is saved.

Operation: saveProductMetafields
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring

Request body

Required: object

Responses

200SavedProductMetafields

POST/merchant/stores/{storeId}/products/{productId}/publish

Publish a product to generated storefronts

Operation: publishMerchantProduct
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring
deferCollectionRefreshqueryoptionalstring

Responses

200Product published and audit event writtenProductMutationResponse

GET/merchant/stores/{storeId}/products/{productId}/stock

A product's quantity at each location, and whether each variant keeps selling at zero

Operation: getMerchantProductStock
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring

Responses

200The product's stockProductStock

PUT/merchant/stores/{storeId}/products/{productId}/stock

Set a variant's quantity at each location (absolute numbers), audited as stock adjustments

Operation: setMerchantProductStock
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdpathrequiredstring

Request body

Required: ProductStockUpdateRequest

Responses

200The product's stock after the changeProductStock

POST/merchant/stores/{storeId}/returns/{returnRequestId}/approve

Approve a requested return

Operation: approveMerchantReturnRequest
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
returnRequestIdpathrequiredstring

Request body

Optional: ReturnDecisionRequest

Responses

200Return approvedReturnRequestMutationResponse

POST/merchant/stores/{storeId}/returns/{returnRequestId}/receive

Receive a return and explicitly restock selected lines

Operation: receiveMerchantReturnRequest
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
returnRequestIdpathrequiredstring

Request body

Optional: ReturnReceiveRequest

Responses

200Return received and restock ledger entries recorded when requestedReturnRequestMutationResponse

POST/merchant/stores/{storeId}/returns/{returnRequestId}/reject

Reject a requested return

Operation: rejectMerchantReturnRequest
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
returnRequestIdpathrequiredstring

Request body

Optional: ReturnDecisionRequest

Responses

200Return rejectedReturnRequestMutationResponse

GET/merchant/stores/{storeId}/reviews

List product reviews for moderation and support

Operation: listMerchantProductReviews
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
productIdqueryoptionalstring
statusqueryoptionalProductReviewStatus
customerIdqueryoptionalstring
limitqueryoptionalinteger
offsetqueryoptionalinteger

Responses

200Product reviewsProductReviewListResponse

POST/merchant/stores/{storeId}/reviews/{reviewId}/moderate

Approve, reject, hide, or return a review to pending

Operation: moderateProductReview
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
reviewIdpathrequiredstring

Request body

Required: ProductReviewModerationRequest

Responses

200Review moderated and aggregate refreshedProductReviewMutationResponse

PUT/merchant/stores/{storeId}/reviews/{reviewId}/response

Add or update the merchant response on a review

Operation: respondToProductReview
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
reviewIdpathrequiredstring

Request body

Required: ProductReviewResponseRequest

Responses

200Merchant response saved and auditedProductReviewMutationResponse

GET/merchant/stores/{storeId}/settings

Get tenant-scoped store settings

Operation: getStoreSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Store settings for the active tenantStoreSettings
403Merchant role cannot view store settingsErrorResponse

PATCH/merchant/stores/{storeId}/settings

Update tenant-scoped profile, branding, and plan settings

Operation: updateStoreSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: StoreSettingsUpdateRequest

Responses

200Updated store settingsStoreSettingsUpdateResponse
403Merchant role cannot update these settingsErrorResponse

GET/merchant/stores/{storeId}/storefront-filters

The filters every collection page shows, and the fields that can be one (NOR-939)

Operation: getStorefrontFilterSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The filtersobject

PUT/merchant/stores/{storeId}/storefront-filters

Save the store's filters in order, with shopper names; facets null goes back to the defaults (NOR-939)

Operation: saveStorefrontFilterSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

200The filtersobject

GET/merchant/stores/{storeId}/storefront/generation-jobs/{jobId}

How far one of this store's website builds has got

Operation: getStorefrontGenerationJob
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
jobIdpathrequiredstring

Responses

200The build's statusobject
404No such build for this storeErrorResponse

POST/merchant/stores/{storeId}/storefront/generation-requests

Submit an AI storefront generation request for a merchant store

Operation: submitStorefrontGenerationRequest
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: StorefrontGenerationRequest

Responses

202Storefront generation request queuedStorefrontGenerationSubmission

GET/merchant/stores/{storeId}/storefront/versions

List generated storefront version history for a merchant store

Operation: listStorefrontVersions
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Storefront version historyStorefrontVersionHistory

GET/merchant/stores/{storeId}/storefront/versions/{storefrontVersionId}

Get generated storefront preview and optional diff

Operation: getStorefrontVersionPreview
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
storefrontVersionIdpathrequiredstring
compareToVersionIdqueryoptionalstring

Responses

200Storefront version previewStorefrontVersionPreview

POST/merchant/stores/{storeId}/storefront/versions/{storefrontVersionId}/approve

Approve a generated storefront version for publishing

Operation: approveStorefrontVersion
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
storefrontVersionIdpathrequiredstring

Request body

Optional: StorefrontVersionActionRequest

Responses

200Approved storefront versionStorefrontVersion

POST/merchant/stores/{storeId}/storefront/versions/{storefrontVersionId}/publish

Publish a generated storefront version

Operation: publishStorefrontVersion
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
storefrontVersionIdpathrequiredstring

Request body

Optional: StorefrontPublishRequest

Responses

200Published storefront versionStorefrontVersion

POST/merchant/stores/{storeId}/storefront/versions/{storefrontVersionId}/rollback

Roll back live storefront to a previous approved or live version

Operation: rollbackStorefrontVersion
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
storefrontVersionIdpathrequiredstring

Request body

Optional: StorefrontVersionActionRequest

Responses

200Rolled back storefront versionStorefrontVersion

POST/merchant/stores/{storeId}/storefront/versions/{storefrontVersionId}/targeted-edits

Request a targeted edit against a generated storefront version

Operation: requestStorefrontTargetedEdit
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
storefrontVersionIdpathrequiredstring

Request body

Required: StorefrontTargetedEditRequest

Responses

201Targeted edit request acceptedStorefrontGenerationSubmission

POST/merchant/stores/{storeId}/switch

Switch the active store for the current merchant session

Operation: switchMerchantActiveStore
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Active store context and permissionsResolvedMerchantAccess
403Merchant cannot access this storeErrorResponse

GET/merchant/stores/{storeId}/tax-settings

Get store tax provider settings

Operation: getStoreTaxSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Store tax settingsStoreTaxSettings

PATCH/merchant/stores/{storeId}/tax-settings

Update store tax provider and display settings

Operation: updateStoreTaxSettings
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: StoreTaxSettingsRequest

Responses

200Store tax settings updatedStoreTaxSettings

POST/merchant/stores/{storeId}/tax-settings/test

Test configured tax provider health

Operation: testStoreTaxProvider
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200Tax provider healthTaxProviderHealth

GET/merchant/stores/{storeId}/website-builder

The website builder's conversation (NOR-961 / NOR-962)

Operation: getWebsiteBuilder
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

200The conversationWebsiteBuilder

POST/merchant/stores/{storeId}/website-builder/builds

Put a build into the conversation (NOR-963)

Operation: recordWebsiteBuild
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201The request and the replyobject

POST/merchant/stores/{storeId}/website-builder/messages

Ask for a change to the page in view (NOR-961 / NOR-962)

Operation: askWebsiteBuilder
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Required: object

Responses

201The request and the replyobject

POST/merchant/stores/{storeId}/website-builder/undo

Undo a change, or the latest one (NOR-962)

Operation: undoWebsiteBuilderChange
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Request body

Optional: object

Responses

201The undo and its replyobject
409Refused, with the reason

POST/merchant/stores/{storeId}/website-preview

A pass to the store's private website preview (NOR-960)

Operation: createStorefrontPreviewPass
Audience: Merchant admin app and trusted integrations
Access: MerchantSession
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring

Responses

201The passobject

Provider Webhooks

Provider callback endpoints that verify external payment and recurring billing events.

6 operations

POST/webhooks/shippo/live

Shippo live-mode events (tracking, transactions, batches)

Operation: receiveShippoLiveWebhook
Audience: Configured payment and billing providers
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

tokenqueryrequiredstring

Responses

200Event receivedStripeWebhookReceipt
400The body is not a Shippo eventErrorResponse
401Token missing or wrongErrorResponse
503This endpoint has no token configured yetErrorResponse

POST/webhooks/shippo/test

Shippo test-mode events (tracking, transactions, batches)

Operation: receiveShippoTestWebhook
Audience: Configured payment and billing providers
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

tokenqueryrequiredstring

Responses

200Event receivedStripeWebhookReceipt
400The body is not a Shippo eventErrorResponse
401Token missing or wrongErrorResponse
503This endpoint has no token configured yetErrorResponse

POST/webhooks/stores/{storeId}/membership-billing/{gateway}

Receive and verify recurring membership billing webhook events

Operation: processMembershipBillingWebhook
Audience: Configured payment and billing providers
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
gatewaypathrequiredstring

Request body

Required: object

Responses

200Recurring billing webhook processed or replay ignored idempotentlyMembershipBillingWebhookProcessResponse
401Invalid webhook signatureErrorResponse

POST/webhooks/stores/{storeId}/payments/{gateway}

Receive and verify payment gateway webhook events

Operation: processPaymentWebhook
Audience: Configured payment and billing providers
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

storeIdpathrequiredstring
gatewaypathrequiredstring

Request body

Required: object

Responses

200Webhook processed or replay ignored idempotentlyGatewayWebhookProcessResponse
401Invalid webhook signatureErrorResponse

POST/webhooks/stripe/connect

Stripe events on merchants' connected accounts

Operation: receiveStripeConnectWebhook
Audience: Configured payment and billing providers
Access: Public or provider verified
Idempotency: Not required by contract

Responses

200Event receivedStripeWebhookReceipt
400Signature missing or invalidErrorResponse

POST/webhooks/stripe/platform

Stripe events on the ReTale platform account

Operation: receiveStripePlatformWebhook
Audience: Configured payment and billing providers
Access: Public or provider verified
Idempotency: Not required by contract

Responses

200Event receivedStripeWebhookReceipt
400Signature missing or invalidErrorResponse

Platform API

Low-risk platform endpoints that do not expose tenant data.

3 operations

GET/health

API health check

Operation: getHealth
Audience: Operations and health checks
Access: Public or provider verified
Idempotency: Not required by contract

Responses

200API health responseHealthResponse

GET/storefront-hosts/{host}

Which store a host serves, and its canonical spelling

Operation: resolveStorefrontHost
Audience: Operations and health checks
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

hostpathrequiredstring

Responses

200The store this host servesStorefrontHost
404No live store answers on this host

GET/storefront-previews/{pass}

Which store a website builder preview pass shows (NOR-960)

Operation: resolveStorefrontPreview
Audience: Operations and health checks
Access: Public or provider verified
Idempotency: Not required by contract

Parameters

passpathrequiredstring

Responses

200The store the pass shows, and when the pass stops workingobject
404Not a current preview pass

Generated storefront boundary

Generated code cannot bypass fixed commerce flows

Allowed generated behavior

Generated storefronts may render layouts, product grids, content pages, SEO metadata, reviews, visual styling, and local presentation state using documented public API and SDK surfaces.

Fixed platform behavior

Cart mutation, tax quotes, inventory reservation, checkout sessions, payment tokenization, order creation, login, account access, loyalty redemption, memberships, refunds, and moderation stay in fixed platform code.

Forbidden bypasses

Generated code must not query the database, import server-only modules, call gateways directly, store secrets, process raw card data, disable validation, bypass rate limits, or publish without approval gates.

Generated storefronts must use @retale/commerce-sdk for cart, checkout, payment, login, account, tax, inventory, order, loyalty, membership, and review workflows. Direct gateway, database, server-only module, secret, and internal route imports are forbidden.

Local and sandbox examples

Requests without production credentials

Health check

curl -s http://localhost:4100/api/v1/health

Public catalog

curl -s http://localhost:4100/api/v1/stores/demo-store/products?limit=12&offset=0

Merchant session shape

curl -s -H "Authorization: Bearer $RETALE_LOCAL_MERCHANT_SESSION" \
  -H "X-ReTale-Store-Id: $RETALE_LOCAL_STORE_ID" \
  http://localhost:4100/api/v1/merchant/stores/$RETALE_LOCAL_STORE_ID/orders?limit=10&offset=0

Merchant examples use a local session token from the admin login flow. Do not place provider credentials, payment gateway keys, database URLs, or production bearer tokens in public docs or generated storefronts.