Get Consents

GET https://api.firmly.work/api/v2/domains/{domain}/cart/consents

​​ Overview

Retrieves the current consent settings for a buyer’s cart session. This endpoint returns all available consent options along with their current status, including whether they have been signed by the buyer.

​​ How Consent Management Works

1. Session-Based: Consents are stored on the cart session and persist until checkout completion.
2. Type-Based: Different consent types (marketing, terms, privacy) are supported.
3. UI Placement: Each consent carries a ui_slot hint for placement in your checkout UI.

​​ Authentication

• x-firmly-authorization (string, required) — Device access token from Browser Session

​​ Path Parameters

• domain (string, required) — Domain of the merchant website (e.g., staging.luma.gift)

​​ Response

Returns a JSON array of consent objects (no top-level wrapper). Each item has the following fields:

• id (string, required) — Unique identifier for the consent.

• ui_slot (string, required) — UI placement hint. One of:

  • UNDER_EMAIL_INPUT — Display under the email field
  • ABOVE_PLACE_ORDER_BUTTON — Display above the place-order button

• text (string, required) — Plain-text version of the consent (use for accessibility and as a fallback).

• html (string) — Optional HTML version with rich formatting and links. Render this when present; fall back to text otherwise.

• type (string, required) — Type of consent. One of:

  • MARKETING — Marketing communications
  • TERMS_AND_CONDITIONS — Terms of service
  • PRIVACY_POLICY — Privacy policy
  • OTHER — Anything that does not fit the above

• explicit (boolean, required) — true when the buyer must take an explicit action (e.g. tick a checkbox); false when the consent is implicitly granted by completing checkout.

• required (boolean, required) — Whether this consent must be accepted for checkout to complete.

• revokable (boolean, required) — Whether the buyer can revoke this consent after signing.

• signed (boolean, required) — Whether this consent is considered signed. Computed server-side as signed = hasSignature OR (explicit === false AND required === true) — so implicit-required consents return signed: true automatically without the buyer having explicitly accepted them.

​​ Code Examples

curl -X GET https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/consents \
  -H "x-firmly-authorization: YOUR_TOKEN"

const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/consents', {
  method: 'GET',
  headers: {
    'x-firmly-authorization': 'YOUR_TOKEN'
  }
});

const consents = await response.json();

import requests

response = requests.get(
    'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/consents',
    headers={
        'x-firmly-authorization': 'YOUR_TOKEN'
    }
)

consents = response.json()

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/consents');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-firmly-authorization: YOUR_TOKEN'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$consents = json_decode($response, true);
curl_close($ch);

​​ Response Example

[
  {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "ui_slot": "UNDER_EMAIL_INPUT",
    "text": "I would like to receive marketing emails about special offers and new products.",
    "type": "MARKETING",
    "explicit": true,
    "required": false,
    "revokable": true,
    "signed": false
  },
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "ui_slot": "ABOVE_PLACE_ORDER_BUTTON",
    "text": "I agree to the Terms of Service and Privacy Policy.",
    "html": "I agree to the <a href='/terms'>Terms of Service</a> and <a href='/privacy'>Privacy Policy</a>.",
    "type": "TERMS_AND_CONDITIONS",
    "explicit": true,
    "required": true,
    "revokable": false,
    "signed": true
  }
]

​​ Default Consent States

If the merchant has not configured explicit consents but has set marketing_consent_text in their Firmly configuration, a single marketing consent is generated:

• It is optional (required: false) and revokable (revokable: true)
• No other consents are created by default

If the merchant has configured neither explicit consents nor marketing_consent_text, the endpoint returns an empty array.

​​ Error Responses

Errors return a JSON body with code, error, and description. Program against the error value — descriptions are human-readable and may change.

{ "code": 400, "error": "MissingAuthHeader", "description": "x-firmly-authorization header is missing or invalid." }

{ "code": 400, "error": "InvalidToken", "description": "Jwt token is invalid." }

{ "code": 400, "error": "InvalidAPIToken", "description": "API token is invalid." }

{ "code": 400, "error": "BadRequest", "description": "Bad request." }

{ "code": 401, "error": "Unauthorized", "description": "Unauthorized." }

{ "code": 401, "error": "InvalidJWTToken", "description": "Jwt token is invalid." }

{ "code": 404, "error": "PartnerNotFound", "description": "Partner not found." }

{ "code": 404, "error": "DomainNotFound", "description": "This domain was not found in firmly servers." }

{ "code": 404, "error": "CartNotFound", "description": "Cart was not found." }

{ "code": 412, "error": "OperationNotSupported", "description": "This operation is not supported for this store." }