Checkouts

Triggering a checkout

post

This endpoint initiates a checkout for a given cart or quote. The customer must be active while the checkout is in progress. Checkout is an atomic operation — it either succeeds or fails. If a checkout request fails, an appropriate validation message is returned. Depending on the issue, the checkout payload or cart content can be adjusted to meet the validation rules, and the request can then be retried.

The checkout process performs the following operations:

• Validates checkout

  • checks if cart data is provided

  • checks if customer data is provided

  • checks if only one payment method is provided

  • checks if customer mixin is compliant with the customer mixin schema

  • checks if customer address mixin is compliant with the address mixin schema

• Validates cart data

  • checks if product prices are valid (is existing, has valid date range, quantity is valid for a wholesale price)

  • checks if the free shipping discount is properly applied (it fails when cart contains a free shipping coupon but the shipping calculation is not equal to zero)

  • checks if products in cart are valid (is existing, has a valid tax code) and still in stock

  • checks if used coupons are valid

  • checks if the currency in the cart is the same as configured for the site

  • checks if the selected delivery window capacity is valid

  • checks if the cart's delivery window has all required fields

• Creates an order

• Handles the payment

• Closes the cart

Authorizations

CustomerAccessToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Header parameters

saas-tokenstringOptional

Customer’s saasToken retrieved when logging in a customer. The header is required for customer's checkout. If the checkout is done by a guest then the header can be skipped.

Example: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2MTQ0MzU2MyIsImV4cCI6MTY5Nzk3MDUyOH0.F0b5jr6KeSoBCj-suTLuasmydaJEudc1ZrESkQXSCGk

Body

application/json

or

Responses

200

The request was successful. A unique order ID is returned.

application/json

orderIdstringOptional

Order’s unique identifier generated when a checkout is triggered.

paymentDetailsobject · nullableOptional

checkoutIdstring · nullableOptional

400

Request was syntactically incorrect. Details are be provided within the response payload.

application/json

401

Access forbidden. The authorization token has expired.

application/json

403

Authorization token's scopes do not match scopes required by the endpoint.

application/json

409

Selected delivery window does not have available capacity

application/json

500

Some server side exception occurred which prevented it from correctly returning the result.

application/json

post

/checkout/{tenant}/checkouts/order

HTTPcURLJavaScriptPython

POST /checkout/{tenant}/checkouts/order HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1167

{
  "cartId": "9b36757a-5ea1-4689-9ed3-fb630eb5048c",
  "paymentMethods": [
    {
      "provider": "payment-gateway",
      "customAttributes": {
        "customer": "635544345",
        "modeId": "9a33c7a5-9535-42af-a936-2fa6ece27579"
      },
      "method": "invoice"
    }
  ],
  "currency": "EUR",
  "shipping": {
    "methodId": "4-more_hours_timeframe",
    "zoneId": "deliveryarea",
    "methodName": "Delivery method name",
    "amount": 10,
    "shippingTaxCode": "STANDARD"
  },
  "deliveryWindowId": "cbda2a28-f0cc-11ed-a05b-0242ac120003",
  "addresses": [
    {
      "contactName": "John Doe",
      "companyName": "Emporix",
      "street": "Fritz-Elsaas",
      "streetNumber": "20",
      "streetAppendix": "",
      "zipCode": "70173",
      "city": "Stuttgart",
      "country": "DE",
      "state": "",
      "contactPhone": "123456789",
      "type": "SHIPPING",
      "metadata": {
        "mixins": {}
      },
      "mixins": {}
    },
    {
      "contactName": "John Doe",
      "companyName": "Emporix",
      "street": "Fritz-Elsaas",
      "streetNumber": "20",
      "streetAppendix": "",
      "zipCode": "70173",
      "city": "Stuttgart",
      "country": "DE",
      "state": "",
      "contactPhone": "123456789",
      "type": "BILLING",
      "metadata": {
        "mixins": {}
      },
      "mixins": {}
    }
  ],
  "customer": {
    "id": "8765472",
    "title": "MR",
    "firstName": "John",
    "middleName": "",
    "lastName": "Doe",
    "contactPhone": "56432245",
    "email": "[email protected]",
    "company": "Emporix",
    "metadata": {
      "mixins": {}
    },
    "mixins": {}
  }
}

Request checkout exampleRequest checkout from the quote exampleRequest guest checkout

{
  "orderId": "B702231",
  "paymentDetails": null,
  "checkoutId": ""
}