Fluid Commerce APIs (1.0)

The Fluid Commerce APIs provides a comprehensive set of APIs designed to integrate Fluid's powerful services into your applications seamlessly. This bundle offers robust functionality for enhancing messaging solutions, streamlining data management, and improving customer interactions. With detailed documentation, secure authentication, and flexible integration options, the Fluid Public API Bundle is engineered to help you leverage our services efficiently and effectively, unlocking new potentials and achieving greater connectivity within your systems.

Download OpenAPI description

swagger.json

swagger.yaml

Overview

E-mail support@fluid.app

License MIT

Servers

Mock server

https://docs.fluid.app/_mock/docs/apis/swagger/

Production server with company subdomain

https://{company}.fluid.app/

Local development server

http://fluid.lvh.me:{port}/

Admins

Operations

Agreements

Operations

Announcements

Operations

ApplePay

Operations

Application Theme Templates

Operations

Application Themes

Operations

ApplicationThemeResources

Operations

ApplicationThemeTemplates

Operations

Authentication

Operations

Bank Accounts

Operations

Business Types

Operations

Callback Definitions

Operations

Callback Registrations

Operations

Callback Schemas

Operations

Carts

Operations

Append metadata field

Request

Append metadata field(s) to a cart.

Path

cart_tokenstringrequired

Bodyapplication/json

metadataobjectrequired

A JSON object that can store any custom data structure. When provided, merges with existing metadata data.

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/append_metadata' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {}
  }'

Responses

success

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Remove metadata fields

Request

Remove metadata field(s) from a cart

Path

cart_tokenstringrequired

Bodyapplication/json

cartobjectrequired

cart.metadataArray of stringsrequired

Array of metadata keys to remove. Supports dot notation for nested keys.

Example: ["level","referred_by.user.id","location_ids"]

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/remove_metadata' \
  -H 'Content-Type: application/json' \
  -d '{
    "cart": {
      "metadata": [
        "level",
        "referred_by.user.id",
        "location_ids"
      ]
    }
  }'

Responses

success

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Creates a cart

Request

Create a cart. Items, attribution, immutable_items, order_confirmation_url, order_failure_url, and enrollment_pack_id are optional. Buyer rep assignment follows this priority: 1. If JWT is provided, extracts user from JWT and assigns as the rep. 2. If session cookie is present, extracts user from session and assigns it as the rep. 3. If no authentication is provided, cart is created without a rep. When authenticated as a rep, the cart will include rep-specific pricing.

Query

jwtstring

JWT token for user authentication. When provided, extracts user and assigns it as the rep to the cart.

Example: jwt=eyJhbGciOiJIUzI1NiJ9.eyJhdXRoX3R5cGUiOiJ1c2VyX2NvbXBhbnkiLCJpZCI6MTIzfQ...

Headers

Cookiestring

Session cookie (_fluid_session)

Bodyapplication/json

Cart params

country_codestringrequired

ISO 2-letter country code

Example: "US"

visitor_tokenstring

Visitor token. DEPRECATED: Will be removed in a future version; please use session_uuid instead

Example: "vt_2a3v3f9s8xRCN"

session_uuidstring

Session UUID

Example: "0195ff0f-9a6c-70e1-9037-f42bfd23b5fb"

itemsArray of objects

immutable_itemsboolean

Whether the cart is immutable

Default false

Example: true

fluid_shopstringrequired

The domain of your Fluid shop (excluding the scheme)

Example: "myco.fluid.app"

sourcestring

The source of the cart

Enum"web""mobile""external""admin"

Example: "admin"

attributionobject or object or object or object or object

Default {"id":456,"share_guid":"james-bond007"}

One of:

order_confirmation_urlstring

The URL of a custom Order Confirmation Page to send customers to after the order is approved.

Example: "https://myco.fluid.app/pages/order-confirmation?token={order_token}"

order_failure_urlstring

The URL to redirect customers to when a payment fails on external APM integrations. If not provided, defaults to the checkout page.

Example: "https://myco.fluid.app/pages/payment-failed"

timezonestring

User timezone. Defaults to 'UTC' if not provided.

Example: "America/New_York"

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts?jwt=string' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: string' \
  -d '{
    "country_code": "US",
    "visitor_token": "vt_2a3v3f9s8xRCN",
    "session_uuid": "0195ff0f-9a6c-70e1-9037-f42bfd23b5fb",
    "items": [
      {
        "variant_id": 90,
        "quantity": 2,
        "display_to_customer": true,
        "subscription": true,
        "subscription_plan_id": 123,
        "cv": 10,
        "qv": 10,
        "price": 100,
        "parent_id": 1
      }
    ],
    "immutable_items": true,
    "fluid_shop": "myco.fluid.app",
    "source": "admin",
    "attribution": {
      "id": 456,
      "share_guid": "james-bond007"
    },
    "order_confirmation_url": "https://myco.fluid.app/pages/order-confirmation?token={order_token}",
    "order_failure_url": "https://myco.fluid.app/pages/payment-failed",
    "timezone": "America/New_York"
  }'

Responses

cart created without email callback (no email)

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates cart address

Request

Path

cart_tokenstringrequired

Bodyapplication/json

typestring

Enum"ship_to""bill_to"

Example: "bill_to"

jwtstring or null

Example: "eyJhbGciO1NiJ9.eyJhdXcyNjN9.AZ-4PAgFwVyGp"

address_idinteger or null

Example: 456

addressobject or null

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/address' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "bill_to",
    "jwt": "eyJhbGciO1NiJ9.eyJhdXcyNjN9.AZ-4PAgFwVyGp",
    "address_id": 456,
    "address": {
      "id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "12345",
      "country_code": "US"
    }
  }'

Responses

address updated with address id

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Retrieves a cart

Request

Path

cart_tokenstringrequired

Query

payment_methods_includesstring

curl -i -X GET \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}?payment_methods_includes=string'

Responses

cart found

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates a cart

Request

Path

cart_tokenstringrequired

Bodyapplication/json

emailstring(email)

phonestring

Example: "4035551212"

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "phone": "4035551212"
  }'

Responses

cart updated with phone number validation

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Applies a discount to the cart

Request

Path

cart_tokenstringrequired

Bodyapplication/json

discount_codesArray of strings

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/discount' \
  -H 'Content-Type: application/json' \
  -d '{
    "discount_codes": [
      "string"
    ]
  }'

Responses

