Skip to content
/
Integration Checklist
Last updated

Integration Checklist

This checklist guides you through integrating with the Tote Online Ordering API in 10 milestones. Each milestone builds on the previous one, following the natural API dependency chain. Complete each milestone before moving to the next.

Milestone 1: Sandbox Access

Getting Started | Authentication

  • Complete partner onboarding to receive your base URL, client_id, and client_secret
  • Authenticate and receive an access token (POST /auth/token)
  • Cache the token and handle 24-hour expiry with automatic refresh
  • Confirm error responses match the documented error envelope format
  • Verify your client handles 401 responses by re-authenticating

Milestone 2: Menu & Location Sync

Menu Sync | Modifiers Deep Dive

  • List locations accessible to your credentials (GET /locations)
  • Retrieve a full menu for a location (GET /locations/{locationId}/menu)
  • Parse nested modifier groups (up to 3 levels deep)
  • Implement menu metadata polling for cache invalidation (GET /locations/{locationId}/menu/metadata)
  • Handle items with time windows (daily_sales_start_time / daily_sales_end_time)
  • Display age-restricted item indicators (age_verification_required)

Milestone 3: Cart Management

Cart Lifecycle

  • Create a cart for a location (POST /carts)
  • Add an item with modifier selections (POST /carts/{cartId}/items)
  • Update item quantity (PUT /carts/{cartId}/items/{itemId})
  • Remove an item from the cart (DELETE /carts/{cartId}/items/{itemId})
  • Calculate prices server-side (POST /carts/{cartId}/calculate)
  • Enforce max_allowed_quantity limits in your UI
  • Handle 422 validation errors (modifier constraints, unavailable items)

Milestone 4: Checkout & Payments

Checkout & Payments

  • Set the handoff mode on the cart (PUT /carts/{cartId}/handoff)
  • Submit checkout with expected_total for optimistic concurrency (POST /carts/{cartId}/checkout)
  • Submit a single payment with an Idempotency-Key header (POST /orders/{orderId}/payments)
  • Handle payment declined (422) and retry with a different tender
  • Verify payment reaches COMPLETED status

Milestone 5: Split Payments

Checkout & Payments

  • Submit a split payment sequence: loyalty, then gift card, then credit/debit
  • Handle partial payment failure (tender 2 of 3 fails) with documented recovery options
  • Verify the order's payment_status transitions to PAID after all tenders succeed
  • Use unique Idempotency-Key per payment submission
  • Confirm remaining balance updates correctly after each partial payment

Milestone 6: Order Tracking

Order Tracking

  • Retrieve an order by ID (GET /orders/{orderId})
  • List orders with cursor-based pagination and filters (GET /orders)
  • Monitor fulfillment_status transitions for order progress updates
  • Handle order cancellation (POST /orders/{orderId}/cancel)
  • Process refunds (POST /orders/{orderId}/refunds)

Milestone 7: Webhooks & Real-Time Events

Webhooks & Real-Time | Handoff Modes

  • Create a webhook subscription (POST /webhooks)
  • Implement HMAC-SHA256 signature verification on your webhook endpoint
  • Process events idempotently (deduplicate by event_id)
  • Handle all 6 event types: order.created, order.status_changed, order.cancelled, stock.updated, menu.changed, location.hours_changed
  • Implement 5-minute reconciliation polling as a fallback
  • Support all handoff modes your integration offers (pickup, curbside, delivery, kiosk)

Milestone 8: Production Readiness

C-Store Features | Error Codes | Rate Limiting

  • Implement exponential backoff with jitter for 429 rate limit responses
  • Cache authentication tokens (do not re-authenticate per request)
  • Handle tender restrictions for c-store items (allowed_tenders field, when active)
  • Verify all error handling matches the error code reference
  • Use Idempotency-Key headers on all write operations
  • Implement circuit breakers for sustained API errors
  • Test the complete flow end-to-end: authenticate -> browse -> cart -> checkout -> pay -> track -> webhook

Milestone 9: Promotions & Fees

Promotions, Fees & Discounts

  • Validate a promo code inline (GET /carts/{cartId}/promo-codes/validate?code=CODE)
  • Apply a promo code to a cart (POST /carts/{cartId}/promo-codes)
  • Verify the discount appears in the PriceCalculation response with source: PROMO_CODE
  • Remove a promo code (DELETE /carts/{cartId}/promo-codes/{code})
  • Handle all 6 rejection reasons (INVALID_CODE, EXPIRED, ALREADY_USED, MINIMUM_NOT_MET, NOT_APPLICABLE, ALREADY_APPLIED)
  • Handle 409 Conflict when applying a second promo code (one code at a time)
  • Display automatic discounts with source: AUTOMATIC from the PriceCalculation response
  • Display fees from the fees array as separate line items (delivery, service, bag, small order)
  • Verify SMALL_ORDER fee auto-applies when cart is below location minimum
  • Handle 409 Conflict with change_reasons at checkout (re-calculate, show updated total, retry)

Milestone 10: Customer Identity & Loyalty Prep

Promotions, Fees & Discounts

  • Set customer_id at cart creation (POST /carts with customer_id field)
  • Update customer_id after browsing via PATCH (PATCH /carts/{cartId} with customer_id)
  • Verify member_pricing_applied is true in PriceCalculation when customer is recognized
  • Revert to anonymous pricing by setting customer_id to null
  • Always re-calculate prices after changing customer_id
  • Filter order history by customer (GET /orders?customer_id=CUST-ID)
  • Verify customer_id propagates from Cart to Order after checkout

This checklist covers API integration. Production infrastructure concerns (monitoring, scaling, deployment) are the partner's responsibility.

Previous page
Next page