Marketplace

Check out a multi-merchant cart

Create a single order for a cart that contains items from multiple merchants in the marketplace, and start a payment for the whole basket. Each item names the merchant it belongs to; items are validated against the marketplace catalog, commission is resolved per merchant, and one payment covers the entire order.

The response includes a client_secret to complete the payment on the storefront and a per-merchant breakdown of gross, discount, commission, and net amounts. Once payment succeeds, the order finalizes automatically — no further call is required.

Discounts. Pass the optional discounts array to apply a merchant’s own promotion or gift card to that merchant’s portion of the basket — each entry names the merchant_store_id and an optional promotion_id and/or gift_card_code, and the discount reduces only that merchant’s subtotal. Marketplace-wide promotions run by the operator apply automatically; you do not pass them. The response reports discount_total, the operator_funded_discount (the share the operator funded), a per-merchant discount_breakdown, and discount_amount plus merchant_gross on each merchant_breakdown entry.

🛡️ The server is the price authority (anti-tampering). You never send money amounts on this call — only identifiers. Each item’s price is recomputed from the marketplace catalog, and a discounts entry only names a promotion_id / gift_card_code; the server independently resolves the actual discount that merchant’s promotion or gift card grants (and the operator-funded share), computes every gross, discount_amount, merchant_gross, commission, and the payment total from those resolved values, and charges exactly that. A named discount that doesn’t validate (expired, ineligible, wrong store) is rejected with 400 discount_invalid rather than silently applied. There is no client-supplied discount_amount or per-item price to tamper with — a manipulated basket cannot lower what is charged. The resolved breakdown is then held server-side and used verbatim to finalize the order after payment succeeds; nothing the client sends after checkout can change what each merchant is paid.

Stock is reserved at checkout: the items are held against each merchant’s inventory immediately so concurrent shoppers cannot oversell the last units, and the hold becomes a real stock reduction when payment succeeds. If an item cannot be held, the call returns 400 insufficient_stock and no order or payment is created. Holds expire automatically if payment is never completed, returning the stock to availability.

Requires the marketplace operator key.

POST

cart

checkout

Check out a multi-merchant cart

curl --request POST \
  --url https://api.tybritelabs.com/v1/cart/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "product_id": "11111111-1111-1111-1111-111111111111",
      "variant_id": "22222222-2222-2222-2222-222222222222",
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "quantity": 2
    }
  ],
  "customer_email": "john.doe@example.com",
  "customer_name": "John Doe",
  "currency": "USD",
  "discounts": [
    {
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "promotion_id": "8a7b6c5d-1234-5678-9abc-def012345678",
      "gift_card_code": "GC-XXXX-YYYY"
    }
  ]
}
'

import requests

url = "https://api.tybritelabs.com/v1/cart/checkout"

payload = {
    "items": [
        {
            "product_id": "11111111-1111-1111-1111-111111111111",
            "variant_id": "22222222-2222-2222-2222-222222222222",
            "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
            "quantity": 2
        }
    ],
    "customer_email": "john.doe@example.com",
    "customer_name": "John Doe",
    "currency": "USD",
    "discounts": [
        {
            "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
            "promotion_id": "8a7b6c5d-1234-5678-9abc-def012345678",
            "gift_card_code": "GC-XXXX-YYYY"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        product_id: '11111111-1111-1111-1111-111111111111',
        variant_id: '22222222-2222-2222-2222-222222222222',
        merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
        quantity: 2
      }
    ],
    customer_email: 'john.doe@example.com',
    customer_name: 'John Doe',
    currency: 'USD',
    discounts: [
      {
        merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
        promotion_id: '8a7b6c5d-1234-5678-9abc-def012345678',
        gift_card_code: 'GC-XXXX-YYYY'
      }
    ]
  })
};