discount applied

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Remove discount from the cart

Request

Path

cart_tokenstringrequired

discount_codestringrequired

curl -i -X DELETE \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/discount/{discount_code}'

Responses

discount removed

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Adds new items to cart, updates quantities of existing items, or removes items with quantity 0

Request

Path

cart_tokenstringrequired

Bodyapplication/json

itemsArray of objectsrequired

Array of items to add, update, or delete. If variant_id already exists in cart, quantity will be updated; otherwise, a new item is added. Set quantity to 0 to remove an item. For custom items without variants, use [title, price, quantity]

Example: [{"variant_id":123,"quantity":2},{"title":"Custom Surcharge","price":"10.99","quantity":1}]

items[].variant_idinteger

ID of the variant to add to cart (if item with this variant_id already exists, its quantity will be updated)

Example: 123

items[].quantityintegerrequired

Quantity to set for this item (replaces existing quantity if item already exists in cart). Set to 0 to remove the item from the cart.

Example: 2

items[].titlestring

Title for custom items without variants

Example: "Custom Surcharge"

items[].pricenumber or string

Price for custom items without variants

Example: "10.99"

items[].subscriptionboolean

allow subscription for item

Example: false

items[].subscription_plan_idinteger

ID of the subscription plan (can be passed when subscription is true)

Example: 456

items[].enrollment_pack_idinteger

ID of the enrollment pack to add to cart item

Example: 789

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "variant_id": 123,
        "quantity": 2
      },
      {
        "title": "Custom Surcharge",
        "price": "10.99",
        "quantity": 1
      }
    ]
  }'

Responses

removes item when quantity is 0

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Removes items from cart

Request

Path

cart_tokenstringrequired

Bodyapplication/json

itemsArray of objectsrequired

items[].variant_idintegerrequired

curl -i -X DELETE \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "variant_id": 0
      }
    ]
  }'

Responses

items removed from cart

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Removes item from cart

Request

Path

cart_tokenstringrequired

item_idstringrequired

curl -i -X DELETE \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items/{item_id}'

Responses

item removed from cart

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Retrieves enroll for cart

Request

Path

cart_tokenstringrequired

Query

placementstring

Default "all"

Enum"pre_purchase""post_purchase""all"

curl -i -X GET \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/enroll?placement=pre_purchase'

Responses

enroll fields found

Bodyapplication/json

enrollobject

metaobject

Response

application/json

