Brainerce Public API (v1)

Brainerce API reference: every public api (v1) operation, with its method, path and a page of its own.

The external integrator REST API under /v1/*. Stable, versioned, auth via api-key (issue from the dashboard at Settings → API keys). Use this when calling Brainerce from outside the dashboard — a headless storefront, ERP sync, BI pipeline, etc. Every endpoint requires a scope (products:read, orders:write, …) on the key. The /v1/ prefix is a versioning anchor — there is no v2 planned, but a future breaking change would ship under /v2/ without disrupting /v1/ integrators.

Public API (v1) operations

Store

Method	Endpoint	Operation
`GET`	`/v1/store`	Get store information

Products

Method	Endpoint	Operation
`GET`	`/v1/products`	List products with pagination
`POST`	`/v1/products`	Create a new product
`GET`	`/v1/products/{id}`	Get a single product by ID
`PATCH`	`/v1/products/{id}`	Update a product
`DELETE`	`/v1/products/{id}`	Delete a product
`POST`	`/v1/products/bulk`	Create many products in one call (queued)
`GET`	`/v1/products/bulk/{jobId}`	Get bulk product creation status
`GET`	`/v1/products/bulk/import/{importId}`	Get aggregate status for a chunked import
`GET`	`/v1/products/bulk/{jobId}/errors`	List per-product failures for a bulk create job
`GET`	`/v1/products/{id}/kit-components`	Get kit components
`PUT`	`/v1/products/{id}/kit-components`	Set kit components
`PATCH`	`/v1/products/{id}/convert-to-variable`	Convert a SIMPLE product to VARIABLE
`PATCH`	`/v1/products/{id}/convert-to-simple`	Convert a VARIABLE product back to SIMPLE
`GET`	`/v1/products/{id}/inventory`	Get inventory for a product
`PUT`	`/v1/products/{id}/inventory`	Update inventory for a product
`POST`	`/v1/products/{id}/variants`	Create a variant for a product
`POST`	`/v1/products/{id}/variants/bulk`	Bulk save variants
`PATCH`	`/v1/products/{id}/variants/{variantId}`	Update a variant
`DELETE`	`/v1/products/{id}/variants/{variantId}`	Delete a variant
`GET`	`/v1/products/{id}/variants/{variantId}/inventory`	Get variant inventory
`PATCH`	`/v1/products/{id}/variants/{variantId}/inventory`	Update variant inventory
`POST`	`/v1/products/{id}/publish-sales-channel`	Publish a product to a sales-channel site
`POST`	`/v1/products/{id}/unpublish-sales-channel`	Unpublish a product from a sales-channel site
`GET`	`/v1/products/{productId}/metafields`	Get metafields for a product
`DELETE`	`/v1/products/{productId}/metafields/{definitionId}`	Delete a product metafield value
`PUT`	`/v1/products/{productId}/metafields/{definitionId}`	Upsert a product metafield value
`GET`	`/v1/products/{productId}/reviews`	List reviews for a product (admin view, includes hidden)
`POST`	`/v1/products/{productId}/reviews`	Submit a product review (server-to-server)

Coupons

Method	Endpoint	Operation
`POST`	`/v1/coupons/{id}/publish-sales-channel`	Publish a coupon to a sales-channel site
`POST`	`/v1/coupons/{id}/unpublish-sales-channel`	Unpublish a coupon from a sales-channel site
`GET`	`/v1/coupons`	List coupons with pagination
`POST`	`/v1/coupons`	Create a new coupon
`GET`	`/v1/coupons/platform-capabilities`	Get platform capabilities for coupon features
`GET`	`/v1/coupons/{id}`	Get a single coupon by ID
`PATCH`	`/v1/coupons/{id}`	Update a coupon
`DELETE`	`/v1/coupons/{id}`	Delete a coupon
`POST`	`/v1/coupons/{id}/sync`	Sync a coupon to all connected platforms
`POST`	`/v1/coupons/{id}/publish`	Publish a coupon to specific platforms

Media

Method	Endpoint	Operation
`GET`	`/v1/media`	List media library assets
`POST`	`/v1/media`	Upload or ingest a media asset
`GET`	`/v1/media/{id}`	Get a media asset by ID
`PATCH`	`/v1/media/{id}`	Update media asset metadata
`DELETE`	`/v1/media/{id}`	Delete a media asset

Orders

Method	Endpoint	Operation
`GET`	`/v1/orders`	List orders with pagination
`POST`	`/v1/orders`	Create a new order
`GET`	`/v1/orders/{id}`	Get a single order by ID
`PATCH`	`/v1/orders/{id}`	Update an order
`GET`	`/v1/orders/{id}/shipments/app-rates`	Live carrier rates for an order
`POST`	`/v1/orders/{id}/shipments/app-label`	Buy a shipping label via the installed shipping app
`GET`	`/v1/orders/{id}/shipments`	Shipments and tracking history for an order
`GET`	`/v1/orders/{id}/custom-fields`	Get the custom field values on an order
`PATCH`	`/v1/orders/{id}/custom-fields`	Set custom field values on an order
`PATCH`	`/v1/orders/{id}/tags`	Set the tags of an order

Order custom fields

Method	Endpoint	Operation
`GET`	`/v1/order-custom-fields`	List order custom field definitions

Customers

Method	Endpoint	Operation
`POST`	`/v1/customers`	Create a new customer
`GET`	`/v1/customers/by-email`	Get a customer by email
`GET`	`/v1/customers/{id}`	Get a customer by ID
`PATCH`	`/v1/customers/{id}`	Update a customer
`POST`	`/v1/customers/{id}/publish-sales-channel`	Attach a customer to a sales channel
`POST`	`/v1/customers/{id}/unpublish-sales-channel`	Detach a customer from a sales channel
`POST`	`/v1/customers/login`	Customer login
`POST`	`/v1/customers/register`	Customer registration
`POST`	`/v1/customers/forgot-password`	Request password reset (Public API)
`POST`	`/v1/customers/reset-password`	Reset password with token (Public API)
`GET`	`/v1/customers/{id}/addresses`	Get customer addresses
`POST`	`/v1/customers/{id}/addresses`	Add a customer address
`PATCH`	`/v1/customers/{id}/addresses/{addressId}`	Update a customer address
`DELETE`	`/v1/customers/{id}/addresses/{addressId}`	Delete a customer address
`GET`	`/v1/customers/{id}/orders`	Get customer orders

Cart

Method	Endpoint	Operation
`POST`	`/v1/cart`	Create a new cart
`GET`	`/v1/cart/session/{sessionToken}`	Get cart by session token
`GET`	`/v1/cart/customer/{customerId}`	Get cart by customer ID
`GET`	`/v1/cart/{cartId}`	Get cart by ID
`POST`	`/v1/cart/{cartId}/items`	Add item to cart
`DELETE`	`/v1/cart/{cartId}/items`	Clear all items from cart
`PATCH`	`/v1/cart/{cartId}/items/{itemId}`	Update cart item (Public API)
`DELETE`	`/v1/cart/{cartId}/items/{itemId}`	Remove item from cart
`POST`	`/v1/cart/{cartId}/coupon`	Apply coupon to cart
`DELETE`	`/v1/cart/{cartId}/coupon`	Remove coupon from cart
`POST`	`/v1/cart/merge`	Merge guest cart into customer cart

Checkout

Method	Endpoint	Operation
`POST`	`/v1/checkout`	Create checkout from cart
`GET`	`/v1/checkout/{checkoutId}`	Get checkout (Public API)
`DELETE`	`/v1/checkout/{checkoutId}`	Delete a checkout
`PATCH`	`/v1/checkout/{checkoutId}/customer`	Set customer info on checkout
`PATCH`	`/v1/checkout/{checkoutId}/shipping-address`	Set shipping address and get available rates
`GET`	`/v1/checkout/{checkoutId}/shipping-rates`	Get available shipping rates
`PATCH`	`/v1/checkout/{checkoutId}/shipping-method`	Select shipping method (Public API)
`GET`	`/v1/checkout/{checkoutId}/pickup-points`	List carrier pickup points (Public API)
`PUT`	`/v1/checkout/{checkoutId}/pickup-point`	Choose a carrier pickup point (Public API)
`PATCH`	`/v1/checkout/{checkoutId}/billing-address`	Set billing address (Public API)
`POST`	`/v1/checkout/{checkoutId}/gift-card`	Apply a gift card to a checkout (Public API)
`DELETE`	`/v1/checkout/{checkoutId}/gift-card/{tenderId}`	Remove a gift card from a checkout (Public API)
`POST`	`/v1/checkout/{checkoutId}/coupon`	Apply coupon to checkout
`DELETE`	`/v1/checkout/{checkoutId}/coupon`	Remove coupon from checkout
`POST`	`/v1/checkout/{checkoutId}/complete`	Complete checkout and create order

Gift cards

Method	Endpoint	Operation
`POST`	`/v1/gift-cards/balance`	Check a gift card balance (Public API)
`GET`	`/v1/gift-cards`	List gift cards
`POST`	`/v1/gift-cards`	Issue a gift card
`GET`	`/v1/gift-cards/liability`	Outstanding gift card liability
`PATCH`	`/v1/gift-cards/bulk/status`	Disable or reactivate many gift cards
`GET`	`/v1/gift-cards/{id}`	Get a gift card and its full ledger
`POST`	`/v1/gift-cards/{id}/reissue`	Re-issue a gift card onto a new code
`PATCH`	`/v1/gift-cards/{id}/adjust`	Adjust a gift card balance
`PATCH`	`/v1/gift-cards/{id}/status`	Enable, disable or revoke a gift card

Method	Endpoint	Operation
`GET`	`/v1/categories`	List categories with pagination
`POST`	`/v1/categories`	Create a new category
`GET`	`/v1/categories/{id}`	Get a single category by ID
`PATCH`	`/v1/categories/{id}`	Update a category
`DELETE`	`/v1/categories/{id}`	Delete a category
`POST`	`/v1/categories/{id}/publish-sales-channel`	Publish a category to a sales-channel site
`POST`	`/v1/categories/{id}/unpublish-sales-channel`	Unpublish a category from a sales-channel site

Brands

Method	Endpoint	Operation
`GET`	`/v1/brands`	List brands with pagination
`POST`	`/v1/brands`	Create a new brand
`GET`	`/v1/brands/{id}`	Get a single brand by ID
`PATCH`	`/v1/brands/{id}`	Update a brand
`DELETE`	`/v1/brands/{id}`	Delete a brand
`POST`	`/v1/brands/{id}/publish-sales-channel`	Publish a brand to a sales-channel site
`POST`	`/v1/brands/{id}/unpublish-sales-channel`	Unpublish a brand from a sales-channel site

Method	Endpoint	Operation
`GET`	`/v1/tags`	List tags with pagination
`POST`	`/v1/tags`	Create a new tag
`GET`	`/v1/tags/{id}`	Get a single tag by ID
`PATCH`	`/v1/tags/{id}`	Update a tag
`DELETE`	`/v1/tags/{id}`	Delete a tag
`POST`	`/v1/tags/{id}/publish-sales-channel`	Publish a tag to a sales-channel site
`POST`	`/v1/tags/{id}/unpublish-sales-channel`	Unpublish a tag from a sales-channel site

Attributes

Method	Endpoint	Operation
`GET`	`/v1/attributes`	List attributes with pagination
`POST`	`/v1/attributes`	Create a new attribute
`GET`	`/v1/attributes/{id}`	Get a single attribute by ID
`PATCH`	`/v1/attributes/{id}`	Update an attribute
`DELETE`	`/v1/attributes/{id}`	Delete an attribute
`GET`	`/v1/attributes/{id}/options`	Get attribute options
`POST`	`/v1/attributes/{id}/options`	Create an attribute option

Shipping

Method	Endpoint	Operation
`GET`	`/v1/shipping/zones`	List shipping zones with pagination
`POST`	`/v1/shipping/zones`	Create a new shipping zone
`GET`	`/v1/shipping/zones/{zoneId}`	Get a single shipping zone by ID
`PATCH`	`/v1/shipping/zones/{zoneId}`	Update a shipping zone
`DELETE`	`/v1/shipping/zones/{zoneId}`	Delete a shipping zone
`GET`	`/v1/shipping/zones/{zoneId}/rates`	Get shipping rates for a zone
`POST`	`/v1/shipping/zones/{zoneId}/rates`	Create a shipping rate for a zone
`PATCH`	`/v1/shipping/zones/{zoneId}/rates/{rateId}`	Update a shipping rate
`DELETE`	`/v1/shipping/zones/{zoneId}/rates/{rateId}`	Delete a shipping rate

Tax

Method	Endpoint	Operation
`GET`	`/v1/tax/rates`	List tax rates for the store
`POST`	`/v1/tax/rates`	Create a new tax rate
`GET`	`/v1/tax/rates/{rateId}`	Get a single tax rate by ID
`PATCH`	`/v1/tax/rates/{rateId}`	Update a tax rate
`DELETE`	`/v1/tax/rates/{rateId}`	Delete a tax rate
`GET`	`/v1/tax/presets`	List available country tax presets
`POST`	`/v1/tax/presets/{presetKey}/apply`	Apply a country tax preset

Tax classes

Method	Endpoint	Operation
`GET`	`/v1/tax-classes`	List the store tax classes
`POST`	`/v1/tax-classes`	Create a tax class
`GET`	`/v1/tax-classes/{id}`	Get a tax class with its dependent counts
`PATCH`	`/v1/tax-classes/{id}`	Update a tax class
`DELETE`	`/v1/tax-classes/{id}`	Delete a tax class (409 while dependents exist)
`PATCH`	`/v1/tax-classes/{id}/set-default`	Set this tax class as the store default
`POST`	`/v1/tax-classes/{id}/assign`	Bulk-assign a tax class to products / variants / categories
`POST`	`/v1/tax-classes/{id}/merge-into/{target}`	Merge this tax class into another, moving all FKs, then delete it

Regions

Method	Endpoint	Operation
`GET`	`/v1/regions`	List the store regions
`POST`	`/v1/regions`	Create a region
`GET`	`/v1/regions/{regionId}`	Get a region
`PATCH`	`/v1/regions/{regionId}`	Update a region
`DELETE`	`/v1/regions/{regionId}`	Delete a region
`GET`	`/v1/regions/{regionId}/compatible-providers`	List installed providers compatible with this region
`PATCH`	`/v1/regions/{regionId}/set-default`	Set this region as the store default
`PUT`	`/v1/regions/{regionId}/payment-providers`	Replace the region enabled payment providers
`GET`	`/v1/regions/{regionId}/prices`	List the region manual price overrides
`PUT`	`/v1/regions/{regionId}/prices`	Bulk upsert/remove the region manual price overrides
`DELETE`	`/v1/regions/{regionId}/prices/{priceId}`	Delete one manual price override
`POST`	`/v1/regions/{regionId}/countries`	Add countries to a region
`DELETE`	`/v1/regions/{regionId}/countries/{code}`	Remove a country from a region

Metafield definitions

Method	Endpoint	Operation
`GET`	`/v1/metafield-definitions`	List metafield definitions
`POST`	`/v1/metafield-definitions`	Create a new metafield definition
`GET`	`/v1/metafield-definitions/{id}`	Get a single metafield definition by ID
`PATCH`	`/v1/metafield-definitions/{id}`	Update a metafield definition
`DELETE`	`/v1/metafield-definitions/{id}`	Delete a metafield definition
`PUT`	`/v1/metafield-definitions/{id}/platforms`	Replace platform publishing configuration

Email

Method	Endpoint	Operation
`GET`	`/v1/email/settings`	Get email settings for store
`PUT`	`/v1/email/settings`	Update email settings for store
`GET`	`/v1/email/templates`	Get all email templates for store
`POST`	`/v1/email/templates`	Create a new email template
`GET`	`/v1/email/templates/{templateId}`	Get email template by ID
`DELETE`	`/v1/email/templates/{templateId}`	Delete an email template
`PUT`	`/v1/email/templates/{templateId}`	Update an email template
`POST`	`/v1/email/templates/{templateId}/preview`	Preview an email template with sample data

Storefront bot

Method	Endpoint	Operation
`GET`	`/v1/storefront-bot/settings`	Get Storefront Bot settings for every connection on the store
`PUT`	`/v1/storefront-bot/settings`	Update one connection’s Storefront Bot settings
`GET`	`/v1/storefront-bot/conversations`	List Storefront Bot conversations
`GET`	`/v1/storefront-bot/conversations/{id}`	Get one Storefront Bot conversation transcript
`POST`	`/v1/storefront-bot/conversations/{id}/summarize`	Summarize a Storefront Bot conversation

Metafield conflicts

Method	Endpoint	Operation
`GET`	`/v1/metafield-conflicts`	Get pending metafield conflicts
`POST`	`/v1/metafield-conflicts/{conflictId}/resolve`	Resolve a metafield conflict
`POST`	`/v1/metafield-conflicts/{conflictId}/ignore`	Ignore a metafield conflict

Oauth providers

Method	Endpoint	Operation
`GET`	`/v1/oauth-providers`	Get all OAuth provider configurations
`POST`	`/v1/oauth-providers`	Configure an OAuth provider
`GET`	`/v1/oauth-providers/{provider}`	Get OAuth provider configuration
`PATCH`	`/v1/oauth-providers/{provider}`	Update OAuth provider configuration
`DELETE`	`/v1/oauth-providers/{provider}`	Delete OAuth provider configuration

Reviews

Method	Endpoint	Operation
`PATCH`	`/v1/reviews/{id}/hide`	Hide a review from the storefront
`PATCH`	`/v1/reviews/{id}/show`	Unhide a previously hidden review

Review images

Method	Endpoint	Operation
`PATCH`	`/v1/review-images/{id}/hide`	Hide a single review photo, leaving the review itself visible
`PATCH`	`/v1/review-images/{id}/show`	Show a review photo (also approves one that was awaiting a decision)

Method	Endpoint	Operation
`GET`	`/v1/newsletter-benefit/settings`	Get the newsletter signup benefit settings
`PUT`	`/v1/newsletter-benefit/settings`	Create or replace the newsletter signup benefit settings
`GET`	`/v1/newsletter-benefit/grants`	List issued newsletter benefits
`POST`	`/v1/newsletter-benefit/grants/{grantId}/resend`	Re-send an issued newsletter benefit

Public API (v1)