canonical: https://jentic.com/apis/brandlovers.com/brandlovers

# BrandLovers Marketplace API V1

The BrandLovers Marketplace API gives sellers a programmatic surface for the BrandLovers e-commerce marketplace, covering product onboarding, order lifecycle updates, shipment status, and customer support tickets across 36 endpoints. Sellers can publish or update SKUs, push price and stock changes in bulk, mark orders as sent or delivered, register exchanges and returns, and exchange messages on customer tickets. All requests are JSON over HTTPS authenticated with a per-seller authorization token issued from the BrandLovers admin console. The API is shaped for marketplace integrators that want to keep their internal commerce systems in sync with the BrandLovers storefront.

## For AI agents

Manage products, orders, shipments, and customer tickets for a BrandLovers marketplace seller account through 36 JSON endpoints behind a single authorization-header token.

## Scope

Does not handle payment processing, shipping rate calculation, or buyer-side checkout - use for seller-side product, order, shipment, and ticket management on the BrandLovers marketplace only.

## Capabilities

- Publish a new product to the marketplace via POST /product and update it later with PUT `/product/{skuSellerId}`
- Push bulk price and stock changes through PUT `/products/prices` and PUT `/products/stocks`
- List orders by status using GET `/orders/status/new`, /approved, /sent, /delivered, /canceled, and partial-state variants
- Mark a shipment as sent, delivered, returned, or exchanged via POST `/order/{orderId}/shipment/{action}`
- Open and reply to customer support tickets through POST /ticket and POST `/ticket/{ticketId}/message`
- Toggle product availability with PUT `/product/{skuSellerId}/status` and PUT `/products/status`
- Reconcile shipped or delivered orders in bulk with GET `/orders/shipments/shipped` and GET `/orders/shipments/delivered`

## Use cases

### Seller onboarding and catalogue sync

Seed BrandLovers with the seller's full SKU catalogue and keep prices and stock in step with the upstream ERP or PIM. The integration calls POST /product per item on first sync, then uses PUT `/products/prices` and PUT `/products/stocks` for bulk updates whenever cost, MSRP, or warehouse counts change. This avoids manual catalogue uploads and prevents oversells.

Example prompt: POST /product for each SKU in the source feed, then on cadence call PUT `/products/prices` with the changed price array and PUT `/products/stocks` with the changed stock array.

### Order fulfilment automation

Pull new orders into the warehouse system and push status back as they progress. Poll GET `/orders/status/new` for orders to pick, then call POST `/order/{orderId}/shipment/sent` with carrier and tracking once the parcel leaves, and POST `/order/{orderId}/shipment/delivered` when the carrier confirms drop-off. This keeps the buyer-facing order status accurate without double data entry.

Example prompt: GET `/orders/status/new`, for each order call POST `/order/{orderId}/shipment/sent` with the carrier tracking code, then on delivery confirmation call POST `/order/{orderId}/shipment/delivered.`

### Returns and exchange handling

When a buyer returns an item, the seller registers it through POST `/order/{orderId}/shipment/return` so refunds and inventory restocks can be triggered downstream. Exchanges follow the same pattern with POST `/order/{orderId}/shipment/exchange.` Pairing this with PUT `/product/{skuSellerId}/stock` keeps stock counts honest after the returned unit is graded.

Example prompt: On return receipt, call POST `/order/{orderId}/shipment/return` with the reason code, then PUT `/product/{skuSellerId}/stock` to add 1 unit back to availability.

### Customer support ticket triage

Open tickets on behalf of buyers when an issue is detected (for example a delayed shipment) and have a support agent reply through the same API. POST /ticket creates the ticket against an order, POST `/ticket/{ticketId}/message` appends replies, and PUT `/ticket/{ticketId}/status` closes it once resolved. GET /tickets and GET `/ticket/{ticketId}/messages` drive the support agent's worklist.

Example prompt: POST /ticket with orderId and an opening message, then on each agent reply call POST `/ticket/{ticketId}/message` and finally PUT `/ticket/{ticketId}/status` to close.

### AI agent integration via Jentic

An agent that runs marketplace operations for a seller can discover BrandLovers through Jentic, load the relevant product or order operation, and execute it without holding the per-seller authorization token in its prompt. Jentic injects the token only at execution time and returns typed responses the agent can act on.