{
  "enroll": {
    "id": 1,
    "active": true,
    "default": false,
    "title": "Customer Details",
    "fields": [ … ]
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Sets cart payment method

Request

Path

cart_tokenstringrequired

typestringrequired

Type of payment method

Enum"credit_card""paypal""bread""affirm""klarna""g_cash_citcon""ali_pay_citcon"

Query

jwtstring

JWT token to authenticate (Optional, if payment method id is not provided)

payment_method_idinteger

Payment Method id (Optional)

Bodyapplication/jsonrequired

billing_postal_codestring

Billing postal code

Example: "123"

payment_methodobjectrequired

payment_method.token_providerstring

Payment method token provider (optional for spreedly)

Example: "vgs"

payment_method.tokenstring

Payment method token from provider

payment_method.last_fourstring

Last 4 digits of credit card (optional for vgs)

payment_method.card_typestring

Type of credit card(visa, mastercard, etc)(optional for vgs)

payment_method.cvv_tokenstring

CVV Token value

payment_method.exp_monthstring

Expiration month (MM)

payment_method.exp_yearstring

Expiration year (YYYY)

payment_method.card_holderstring

Card holder full name (optional for spreedly)

payment_method.payment_account_idstring

Selected payment account id (required only when integration_class is Droplet)

billing_addressobject

payment_accountstring

Payment account UUID; when supplied, it overrides implicit payment account inference.

Example: "pa_MyW8X11CuEbZyGHUi0DOHZrlzFE1cXhA"

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/payment_methods/{type}?jwt=string&payment_method_id=0' \
  -H 'Content-Type: application/json' \
  -d '{
    "billing_postal_code": "123",
    "payment_method": {
      "token_provider": "vgs",
      "token": "string",
      "last_four": "string",
      "card_type": "string",
      "cvv_token": "string",
      "exp_month": "string",
      "exp_year": "string",
      "card_holder": "string",
      "payment_account_id": "string"
    },
    "billing_address": {
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "payment_account": "pa_MyW8X11CuEbZyGHUi0DOHZrlzFE1cXhA"
  }'

Responses

payment method added with billing address

Bodyapplication/json

cardobjectrequired

card.user_idstring or null

Example: "123"

card.spreedly_tokenstring

Example: "01JKFTVM6Z44YFPSS9KK36KMSV"

card.full_namestring

Example: "John Doe"

card.monthinteger

Example: 3

card.yearinteger

Example: 2032

card.numberstring

Example: "XXXX-XXXX-XXXX-4444"

card.last_four_digitsstring

Example: "4444"

card.first_six_digitsstring or null

Example: "555555"

card.card_typestring

Example: "master"

card.address_idinteger or null

Example: 123

card.fingerprintstring or null

Example: "6eb05c4c7fc52fec38ef6e0651e8225be41c"

card.defaultboolean

Example: false

card.activeboolean

Example: true

card.created_atstring(date-time)

Example: "2021-01-01T00:00:00Z"

card.updated_atstring(date-time)

Example: "2021-01-01T00:00:00Z"

card.fluidboolean

Example: true

card.testboolean or null

Example: true

card.emailstring or null

Example: "john@example.com"

card.customer_idstring or null

Example: "123"

card.fluid_pay_account_idstring or null

Example: "123"

card.token_providerstring or null

Example: "vgs"

card.tokenstring or null

Example: "01JKFTVM6Z44YFPSS9KK36KMSV"

card.cvv_tokenstring or null

Example: "411"

Response

application/json

{
  "card": {
    "user_id": "123",
    "spreedly_token": "01JKFTVM6Z44YFPSS9KK36KMSV",
    "full_name": "John Doe",
    "month": 3,
    "year": 2032,
    "number": "XXXX-XXXX-XXXX-4444",
    "last_four_digits": "4444",
    "first_six_digits": "555555",
    "card_type": "master",
    "address_id": 123,
    "fingerprint": "6eb05c4c7fc52fec38ef6e0651e8225be41c",
    "default": false,
    "active": true,
    "created_at": "2021-01-01T00:00:00Z",
    "updated_at": "2021-01-01T00:00:00Z",
    "fluid": true,
    "test": true,
    "email": "john@example.com",
    "customer_id": "123",
    "fluid_pay_account_id": "123",
    "token_provider": "vgs",
    "token": "01JKFTVM6Z44YFPSS9KK36KMSV",
    "cvv_token": "411"
  }
}

Gets VGS vault access token

Request

Path

cart_tokenstringrequired

payment_account_idstringrequired

curl -i -X GET \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/payment_account/{payment_account_id}/vault'

Responses

VGS vault access token

Bodyapplication/json

vaultobjectrequired

vault.vault_idstringrequired

Example: "tntydlnduqt"

vault.environmentstringrequired

Example: "sandbox or live"

vault.access_tokenstringrequired

Example: "eyJhbGci..."

vault.route_idstringrequired

Example: "e83a1bc9-1212-41e8-9ed2-c04efec22b03"

metaobjectrequired

meta.request_idstring

Example: "123e4567-e89b-12d3-a456-426614174000"

meta.timestampstring

Example: "2021-01-01T00:00:00Z"

Response

application/json

{
  "vault": {
    "vault_id": "tntydlnduqt",
    "environment": "sandbox or live",
    "access_token": "eyJhbGci...",
    "route_id": "e83a1bc9-1212-41e8-9ed2-c04efec22b03"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Sets cart shipping method

Request

Path

cart_tokenstringrequired

Bodyapplication/json

shipping_method_idstringrequired

ID of the shipping method to use

Example: 10

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/shipping_method' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipping_method_id": 10
  }'

Responses

shipping method set

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Completes cart checkout

Request

Path

cart_tokenstringrequired

Bodyapplication/json

payment_uuidstring or null

Example: "123e4567-e89b-12d3-a456-426614174000"

kount_session_idstring or null

Example: "123e4567-e89b-12d3-a456-426614174000"

browser_infoobject or null

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/checkout' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "kount_session_id": "123e4567-e89b-12d3-a456-426614174000",
    "browser_info": {
      "color_depth": 100,
      "screen_height": 100,
      "screen_width": 100,
      "time_zone": 100,
      "java_enabled": true,
      "java_script_enabled": true,
      "language": "en"
    }
  }'

Responses

checkout completed

Bodyapplication/json

orderobject

metaobject

Response

application/json

{
  "order": {
    "id": 0,
    "first_name": "string",
    "last_name": "string",
    "external_id": "string",
    "email": "string",
    "phone": "string",
    "order_number": "string",
    "token": "string",
    "status": "string",
    "order_status": "string",
    "financial_status": "string",
    "fulfillment_status": "string",
    "warehouse_id": 0,
    "order_type": "string",
    "amount": "string",
    "refundable_amount": 10.5,
    "note": {},
    "recurring": [ … ],
    "order_confirmation_url": "string",
    "currency_code": "string",
    "created_at": "string",
    "updated_at": "string",
    "metadata": {},
    "enrollment_pack": { … },
    "source": "web",
    "split_payment": {}
  },
  "meta": {
    "request_id": "f5473a8c-8a86-4e0e-b3e8-95392003921b",
    "timestamp": "2024-12-10T08:04:10Z",
    "shop_url": "https://example.com"
  }
}

Retrieves cart company information

Request

Path

cart_tokenstringrequired

curl -i -X GET \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/cart_info'

Responses

company info found

Bodyapplication/json

languagesArray of objects

countriesArray of objects

Response

application/json

{
  "languages": [
    { … }
  ],
  "countries": [
    { … }
  ]
}

Updates the language of a cart

Request

Path

cart_tokenstringrequired

Bodyapplication/jsonrequired

List of valid iso are at /api/carts/{cart_token}/cart_info

language_isostring

Example: "en"

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/change_language' \
  -H 'Content-Type: application/json' \
  -d '{
    "language_iso": "en"
  }'

Responses

cart's language_iso changed

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates the country of a cart, also updates the currency code

Request

Path

cart_tokenstringrequired

Bodyapplication/json

ISO country code to update the cart to

country_codestringrequired

Example: "US"

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/update_country' \
  -H 'Content-Type: application/json' \
  -d '{
    "country_code": "US"
  }'

Responses

cart's country and currency code changed

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Create magic link for cart

Request

Path

cart_tokenstringrequired

Bodyapplication/json

emailstringrequired

Example: "example@gmail.com"

fluid_shopstringrequired

Example: "fluid.app"

lookup_onlyboolean

Example: true

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/magic_link' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "example@gmail.com",
    "fluid_shop": "fluid.app",
    "lookup_only": true
  }'

Responses

magic link created

Bodyapplication/json

multi_factor_authenticationobject

metaobject

Response

application/json

{
  "multi_factor_authentication": {
    "uuid": "string",
    "authenticated": true,
    "verification_channel": "string",
    "verification_code_expires_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z"
  }
}

Confirm magic link for cart

Request

Path

cart_tokenstringrequired

Bodyapplication/json

uuidstringrequired

multi_factor_authenticationobjectrequired

multi_factor_authentication.verification_codestringrequired

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/confirm_magic_link' \
  -H 'Content-Type: application/json' \
  -d '{
    "uuid": "string",
    "multi_factor_authentication": {
      "verification_code": "string"
    }
  }'

Responses

magic link confirmed

Bodyapplication/json

jwtstring

authenticatedboolean

auth_typestring

metaobject

Response

application/json

{
  "jwt": "string",
  "authenticated": true,
  "auth_type": "string",
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Add enrollment to existing cart

Request

Path

cart_tokenstringrequired

Bodyapplication/json

enrollment_pack_idintegerrequired

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/enrollment' \
  -H 'Content-Type: application/json' \
  -d '{
    "enrollment_pack_id": 0
  }'

Responses

Enrollment pack added to cart

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Adds subscribe:true to cart item

Request

Path

cart_tokenstringrequired

item_idstringrequired

Query

subscription_plan_idinteger

ID of the subscription plan to use

Example: subscription_plan_id=123

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items/{item_id}/subscribe?subscription_plan_id=0'

Responses

subscription true updated

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates subscribe:false to cart item

Request

Path

cart_tokenstringrequired

item_idstringrequired

curl -i -X DELETE \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items/{item_id}/subscribe'

Responses

subscription false updated

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates bundled items metadata for a cart item

Request

Updates the bundled_items metadata for a specific cart item. Accepts minimal input (variant_id, quantity, display_to_customer) and automatically fetches additional product information from the database. Items with quantity 0 will be removed from the bundled items metadata. Returns errors for invalid variant IDs but continues processing valid ones.

Path

cart_tokenstringrequired

item_idstringrequired

Bodyapplication/json

bundled_itemsArray of objectsrequired

Array of bundled items with minimal data - additional fields are fetched automatically

bundled_items[].variant_idintegerrequired

ID of the variant to include in bundle

Example: 66894

bundled_items[].quantityintegerrequired

Quantity of this bundled item

Example: 2

bundled_items[].display_to_customerbooleanrequired

Whether to display this bundled item to the customer

Example: true

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items/{item_id}/bundled_items' \
  -H 'Content-Type: application/json' \
  -d '{
    "bundled_items": [
      {
        "variant_id": 66894,
        "quantity": 2,
        "display_to_customer": true
      }
    ]
  }'

Responses

bundled items updated successfully

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates a cart item's volume totals

Request

Updates the cv_total and/or qv_total of a cart item. Only the attributes that are passed in the request will be updated. The cart's cv_total and qv_total will be automatically recalculated as the sum of all cart items' volume totals.

Path

cart_tokenstringrequired

The cart token

Example: abc123def456

item_idintegerrequired

The cart item ID

Example: 123

Bodyapplication/jsonrequired

Volume update parameters

cv_totalinteger

Optional: New CV total for the cart item

Example: 20

qv_totalinteger

Optional: New QV total for the cart item

Example: 15

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items/{item_id}/update_volumes' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cv_total": 20,
    "qv_total": 15
  }'

Responses

Volume totals updated successfully

Bodyapplication/json

cartobjectrequired

cart.idinteger

Example: 123

cart.statestring

Example: "start"

cart.processedboolean

Determines if a cart payment has been processed or not.

Example: false

cart.valid_for_checkoutboolean

Example: true

cart.buyer_rep_idinteger or null

Example: 1

cart.buyer_repobject or null

One of:

cart.volume_repobject or null

One of:

cart.currency_symbolstring

Example: "$"

cart.currency_codestring

Example: "USD"

cart.shipping_total_for_displaystring

Example: "Free"

cart.phonestring or null

Example: "4035551212"

cart.payment_method_auto_assignableboolean

Determines if a payment method can be auto-assigned to the cart.

Example: true

cart.attribution(object or object or object or object or object) or null

Default {"id":456,"share_guid":"james-bond007"}

One of:

cart.agreementsArray of objects or null

cart.amount_totalstring

Example: "121.65"

cart.amount_total_in_currencystring

Example: "$121.65 (USD)"

cart.sub_totalstring

Example: "100.00"

cart.sub_total_in_currencystring

Example: "$100.00 (USD)"

cart.subtotal_after_discountsstring

Example: "90.00"

cart.tax_totalstring

Example: "20.00"

cart.tax_total_in_currencystring

Example: "$20.00 (USD)"

cart.shipping_totalstring or null

Example: "1.65"

cart.shipping_total_in_currencystring

Example: "$1.65 (USD)"

cart.shipping_discountnumber

Example: 10.25

cart.discount_totalstring

Example: "2.99"

cart.discount_total_in_currencystring

Example: "$2.99 (USD)"

cart.discount_breakdownobject

cart.external_discountobject

cart.transaction_feenumber or string

Example: "1.90"

cart.transaction_fee_in_currencystring

Example: "$1.90 (USD)"

cart.cv_totalinteger

Example: 10

cart.qv_totalinteger

Example: 15

cart.companyobject

cart.payment_accountstring or null

Example: "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An"

cart.payment_methodnull or object or object or object or object or object or object

One of:

null

cart.emailstring or null

Example: "user@example.com"

cart.enrollment_feenumber or string

Example: "10.45"

cart.enrollment_fee_in_currencystring

Example: "$10.45"

cart.discount_codesArray of strings

Example: ["DISCOUNT10","DISCOUNT11"]

cart.language_isostring or null

Example: "en"

cart.cart_tokenstring

Example: "abc123"

cart.immutable_itemsboolean

Example: false

cart.digital_onlyboolean

Example: false

cart.requires_3dsboolean

Example: false

cart.itemsArray of objects

cart.ship_toobject or null

cart.bill_toobject or null

cart.shipping_methodobject or null

cart.available_shipping_methodsArray of objects

cart.available_payment_methodsArray of objects or objects

cart.countryobject

cart.typestring

Enum"regular""enrollment"

Example: "regular"

cart.enrollment_pack_idinteger or null

Example: 1

cart.enrollment_packobject or null

cart.metadataobject

A JSON object that can store any custom data structure.

cart.recurringArray of objects or null

Default [{"subtotal":"10.0","subtotal_in_currency":"$10.0","interval":1,"interval_unit":"month","subtotal_for_display":"$10.00 every 1 month","start_date":"2025-05-27"}]

One of:

cart.messagesobject

Example: {"errors":["Insufficient inventory","Product no longer available"],"warnings":["Low stock warning","Shipping delays expected"],"info":["Free shipping available","Volume discount applied"]}

cart.points_enabledboolean

Example: true

cart.points_appliedinteger

Example: 100

cart.points_valuenumber

Example: 10

cart.remaining_amount_for_cardnumber or string

Example: "10.0"

metaobjectrequired

meta.shop_urlstringrequired

Example: "https://myco.fluid.app"

meta.checkout_urlstringrequired

Example: "https://checkout.fluid.com/checkout?jwt=abc123"

meta.request_idstringrequired

Example: "f5473a8c-8a86-4e0e-b3e8-95392003921b"

meta.timestampstringrequired

Example: "2024-12-10T08:04:10Z"

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "shop_url": "https://myco.fluid.app",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "request_id": "f5473a8c-8a86-4e0e-b3e8-95392003921b",
    "timestamp": "2024-12-10T08:04:10Z"
  }
}

