Copy page

Marketfront API

Getting Started

This guide walks you through setting up a direct API integration with the Gett platform. You'll learn how to authenticate, set up your development environment, and make your first API calls.

What You Can Build

With the API integration, you have complete control over the user experience:

• Find Stores — Search for stores by location, cuisine, or keyword
• Browse Menus — Display complete CatalogSets with sections, items, and customization options
• Manage Carts — Add, update, and remove items with full modifier support
• Process Orders — Validate and place orders with delivery or pickup fulfillment
• Handle Payments — Secure payment processing with PCI-compliant infrastructure

Key Concepts

Concept	Description
Store	A merchant/restaurant offering food delivery
CatalogSet	The complete menu structure (immutable, highly cacheable)
Catalog	A specific menu within a CatalogSet (e.g., "Lunch Menu") with availability windows
Section	A menu category (e.g., "Appetizers") containing items
Item	A purchasable food product with pricing and optional modifiers
ModifierGroup	Customization options for items (e.g., "Size", "Toppings")
Cart	Shopping cart with line items (managed by your application)
Order	A validated cart submitted for fulfillment

Prerequisites

Requirement	Description
Partner Account	Contact our partnerships team to register
API Key	Secret key for server-to-server authentication (details)
Backend Server	A server to make authenticated API calls

Step 1: Get Your Credentials

After registering as a partner, you'll receive:

Credential	Environment	Purpose
Sandbox API Key	Development	Testing and development
Production API Key	Live	Production deployments

Step 2: Set Up Your Environment

Environment Variables

Code
GETT_API_KEY=your_sandbox_api_key_here
GETT_API_URL=https://api.gett.co

Base URL

There is one base URL — your API key (sandbox or production) selects the environment:

https://api.gett.co/v1

Step 3: Make Your First API Call

Find Stores

Search for stores available for delivery at a given location:

Code
curl -X POST https://api.gett.co/v1/marketfront/stores/discover \
  -H "Authorization: Bearer $GETT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": 40.7411,
      "longitude": -73.9897
    }
  }'

Response (against a sandbox key — the seeded test store described in Step 4):

Code
{
  "stores": [
    {
      "storeId": "db1d5d2e-ab32-7fe5-8e2f-d613d14dc659",
      "catalogSetId": "6e309c7b-da05-ca83-9a2e-abbcf5bccb71",
      "name": "SandboxIntegrated Test Store",
      "description": "SANDBOXINTEGRATED TEST STORE",
      "fulfillmentModes": ["PICKUP", "DELIVERY_BY_MERCHANT"],
      "distanceMiles": 0.0,
      "isAcceptingOrders": true
    }
  ],
  "totalCount": 1,
  "hasMore": false
}

These are the sandbox store's actual ids. They are derived deterministically from the store's name, so they survive a re-seed and are stable to develop against — but read them from this response rather than hard-coding them in your client, because nothing about that stability is part of the API contract. A live key returns real merchants here, and Store carries further optional fields (imageUrl, rating, reviewCount, priceLevel, categories, availability) that the sandbox store does not populate.

Get a Store's Menu

Fetch the CatalogSet (this is cacheable!):

Code
curl https://api.gett.co/v1/marketfront/catalog-sets/b6e10d92-47af-4c38-8b21-9e5d0a7f6c14 \
  -H "Authorization: Bearer $GETT_API_KEY"

Step 4: Test in Sandbox

The sandbox is seeded with a single deterministic test store. Discover it by searching at its location:

Test Location

Field	Value
Latitude	40.7411
Longitude	-73.9897
Address	1 Sandbox Plaza, New York, NY 10001

Code
curl -X POST https://api.gett.co/v1/marketfront/stores/discover \
  -H "Authorization: Bearer $GETT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "location": { "latitude": 40.7411, "longitude": -73.9897 } }'

Test Store

Field	Value
Name	SandboxIntegrated Test Store
Fulfillment	Delivery & pickup
Menu	Sandbox Classic Burger ($9.50, with an "Add-ons" modifier group), Sandbox Fries ($3.50), Sandbox Cola ($2.50)

The discovery response returns the store's storeId and catalogSetId — use those for GET /catalog-sets/{catalogSetId} and when building a cart. They're stable, but read them from the API rather than hard-coding them.