Example prompt: Through Jentic, search 'mark a marketplace order as shipped', load the operation that targets POST `/order/{orderId}/shipment/sent`, and execute with orderId and tracking code provided by the warehouse system.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/product` | Publish a new product (SKU) to the marketplace |
| PUT | `/products/prices` | Bulk-update prices across many SKUs |
| PUT | `/products/stocks` | Bulk-update stock counts across many SKUs |
| GET | `/orders/status/new` | List new orders waiting to be processed |
| POST | `/order/{orderId}/shipment/sent` | Mark an order as shipped with tracking |
| POST | `/order/{orderId}/shipment/delivered` | Mark an order as delivered |
| POST | `/ticket` | Open a support ticket against an order |
| POST | `/ticket/{ticketId}/message` | Append a message to an existing ticket |

## Key resources

- **Products** — Create, update, price, stock, and toggle availability of seller SKUs via /product and /products endpoints
- **Orders** — List orders by status (new, approved, sent, delivered, canceled, partial states) and retrieve a specific order by id
- **Shipments** — Update an order shipment to sent, delivered, returned, exchanged, or canceled via `/order/{orderId}/shipment/{action}`
- **Tickets** — Open support tickets, append messages, list ticket threads, and update ticket status

## Why Jentic

- **Setup:** Wiring BrandLovers by hand means passing the seller authorization token in the header and coordinating the product, order, shipment, and ticket calls across the marketplace v1 paths. Through Jentic you install once, import the BrandLovers Marketplace API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** BrandLovers puts the resource id in the URL path (`/order/{orderId}/shipment/sent`, `/ticket/{ticketId}/message`), so a rule can pin your agent to one order or ticket. You choose the operations it may call, so writes like publishing a product or updating prices and stocks are only included if you add them, and a fulfilment agent can be held to the shipment paths.
- **Credential handling:** Your BrandLovers seller authorization token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'mark a marketplace order as shipped' or 'publish a product to the marketplace', and Jentic returns the matching BrandLovers operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Braintree GraphQL API** — Process the underlying card and wallet payments for orders captured in BrandLovers
- **Brandfolder API** — Pull approved product imagery from Brandfolder when publishing SKUs to BrandLovers
- **Braze API** — Notify customers via Braze when a BrandLovers order ships or a return is confirmed

## FAQ

### What authentication does the BrandLovers Marketplace API use?

The API uses an apiKey scheme: a per-seller authorization token passed in the authorization header on every request. The token is issued from the BrandLovers admin console. Through Jentic, that token is held in the encrypted vault and attached to each call at execution time.

### Can I bulk-update prices and stock with the BrandLovers Marketplace API?

Yes. PUT `/products/prices` accepts an array of SKU price updates and PUT `/products/stocks` accepts an array of stock updates, so a single request can move many SKUs at once. Use these for nightly catalogue syncs rather than calling per-SKU endpoints in a loop.

### How do I mark an order as shipped with the BrandLovers Marketplace API?

Call POST `/order/{orderId}/shipment/sent` with the carrier and tracking code in the body. When the carrier confirms delivery, follow up with POST `/order/{orderId}/shipment/delivered.` The order moves through the corresponding status that buyers see on the marketplace.

### What are the rate limits for the BrandLovers Marketplace API?

The OpenAPI spec does not declare numeric rate limits. The marketplace asks integrators to use the bulk endpoints (PUT `/products/prices`, PUT `/products/stocks`) for catalogue-wide updates and to back off when 429 responses are returned during peak sync windows.

### How do I publish a new product to BrandLovers through Jentic?

Install with pip install jentic, then await client.search('publish a product to a marketplace'), await client.load on the operation that targets POST /product, and await client.execute with the SKU payload. Jentic attaches the seller authorization token automatically.

### Can I open and respond to customer tickets via the BrandLovers Marketplace API?

Yes. POST /ticket opens a ticket tied to an order, POST `/ticket/{ticketId}/message` appends a message, GET `/ticket/{ticketId}/messages` retrieves the thread, and PUT `/ticket/{ticketId}/status` closes or reopens the ticket. GET /tickets surfaces the full work queue.

### Can I limit what my agent is allowed to do with the BrandLovers Marketplace API?

Yes. Because you run Jentic One yourself, your own rules decide which BrandLovers operations and credentials the agent may use, so a fulfilment agent can be held to the shipment paths like POST `/order/{orderId}/shipment/sent` and delivered while writes such as POST /product or PUT `/products/prices` and PUT `/products/stocks` are included only if you add them. BrandLovers also puts the resource id in the URL path, as in `/order/{orderId}/shipment/sent` and `/ticket/{ticketId}/message`, so a rule can pin the agent to a single order or ticket. Your seller authorization token stays with your self-hosted instance and is attached only at execution time, never in the agent's prompt.