Removes rep_buyer and customer for the cart

Request

Path

cart_tokenstringrequired

curl -i -X DELETE \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/logout'

Responses

Logout successful

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates cart attribution

Request

Updates attribution data for a cart

Path

cart_tokenstringrequired

Bodyapplication/json

attributionobject or object or object or objectrequired

One of:

attribution.share_guidstringrequired

Example: "james-bond007"

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/attribution' \
  -H 'Content-Type: application/json' \
  -d '{
    "attribution": {
      "share_guid": "james-bond007"
    }
  }'

Responses

attribution updated

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Updates the buyer rep for the cart

Request

Updates the buyer rep of a cart based on the provided customer_id

Path

cart_tokenstringrequired

Bodyapplication/json

customer_idintegerrequired

ID of the customer to set as buyer rep

Example: 123

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/buyer_rep' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": 123
  }'

Responses

buyer rep updated

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Updates the volume rep for the cart

Request

Updates the volume rep of a cart based on the provided volume_rep_id

Path

cart_tokenstringrequired

Bodyapplication/json

volume_rep_idinteger or null

ID of the user company to set as volume rep

Example: 123

order_on_behalf_ofboolean

Whether the order is on behalf of another volume rep

Example: true

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/volume_rep' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "volume_rep_id": 123,
    "order_on_behalf_of": true
  }'

