Once the cart is complete and shipping information is set, you're ready to initiate checkout. This step creates a payment session using your configured gateway (e.g. Stripe). The customer is then redirected to a secure hosted checkout page to complete their purchase.

This section covers:

• Checkout overview
• Customizing the checkout flow
• Common checkout errors

📘

Note: Full request/response schemas are available in the API reference

🛒 Checkout Overview

• Checkout is triggered via a single API call
• A secure payment session is created
• A url is returned — redirect the user to this page to complete payment

Endpoint: POST /checkout/:cart_id

Response:

json

JavaScript Example:

javascript

💳 Sample Hosted Checkout Page

💡

Testing your flow: Use test cards such as 4242 4242 4242 4242 with:

• A valid future date, such as 12/34

• Any 3-digit CVC (or 4-digit for Amex)

• Any name, address, or other form fields.

For more options, see Stripe Documentation

🛠️ Customizing the Checkout Flow

Diddo supports flexible checkout configurations depending on your needs:

• Hosted Checkout (default): Stripe-hosted, secure, and compliant
• Embedded Checkout: Integrate Stripe Elements for a fully branded frontend experience
• Custom Gateways: Have your own payment provider? We can support it with a tailored flow

💬

Need a custom setup? Contact our team to configure embedded flows, multi-gateway support or custom integrations.

⚠️ Common Checkout Validation Errors

Before a checkout session is created, the API validates the cart for completeness. If any required information is missing or invalid, the request will return a structured error response with an appropriate HTTP status code.

🛒 Cart Not Found

1. Status: 400 Bad Request
2. Code: CART_NOT_FOUND

json

🔁 Cart Already Submitted

1. Status: 409 Conflict
2. Code: ALREADY_SUBMITTED
3. Reason: A checkout session has already been created for this cart.

json

👤 Missing Buyer Information

1. Status: 400 Bad Request
2. Code: BUYER_IDENTITY_MISSING
3. Reason: Customer information is required before proceeding to checkout.

json

💰 Missing Total Cost

1. Status: 400 Bad Request
2. Code: MISSING_TOTAL_COST
3. Reason: Cart has no total cost value. Typically indicates misconfigured pricing or variants.

json

🏬 Missing Store Information

1. Status: 400 Bad Request
2. Code: MISSING_STORES or MISSING_STORE_DOMAIN
3. Reason: Every cart must contain at least one valid store with a domain.

json

🚚 Shipping Method Not Selected

1. Status: 422 Unprocessable Entity
2. Code: SHIPPING_ADDRESS_UNAVAILABLE
3. Reason: A shipping method must be selected before initiating checkout.

json

📦 Missing or Invalid Cart Lines

1. Status: 400 Bad Request
2. Code: MISSING_CART_LINES or VARIANT_NOT_FOUND
3. Reason: Cart items are missing or improperly configured.

json

💡

Frontend Tip: Validate the cart state before initiating checkout to avoid unnecessary API calls and user friction. See Error Handling for recovery strategies and retry logic.

🔗 Next: Error Handling →