Copy page

SDK Guides

Sessions

Sessions allow distribution partners to establish consumer context for the ordering experience. Your platform provides user information to Gett, enabling a seamless experience with pre-filled details.

How It Works

1. User authenticates on your platform (your own auth system)
2. Your backend creates a Gett session with user information via the Gett API
3. You initialize the Marketfront SDK with the session token
4. User enjoys a seamless ordering experience with their information pre-filled

---

How the SDK Manages Sign-in

The SDK manages authentication progressively. Pass whatever user context you have at session creation — even an empty body produces a valid session suitable for anonymous browse. When the user reaches a checkout action, the embed prompts for sign-in inside its own UI; no host-page sign-in trigger is required, and you do not call any sign-in or upgrade endpoint yourself.

If you already have the user's identity at session-creation time, supply it via the request body below and the SDK skips the in-embed sign-in step.

---

Session Creation

Endpoint

Environment	URL
Sandbox	https://api-sandbox.gett-tech.com/v1/marketplace/session/create
Production	https://api.gett-tech.com/v1/marketplace/session/create

Code
POST /v1/marketplace/session/create
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Authenticated with your partner API key (server-to-server only — never call this from a browser).

Request Body

Code
{
  "partnerUserId": "user_12345",
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+15551234567",
  "address": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101"
  }
}

Every field is optional. An empty body is valid — it produces an anonymous session, and the embed prompts the user to sign in when they reach checkout.

Field	Type	Required	Description
partnerUserId	string	No	Stable user identifier in your system. Server mints a gen_<guid> if omitted.
email	string	Required when firstName or lastName is present	User's email address.
firstName	string	Required when email or lastName is present	User's first name.
lastName	string	Required when email or firstName is present	User's last name.
phone	string	No	E.164 format (e.g., +15551234567). Must be SMS-capable for order notifications.
address	object	No	Default delivery address — powers initial store discovery. See address below.

The email / firstName / lastName triple is all-or-nothing: supplying any one without the others returns 400 LEVEL_1_INCOMPLETE. Supply all three to resolve a Gett user up front, or omit all three to keep the session anonymous (the embed will prompt for sign-in at checkout).

address object

Code
{
  "address1": "123 Main St",
  "address2": "Apt 4B",
  "city": "Seattle",
  "state": "WA",
  "postalCode": "98101"
}

Field	Type	Required	Description
address1	string	Yes	Street address.
address2	string	No	Apartment, suite, unit, etc.
city	string	Yes	City.
state	string	Yes	Region or state.
postalCode	string	Yes	Postal code.

Response

Code
{
  "token": "gett_sess_abc123xyz",
  "expiresAt": "2025-01-15T12:00:00Z",
  "partnerUserId": "user_12345"
}

Field	Type	Description
token	string	Session token. Pass to the Marketfront SDK to establish consumer context.
expiresAt	string	ISO 8601 expiration timestamp.
partnerUserId	string	Echoes the caller-supplied partnerUserId, or the server-minted gen_<guid> when none was supplied. Store this to correlate sessions across token refreshes.

Using the Session Token

Initialize the Marketfront SDK with the session token returned from session creation. The session token encodes your partner identity, so no separate Partner ID is needed.

Vanilla TypeScript

Code
import '@gett-co/marketfront';

// Your backend creates the session with user data
const { token } = await yourBackend.createGettSession(user);

const el = document.createElement('gett-marketfront');
el.sessionToken = token;
document.getElementById('container')!.appendChild(el);

React

Code
import '@gett-co/marketfront';

function OrderPage({ sessionToken }: { sessionToken: string }) {
  return (
    <gett-marketfront
      session-token={sessionToken}
      onOrderComplete={(order) => console.log('Order:', order.id)}
    />
  );
}

---

Session Lifecycle

Expiration

Sessions expire 7 days after creation. The exact expiry is in the response's expiresAt field. Token lifetime is set by Gett and is not negotiable per request. Before expiration, create a new session:

Code
POST https://api.gett-tech.com/v1/marketplace/session/create

The new session will inherit any in-progress cart from the previous session for the same partnerUserId.

To end a session early (e.g., on user logout), discard the token client-side. Calls made with a discarded token will continue to authorize until its natural expiry, so don't rely on discard alone to terminate a session.

---

Security

API Key Protection

Your API key authenticates session creation requests. Never expose it in client-side code.

Code
// Never do this in frontend code
const response = await fetch('https://api.gett-tech.com/v1/marketplace/session/create', {
  headers: { 'Authorization': `Bearer ${API_KEY}` } // Exposed!
});

// Always call from your backend
const response = await yourBackend.createGettSession(userId);

Session Token Handling

Session tokens are safe for client-side use but should still be handled carefully:

• Tokens are scoped to a single session and user
• Tokens cannot be used to create new sessions
• Tokens expire automatically

Data Privacy

• User data is processed according to Gett's privacy policy
• You are responsible for obtaining appropriate consent from your users
• Gett does not share user data with third parties

---

Error Handling

Session Creation Errors

Error Code	HTTP Status	Description	Resolution
invalid_api_key	401	API key is invalid or revoked	Verify your API key
invalid_email	400	Email format is invalid	Provide valid email
invalid_phone	400	Phone format is invalid	Use E.164 format
invalid_address	400	Address could not be validated	Verify address fields
rate_limited	429	Too many requests	Implement backoff

Session Token Errors

Error Code	HTTP Status	Description	Resolution
session_expired	401	Session token has expired	Create a new session
session_invalid	401	Session token is malformed or revoked	Create a new session
session_not_found	404	Session does not exist	Create a new session

---

Next Steps

• Payments — Card-on-File setup and payment interchange
• Events — Handle order lifecycle events
• SDK Reference — Complete SDK API documentation