Checkout Lifecycle

The Checkout API facilitates the transition from a shopping session to a confirmed transaction. It enforces real-time inventory validation, calculates final totals, and secures payments via our native Stripe and Paystack integrations.

The 3-Step Handshake

1Initialize: Send the cart and address details to obtain a Gateway Authorization URL.
2Payment: The shopper completes the transaction on the provider's secure hosted page.
3Finalize: Verify the transaction reference to deduct inventory and create the order.

01. Initialize Checkout

This endpoint calculates the Grand Total by summing the database-stored product prices and your provided tax/shipping costs. It also locks the shipping details into the cart record.

POST /v1/checkout/initialize

JSON BODY

cartId (uuid)Required. Must be owned by the authenticated customer.
callbackUrl (url)Required. The success page on your storefront.
shippingAddress / billingAddress (object)Required. Objects containing first_name, line1, city, country, etc.
taxAmount / shippingAmount (number)Optional. Decimals (e.g. 5.50). We automatically convert these to integers for the gateway.

Implementation

const addressDetails = {
    first_name: 'John',
	last_name: 'Doe',
	line1: 'Street 1',
	line2: 'Street 2', // Optional
	city: 'City,
	state: 'State,
	postal_code: 'code',
	country: 'Country',
	phone: 'Phone',
}

const shippingInfo = {
  shipping: addressDetails,
  billing: addressDetails
}
  
const startCheckout = async (cartId, shippingInfo) => {
  const res = await fetch('https://api.electivecommerce.com/v1/checkout/initialize', {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token')
    },
    body: JSON.stringify({
      cartId: cartId,
      callbackUrl: window.location.origin + '/order-success',
      shippingAddress: shippingInfo.shipping,
      billingAddress: shippingInfo.billing,
      taxAmount: 5.00,      // Optional: calculated by your frontend/service
      shippingAmount: 10.00 // Optional: calculated by your frontend/service
    })
  });

  const { success, payment } = await res.json();
  if (success) {
    // Redirect shopper to the payment gateway (Stripe/Paystack)
    window.location.href = payment.authorization_url;
  }
};

02. Verify & Finalize

After payment, the shopper returns to your callbackUrl with a reference. Call this endpoint to move the order to the processing state.

POST /v1/checkout/verify

JSON BODY

reference (string)Required. The transaction reference from the URL query params.
cartId (uuid)Required. Used to reconcile the final order items.

Implementation

const finalizeOrder = async () => {
  const params = new URLSearchParams(window.location.search);
  const ref = params.get('reference') || params.get('trxref');
  const cartId = localStorage.getItem('active_cart_id');

  const res = await fetch('https://api.electivecommerce.com/v1/checkout/verify', {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token')
    },
    body: JSON.stringify({ cartId, reference: ref })
  });

  const { success, orderId } = await res.json();
  if (success) {
    // Display Order #orderId to the customer
    localStorage.removeItem('active_cart_id');
  }
};

Plan Constraints & Security

Elective Commerce enforces strict payment rules based on your store's subscription status. Failure to adhere to these will result in 403 Forbidden errors.

Restriction	Free Plan	Pro Plan
Allowed Keys	Test Keys Only (pk_test_...)	All Keys (Test + Live)
Transaction Mode	Sandbox / Simulation	Live Production
Subscription Expiry	Not Applicable	If expired, Checkout endpoints are disabled immediately.