Skip to content

README.md

Latest commit

 

History

History
199 lines (156 loc) · 8.37 KB

README.md

File metadata and controls

199 lines (156 loc) · 8.37 KB

Checkout Package

Checkout Session

Creating a Checkout Session

The createCheckoutSession function creates a new checkout session with GoDaddy's commerce API.

import { createCheckoutSession } from "@godaddy/react";

const session = await createCheckoutSession(input, options);

Checkout Session Input Configuration

The first parameter accepts all checkout session configuration options from the GraphQL schema:

Required Parameters

  • storeId (string): The ID of the store this checkout session belongs to
  • returnUrl (string): URL to redirect to when user cancels checkout
  • successUrl (string): URL to redirect to after successful checkout
  • draftOrderId (string): ID of an existing draft order (required if lineItems not provided)
  • lineItems ([CheckoutSessionLineItemInput!]): Line items to create a draft order from (required if draftOrderId not provided)

Optional Parameters

  • appearance (GoDaddyAppearanceInput): Appearance configuration for the checkout (see Appearance)
  • channelId (string): The ID of the sales channel that originated this session
  • customerId (string): Customer ID for the checkout session
  • enableAddressAutocomplete (boolean): Enable address autocomplete
  • enableBillingAddressCollection (boolean): Enable billing address collection
  • enableLocalPickup (boolean): Enable local pickup option
  • enableNotesCollection (boolean): Enable order notes collection
  • enablePaymentMethodCollection (boolean): Enable payment method collection
  • enablePhoneCollection (boolean): Enable phone number collection
  • enablePromotionCodes (boolean): Enable promotion/discount codes
  • enableShipping (boolean): Enable shipping
  • enableShippingAddressCollection (boolean): Enable shipping address collection
  • enableSurcharge (boolean): Enable surcharge fees
  • enableTaxCollection (boolean): Enable tax collection
  • enableTips (boolean): Enable tip/gratuity options
  • enabledLocales ([String!]): List of enabled locales
  • enabledPaymentProviders ([String!]): List of enabled payment providers
  • environment (enum): Environment - ote, prod
  • expiresAt (DateTime): When the session expires
  • locations ([CheckoutSessionLocationInput!]): Available pickup locations
  • operatingHours (CheckoutSessionOperatingHoursMapInput): Store operating hours configuration (see Operating Hours)
  • paymentMethods (CheckoutSessionPaymentMethodsInput): Payment method configurations
  • shipping (CheckoutSessionShippingOptionsInput): Shipping configuration — primarily used to set an originAddress for shipping rate calculations and an optional fulfillmentLocationId
  • sourceApp (string): The source application that created this checkout session
  • storeName (string): The name of the store this checkout session belongs to
  • taxes (CheckoutSessionTaxesOptionsInput): Tax configuration — used to set an originAddress for tax calculations (e.g. the store or warehouse address that taxes are calculated from)
  • url (string): Custom URL for the checkout session

Checkout Session Options

The CheckoutSessionOptions interface allows you to configure authentication and other settings:

interface CheckoutSessionOptions {
	auth?: {
		clientId: string;
		clientSecret: string;
	};
}

Authentication Options

  • auth.clientId (string): OAuth2 client ID for GoDaddy API authentication
  • auth.clientSecret (string): OAuth2 client secret for GoDaddy API authentication

When provided, these credentials will be used to obtain an access token for API requests. If not provided, the function will use empty strings which may result in authentication failures.

Environment Support

The checkout session supports multiple environments through the input parameter:

  • prod: Production environment (https://api.godaddy.com)
  • ote: OTE environment (https://api.ote-godaddy.com)

API Scopes

The checkout session automatically requests the following OAuth2 scope:

  • commerce.product:read

Operating Hours

The operatingHours field configures local pickup scheduling — time zones, lead times, pickup windows, and slot intervals.

operatingHours: {
  default: {
    timeZone: 'America/New_York',
    leadTime: 60,
    pickupWindowInDays: 7,
    pickupSlotInterval: 30,
    hours: {
      monday: { enabled: true, openTime: '09:00', closeTime: '17:00' },
      tuesday: { enabled: true, openTime: '09:00', closeTime: '17:00' },
      wednesday: { enabled: true, openTime: '09:00', closeTime: '17:00' },
      thursday: { enabled: true, openTime: '09:00', closeTime: '17:00' },
      friday: { enabled: true, openTime: '09:00', closeTime: '18:00' },
      saturday: { enabled: true, openTime: '10:00', closeTime: '16:00' },
      sunday: { enabled: false, openTime: null, closeTime: null },
    },
  },
}

Store Hours Fields

Field Type Required Description
timeZone string Yes IANA timezone for the store (e.g. America/New_York). All slot times are displayed in this timezone.
leadTime number Yes Minimum advance notice in minutes before a pickup can be scheduled. Controls the earliest available slot (now + leadTime).
pickupWindowInDays number Yes Number of days ahead customers can schedule pickup. Set to 0 for ASAP-only mode (no date/time picker).
pickupSlotInterval number No Minutes between selectable time slots (e.g. 30 → 10:00, 10:30, 11:00…). Defaults to 30 if omitted. Separate from leadTime — the interval controls slot spacing, while leadTime controls advance notice.
hours object Yes Per-day operating hours. Each day has enabled (boolean), openTime (HH:mm or null), and closeTime (HH:mm or null).

Behavior Notes

  • ASAP option — Shown for today only, when the store can fulfill an order (now + leadTime) before closing time.
  • Lead time vs slot interval — A store with leadTime: 1440 (24 hours) and pickupSlotInterval: 15 shows 15-minute slots starting tomorrow, not 24-hour gaps.
  • Timezone handling — All date/time logic uses the store's timeZone, not the customer's browser timezone. A store in Phoenix shows Phoenix hours regardless of where the customer is browsing from.
  • No available slots — When leadTime exceeds the entire pickup window, or no days are enabled, a "No available time slots" banner is shown.

Appearance

The appearance field customizes the checkout's look and feel.

appearance: {
  theme: 'base',
  variables: {
    primary: '#4f46e5',
    background: '#ffffff',
    foreground: '#111827',
    radius: '0.5rem',
  },
}

Theme

Value Description
base Default theme
orange Orange accent theme
purple Purple accent theme

CSS Variables

All fields are optional strings. Pass any subset to override the defaults.

Variable Description
accent Accent color
accentForeground Text on accent backgrounds
background Page background
border Border color
card Card background
cardForeground Text on cards
defaultFontFamily Default font family
destructive Destructive action color (errors, delete)
destructiveForeground Text on destructive backgrounds
fontMono Monospace font family
fontSans Sans-serif font family
fontSerif Serif font family
foreground Primary text color
input Input field background
muted Muted/subtle background
mutedForeground Text on muted backgrounds
popover Popover background
popoverForeground Text in popovers
primary Primary brand color
primaryForeground Text on primary backgrounds
radius Border radius (e.g. 0.5rem)
ring Focus ring color
secondary Secondary color
secondaryBackground Secondary background
secondaryForeground Text on secondary backgrounds

Codegen

For now the schema will be downloaded from the order schema.

pnpm run codegen

Todos

  • Add tests
  • Refactor some external libs
    • graphql-request
    • arktype - try valibot instead for bundle size sad to lose devx but can be mmuch smaller
    • floating ui dependencies