canonical: https://jentic.com/apis/beebs.app/beebs

# Beebs App Orders API

The Beebs Orders API manages marketplace orders and their payments. It lists a buyer's orders, reads a single order, and moves an order through its lifecycle with cancel, litigation cancel, additional depositing time, in-delivery, retrieved, and seller return-approval actions. Payment operations take Apple Pay and Google Pay, including an Apple Pay session setup.

## For AI agents

List and read marketplace orders, advance them through cancel, delivery, retrieved, and return states, and take Apple Pay and Google Pay payments. Returns JSON over a REST API authenticated with an API key.

## Scope

Does not manage product catalogues, inventory, or shipping labels. Use for marketplace order lifecycle and Apple Pay and Google Pay payments only.

## Capabilities

- List a buyer's marketplace orders and read a single order's detail
- Cancel an order or cancel a litigation on it
- Advance an order through depositing, delivery, and retrieved states
- Approve a buyer's return request as the seller
- Take payments through Apple Pay and Google Pay

## Use cases

### AI Agent Order Integration via Jentic

An agent that handles marketplace fulfilment can call the Beebs Orders API through Jentic without wiring the API key or shaping the payment payloads. The agent searches by intent, receives the operation schema, and lists orders or advances one through its lifecycle. This fits seller-side agents that track orders and confirm deliveries.

Example prompt: Search Jentic for 'list my orders', load the operation schema, and read back the buyer's orders

### Order Lifecycle Management

Move an order from placement through delivery and completion. The Beebs Orders API lets an agent list orders, read one, grant additional depositing time, mark it in delivery, mark it retrieved, or cancel it, so a fulfilment workflow can advance each order to its next state.

Example prompt: Call GET /orders to list orders, then POST `/orders/{id}/in-delivery` to mark one in delivery

### Seller Return Approval

Let a seller agent approve a buyer's return on a specific order. The Beebs Orders API exposes a seller return-approval action and a litigation-cancel action, so an agent can resolve returns and disputes directly against the order.

Example prompt: Call POST `/orders/{id}/sellerApproveReturn` to approve a buyer's return

### Marketplace Payments

Take payment for an order through Apple Pay or Google Pay. The Beebs Orders API processes an Apple Pay or Google Pay payment and can open an Apple Pay session first, so a checkout agent can complete payment alongside the order it belongs to.

Example prompt: Call POST `/payment/applepay` to take an Apple Pay payment for an order

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/orders` | List the buyer's orders |
| GET | `/orders/{id}` | Get one order |
| POST | `/orders/{id}/cancel` | Cancel an order |
| POST | `/orders/{id}/in-delivery` | Mark an order in delivery |
| POST | `/orders/{id}/retrieved` | Mark an order retrieved |
| POST | `/orders/{id}/sellerApproveReturn` | Approve a return as the seller |
| POST | `/payment/applepay` | Make an Apple Pay payment |
| POST | `/payment/googlepay` | Make a Google Pay payment |

## Key resources

- **Orders** — List, read, and advance orders through their lifecycle states
- **Payment** — Apple Pay and Google Pay payments and Apple Pay session setup

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 14 / 100
- **Maturity:** Non-Ready
- **Dimensions:**
  - Foundational Compliance: 90 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 4 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 16 / 100
- **View full report:** https://jentic.com/apis/beebs.app/beebs/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Beebs Orders API by hand means managing its API key in the Authorization header, pointing calls at the right order id, and shaping the Apple Pay and Google Pay payment payloads yourself. Through Jentic you install once, import Beebs from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Beebs puts the order id in the URL path (`/orders/{id}/...`), so a rule can pin your agent to one order and the operations you pick. You choose the operations it may call, so state-changing ones like cancelling an order or approving a return are not included unless you add them.
- **Credential handling:** Your Beebs API key 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 'list my orders' or 'take an Apple Pay payment', and Jentic returns the matching Beebs operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Flipkart Seller API** — Alternative marketplace seller order management
- **Squarespace Commerce API** — Alternative commerce order and inventory management
- **Loop Returns API** — Dedicated returns and exchange workflows

## FAQ

### Is there a Beebs MCP server?

You don't need a separate MCP server to give your agent the Beebs Orders API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the order and payment operations it needs.

### Can I limit what my agent is allowed to do with the Beebs Orders API?

Yes. The order id sits in the URL path, so you write a rule that allows reading orders and marking delivery for one order, and the agent can advance that order while cancelling it or approving returns stays out of reach. Every call is logged by your self-hosted instance.

### What authentication does the Beebs Orders API use?

The Beebs Orders API authenticates with an API key sent in the Authorization header, per its OpenAPI spec. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time, so it never reaches the agent's context.

### Can I take Apple Pay and Google Pay payments with the Beebs Orders API?

Yes. One operation processes an Apple Pay payment and another processes a Google Pay payment, with a separate call to open an Apple Pay session first. These sit alongside the order lifecycle operations.

### What are the rate limits for the Beebs Orders API?

The OpenAPI spec does not specify rate limits. Check the vendor's documentation at https://beebs.app for current limits.

### How do I list orders with the Beebs Orders API through Jentic?

Search Jentic for 'list my orders' and it returns the Beebs orders operation with its input schema; the agent reads back the buyer's orders as JSON. To run it on your own infrastructure, install Jentic One from its GitHub repo.