Responses

volume rep removed

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Updates cart messages

Request

Add or update error, warning, and info messages on a cart. These messages can be used to prevent checkout or provide feedback to users. Supports setting errors (which prevent checkout), warnings, and informational messages.

Path

cart_tokenstringrequired

Bodyapplication/json

errorsArray of strings

Array of error messages. These messages prevent cart checkout.

Example: ["Insufficient inventory","Product no longer available"]

warningsArray of strings

Array of warning messages for user awareness.

Example: ["Low stock warning","Shipping delays expected"]

infoArray of strings

Array of informational messages.

Example: ["Free shipping available","Volume discount applied"]

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/messages' \
  -H 'Content-Type: application/json' \
  -d '{
    "errors": [
      "Insufficient inventory",
      "Product no longer available"
    ],
    "warnings": [
      "Low stock warning",
      "Shipping delays expected"
    ],
    "info": [
      "Free shipping available",
      "Volume discount applied"
    ]
  }'

Responses

messages updated successfully

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Clears cart messages

Request

Clear all cart messages or specific message types (errors, warnings, info). If no message_types are specified, all messages are cleared.

Path

cart_tokenstringrequired

Bodyapplication/json

message_typesArray of strings

Specific message types to clear. If not provided, all messages are cleared.

Items Enum"errors""warnings""info"

Example: ["errors","warnings"]

curl -i -X DELETE \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/messages' \
  -H 'Content-Type: application/json' \
  -d '{
    "message_types": [
      "errors",
      "warnings"
    ]
  }'

Responses

all messages cleared when no types specified

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Updates cart metadata

Request

Updates the metadata field of a cart with custom data. The provided metadata object will be merged with existing metadata. Note: The parameter is still named 'metadata' for backward compatibility.

Path

cart_tokenstringrequired

Bodyapplication/jsonrequired

metadataobjectrequired

Custom data to merge with existing cart metadata

Example: {"custom_field":"value","shipping_preferences":{"express":true}}

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/metadata' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "custom_field": "value",
      "shipping_preferences": {
        "express": true
      }
    }
  }'

Responses

metadata updated successfully

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Recalculates cart totals and pricing

Request

Recalculates the cart by calling save_cart! on the carts service, which updates totals, pricing, taxes, and other calculated fields. Optionally filters available payment methods and updates allowed integration classes.

Path

cart_tokenstringrequired

Query

payment_methods_includesstring

Comma-separated list of payment method integration classes to include (e.g., 'CreditCard,Klarna'). Updates cart's allowed integration classes.

payment_accountstring

Payment account UUID to associate with the cart

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/recalculate?payment_account=string&payment_methods_includes=string'

Responses

cart recalculated with payment account

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Update cart items prices

Request

Path

cart_tokenstringrequired

Cart token

Bodyapplication/json

cart_itemsArray of objectsrequired

Array of cart items with their new prices

cart_items[].idintegerrequired

Cart item ID

Example: 123

cart_items[].pricenumber(decimal)required

New price for the cart item

Example: 29.99

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/update_cart_items_prices' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cart_items": [
      {
        "id": 123,
        "price": 29.99
      }
    ]
  }'

Responses

filters out non-existent cart items and updates only matching ones

Bodyapplication/json

cartobjectrequired

cart.cart_tokenstring

cart.metadataobject

cart.property name*anyadditional property

metaobjectrequired

meta.request_idstring

meta.timestampstring(date-time)

Response

application/json

{
  "cart": {
    "cart_token": "string",
    "metadata": { … }
  },
  "meta": {
    "request_id": "string",
    "timestamp": "2019-08-24T14:15:22Z"
  }
}

Updates cart totals manually

Request

Manually updates cart totals such as discount, tax, shipping, amount, and transaction fee. This will always skips internal tax and shipping calculations to preserve the manual values. This is useful for external integrations that need to override calculated totals.

Path

cart_tokenstringrequired

Bodyapplication/json

Cart totals to update

non-empty

discount_totalnumber or null

Discount total amount

Example: 15.5

tax_totalnumber or null

Tax total amount.

Example: 8.75

shipping_totalnumber or null

Shipping total amount.

Example: 12

amount_totalnumber or null

Total amount including all fees

Example: 125.25

transaction_feenumber or null

Transaction fee amount

Example: 3.5

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/update_totals' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "discount_total": 15.5,
    "tax_total": 8.75,
    "shipping_total": 12,
    "amount_total": 125.25,
    "transaction_fee": 3.5
  }'

Responses

cart totals updated successfully

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z"
  }
}

Applies points redemption to cart

Request

Apply points redemption to reduce the cart total. Requires the cart to have an associated customer and sufficient available points. Points redemption is stored in cart metadata and will be processed during checkout.

Path

cart_tokenstringrequired

The cart token

Bodyapplication/json

points_amountintegerrequired

Amount of points to redeem (must be greater than 0)

Example: 500

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/apply_points' \
  -H 'Content-Type: application/json' \
  -d '{
    "points_amount": 500
  }'

Responses

points applied successfully

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Removes points redemption from cart

Request

Remove previously applied points redemption from the cart. This restores the cart total to its original amount.

Path

cart_tokenstringrequired

The cart token

curl -i -X DELETE \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/remove_points'

Responses

points removed successfully

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Sets a saved payment method for a cart

Request

Sets a saved payment method for a cart. Requires customer authentication or company admin access. The payment method must belong to the customer's fluid pay account.

Path

cart_tokenstringrequired

The cart token

Example: abc123def456

Bodyapplication/jsonrequired

