Cart and checkout

Connect API · https://api.conciar.com/connect/v1

Carts and webshop orders are secret-key calls: run them on your server. Totals in cart responses are plain numbers; cart and order responses are the stored records with their relations, limited to the fields a storefront may see.

INFO

De API-referentie is in het Engels.

Create a cart

POST/connect/v1/store/cart/init

Alleen geheime sleutelVereist X-Sales-Channel

Rate limit: 30/min per key

curl -X POST "https://api.conciar.com/connect/v1/store/cart/init" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token"

Voorbeeldantwoord · 201

{
  "data": {
    "cart_token": "example_cart_token",
    "cart": {
      "cart_token": "example_cart_token",
      "items": [],
      "totals": {
        "subtotal": 0,
        "discount": 0,
        "promotion_discount": 0,
        "total": 0,
        "…": "…"
      },
      "…": "…"
    }
  }
}

Set cart lines and coupons

Declarative: quantities are set, not added, and the coupons you send replace the current ones (send none to clear). A line's price is fixed when it is first added.

POST/connect/v1/store/cart/sync

Alleen geheime sleutelVereist X-Sales-Channel

Rate limit: 120/min per key

Body

cart_tokenstringverplicht
The cart.
items[].product_idintegerverplicht
Product id (required when items is sent).
items[].product_variant_idinteger
Variant of that product (ignored when it belongs to another product).
items[].quantityintegerverplicht
Min 0; 0 removes the line (required when items is sent).
items[].purchase_typestring
one_time (default) or subscription.
items[].metadataobject
Your own data for the line.
coupon_codesstring[]
All coupons for the cart; an empty list clears them.
coupon_codestring
One coupon instead of coupon_codes (ignored when coupon_codes is sent).
organization_customer_idinteger
Link the cart to a member.

Statuscodes

404Cart not found or no longer active.
422Validation, an invalid or expired coupon, or more than one coupon on a channel without stacking.

curl -X POST "https://api.conciar.com/connect/v1/store/cart/sync" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token" \
  -H "Content-Type: application/json" \
  -d '{
    "cart_token": "example_cart_token",
    "items": [
      {
        "product_id": 9001,
        "quantity": 2
      }
    ]
  }'

Voorbeeldantwoord · 200

{
  "cart": {
    "cart_token": "example_cart_token",
    "items": [
      {
        "product_id": 9001,
        "quantity": 2,
        "promotion_discount": 0,
        "promotions": [],
        "line_total": 49.9,
        "…": "…"
      }
    ],
    "totals": {
      "subtotal": 49.9,
      "discount": 0,
      "promotion_discount": 0,
      "total": 49.9,
      "currency_id": 1,
      "coupons": [],
      "promotions": [],
      "free_shipping": null
    },
    "…": "…"
  }
}

Get a cart

GET/connect/v1/store/cart/{cart_token}

Alleen geheime sleutelVereist X-Sales-Channel

Padparameters

cart_tokenstringverplicht
The token from POST /store/cart/init.

Statuscodes

404Unknown, converted or expired cart.

curl "https://api.conciar.com/connect/v1/store/cart/example_cart_token" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token"

Voorbeeldantwoord · 200

{
  "cart": {
    "cart_token": "example_cart_token",
    "items": [
      "…"
    ],
    "totals": {
      "…": "…"
    },
    "…": "…"
  }
}

Check a cart before checkout

Blocking issues per line (unavailable, not_in_channel, out_of_stock, insufficient_stock, variant_unavailable), price changes on live-pricing channels, and coupons that no longer apply.

GET/connect/v1/store/cart/{cart_token}/checkout-check

Alleen geheime sleutelVereist X-Sales-Channel

Padparameters

cart_tokenstringverplicht
The token from POST /store/cart/init.

Statuscodes

404Unknown, converted or expired cart.

Goed om te weten

issues[]: {sku, name, type} (insufficient_stock adds available). warnings[]: {sku, name, original_price, new_price, currency}. coupon_warnings[]: {code, reason}.

curl "https://api.conciar.com/connect/v1/store/cart/example_cart_token/checkout-check" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token"

Voorbeeldantwoord · 200

{
  "can_proceed": true,
  "issues": [],
  "has_changes": false,
  "warnings": [],
  "coupon_warnings": []
}

Shipping methods for a cart

POST/connect/v1/store/cart/{cart_token}/shipping-methods

Alleen geheime sleutelVereist X-Sales-Channel

Rate limit: 120/min per key

Padparameters

cart_tokenstringverplicht
The token from POST /store/cart/init.

Body

country_codestringverplicht
ISO-2.
postal_codestring
Max 20.
province, city, districtstring
Max 100 each.

Statuscodes

404Unknown, converted or expired cart.

Goed om te weten

When nothing ships to the address the answer is still 200: shipping_methods is [] with a message.

curl -X POST "https://api.conciar.com/connect/v1/store/cart/example_cart_token/shipping-methods" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "NL",
    "postal_code": "1000 AA"
  }'

