# 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-tech.com
```

### Base URL

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

`https://api.gett-tech.com/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-tech.com/v1/marketfront/stores/discover \
  -H "Authorization: Bearer $GETT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "latitude": 40.7484,
      "longitude": -73.9857
    }
  }'
```

Response:
```json
{
  "stores": [
    {
      "storeId": "store_abc123",
      "catalogSetId": "catalogset_xyz789",
      "name": "Pizza Palace",
      "description": "Authentic New York pizza since 1985",
      "imageUrl": "https://images.gett-tech.com/stores/pizza-palace.jpg",
      "rating": 4.5,
      "reviewCount": 128,
      "distanceMiles": 0.8,
      "isAcceptingOrders": true
    }
  ],
  "totalCount": 42,
  "hasMore": true
}
```

### Get a Store's Menu

Fetch the CatalogSet (this is cacheable!):

```bash
curl https://api.gett-tech.com/v1/marketfront/catalog-sets/catalogset_xyz789 \
  -H "Authorization: Bearer $GETT_API_KEY"
```

## Step 4: Test in Sandbox

The sandbox environment provides test data for development:

### Test Addresses

| Address | Location | Available Stores |
|---------|----------|------------------|
| `123 Test Street, New York, NY 10001` | NYC | Multiple test stores |
| `456 Demo Avenue, Los Angeles, CA 90001` | LA | Multiple test stores |

### Test Stores

| Store ID | Name | Features |
|----------|------|----------|
| `store_pizza_test` | Pizza Palace | Full menu, delivery & pickup |
| `store_burger_test` | Burger Barn | Simple menu, delivery only |
| `store_sushi_test` | Sushi Supreme | Complex menu, pickup only |

Each store's supported fulfillment types are exposed on the Store response via the top-level `deliveryAllowed` and `pickupAllowed` flags. Use these to filter discovery results and to label restaurant cards — do not infer capability from the presence of a delivery zone or from a store name.

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

| Card Number | Result |
|-------------|--------|
| `4111 1111 1111 1111` | Successful payment |
| `4000 0000 0000 0002` | Payment declined |
| `4000 0000 0000 9995` | Insufficient funds |

Use any future expiration date and any 3-digit CVV. See [Payments](/distribution-partners/shared-guides/payments) for more details on payment integration.

## 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 the [API Reference](/api/marketfront) for rate limits, caching strategies, and security best practices.

## 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