The ID of the saved payment method to set

payment_method_idintegerrequired

ID of the saved payment method

Example: 123

curl -i -X POST \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/set_saved_payment_method' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_method_id": 123
  }'

Responses

Payment method set successfully

Bodyapplication/json

cartobjectrequired

cart.idinteger

Example: 123

cart.statestring

Example: "start"

cart.processedboolean

Determines if a cart payment has been processed or not.

Example: false

cart.valid_for_checkoutboolean

Example: true

cart.buyer_rep_idinteger or null

Example: 1

cart.buyer_repobject or null

One of:

cart.volume_repobject or null

One of:

cart.currency_symbolstring

Example: "$"

cart.currency_codestring

Example: "USD"

cart.shipping_total_for_displaystring

Example: "Free"

cart.phonestring or null

Example: "4035551212"

cart.payment_method_auto_assignableboolean

Determines if a payment method can be auto-assigned to the cart.

Example: true

cart.attribution(object or object or object or object or object) or null

Default {"id":456,"share_guid":"james-bond007"}

One of:

cart.agreementsArray of objects or null

cart.amount_totalstring

Example: "121.65"

cart.amount_total_in_currencystring

Example: "$121.65 (USD)"

cart.sub_totalstring

Example: "100.00"

cart.sub_total_in_currencystring

Example: "$100.00 (USD)"

cart.subtotal_after_discountsstring

Example: "90.00"

cart.tax_totalstring

Example: "20.00"

cart.tax_total_in_currencystring

Example: "$20.00 (USD)"

cart.shipping_totalstring or null

Example: "1.65"

cart.shipping_total_in_currencystring

Example: "$1.65 (USD)"

cart.shipping_discountnumber

Example: 10.25

cart.discount_totalstring

Example: "2.99"

cart.discount_total_in_currencystring

Example: "$2.99 (USD)"

cart.discount_breakdownobject

cart.external_discountobject

cart.transaction_feenumber or string

Example: "1.90"

cart.transaction_fee_in_currencystring

Example: "$1.90 (USD)"

cart.cv_totalinteger

Example: 10

cart.qv_totalinteger

Example: 15

cart.companyobject

cart.payment_accountstring or null

Example: "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An"

cart.payment_methodnull or object or object or object or object or object or object

One of:

null

cart.emailstring or null

Example: "user@example.com"

cart.enrollment_feenumber or string

Example: "10.45"

cart.enrollment_fee_in_currencystring

Example: "$10.45"

cart.discount_codesArray of strings

Example: ["DISCOUNT10","DISCOUNT11"]

cart.language_isostring or null

Example: "en"

cart.cart_tokenstring

Example: "abc123"

cart.immutable_itemsboolean

Example: false

cart.digital_onlyboolean

Example: false

cart.requires_3dsboolean

Example: false

cart.itemsArray of objects

cart.ship_toobject or null

cart.bill_toobject or null

cart.shipping_methodobject or null

cart.available_shipping_methodsArray of objects

cart.available_payment_methodsArray of objects or objects

cart.countryobject

cart.typestring

Enum"regular""enrollment"

Example: "regular"

cart.enrollment_pack_idinteger or null

Example: 1

cart.enrollment_packobject or null

cart.metadataobject

A JSON object that can store any custom data structure.

cart.recurringArray of objects or null

Default [{"subtotal":"10.0","subtotal_in_currency":"$10.0","interval":1,"interval_unit":"month","subtotal_for_display":"$10.00 every 1 month","start_date":"2025-05-27"}]

One of:

cart.messagesobject

Example: {"errors":["Insufficient inventory","Product no longer available"],"warnings":["Low stock warning","Shipping delays expected"],"info":["Free shipping available","Volume discount applied"]}

cart.points_enabledboolean

Example: true

cart.points_appliedinteger

Example: 100

cart.points_valuenumber

Example: 10

cart.remaining_amount_for_cardnumber or string

Example: "10.0"

metaobjectrequired

meta.shop_urlstringrequired

Example: "https://myco.fluid.app"

meta.checkout_urlstringrequired

Example: "https://checkout.fluid.com/checkout?jwt=abc123"

meta.request_idstringrequired

Example: "f5473a8c-8a86-4e0e-b3e8-95392003921b"

meta.timestampstringrequired

Example: "2024-12-10T08:04:10Z"

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "shop_url": "https://myco.fluid.app",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "request_id": "f5473a8c-8a86-4e0e-b3e8-95392003921b",
    "timestamp": "2024-12-10T08:04:10Z"
  }
}

Updates a cart item's variant

Request

Updates a cart item to use a different variant. If the target variant already exists in another cart item, the quantities are consolidated.

Consolidation behavior:

If cart already has an item with the target variant_id, the source item's quantity is added to the existing item
The source item is then removed
Otherwise, the cart item's variant is updated directly

Optional quantity parameter:

If provided, uses this quantity instead of the current cart item quantity when updating to a new variant
When consolidating, this quantity is added to the existing item's quantity (not replacing it)

Path

cart_tokenstringrequired

The cart token

Example: abc123def456

item_idintegerrequired

The cart item ID

Example: 123

Bodyapplication/jsonrequired

Variant update parameters

variant_idintegerrequired

The new variant ID to assign to this cart item

Example: 456

quantityinteger

Optional: Override the quantity (must be >= 1)

Example: 2

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/items/{item_id}/variant' \
  -H 'Content-Type: application/json' \
  -d '{
    "variant_id": 456,
    "quantity": 2
  }'

Responses

Variant updated successfully

Bodyapplication/json

cartobjectrequired

cart.idinteger

Example: 123

cart.statestring

Example: "start"

cart.processedboolean

Determines if a cart payment has been processed or not.

Example: false

cart.valid_for_checkoutboolean

Example: true

cart.buyer_rep_idinteger or null

Example: 1

cart.buyer_repobject or null

One of:

cart.volume_repobject or null

One of:

cart.currency_symbolstring

Example: "$"

cart.currency_codestring

Example: "USD"

cart.shipping_total_for_displaystring

Example: "Free"

cart.phonestring or null

Example: "4035551212"

cart.payment_method_auto_assignableboolean

Determines if a payment method can be auto-assigned to the cart.

Example: true

cart.attribution(object or object or object or object or object) or null

Default {"id":456,"share_guid":"james-bond007"}

One of:

cart.agreementsArray of objects or null

cart.amount_totalstring

Example: "121.65"