Voorbeeldantwoord · 200

{
  "shipping_methods": [
    {
      "id": 3,
      "type": "flat_rate",
      "sort_order": 1,
      "is_free": false,
      "carrier": null,
      "delivery_type": "delivery",
      "resolved_info": {
        "name": "Standard",
        "description": null
      },
      "rate": {
        "amount": 4.95,
        "display_price": "€ 4,95",
        "currency": {
          "symbol": "EUR",
          "…": "…"
        }
      }
    }
  ]
}

Payment methods for a cart

Methods that accept the cart amount. A cart with subscription lines only gets methods that support recurring payments.

POST/connect/v1/store/cart/{cart_token}/payment-methods

Alleen geheime sleutelVereist X-Sales-Channel

Rate limit: 120/min per key

Padparameters

cart_tokenstringverplicht
The token from POST /store/cart/init.

Body

shipping_method_idinteger
Chosen shipping method (an existing id).
country_idinteger
Country id from GET /countries.

Statuscodes

404Unknown, converted or expired cart.

Goed om te weten

The amount checked is the cart in the X-Currency currency (else EUR). When no method fits the answer is still 200: payment_methods is [] with a message.

curl -X POST "https://api.conciar.com/connect/v1/store/cart/example_cart_token/payment-methods" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_method_id": 3
  }'

Voorbeeldantwoord · 200

{
  "payment_methods": [
    {
      "id": 1,
      "key": "ideal",
      "type": "redirect",
      "name": "iDEAL",
      "logo": "…",
      "status": "live",
      "fixed_fee": null,
      "fixed_percentage": 0,
      "requires": [],
      "payment_service_provider_id": 2,
      "payment_service_provider_key": "example_psp",
      "min_amount": null,
      "max_amount": null
    }
  ]
}

List payment methods

The payment methods enabled for the organization, narrowed to the channel's own selection when it has one. type is wallet (Apple Pay, Google Pay) or redirect; requires lists the customer details a method needs (name, email, phone, billing_address, birth_date).

GET/connect/v1/store/payment-methods

Publishable of geheime sleutelVereist X-Sales-Channel

Queryparameters

amountnumber
0–99999999, in the channel currency. Drop methods whose minimum or maximum excludes this amount.
recurringboolean
Only methods that support recurring payments.

curl "https://api.conciar.com/connect/v1/store/payment-methods" \
  -H "Accept: application/json" \
  -H "X-Api-Key: pk_your_publishable_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token"

Voorbeeldantwoord · 200

{
  "payment_methods": [
    {
      "id": 1,
      "key": "ideal",
      "type": "redirect",
      "name": "iDEAL",
      "logo": "…",
      "status": "live",
      "supports_recurrent": false,
      "requires": [],
      "payment_service_provider_id": 2,
      "payment_service_provider_key": "example_psp",
      "min_amount": null,
      "max_amount": null
    }
  ],
  "currency": "EUR"
}

Find pickup points

PostNL pickup points near a postcode. Only when the merchant has PostNL enabled.

GET/connect/v1/store/shipping/locations

Alleen geheime sleutelVereist X-Sales-Channel

Queryparameters

country_codestringverplicht
ISO-2.
postal_codestringverplicht
Max 16.

Statuscodes

404No shipping carrier is available.

curl "https://api.conciar.com/connect/v1/store/shipping/locations?country_code=NL&postal_code=1000AA" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token"

Voorbeeldantwoord · 200

{
  "locations": [
    {
      "code": "123456",
      "name": "Example pickup point",
      "distance": 350,
      "latitude": 52,
      "longitude": 4,
      "address": {
        "…": "…"
      },
      "delivery_options": [
        "PG"
      ],
      "opening_hours": {
        "Monday": [
          "09:00-18:00"
        ]
      }
    }
  ]
}

Delivery timeframes

PostNL daytime delivery windows from tomorrow up to seven days ahead.

GET/connect/v1/store/shipping/delivery-options

Alleen geheime sleutelVereist X-Sales-Channel

Queryparameters

country_codestringverplicht
ISO-2.
postal_codestringverplicht
Max 16.
house_numberstringverplicht
Max 16.

Statuscodes

404No shipping carrier is available.

curl "https://api.conciar.com/connect/v1/store/shipping/delivery-options?country_code=NL&postal_code=1000AA&house_number=1" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token"

Voorbeeldantwoord · 200

{
  "delivery_options": [
    {
      "date": "2026-10-17",
      "timeframes": [
        {
          "from": "09:00:00",
          "to": "12:00:00",
          "options": [
            "Daytime"
          ]
        }
      ]
    }
  ]
}

Place a webshop order

Turns a cart into an order and starts the payment. Redirect methods return payment_url; with an Apple Pay or Google Pay token the charge happens in this call. Customer details are required unless a bearer token is sent or the channel allows guest checkout.

POST/connect/v1/store/orders