Each store's supported fulfillment types are exposed on the Store response as fulfillmentModes, an array of the same FulfillmentType values the discovery filter and the order graph use (PICKUP, DELIVERY_BY_MERCHANT). Filter or badge stores off this set — do not infer capability from the presence of a delivery zone or from a store name. The array is empty only for a store that offers neither mode.

Per-store capability flags (how a supported mode can be used) are nested under options:

Field	Meaning
options.acceptsDeliveryTips	Whether this store accepts tips on delivery orders.
options.acceptsPickupTips	Whether this store accepts tips on pickup orders.

Hide the tip input in your UI (and send amounts.tip = 0) when the relevant flag is false. Submitting a non-zero tip for a mode the store doesn't accept tips in will fail validation. Tips are submitted as amounts.tip on validateOrder and placeOrder requests — see Order Amounts in the Payments guide for the full amounts shape. The options object may include additional fields in future API versions — your client should ignore any field it doesn't recognize.

Test Payment Cards

These cards work only against a sandbox API key and a sandbox store. A live key will never produce this behaviour.

No payment processor is contacted and no card is ever charged. The sandbox interprets these numbers itself and synthesizes the outcome — nothing leaves Gett. The numbers follow the widely-used test-card convention, so fixtures you already have will usually transfer unchanged; they are not credentials for, and will not behave the same against, any third-party service.

Each card produces a specific errors[].code on place, so you can drive payment and order-availability failure handling without a real provider call:

Card Number	errors[].code	Scenario
4111 1111 1111 1111	—	Successful payment
4242 4242 4242 4242	—	Successful payment
4000 0000 0000 0002	PAYMENT_FAILED	Declined, no reason given
4000 0000 0000 9995	INSUFFICIENT_FUNDS	Declined for insufficient funds
4000 0000 0000 0127	INCORRECT_CVC	Declined — security code did not match
4000 0000 0000 0069	CARD_EXPIRED	Declined — card expired
4000 0000 0000 9987	CARD_LOST_OR_STOLEN	Declined — card cannot be used
4000 0000 0000 9979	CARD_LOST_OR_STOLEN	Declined — card cannot be used
4000 0000 0000 0119	PROCESSING_ERROR	Temporary fault at the processor
4000 0566 5566 5556	DELIVERY_UNAVAILABLE	Delivery address is outside the service area
5555 5555 5555 4444	STORE_CLOSED	Store is currently closed

Use any future expiration date and any 3-digit CVV. Any card number not listed here is approved, so you can use your own fixtures for happy-path testing.

Two notes on handling these:

• CARD_LOST_OR_STOLEN is returned for both cards on purpose, and its message is deliberately the same generic decline copy as PAYMENT_FAILED. Branch on the code if you need to, but do not tell a cardholder their card is reported lost or stolen.
• PROCESSING_ERROR is the only scenario here where retrying the same card is sensible. The rest are decisions about the card; ask for a different payment method.

errors[].code is an open enum — treat any code you do not recognise as a generic payment failure rather than hard-failing. See Order lifecycle → Error codes for the full list, and Payments for payment integration generally.

Step 5: Implement the Order Flow

A typical order flow involves these API calls in sequence:

Every call uses your partner API key — there is no session layer on the partner API surface. Supply the Idempotency-Key header on placeOrder to make order submission safe to retry, and carry the end user's client context on the order body:

Code
const response = await fetch(`${GETT_API_URL}/v1/marketfront/orders/place`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${GETT_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    ...orderPayload,
    // Required. Forward the customer's own values from the request your front
    // end received — not your server's. See "End-user client context".
    client: { ip: customerIp, userAgent: customerUserAgent },
  }),
});

See the Order Lifecycle for state machine details, and the API Reference for request/response schemas.

Going to Production

When you're ready to go live, swap your sandbox key for your production key — the base URL is unchanged:

1. Switch to your Production API Key
2. Remove any test data references
3. Verify the integration with a small batch of real orders

See Conventions for rate limits, caching strategies, and error handling, and the API Reference for the full endpoint and schema documentation.

Next Steps

• Authentication — API keys, environments, and security best practices
• Order Lifecycle — State machine and status transitions
• Payments — Payment integration options
• Schemas — Type definitions and data models
• API Reference — Complete endpoint documentation