Mock Gridbees Promotion Engine
Community OpenAPI document · agent-readyE CommerceOrder Managementoauth277 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Manage Gridbees commerce data - contacts, products, offers, orders, and promotions - across 77 endpoints in the Promotion Engine sandbox.
Use for: I need to search for a Gridbees contact by attribute, Upsert a Gridbees contact record, Activate a Gridbees web account, Check whether a Gridbees web account is active
Not supported: Does not handle card payment capture, shipping label generation, or storefront rendering - use for Gridbees commerce data, offers, orders, and promotions only.
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.
Install Jentic One Beta
Connect the Promotion Engine to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Promotion Engine, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmock.gridbees.com%2Fgridbees" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fmock.gridbees.com%2Fgridbees" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Promotion Engine API.
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
Patterns agents use Promotion Engine API for, with concrete tasks.
★ 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.
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.
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.
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.
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
77 endpoints — gridbees promotion engine is a merchant-facing e-commerce backend that manages contacts, products, offers, orders, pricing, and promotions across the gridbees commerce stack.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Complementary
Stripe API
Card and wallet payment processor that pairs with the Gridbees order flow
Use Stripe alongside Gridbees to take payments for orders captured by the Booking Service - Gridbees orders carry payment metadata but do not process cards.
FAQs
Specific to using Promotion Engine API through Jentic.
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.
GET STARTED