cart.amount_total_in_currencystring

Example: "$121.65 (USD)"

cart.sub_totalstring

Example: "100.00"

cart.sub_total_in_currencystring

Example: "$100.00 (USD)"

cart.subtotal_after_discountsstring

Example: "90.00"

cart.tax_totalstring

Example: "20.00"

cart.tax_total_in_currencystring

Example: "$20.00 (USD)"

cart.shipping_totalstring or null

Example: "1.65"

cart.shipping_total_in_currencystring

Example: "$1.65 (USD)"

cart.shipping_discountnumber

Example: 10.25

cart.discount_totalstring

Example: "2.99"

cart.discount_total_in_currencystring

Example: "$2.99 (USD)"

cart.discount_breakdownobject

cart.external_discountobject

cart.transaction_feenumber or string

Example: "1.90"

cart.transaction_fee_in_currencystring

Example: "$1.90 (USD)"

cart.cv_totalinteger

Example: 10

cart.qv_totalinteger

Example: 15

cart.companyobject

cart.payment_accountstring or null

Example: "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An"

cart.payment_methodnull or object or object or object or object or object or object

One of:

null

cart.emailstring or null

Example: "user@example.com"

cart.enrollment_feenumber or string

Example: "10.45"

cart.enrollment_fee_in_currencystring

Example: "$10.45"

cart.discount_codesArray of strings

Example: ["DISCOUNT10","DISCOUNT11"]

cart.language_isostring or null

Example: "en"

cart.cart_tokenstring

Example: "abc123"

cart.immutable_itemsboolean

Example: false

cart.digital_onlyboolean

Example: false

cart.requires_3dsboolean

Example: false

cart.itemsArray of objects

cart.ship_toobject or null

cart.bill_toobject or null

cart.shipping_methodobject or null

cart.available_shipping_methodsArray of objects

cart.available_payment_methodsArray of objects or objects

cart.countryobject

cart.typestring

Enum"regular""enrollment"

Example: "regular"

cart.enrollment_pack_idinteger or null

Example: 1

cart.enrollment_packobject or null

cart.metadataobject

A JSON object that can store any custom data structure.

cart.recurringArray of objects or null

Default [{"subtotal":"10.0","subtotal_in_currency":"$10.0","interval":1,"interval_unit":"month","subtotal_for_display":"$10.00 every 1 month","start_date":"2025-05-27"}]

One of:

cart.messagesobject

Example: {"errors":["Insufficient inventory","Product no longer available"],"warnings":["Low stock warning","Shipping delays expected"],"info":["Free shipping available","Volume discount applied"]}

cart.points_enabledboolean

Example: true

cart.points_appliedinteger

Example: 100

cart.points_valuenumber

Example: 10

cart.remaining_amount_for_cardnumber or string

Example: "10.0"

metaobjectrequired

meta.shop_urlstringrequired

Example: "https://myco.fluid.app"

meta.checkout_urlstringrequired

Example: "https://checkout.fluid.com/checkout?jwt=abc123"

meta.request_idstringrequired

Example: "f5473a8c-8a86-4e0e-b3e8-95392003921b"

meta.timestampstringrequired

Example: "2024-12-10T08:04:10Z"

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "shop_url": "https://myco.fluid.app",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "request_id": "f5473a8c-8a86-4e0e-b3e8-95392003921b",
    "timestamp": "2024-12-10T08:04:10Z"
  }
}

Updates cart json_data (DEPRECATED - use /metadata instead)Deprecated

Request

⚠️ DEPRECATED: This endpoint is maintained for backward compatibility only. Please use PATCH /api/carts/{cart_token}/metadata instead.

Updates the metadata field of a cart with custom data. The provided json_data object will be merged with existing metadata.

Path

cart_tokenstringrequired

Bodyapplication/jsonrequired

json_dataobjectrequired

Custom data to merge with existing cart metadata

Example: {"custom_field":"value","shipping_preferences":{"express":true}}

curl -i -X PATCH \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/carts/{cart_token}/json_data' \
  -H 'Content-Type: application/json' \
  -d '{
    "json_data": {
      "custom_field": "value",
      "shipping_preferences": {
        "express": true
      }
    }
  }'

Responses

json_data updated successfully

Bodyapplication/json

cartobject

metaobject

Response

application/json

{
  "cart": {
    "id": 123,
    "state": "start",
    "processed": false,
    "valid_for_checkout": true,
    "buyer_rep_id": 1,
    "buyer_rep": { … },
    "volume_rep": { … },
    "currency_symbol": "$",
    "currency_code": "USD",
    "shipping_total_for_display": "Free",
    "phone": "4035551212",
    "payment_method_auto_assignable": true,
    "attribution": { … },
    "agreements": [ … ],
    "amount_total": "121.65",
    "amount_total_in_currency": "$121.65 (USD)",
    "sub_total": "100.00",
    "sub_total_in_currency": "$100.00 (USD)",
    "subtotal_after_discounts": "90.00",
    "tax_total": "20.00",
    "tax_total_in_currency": "$20.00 (USD)",
    "shipping_total": "1.65",
    "shipping_total_in_currency": "$1.65 (USD)",
    "shipping_discount": 10.25,
    "discount_total": "2.99",
    "discount_total_in_currency": "$2.99 (USD)",
    "discount_breakdown": { … },
    "external_discount": { … },
    "transaction_fee": "1.90",
    "transaction_fee_in_currency": "$1.90 (USD)",
    "cv_total": 10,
    "qv_total": 15,
    "company": { … },
    "payment_account": "pa_Zcx1cDSwVdFoISFiWhwGKKjDLH9dM3An",
    "payment_method": {},
    "email": "user@example.com",
    "enrollment_fee": "10.45",
    "enrollment_fee_in_currency": "$10.45",
    "discount_codes": [ … ],
    "language_iso": "en",
    "cart_token": "abc123",
    "immutable_items": false,
    "digital_only": false,
    "requires_3ds": false,
    "items": [ … ],
    "ship_to": { … },
    "bill_to": { … },
    "shipping_method": { … },
    "available_shipping_methods": [ … ],
    "available_payment_methods": [ … ],
    "country": { … },
    "type": "regular",
    "enrollment_pack_id": 1,
    "enrollment_pack": { … },
    "metadata": {},
    "recurring": [ … ],
    "messages": { … },
    "points_enabled": true,
    "points_applied": 100,
    "points_value": 10,
    "remaining_amount_for_card": "10.0"
  },
  "meta": {
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "timestamp": "2021-01-01T00:00:00Z",
    "checkout_url": "https://checkout.fluid.com/checkout?jwt=abc123",
    "shop_url": "https://myco.fluid.app"
  }
}