fetch('https://api.tybritelabs.com/v1/cart/checkout', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/cart/checkout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'product_id' => '11111111-1111-1111-1111-111111111111',
                'variant_id' => '22222222-2222-2222-2222-222222222222',
                'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
                'quantity' => 2
        ]
    ],
    'customer_email' => 'john.doe@example.com',
    'customer_name' => 'John Doe',
    'currency' => 'USD',
    'discounts' => [
        [
                'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
                'promotion_id' => '8a7b6c5d-1234-5678-9abc-def012345678',
                'gift_card_code' => 'GC-XXXX-YYYY'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/cart/checkout"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"product_id\": \"11111111-1111-1111-1111-111111111111\",\n      \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"quantity\": 2\n    }\n  ],\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"currency\": \"USD\",\n  \"discounts\": [\n    {\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"promotion_id\": \"8a7b6c5d-1234-5678-9abc-def012345678\",\n      \"gift_card_code\": \"GC-XXXX-YYYY\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/cart/checkout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"product_id\": \"11111111-1111-1111-1111-111111111111\",\n      \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"quantity\": 2\n    }\n  ],\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"currency\": \"USD\",\n  \"discounts\": [\n    {\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"promotion_id\": \"8a7b6c5d-1234-5678-9abc-def012345678\",\n      \"gift_card_code\": \"GC-XXXX-YYYY\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/cart/checkout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"product_id\": \"11111111-1111-1111-1111-111111111111\",\n      \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"quantity\": 2\n    }\n  ],\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"currency\": \"USD\",\n  \"discounts\": [\n    {\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"promotion_id\": \"8a7b6c5d-1234-5678-9abc-def012345678\",\n      \"gift_card_code\": \"GC-XXXX-YYYY\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "order_group_id": "44444444-4444-4444-4444-444444444444",
  "group_number": "MKT-100042",
  "payment_intent_id": "pi_3Pxxxxxxxxxxxx",
  "client_secret": "pi_3Pxxxxxxxxxxxx_secret_yyyyyyyy",
  "currency": "USD",
  "subtotal": 245,
  "total_amount": 230,
  "discount_total": 15,
  "operator_funded_discount": 5,
  "discount_breakdown": [
    {
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "merchant_discount": 10,
      "gift_card_amount": 0,
      "operator_funded_discount": 5
    }
  ],
  "merchant_breakdown": [
    {
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "merchant_gross": 245,
      "discount_amount": 15,
      "gross_amount": 230,
      "commission_amount": 23,
      "net_amount": 207,
      "commission_rule_id": "7e6d5c4b-1234-5678-9abc-def012345678"
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

{
  "error": {
    "code": "provider_error",
    "message": "Payment initialization failed"
  }
}

Authorizations

Authorization

string

header

required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

Format: tybrite_sk_live_* (production) or tybrite_sk_test_* (sandbox)
Full read/write access to all endpoints
⚠️ NEVER expose in client-side code or public repositories
Required for: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
Read-only access (GET requests only, plus POST semantic search)
✅ Safe for client-side JavaScript, mobile apps, and public code
Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

Authentication endpoints (/v1/auth/*): Secret key required
Payment verification (POST /v1/payments/verify): Secret key required
AI Recommendations (POST /v1/recommendations): Secret key required
Semantic Search (POST /v1/search): Both key types allowed (read-only operation)
All write operations: Secret key required
All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Headers

x-customer-token

string

Session token of a shopper signed in through Galactic Core, tying the checkout to their account rather than treating it as a guest checkout. Optional. Also accepted as x-auth-token.

x-auth-token

string

Alias of x-customer-token.

Body

application/json

items

object[]

required

The cart line items to check out.

Minimum array length: 1

Show child attributes

customer_email

string<email>

required

customer_name

string

customer_phone

string

currency

string

ISO currency code for the order. Defaults to USD.

Example:

"USD"

shipping_address

object

billing_address

object

discounts

object[]

Optional per-merchant discounts. Each entry applies a merchant's own promotion and/or gift card to that merchant's portion of the basket, reducing only that merchant's subtotal. Marketplace-wide promotions run by the operator apply automatically and are not passed here.

Show child attributes

attribution

object

Where the shopper came from, recorded so the sale is credited to the right traffic source in the merchant's reports. The same fields are also accepted at the top level of this request body if you already send them that way.

Show child attributes

Response

The multi-merchant order was created and is awaiting payment.

A created multi-merchant order awaiting payment. Use client_secret to complete the payment on the storefront; the order finalizes automatically once payment succeeds.

order_group_id

string<uuid>

Identifier for the multi-merchant order.

group_number

string

Human-readable reference for the order.

Example:

"MKT-100042"

payment_intent_id

string

Identifier of the payment to complete on the storefront.

client_secret

string

Secret used by the storefront payment form to complete the charge.

currency

string

Example:

"USD"

subtotal

number

Example:

245

total_amount

number

Example:

245

discount_total

number

Total discount applied across the whole basket — the sum of every merchant's own promotion and gift card discounts plus any marketplace-wide promotion run by the operator.

Example:

10

operator_funded_discount

number

The portion of discount_total funded by the marketplace operator (for example a marketplace-wide promotion). The remainder is funded by individual merchants.

Example:

5

discount_breakdown

object[]

Per-merchant breakdown of how discounts were applied.

Show child attributes

merchant_breakdown

object[]

Per-merchant gross, discount, commission, and net amounts for this order.

Show child attributes

Check out a multi-merchant cart

curl --request POST \
  --url https://api.tybritelabs.com/v1/cart/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "product_id": "11111111-1111-1111-1111-111111111111",
      "variant_id": "22222222-2222-2222-2222-222222222222",
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "quantity": 2
    }
  ],
  "customer_email": "john.doe@example.com",
  "customer_name": "John Doe",
  "currency": "USD",
  "discounts": [
    {
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "promotion_id": "8a7b6c5d-1234-5678-9abc-def012345678",
      "gift_card_code": "GC-XXXX-YYYY"
    }
  ]
}
'

import requests

url = "https://api.tybritelabs.com/v1/cart/checkout"

payload = {
    "items": [
        {
            "product_id": "11111111-1111-1111-1111-111111111111",
            "variant_id": "22222222-2222-2222-2222-222222222222",
            "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
            "quantity": 2
        }
    ],
    "customer_email": "john.doe@example.com",
    "customer_name": "John Doe",
    "currency": "USD",
    "discounts": [
        {
            "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
            "promotion_id": "8a7b6c5d-1234-5678-9abc-def012345678",
            "gift_card_code": "GC-XXXX-YYYY"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        product_id: '11111111-1111-1111-1111-111111111111',
        variant_id: '22222222-2222-2222-2222-222222222222',
        merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
        quantity: 2
      }
    ],
    customer_email: 'john.doe@example.com',
    customer_name: 'John Doe',
    currency: 'USD',
    discounts: [
      {
        merchant_store_id: '3f1a2b4c-1111-2222-3333-444455556666',
        promotion_id: '8a7b6c5d-1234-5678-9abc-def012345678',
        gift_card_code: 'GC-XXXX-YYYY'
      }
    ]
  })
};

fetch('https://api.tybritelabs.com/v1/cart/checkout', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tybritelabs.com/v1/cart/checkout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'product_id' => '11111111-1111-1111-1111-111111111111',
                'variant_id' => '22222222-2222-2222-2222-222222222222',
                'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
                'quantity' => 2
        ]
    ],
    'customer_email' => 'john.doe@example.com',
    'customer_name' => 'John Doe',
    'currency' => 'USD',
    'discounts' => [
        [
                'merchant_store_id' => '3f1a2b4c-1111-2222-3333-444455556666',
                'promotion_id' => '8a7b6c5d-1234-5678-9abc-def012345678',
                'gift_card_code' => 'GC-XXXX-YYYY'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tybritelabs.com/v1/cart/checkout"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"product_id\": \"11111111-1111-1111-1111-111111111111\",\n      \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"quantity\": 2\n    }\n  ],\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"currency\": \"USD\",\n  \"discounts\": [\n    {\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"promotion_id\": \"8a7b6c5d-1234-5678-9abc-def012345678\",\n      \"gift_card_code\": \"GC-XXXX-YYYY\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/cart/checkout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"product_id\": \"11111111-1111-1111-1111-111111111111\",\n      \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"quantity\": 2\n    }\n  ],\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"currency\": \"USD\",\n  \"discounts\": [\n    {\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"promotion_id\": \"8a7b6c5d-1234-5678-9abc-def012345678\",\n      \"gift_card_code\": \"GC-XXXX-YYYY\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tybritelabs.com/v1/cart/checkout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"product_id\": \"11111111-1111-1111-1111-111111111111\",\n      \"variant_id\": \"22222222-2222-2222-2222-222222222222\",\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"quantity\": 2\n    }\n  ],\n  \"customer_email\": \"john.doe@example.com\",\n  \"customer_name\": \"John Doe\",\n  \"currency\": \"USD\",\n  \"discounts\": [\n    {\n      \"merchant_store_id\": \"3f1a2b4c-1111-2222-3333-444455556666\",\n      \"promotion_id\": \"8a7b6c5d-1234-5678-9abc-def012345678\",\n      \"gift_card_code\": \"GC-XXXX-YYYY\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "order_group_id": "44444444-4444-4444-4444-444444444444",
  "group_number": "MKT-100042",
  "payment_intent_id": "pi_3Pxxxxxxxxxxxx",
  "client_secret": "pi_3Pxxxxxxxxxxxx_secret_yyyyyyyy",
  "currency": "USD",
  "subtotal": 245,
  "total_amount": 230,
  "discount_total": 15,
  "operator_funded_discount": 5,
  "discount_breakdown": [
    {
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "merchant_discount": 10,
      "gift_card_amount": 0,
      "operator_funded_discount": 5
    }
  ],
  "merchant_breakdown": [
    {
      "merchant_store_id": "3f1a2b4c-1111-2222-3333-444455556666",
      "merchant_gross": 245,
      "discount_amount": 15,
      "gross_amount": 230,
      "commission_amount": 23,
      "net_amount": 207,
      "commission_rule_id": "7e6d5c4b-1234-5678-9abc-def012345678"
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

{
  "error": {
    "code": "provider_error",
    "message": "Payment initialization failed"
  }
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Check out a multi-merchant cart

Authorizations

Headers

Body

Response