canonical: https://jentic.com/apis/mock.gridbees.com/gridbees

# Mock Gridbees Promotion Engine

Gridbees Promotion Engine is a merchant-facing e-commerce backend that manages contacts, products, offers, orders, pricing, and promotions across the Gridbees commerce stack. The API spans 77 endpoints across customer service, booking, promotion, offer, master data, product, and pricing services, with all timestamps using UTC and the format yyyy-MM-dd'T'HH:mm:ss.SSSZ. Authentication uses OAuth 2.0 plus an API key required on every call, and this specification points at the public mock host used for sandbox testing.

## For AI agents

Manage Gridbees commerce data - contacts, products, offers, orders, and promotions - across 77 endpoints in the Promotion Engine sandbox.

## Scope

Does not handle card payment capture, shipping label generation, or storefront rendering - use for Gridbees commerce data, offers, orders, and promotions only.

## Capabilities

- Search, upsert, and delete merchant contact records via `/contact/search` and `/contact/upsert`
- Activate and check web account status through `/webaccount/activate` and `/webaccount/check`
- Manage product catalogue records under the Product Service tag
- Build and publish offers as bundles of products with prices and additional services
- Issue and reconcile orders that contain order lines tied to specific offers
- Apply promotion rules and pricing through the Promotion and Pricing services
- Maintain reference master data shared across booking, customer, and offer services

## Use cases

### Merchant contact synchronisation

Merchants synchronise their CRM with Gridbees by streaming contacts via `/contact/stream`, upserting new records through `/contact/upsert`, and managing custom attributes with `/contact/addattributes` and `/contact/deleteattributes.` The contact endpoints support both targeted search and bulk streaming so the integration scales as the merchant database grows.

Example prompt: Stream contacts via `/contact/stream` for the last 24 hours and upsert each row into the merchant CRM, then call `/contact/addattributes` to flag any new segment tags.

### Offer and order orchestration

The Offer Service composes products into commercial bundles with prices, additional services, and a publication period; the Booking and Customer services then turn published offers into orders made up of order lines for individual customers. Orders carry the addresses, amounts, and payment metadata that downstream fulfilment systems require, all in UTC timestamps.

Example prompt: Create an offer through the Offer Service that bundles two products with a price and a 30-day publication window, then create an order on that offer for an existing customer record.

### Promotion and pricing rules

The Promotion Service evaluates pricing rules against the current basket of offers and customer attributes to determine which discounts apply, while the Pricing Service exposes the underlying price calculations. Together they let a merchant centralise promotional logic without coding it into each storefront or POS surface.

Example prompt: Submit a basket containing two offers and a customer ID to the Promotion Service, retrieve the applicable promotion, and return the final price from the Pricing Service.

### Agent integration via Jentic

An AI assistant for a merchant can search Jentic for 'upsert a Gridbees contact', load the `/contact/upsert` schema, and execute the call without exposing the OAuth token or API key. The same agent can chain into offer and pricing operations to compose a promotional bundle without ever browsing the 77-endpoint surface manually.

Example prompt: Search Jentic for 'upsert a Gridbees contact', load the `/contact/upsert` schema, and execute it with a contact payload pulled from the merchant CRM.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/contact/search` | Search merchant contacts |
| POST | `/contact/upsert` | Insert or update a contact |
| GET | `/contact/get/{contactid}` | Retrieve a contact by ID |
| POST | `/contact/addattributes` | Add custom attributes to a contact |
| POST | `/contact/deleteattributes` | Remove custom attributes from a contact |
| POST | `/webaccount/activate` | Activate a customer web account |
| POST | `/webaccount/check` | Check whether a web account is active |

## Key resources

- **Customer Service** — Manage contacts and web accounts, including search, upsert, and attribute updates
- **Booking Service** — Create and manage orders composed of order lines
- **Promotion Service** — Evaluate promotion rules against baskets of offers
- **Offer Service** — Compose products into priced offers with publication windows
- **MasterData Service** — Reference data shared across the Gridbees services
- **Product Service** — Manage SKU-level product records
- **Pricing Service** — Compute prices for offers and orders

## Why Jentic

- **Setup:** Wiring the Gridbees Promotion Engine by hand means running its OAuth2 flow, refreshing tokens, and coding contact, web account, and promotion calls yourself. Through Jentic you install once, import the Promotion Engine from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** Gridbees puts the contact id in the URL path (`/contact/get/{contactid}`), so a rule can pin your agent to reading one contact: it can search contacts and read that contact's record. You choose the operations it may call, so upserting contacts and deleting attributes are not included unless you add them.
- **Credential handling:** Your Gridbees OAuth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search Gridbees contacts' or 'activate a web account', and Jentic returns the matching Gridbees operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Shopify Admin API** — Hosted commerce platform with built-in storefront, orders, and discounts
- **Magento Commerce API** — Open-source and commerce-cloud platform with promotion rules and order management
- **Stripe API** — Card and wallet payment processor that pairs with the Gridbees order flow

## FAQ

### What authentication does the Gridbees Promotion Engine use?

Gridbees uses OAuth 2.0 over HTTPS, and every call additionally requires an API key. Through Jentic the OAuth client and API key are stored in your Jentic One instance, and the agent receives only the access token needed for the operation it is executing.

### Can I bulk-import merchant contacts into Gridbees?

Yes. `/contact/stream` is intended for high-volume reads, `/contact/upsert` handles insert-or-update writes, and `/contact/addattributes` lets you attach custom attributes to existing contacts without rewriting the full record.

### What are the rate limits for the Gridbees API?

The OpenAPI specification does not declare rate limits, and this is the public mock host. Confirm production limits with Gridbees before running large jobs and back off on HTTP 429.

### How do I create a Gridbees order through Jentic?

Run pip install jentic, search Jentic for 'create a Gridbees order', load the Booking Service operation schema, and execute it with the customer ID and the offer IDs that should be on the order. Jentic injects the OAuth token and API key automatically.

### Why does the base URL point at mock.gridbees.com?

This specification targets the public Gridbees mock host used for sandbox testing. Production integrations should swap the base URL for the merchant's production Gridbees endpoint while keeping the same path and method shape.

### Is the Gridbees API free to use?

Gridbees is a commercial commerce platform; production access is gated by a merchant contract. The mock host is intended for evaluation and testing. Get started with Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the Gridbees Promotion Engine API?

Yes. Because Jentic One is self-hosted, you write the rules that decide which Gridbees operations and credentials your agent may use. Since Gridbees puts the contact id in the URL path (`/contact/get/{contactid}`), you can pin the agent to reading a single contact and searching contacts while leaving writes like `/contact/upsert` and attribute deletion out of scope. Those operations are only available to the agent if you explicitly add them to its allowed set.