Collections

Operations

Companies

Operations

Company Admins

Operations

Company Countries

Operations

Company Custom Catch Ups

Operations

Company Discounts

Operations

Company Email Settings

Operations

Company Media

Operations

Company Mobile Widgets

Operations

Company Pages

Operations

Pages

Operations

Company Settings - Checkout

Operations

Company Settings - Countries

Operations

Company Settings - Languages

Operations

Company Settings - Warehouses

Operations

Company Webhook Events

Operations

Contacts

Operations

Currencies

Operations

Customer Orders

Operations

CustomerNotes

Operations

Customers

Operations

DAM Query

Operations

Dam

Operations

Default Libraries

Operations

DefaultMySites

Operations

Devices

Operations

Display Settings

Operations

Domains

Operations

Drop Zones

Operations

Droplet Categories

Operations

Droplet Installations

Operations

Droplets

Operations

Enrollment Packs

Operations

Enrollments

Operations

Entities

Operations

FairShare Order Journey

Operations

Fantasy Points

Operations

Feature Flags

Operations

File Resources

Operations

Fluid Pay

Operations

Form Elements

Operations

Forms

Operations

GlobalEmbeds

Operations

Impersonation

Operations

Inventory Levels

Operations

Labels

Operations

MCC Codes

Operations

Media

Operations

Menus

Operations

Metafield Definitions

Operations

Metafields

Operations

Multi Factor Authentications

Operations

Multi-Factor Authentications

Operations

Notifications

Operations

Onboarding

Operations

Onboarding Info

Operations

Order Fulfillments

Operations

Orders

Operations

Owners

Operations

Payment

Operations

Payment Accounts

Operations

Payment Integrations

Operations

Payments

Operations

Paypal

Operations

Points Ledgers

Operations

Posts

Operations

ProductBundles

Operations

ProductImages

Operations

ProductSubscriptionPlans

Operations

Products

Operations

Prompts

Operations

Public Assets

Operations

Public Companies

Operations

Public Drop Zones

Operations

Ranks

Operations

Redirects

Operations

Refunds

Operations

Reps

Operations

Roles

Operations

Search

Operations

Settings

Operations

Settings - Companies

Operations

Shop

Operations

Sitemap

Operations

Subscription Plans

Operations

Subscriptions

Operations

System Monitoring

Operations

Tax Categories

Operations

Theme Region Rules

Operations

Tracking Informations

Operations

Tree Nodes

Operations

Trees

Operations

Users

Operations

Variant Countries

Operations

VariantCountries

Operations

VariantImages

Operations

VariantInventoryLevels

Operations

Variants

Operations

Webhook Schemas

Operations

Webhooks

Operations

Get a specific media

Request

Path

idintegerrequired

Media ID

Example: 1

Query

language_isostring

Language code for translations (e.g., 'en', 'es', 'de')

curl -i -X GET \
  'https://docs.fluid.app/_mock/docs/apis/swagger/api/media/{id}?language_iso=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Media retrieved successfully

Bodyapplication/json

idinteger

user_idinteger or null

titlestring

descriptionobject or null

media_typestring

media_formatstring or null

strippedstring or null

share_linkstring or null

preview_linkstring or null

video_urlstring or null

image_urlstring or null

pdf_urlstring or null

activeboolean

viewsinteger

leadsinteger

watchobject or null

video_statusstring or null

durationinteger or null

kindstring or null

cta_urlstring or null

cta_button_textstring or null

cta_action_typestring or null

cta_enabledboolean

labelstring or null

display_tagstring or null

promptsArray of objects

attached_shareablesArray of objects

ranksArray of objects

visibilityinteger or null

video_shopping_enabledboolean

prompts_enabledboolean

created_atstring

application_theme_template_idinteger or null

settingsobject

countriesArray of objects

Response

application/json

{
  "id": 0,
  "user_id": 0,
  "title": "string",
  "description": {},
  "media_type": "string",
  "media_format": "string",
  "stripped": "string",
  "share_link": "string",
  "preview_link": "string",
  "video_url": "string",
  "image_url": "string",
  "pdf_url": "string",
  "active": true,
  "views": 0,
  "leads": 0,
  "watch": {},
  "video_status": "string",
  "duration": 0,
  "kind": "string",
  "cta_url": "string",
  "cta_button_text": "string",
  "cta_action_type": "string",
  "cta_enabled": true,
  "label": "string",
  "display_tag": "string",
  "prompts": [
    {}
  ],
  "attached_shareables": [
    {}
  ],
  "ranks": [
    {}
  ],
  "visibility": 0,
  "video_shopping_enabled": true,
  "prompts_enabled": true,
  "created_at": "string",
  "application_theme_template_id": 0,
  "settings": {},
  "countries": [
    { … }
  ]
}

Fluid Commerce APIs (1.0)

Admins

Agreements

Announcements

ApplePay

Application Theme Templates

Application Themes

ApplicationThemeResources

ApplicationThemeTemplates

Authentication

Bank Accounts

Business Types

Callback Definitions

Callback Registrations

Callback Schemas

Carts

Append metadata field

Request

Responses

Was this helpful?

Remove metadata fields

RequestExpand all

Responses

Was this helpful?

Creates a cart

RequestExpand all

Responses

Was this helpful?

Updates cart address

RequestExpand all

Responses

Was this helpful?

Retrieves a cart

Request

Responses

Was this helpful?

Updates a cart

Request

Responses

Was this helpful?

Applies a discount to the cart

Request

Responses

Was this helpful?

Remove discount from the cart

Request

Responses

Was this helpful?

Adds new items to cart, updates quantities of existing items, or removes items with quantity 0

RequestExpand all

Responses

Was this helpful?

Removes items from cart

RequestExpand all

Responses

Was this helpful?

Removes item from cart

Request

Responses

Was this helpful?

Retrieves enroll for cart

Request

Responses

Was this helpful?

Sets cart payment method

RequestExpand all

Responses

Was this helpful?

Gets VGS vault access token

Request

Responses

Was this helpful?

Sets cart shipping method

Request

Responses

Was this helpful?

Completes cart checkout

RequestExpand all

Responses

Was this helpful?

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request