Skip to content

Checkout (V2) ​

Use these endpoints to create an order from a V2 cart.

CustomerMethod and pathAuthentication
AuthenticatedPOST /v2/carts/checkoutAuthorization: Bearer JWT_TOKEN
GuestPOST /v2/carts/guest/checkoutX-Session-Id header (required)

Every request must have the X-MerchantApiKey header. For an authenticated customer, if you send the X-Session-Id header, the API first merges the guest cart into the cart of the customer.

Request body ​

ParameterTypeRequiredDescription
firstNamestringYesFirst name of the customer. 2 to 100 characters.
lastNamestringYesLast name of the customer. 2 to 100 characters.
emailstringYesEmail address of the customer.
phoneNumberstringYesPhone number of the customer.
paymentMethodstringYesPayment method that the customer selects.
shippingAddressstringOnly for shippable itemsDelivery address.
shippingMethodstringOnly for shippable itemsShipping method.
statestringOnly for shippable itemsState of the delivery address.
citystringOnly for shippable itemsCity of the delivery address.
countrystringNoCountry of the delivery address.
areastringNoArea. 2 to 100 characters.
landmarkstringNoLandmark. 2 to 100 characters.
billingAddressstringNoBilling address, if different from the delivery address.
deliveryQuoteIdstringNoID of a delivery quote that you got before checkout.
payOfflinebooleanNoSet to true if the customer pays offline.
promoCodestringNoPromotion code to apply.
currencystringNoPayment currency. The default is the default currency of the store.
metaobjectNoExtra data to store with the order.
sessionIdstringNoGuest session ID. For a guest checkout, the X-Session-Id header has priority.
subtotal, discountAmount, shippingFee, taxAmount, totalAmountnumberNoAmounts from your storefront. The API calculates the final amounts.

NOTE

A cart that has only digital items does not need shippingAddress, shippingMethod, state and city.

Example request ​

javascript
fetch('https://api.shopsynch.com/v2/carts/checkout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer JWT_TOKEN',
    'X-MerchantApiKey': 'MERCHANT_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'John',
    lastName: 'Doe',
    email: 'john.doe@example.com',
    phoneNumber: '+2348000000000',
    paymentMethod: 'CARD',
    state: 'California',
    city: 'Los Angeles',
    shippingAddress: '123 Main St, Los Angeles, CA',
    shippingMethod: 'Standard'
  })
})
  .then(response => response.json())
  .then(data => console.log(data));

Response 200 ​

The data field is an order. It has these fields, and others:

FieldTypeDescription
id, orderNumber, status, paymentStatus, totalPricevariousMain order data.
siblingOrderIdsarray of stringsIDs of the other orders that the same checkout created. Pay and track these orders together.
bookingDate, bookingStartTime, bookingCode, bookingStatusvariousBooking details, if the order has a booking.
json
{
  "data": {
    "id": "67a6261a320f3f7368dfec35",
    "orderNumber": "ORD123456",
    "status": "PENDING",
    "paymentStatus": "PENDING",
    "totalPrice": 160.0,
    "siblingOrderIds": []
  },
  "message": "Order initiated successfully",
  "status": true
}

The sample shows some of the fields. See the Order API for all order fields.

Error responses ​

StatusMessage
400Your cart is empty. Please add items to your cart before proceeding.
400Please start a guest session first. (Guest checkout without a session ID.)
400The requested quantity is more than what we have in stock. Only N items are available.

Build with joy