Endpoint index & limits
Every endpoint on the partner API in one place, with its rate limit, plus the limits and defaults the products run on.
On this page
Conventions#
| Base URL | https://api.mm2empire.com |
| Authentication | X-Partner-Key: <secret> on every request. See Authentication. |
| Content type | application/json for every request body and response. |
| Money | Integer US cents. Fields end in Cents; responses carry "currency": "USD". |
| Timestamps | ISO 8601 with offset, for example 2026-09-05T13:21:04+00:00. |
| Writes | Every POST marked below takes an Idempotency-Key header (≤ 128 characters). See Core concepts. |
| Errors | { "error": { "code", "message", "retryable" } }. See Errors. |
| Rate limits | Per company per route family per minute, shared across your keys. 429 with Retry-After. |
| Paging | limit and offset query parameters; responses carry items, total, limit, offset. |
General#
| Endpoint | Purpose | Limit / min |
|---|---|---|
GET /partner/v1/ping | Prove a key works; returns your slug, the key id and our server time. | — |
MM2 Payments — /partner/v1/payments#
| Endpoint | Purpose | Limit / min |
|---|---|---|
POST /customers ⁱ | Link a customer (Roblox username or id, optional externalRef). | 60 |
GET /customers | List linked customers. search, limit ≤ 200. | 120 |
GET /customers/{ref} | One customer by any identifier. | 120 |
GET /customers/{ref}/inventory | What they hold, stacked, with your quote per stack. game, limit ≤ 100. | 60 |
POST /sessions ⁱ | Open a pop-up session; returns token and URL. | 60 |
GET /sessions/{id} | Session status, payments, orderCompletedAt. | 120 |
POST /sessions/{id}/close | End a session and fire its order rollup now. | 60 |
POST /quote | Price stacks without selling. | 60 |
POST /sell ⁱ | Sell stacks to you. Per-item outcomes. | 20 |
GET /payments | Payments taken. orderId, sessionId, customerRef, limit ≤ 200. | 120 |
GET /payments/{id} | One payment. | 120 |
GET /orders/{orderId} | Everything under one of your order ids. | 120 |
GET /items | Your rate card. search, itemType, rarity, limit ≤ 100. | 60 |
POST /deposits ⁱ | Where a customer sends items: live bots, join links, pop-up URL. | 60 |
POST /withdrawals ⁱ | Return a customer's own items to their Roblox account. ≤ 4 item types. | 20 |
GET /withdrawals/{id} | One withdrawal's status. | 120 |
ⁱ takes an Idempotency-Key.
MM2 Payouts — /partner/v1/payouts#
| Endpoint | Purpose | Limit / min |
|---|---|---|
GET /listings | The catalogue at your prices. Filters, sort, limit ≤ 100, offset ≤ 5000. | 120 |
POST /orders ⁱ | Buy up to 4 stacks / 100 items for a customer and start delivery. | 30 |
GET /orders/{id} | One order, by our id or yours. | 120 |
POST /sessions ⁱ | Open a shop pop-up with a retail multiplier. | 60 |
GET /claims?customerRef= | What one customer still has to collect, and which bot holds it. | 120 |
GET /pool | Float balance, mode and your markup. | 60 |
Limits and defaults#
| Setting | Value | Notes |
|---|---|---|
| Session token lifetime | 5 minutes | One-time. Exchanged when the pop-up opens. |
| Pop-up access window | 30 minutes default, 60 maximum | ttlSeconds on session creation. |
orderId length | 120 characters | Trimmed. Not required to be unique. |
metadata | 20 keys, scalar values | Strings, integers, booleans or null. No nesting. |
| Idempotency key length | 128 characters | |
| Stacks per sell request | 200 | MM2 Payments /sell. |
| Item types per withdrawal or payout order | 4 | One in-game delivery carries at most four stacks. |
| Items per payout order | 100 | |
| Payout order ceiling | $1,000 default | maxOrderCents, set in the console. Optional daily cap. |
| Retail multiplier | 1.0× to 5.0× | retailMultiplierBps 10000–50000. Rounds up. |
| MM2Empire margin on payouts | Set by staff, at most 100% | markupBps, read-only for partners. |
| Default buy rate (own pool, custom rates) | 50% of catalogue value | defaultBuyRateBps 5000. Seeded from ours on switch. |
| Default stock limit per item | 10 copies | maxInventory. |
| Default relist markup | 10% over value | relistMarkupBps 1000; may be negative down to −50%. |
| Minimum payout | $0.01 default | minPayoutCents. |
| Setting cooldowns | 15 minutes | Funding source, pricing mode, pool mode, claiming earnings. |
| Webhook signature tolerance | 300 seconds | |
| Webhook retries | 20 attempts, exponential backoff to hourly | |
| Webhook delivery log retention | 30 days | |
| Webhook URL length | 2048 characters | https, port 443, public host. |
Changes to the API#
The machine rail is a published contract. Fields are added, never removed or renamed, and a new field is always optional to read. Event types are added under new names; existing payloads keep their shape. If you parse responses strictly, allow unknown fields.