Promotion Engine

Name: Promotion Engine API
Brand: Promotion Engine
Availability: InStock

★ Only Publicly Available OpenAPI DocumentE CommerceOrder Managementoauth277 EndpointsREST

For Agents

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

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.

Install Jentic One Beta (Self-Hosted)

Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic 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

GET STARTED

Start building with Promotion Engine API

Explore with Jentic

View OpenAPI Document

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.

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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

Gridbees OAuth 2.0 client credentials and the per-call API key are stored in the Jentic MAXsystem vault. Agents never see the secret or key; Jentic injects the OAuth token and API key header at execution time.

Intent-based discovery

Agents search Jentic for intents like 'upsert a Gridbees contact' or 'create a Gridbees order' and Jentic returns the matching Customer Service or Booking Service operation with its input schema.

Time to first call

Direct Gridbees integration: 3-5 days to wire OAuth, the per-call API key, and the 77-endpoint surface across services. Through Jentic: under 1 hour to make the first call once credentials are vaulted.

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 the MAXsystem vault, 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 at https://app.jentic.com/sign-up.

Promotion Engine

Connect the Promotion Engine to your agent

Capabilities

Start building with Promotion Engine API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs