# 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](/distribution-partners/shared-guides/authentication)) |
| **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

```bash
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:

```bash
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):
```json
{
  "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!):

```bash
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` |

```bash
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](/distribution-partners/shared-guides/payments#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](/distribution-partners/marketfront-api/guides/order-lifecycle#error-codes)
for the full list, and [Payments](/distribution-partners/shared-guides/payments) for payment
integration generally.

## Step 5: Implement the Order Flow

A typical order flow involves these API calls in sequence:

<Mermaid chart={`graph TD
    A[API Key] --> B[Discover Stores]
    B --> C[Get Store by ID]
    C --> D[Get CatalogSet]
    D --> E[Build Cart]
    E --> F[Validate Order]
    F --> G[Place Order with Idempotency-Key]`} />

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:

```typescript
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](/distribution-partners/marketfront-api/guides/order-lifecycle) for state machine details, and the [API Reference](/api/marketfront#validateOrder) 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](/distribution-partners/marketfront-api/conventions) for rate limits, caching strategies, and error handling, and the [API Reference](/api/marketfront) for the full endpoint and schema documentation.

## Next Steps

- **[Authentication](/distribution-partners/shared-guides/authentication)** — API keys, environments, and security best practices
- **[Order Lifecycle](/distribution-partners/marketfront-api/guides/order-lifecycle)** — State machine and status transitions
- **[Payments](/distribution-partners/shared-guides/payments)** — Payment integration options
- **[Schemas](/api/marketfront/~schemas)** — Type definitions and data models
- **[API Reference](/api/marketfront)** — Complete endpoint documentation