Alleen geheime sleutelVereist X-Sales-ChannelKlanttoken optioneel

Body

cart_tokenstringverplicht
An active cart with items.
shipping_method_idintegerverplicht
From the cart's shipping methods.
payment_method_keystringverplicht
Payment method key.
payment_service_provider_keystringverplicht
Provider key.
return_urlstring
A URL. Required except for applepay and google_pay.
shipping_addressobjectverplicht
city (max 100) and country_id required; street (max 255), house_number (max 20), apartment (max 20), zipcode (max 20), district (max 100), state (max 100) optional.
billing_addressobject
Same fields (city and country_id required when sent); defaults to the shipping address.
customerobject
Required (with email) unless a bearer token is sent or the channel allows guest checkout. email (max 255), first_name, last_name (max 100 each), phone {number (max 20), country_id}.
customer_notesstring
Max 1000.
internal_notesstring
Max 1000. A note for the merchant's staff; never shown to the customer.
pickup_location_codestring
A pickup point code (a number is accepted). Max 32.
apple_pay_token, google_pay_tokenobject|string
Wallet token for an immediate charge (object, JSON or base64). payment_data is still accepted as the older name of google_pay_token.
card_tokenstring
For visa, mastercard and amex: a card token passed to the provider.

Statuscodes

404The shipping method is inactive or belongs to another organization.
422Validation (cart, stock, coupon, address problems), a shipping method or payment method not available for this order, or {status: false, message} with PAYMENT_METHOD_UNAVAILABLE (with reason and limit), INVALID_WALLET_TOKEN or PAYMENT_FAILED (a declined wallet charge; nothing is kept and the cart stays open).
500The provider could not start a redirect payment; nothing is kept.

Goed om te weten

With a wallet token, payment is {type: wallet, method, status (paid or pending), transaction_key} and payment_url is left out.
price_warnings is added when a live-pricing channel repriced a line at checkout.

curl -X POST "https://api.conciar.com/connect/v1/store/orders" \
  -H "Accept: application/json" \
  -H "X-Api-Key: cnct_your_secret_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token" \
  -H "Content-Type: application/json" \
  -d '{
    "cart_token": "example_cart_token",
    "shipping_method_id": 3,
    "payment_method_key": "ideal",
    "payment_service_provider_key": "example_psp",
    "return_url": "https://shop.example.com/checkout/return",
    "customer": {
      "email": "alex@example.com",
      "first_name": "Alex"
    },
    "shipping_address": {
      "street": "Example Street",
      "house_number": "1",
      "zipcode": "1000 AA",
      "city": "Example City",
      "country_id": 150
    }
  }'

Voorbeeldantwoord · 201

{
  "order": {
    "reference": "ORD-EXAMPLE00001",
    "…": "…"
  },
  "invoice": {
    "…": "…"
  },
  "transaction": {
    "…": "…"
  },
  "payment_url": "https://payment-provider.example/checkout/…",
  "transaction_key": "example-transaction-key",
  "payment": {
    "type": "redirect",
    "payment_url": "https://payment-provider.example/checkout/…",
    "transaction_key": "example-transaction-key"
  }
}

Check a payment

Call this when the customer comes back on your return_url. A pending payment is checked live with the provider.

GET/connect/v1/store/payment/{transaction_key}/status

Publishable of geheime sleutelVereist X-Sales-Channel

Rate limit: 60/min per key (a publishable key: per key and IP)

Padparameters

transaction_keystringverplicht
From the order response.

Statuscodes

404Unknown transaction.

curl "https://api.conciar.com/connect/v1/store/payment/example-transaction-key/status" \
  -H "Accept: application/json" \
  -H "X-Api-Key: pk_your_publishable_key" \
  -H "X-Sales-Channel: cnct_ch_your_channel_token"

Voorbeeldantwoord · 200

{
  "transaction_key": "example-transaction-key",
  "status": "paid",
  "is_paid": true,
  "is_pending": false,
  "is_failed": false,
  "amount": "49.90",
  "order_reference": "ORD-EXAMPLE00001"
}

Cart and checkout ​

Create a cart ​

Set cart lines and coupons ​

Body

Statuscodes

Get a cart ​

Padparameters

Statuscodes

Check a cart before checkout ​

Padparameters

Statuscodes

Goed om te weten

Shipping methods for a cart ​

Padparameters

Body

Statuscodes

Goed om te weten

Payment methods for a cart ​

Padparameters

Body

Statuscodes

Goed om te weten

List payment methods ​

Queryparameters

Find pickup points ​

Queryparameters

Statuscodes

Delivery timeframes ​

Queryparameters

Statuscodes

Place a webshop order ​

Body

Statuscodes

Goed om te weten

Check a payment ​

Padparameters

Statuscodes

Cart and checkout

Create a cart

Set cart lines and coupons

Get a cart

Check a cart before checkout

Shipping methods for a cart

Payment methods for a cart

List payment methods

Find pickup points

Delivery timeframes

Place a webshop order

Check a payment