{"openapi":"3.0.3","x-tagGroups":[{"name":"Payments","tags":["Checkout Sessions","Payment Intents","Payment Methods","Payment Links"]},{"name":"Customers","tags":["Customers","Subscriptions","Billing Portal"]},{"name":"Catalog","tags":["Products","Coupons","Promotion Codes"]},{"name":"Platform","tags":["Notification Channels","Claims","Delivery"]},{"name":"System","tags":["SDK","Health","Meta"]}],"info":{"title":"Kling API","description":"Payments and subscriptions platform for Iceland.\n\n## Getting Started\n\n### 1. Get your API keys\n\nSign up at [kling.is](https://kling.is) and retrieve your API keys from the dashboard. You'll have two keys:\n- **Test key** (`sk_test_...`) - Use for development and testing\n- **Live key** (`sk_live_...`) - Use for production\n\n### 2. Authentication\n\nAll API requests require authentication using Bearer tokens:\n\n```bash\ncurl https://api.kling.is/v1/checkout/sessions \\\n -H \"Authorization: Bearer sk_test_...\" \\\n -H \"Content-Type: application/json\"\n```\n\n### 3. Create a Checkout Session\n\nStart accepting payments by creating a checkout session:\n\n```bash\ncurl https://api.kling.is/v1/checkout/sessions \\\n -H \"Authorization: Bearer sk_test_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"amount\": 1000,\n \"currency\": \"ISK\",\n \"success_url\": \"https://example.com/success\"\n }'\n```\n\nThis returns a `url` - redirect your customer there to complete payment.\n\n### 4. Handle the result\n\nAfter payment, the customer is redirected to your `success_url`. For server-side confirmation, register a webhook via `POST /v1/notification-channels` and subscribe to `checkout.session.completed` and `payment_intent.captured`.\n\nIf you asked for your own `form_fields` (for example a gift message or a delivery address), the customer's answers are returned as `custom_fields`, keyed by field name, both on `GET /v1/checkout/sessions/{id}` and in the `checkout.session.completed` webhook data.\n\n## SDKs & Libraries\n\n### Browser SDK (Embedded Checkout)\n\nInstall via npm:\n\n```bash\nnpm install @klingis/embed\n```\n\n```typescript\nimport { Kling } from '@klingis/embed';\n\nconst kling = Kling.init();\nconst result = await kling.checkout({ sessionId: 'cs_xxx' });\n```\n\nOr use the CDN script tag:\n\n```html\n<script src=\"https://api.kling.is/v1/kling.js\"></script>\n<script>\n const kling = Kling.init();\n const result = await kling.checkout({ sessionId: 'cs_xxx' });\n</script>\n```\n\n### TypeScript / JavaScript (Server-side)\n\nInstall the typed server SDK:\n\n```bash\nnpm install @klingis/sdk\n```\n\n### Other Languages\n\nUse this OpenAPI specification with any OpenAPI code generator (e.g. openapi-generator-cli) to create a client in Python, Go, Ruby, Java, etc.\n","version":"1.0.0","x-sdks":{"javascript":{"name":"Kling Browser SDK","type":"browser","description":"Embedded checkout overlay: no redirect, customers stay on your page","install":"npm install @klingis/embed","example":"const kling = Kling.init();\nconst result = await kling.checkout({ sessionId: 'cs_xxx' });\nif (result.success) console.log('Payment:', result.paymentIntentId);"},"typescript":{"name":"Kling TypeScript SDK","type":"server","description":"Typed API client for Node.js / Bun / Deno server-side usage","install":"npm install @klingis/sdk","example":"import { configure, createCheckoutSession } from '@klingis/sdk';\n\nconfigure({ baseUrl: 'https://api.kling.is', headers: { 'x-api-key': 'sk_...' } });\n\nconst session = await createCheckoutSession({\n amount: 1000,\n currency: 'ISK',\n success_url: 'https://example.com/success',\n});"},"other":{"name":"Any Language (via OpenAPI)","type":"generated","description":"Generate a client in Python, Go, Ruby, Java, etc. from this spec","install":"npx @openapitools/openapi-generator-cli generate -i https://api.kling.is/docs/json -g -o ./kling-client"}}},"servers":[{"url":"https://api.kling.is","description":"Production"}],"tags":[{"name":"Checkout Sessions","description":"Create and manage checkout sessions. A checkout session represents a single payment flow: redirect your customer to the session URL to collect payment."},{"name":"Payment Intents","description":"Track the lifecycle of a payment from creation through authorization, capture, and refund. Each payment intent represents a single payment attempt."},{"name":"Payment Methods","description":"Save and manage tokenized payment methods for returning customers. Supports card tokenization with PCI-compliant handling."},{"name":"Payment Links","description":"Create shareable payment links that can be sent to customers via email, SMS, or chat. No integration required."},{"name":"Customers","description":"Create and manage customer records. Customers can have saved payment methods and active subscriptions."},{"name":"Products","description":"Define products with pricing for one-off payments or recurring subscriptions."},{"name":"Subscriptions","description":"Manage recurring billing. Subscriptions are created through checkout sessions with subscription products."},{"name":"Billing Portal","description":"Generate portal sessions that let your customers manage their subscriptions, update payment methods, and view billing history."},{"name":"Coupons","description":"Create discount coupons with percentage or fixed-amount reductions. Coupons can be limited by redemption count and duration."},{"name":"Promotion Codes","description":"Create customer-facing codes that apply coupons at checkout. Codes can be restricted by customer, expiration date, and usage limits."},{"name":"Notification Channels","description":"Configure webhook endpoints and Slack channels to receive real-time notifications about payment events."},{"name":"Claims","description":"Manage bank claims (kröfur) for collecting payments through the Icelandic banking system."},{"name":"SDK","description":"Browser SDK for embedded checkout overlays."},{"name":"Health","description":"Server health and readiness checks."},{"name":"Meta","description":"Server metadata and diagnostics."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key in Bearer format"}},"schemas":{}},"paths":{"/health":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"ok","type":"string"},"timestamp":{"type":"string"},"version":{"type":"string"}},"required":["status","timestamp","version"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"status":{"const":"ok","type":"string"},"timestamp":{"type":"string"},"version":{"type":"string"}},"required":["status","timestamp","version"]}},"text/plain":{"schema":{"type":"object","properties":{"status":{"const":"ok","type":"string"},"timestamp":{"type":"string"},"version":{"type":"string"}},"required":["status","timestamp","version"]}}}}},"operationId":"getHealth","tags":["Health"],"summary":"Liveness check"}},"/ready":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"const":"ok","type":"string"},{"const":"degraded","type":"string"}]},"db":{"type":"boolean"},"timestamp":{"type":"string"}},"required":["status","db","timestamp"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"const":"ok","type":"string"},{"const":"degraded","type":"string"}]},"db":{"type":"boolean"},"timestamp":{"type":"string"}},"required":["status","db","timestamp"]}},"text/plain":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"const":"ok","type":"string"},{"const":"degraded","type":"string"}]},"db":{"type":"boolean"},"timestamp":{"type":"string"}},"required":["status","db","timestamp"]}}}},"503":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"const":"ok","type":"string"},{"const":"degraded","type":"string"}]},"db":{"type":"boolean"},"timestamp":{"type":"string"}},"required":["status","db","timestamp"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"const":"ok","type":"string"},{"const":"degraded","type":"string"}]},"db":{"type":"boolean"},"timestamp":{"type":"string"}},"required":["status","db","timestamp"]}},"text/plain":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"const":"ok","type":"string"},{"const":"degraded","type":"string"}]},"db":{"type":"boolean"},"timestamp":{"type":"string"}},"required":["status","db","timestamp"]}}}}},"operationId":"getReady","tags":["Health"],"summary":"Readiness check (includes DB probe)"}},"/metrics":{"get":{"operationId":"getMetrics","tags":["Health"],"summary":"Prometheus metrics","responses":{"200":{}}}},"/v1":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"documentation":{"type":"string"}},"required":["name","version","documentation"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"documentation":{"type":"string"}},"required":["name","version","documentation"]}},"text/plain":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"documentation":{"type":"string"}},"required":["name","version","documentation"]}}}}},"operationId":"getV1","tags":["Meta"],"summary":"API version info"}},"/v1/device/authorize":{"post":{"parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_url":{"type":"string"},"expires_in":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"poll_interval":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}},"required":["device_code","user_code","verification_url","expires_in","poll_interval"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_url":{"type":"string"},"expires_in":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"poll_interval":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}},"required":["device_code","user_code","verification_url","expires_in","poll_interval"]}},"text/plain":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_url":{"type":"string"},"expires_in":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]},"poll_interval":{"anyOf":[{"format":"integer","default":0,"type":"string"},{"type":"integer"}]}},"required":["device_code","user_code","verification_url","expires_in","poll_interval"]}}}}},"operationId":"postV1DeviceAuthorize","tags":["Device Auth"],"summary":"Start device authorization flow","description":"Initiates a device auth flow for CLI or AI agent. Returns a user code to display and a device code for polling.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_name"],"properties":{"client_name":{"minLength":1,"maxLength":100,"description":"Client identifier, e.g. \"Kling CLI v1.0.0\"","type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["client_name"],"properties":{"client_name":{"minLength":1,"maxLength":100,"description":"Client identifier, e.g. \"Kling CLI v1.0.0\"","type":"string"}}}},"text/plain":{"schema":{"type":"object","required":["client_name"],"properties":{"client_name":{"minLength":1,"maxLength":100,"description":"Client identifier, e.g. \"Kling CLI v1.0.0\"","type":"string"}}}}}}}},"/v1/device/token":{"get":{"parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"device_code","required":true}],"operationId":"getV1DeviceToken","tags":["Device Auth"],"summary":"Poll for device authorization result","description":"Poll this endpoint to check if the user has authorized the device. Returns the API key once authorized.","responses":{"200":{}}}},"/v1/merchant":{"get":{"operationId":"getV1Merchant","tags":["Merchant"],"summary":"Get current merchant profile","description":"Returns the merchant profile associated with the API key.\n\n`capabilities` is the onboarding lifecycle per capability (payments, claims, tap_to_pay). `enabled_capabilities` is the list of capability ids that work right now in this key's environment, derived from what the merchant has configured: `payments.card` (an active card acquirer), `payments.bank_claim` (an active bank-claims provider), `delivery.dropp` (an active Dropp carrier, see the Delivery endpoints). Use it to decide which features to offer; for example only show a pickup-point step when `delivery.dropp` is present. `features` holds rollout flags: `features.pos` is true when the Kling POS (product pages, cash sales, paired terminal, staff PINs, Z-report) is switched on for this merchant; while it is false the POS routes answer 403 `pos_not_enabled`.","responses":{"200":{}}},"patch":{"parameters":[],"operationId":"patchV1Merchant","tags":["Merchant"],"summary":"Update merchant profile","description":"Update merchant profile fields. Only provided fields are updated.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"minLength":1,"maxLength":255,"type":"string"},"merchant_type":{"anyOf":[{"const":"company","type":"string"},{"const":"individual","type":"string"}]},"kennitala":{"minLength":10,"maxLength":10,"pattern":"^\\d{10}$","type":"string"},"phone":{"maxLength":50,"type":"string"},"website":{"maxLength":255,"type":"string"},"business_description":{"maxLength":2000,"type":"string"},"bank_account":{"maxLength":14,"type":"string"},"legal_address":{"type":"object","required":["street","city","postalCode","country"],"properties":{"street":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"minLength":1,"maxLength":255,"type":"string"},"merchant_type":{"anyOf":[{"const":"company","type":"string"},{"const":"individual","type":"string"}]},"kennitala":{"minLength":10,"maxLength":10,"pattern":"^\\d{10}$","type":"string"},"phone":{"maxLength":50,"type":"string"},"website":{"maxLength":255,"type":"string"},"business_description":{"maxLength":2000,"type":"string"},"bank_account":{"maxLength":14,"type":"string"},"legal_address":{"type":"object","required":["street","city","postalCode","country"],"properties":{"street":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}}}}},"text/plain":{"schema":{"type":"object","properties":{"name":{"minLength":1,"maxLength":255,"type":"string"},"merchant_type":{"anyOf":[{"const":"company","type":"string"},{"const":"individual","type":"string"}]},"kennitala":{"minLength":10,"maxLength":10,"pattern":"^\\d{10}$","type":"string"},"phone":{"maxLength":50,"type":"string"},"website":{"maxLength":255,"type":"string"},"business_description":{"maxLength":2000,"type":"string"},"bank_account":{"maxLength":14,"type":"string"},"legal_address":{"type":"object","required":["street","city","postalCode","country"],"properties":{"street":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}}}}}}},"responses":{"200":{}}}},"/v1/merchant/submit":{"post":{"operationId":"postV1MerchantSubmit","tags":["Merchant"],"summary":"Submit merchant for review","description":"Submit the merchant application for review to enable live payments. Requires kennitala, phone, and business description to be set.","responses":{"200":{}}}},"/v1/merchant/registry-lookup":{"post":{"parameters":[],"operationId":"postV1MerchantRegistry-lookup","tags":["Merchant"],"summary":"Look up company in Icelandic registry","description":"Look up a kennitala in the Skatturinn company registry. Returns company name and address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kennitala"],"properties":{"kennitala":{"minLength":10,"maxLength":10,"pattern":"^\\d{10}$","description":"Icelandic kennitala (10 digits)","type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","required":["kennitala"],"properties":{"kennitala":{"minLength":10,"maxLength":10,"pattern":"^\\d{10}$","description":"Icelandic kennitala (10 digits)","type":"string"}}}},"text/plain":{"schema":{"type":"object","required":["kennitala"],"properties":{"kennitala":{"minLength":10,"maxLength":10,"pattern":"^\\d{10}$","description":"Icelandic kennitala (10 digits)","type":"string"}}}}}},"responses":{"200":{}}}},"/v1/merchant/theme/":{"get":{"responses":{"200":{"description":"How the merchant's hosted checkout is branded","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"merchant.theme","type":"string"},"primary_color":{"nullable":true,"anyOf":[{"description":"Hex colour for buttons and accents, e.g. #b45309","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"description":"Hex colour behind the checkout, e.g. #FBF6EE","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"description":"Font family name, e.g. \"Inter\" or \"Red Hat Display\". Google Fonts are loaded by name.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"description":"Font family name for the checkout's headings (title, amount), e.g. \"Archivo Black\". null means headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"description":"Absolute https URL of the merchant's logo, shown at the top of the checkout","type":"string"},{"type":"null"}]},"source":{"nullable":true,"anyOf":[{"description":"Where the theme came from: a website that was scanned, or the surface that pushed it (e.g. kling-pages)","type":"string"},{"type":"null"}]},"updated_at":{"nullable":true,"anyOf":[{"description":"Unix timestamp of the last change, null when no theme is set","type":"number"},{"type":"null"}]}},"required":["object","primary_color","background_color","font_family","heading_font_family","button_roundness","logo_url","source","updated_at"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"object":{"const":"merchant.theme","type":"string"},"primary_color":{"nullable":true,"anyOf":[{"description":"Hex colour for buttons and accents, e.g. #b45309","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"description":"Hex colour behind the checkout, e.g. #FBF6EE","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"description":"Font family name, e.g. \"Inter\" or \"Red Hat Display\". Google Fonts are loaded by name.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"description":"Font family name for the checkout's headings (title, amount), e.g. \"Archivo Black\". null means headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"description":"Absolute https URL of the merchant's logo, shown at the top of the checkout","type":"string"},{"type":"null"}]},"source":{"nullable":true,"anyOf":[{"description":"Where the theme came from: a website that was scanned, or the surface that pushed it (e.g. kling-pages)","type":"string"},{"type":"null"}]},"updated_at":{"nullable":true,"anyOf":[{"description":"Unix timestamp of the last change, null when no theme is set","type":"number"},{"type":"null"}]}},"required":["object","primary_color","background_color","font_family","heading_font_family","button_roundness","logo_url","source","updated_at"]}},"text/plain":{"schema":{"type":"object","properties":{"object":{"const":"merchant.theme","type":"string"},"primary_color":{"nullable":true,"anyOf":[{"description":"Hex colour for buttons and accents, e.g. #b45309","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"description":"Hex colour behind the checkout, e.g. #FBF6EE","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"description":"Font family name, e.g. \"Inter\" or \"Red Hat Display\". Google Fonts are loaded by name.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"description":"Font family name for the checkout's headings (title, amount), e.g. \"Archivo Black\". null means headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"description":"Absolute https URL of the merchant's logo, shown at the top of the checkout","type":"string"},{"type":"null"}]},"source":{"nullable":true,"anyOf":[{"description":"Where the theme came from: a website that was scanned, or the surface that pushed it (e.g. kling-pages)","type":"string"},{"type":"null"}]},"updated_at":{"nullable":true,"anyOf":[{"description":"Unix timestamp of the last change, null when no theme is set","type":"number"},{"type":"null"}]}},"required":["object","primary_color","background_color","font_family","heading_font_family","button_roundness","logo_url","source","updated_at"]}}}},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}}},"operationId":"getV1MerchantTheme","tags":["Merchant"],"summary":"Get the checkout theme","description":"How the merchant's hosted checkout is branded for this key's environment: colours, body and heading fonts, button shape and logo, selected the way the checkout selects them (environment + active). Every field is null until a theme is set for the environment (by the dashboard's Theme screen, a website scan, or a PATCH here).","security":[{"bearerAuth":[]}]},"patch":{"parameters":[],"responses":{"200":{"description":"How the merchant's hosted checkout is branded","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"merchant.theme","type":"string"},"primary_color":{"nullable":true,"anyOf":[{"description":"Hex colour for buttons and accents, e.g. #b45309","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"description":"Hex colour behind the checkout, e.g. #FBF6EE","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"description":"Font family name, e.g. \"Inter\" or \"Red Hat Display\". Google Fonts are loaded by name.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"description":"Font family name for the checkout's headings (title, amount), e.g. \"Archivo Black\". null means headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"description":"Absolute https URL of the merchant's logo, shown at the top of the checkout","type":"string"},{"type":"null"}]},"source":{"nullable":true,"anyOf":[{"description":"Where the theme came from: a website that was scanned, or the surface that pushed it (e.g. kling-pages)","type":"string"},{"type":"null"}]},"updated_at":{"nullable":true,"anyOf":[{"description":"Unix timestamp of the last change, null when no theme is set","type":"number"},{"type":"null"}]}},"required":["object","primary_color","background_color","font_family","heading_font_family","button_roundness","logo_url","source","updated_at"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"object":{"const":"merchant.theme","type":"string"},"primary_color":{"nullable":true,"anyOf":[{"description":"Hex colour for buttons and accents, e.g. #b45309","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"description":"Hex colour behind the checkout, e.g. #FBF6EE","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"description":"Font family name, e.g. \"Inter\" or \"Red Hat Display\". Google Fonts are loaded by name.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"description":"Font family name for the checkout's headings (title, amount), e.g. \"Archivo Black\". null means headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"description":"Absolute https URL of the merchant's logo, shown at the top of the checkout","type":"string"},{"type":"null"}]},"source":{"nullable":true,"anyOf":[{"description":"Where the theme came from: a website that was scanned, or the surface that pushed it (e.g. kling-pages)","type":"string"},{"type":"null"}]},"updated_at":{"nullable":true,"anyOf":[{"description":"Unix timestamp of the last change, null when no theme is set","type":"number"},{"type":"null"}]}},"required":["object","primary_color","background_color","font_family","heading_font_family","button_roundness","logo_url","source","updated_at"]}},"text/plain":{"schema":{"type":"object","properties":{"object":{"const":"merchant.theme","type":"string"},"primary_color":{"nullable":true,"anyOf":[{"description":"Hex colour for buttons and accents, e.g. #b45309","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"description":"Hex colour behind the checkout, e.g. #FBF6EE","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"description":"Font family name, e.g. \"Inter\" or \"Red Hat Display\". Google Fonts are loaded by name.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"description":"Font family name for the checkout's headings (title, amount), e.g. \"Archivo Black\". null means headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"description":"Absolute https URL of the merchant's logo, shown at the top of the checkout","type":"string"},{"type":"null"}]},"source":{"nullable":true,"anyOf":[{"description":"Where the theme came from: a website that was scanned, or the surface that pushed it (e.g. kling-pages)","type":"string"},{"type":"null"}]},"updated_at":{"nullable":true,"anyOf":[{"description":"Unix timestamp of the last change, null when no theme is set","type":"number"},{"type":"null"}]}},"required":["object","primary_color","background_color","font_family","heading_font_family","button_roundness","logo_url","source","updated_at"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}},"409":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}},"422":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}}},"operationId":"patchV1MerchantTheme","tags":["Merchant"],"summary":"Update the checkout theme","description":"Set how the hosted checkout is branded. Only the fields you send change; send null to clear one. Values are validated strictly (hex colours, a font family name, an https logo URL) because they are rendered into the checkout page. The theme is read and written for the key's environment (a test key edits what the test checkout shows). A merchant has one theme row today, shared by both environments with production winning: a live key that finds the row in test claims it (the row moves to live with your changes applied, so a merchant who set up in test and then went live can brand the live checkout), while a test key that finds a live row answers `409 theme_environment_mismatch` and changes nothing. The same theme is shown in the dashboard's Theme screen. Idempotent by nature; an `Idempotency-Key` header is honoured.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"primary_color":{"nullable":true,"anyOf":[{"pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$","description":"Hex colour (#rgb, #rrggbb or #rrggbbaa) for buttons and accents. null clears it.","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$","description":"Hex colour behind the checkout. null clears it.","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{0,63}$","description":"A single font family name (letters, digits, spaces, hyphens), e.g. \"Inter\". Not a font stack. Google Fonts are loaded by name. null clears it.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{0,63}$","description":"Font family name for headings (the title and amount), same rules as font_family, e.g. \"Archivo Black\". null clears it, and headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"pattern":"^https://[^\\s\"'<>]{1,490}$","maxLength":500,"description":"Absolute https URL of the logo shown at the top of the checkout. null removes it.","type":"string"},{"type":"null"}]},"source":{"maxLength":500,"description":"Free label of who set the theme, e.g. kling-pages or the shop's URL. Shown in the dashboard.","type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"primary_color":{"nullable":true,"anyOf":[{"pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$","description":"Hex colour (#rgb, #rrggbb or #rrggbbaa) for buttons and accents. null clears it.","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$","description":"Hex colour behind the checkout. null clears it.","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{0,63}$","description":"A single font family name (letters, digits, spaces, hyphens), e.g. \"Inter\". Not a font stack. Google Fonts are loaded by name. null clears it.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{0,63}$","description":"Font family name for headings (the title and amount), same rules as font_family, e.g. \"Archivo Black\". null clears it, and headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"pattern":"^https://[^\\s\"'<>]{1,490}$","maxLength":500,"description":"Absolute https URL of the logo shown at the top of the checkout. null removes it.","type":"string"},{"type":"null"}]},"source":{"maxLength":500,"description":"Free label of who set the theme, e.g. kling-pages or the shop's URL. Shown in the dashboard.","type":"string"}}}},"text/plain":{"schema":{"type":"object","properties":{"primary_color":{"nullable":true,"anyOf":[{"pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$","description":"Hex colour (#rgb, #rrggbb or #rrggbbaa) for buttons and accents. null clears it.","type":"string"},{"type":"null"}]},"background_color":{"nullable":true,"anyOf":[{"pattern":"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$","description":"Hex colour behind the checkout. null clears it.","type":"string"},{"type":"null"}]},"font_family":{"nullable":true,"anyOf":[{"pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{0,63}$","description":"A single font family name (letters, digits, spaces, hyphens), e.g. \"Inter\". Not a font stack. Google Fonts are loaded by name. null clears it.","type":"string"},{"type":"null"}]},"heading_font_family":{"nullable":true,"anyOf":[{"pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{0,63}$","description":"Font family name for headings (the title and amount), same rules as font_family, e.g. \"Archivo Black\". null clears it, and headings use font_family.","type":"string"},{"type":"null"}]},"button_roundness":{"nullable":true,"anyOf":[{"anyOf":[{"const":"sharp","type":"string"},{"const":"rounded","type":"string"},{"const":"pill","type":"string"}]},{"type":"null"}]},"logo_url":{"nullable":true,"anyOf":[{"pattern":"^https://[^\\s\"'<>]{1,490}$","maxLength":500,"description":"Absolute https URL of the logo shown at the top of the checkout. null removes it.","type":"string"},{"type":"null"}]},"source":{"maxLength":500,"description":"Free label of who set the theme, e.g. kling-pages or the shop's URL. Shown in the dashboard.","type":"string"}}}}}}}},"/v1/events":{"get":{"parameters":[{"schema":{"minimum":1,"maximum":100,"default":25,"anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":100,"default":25,"type":"integer"}]},"in":"query","name":"limit","required":true},{"description":"ISO timestamp — only return events after this time","schema":{"type":"string"},"in":"query","name":"after","required":false}],"operationId":"getV1Events","tags":["Events"],"summary":"List recent events","description":"List events from the event ledger. Use the 'after' parameter to poll for new events since a given timestamp.","responses":{"200":{}}}},"/api/v1/shopify/webhook/":{"post":{"operationId":"postApiV1ShopifyWebhook","responses":{"200":{}}}},"/v1/checkout/sessions/":{"post":{"parameters":[],"responses":{"200":{"description":"A checkout session represents a single payment or subscription signup flow","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"description":"Unique identifier for the checkout session","type":"string"},"object":{"const":"checkout.session","type":"string"},"livemode":{"description":"Whether this is a live mode session (true) or test mode (false)","type":"boolean"},"amount":{"description":"Total amount to charge now, in the smallest currency unit, after any discount. 0 for trial/setup checkouts.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Total amount to charge now, in the smallest currency unit, after any discount. 0 for trial/setup checkouts.","type":"integer"}]},"amount_subtotal":{"description":"Amount before any discount, in the smallest currency unit (equals amount + discount_amount).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Amount before any discount, in the smallest currency unit (equals amount + discount_amount).","type":"integer"}]},"discount_amount":{"description":"Discount applied to the amount charged now, in the smallest currency unit. 0 when no code is applied, or for trial/setup checkouts where the discount applies to the first charge after the trial.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Discount applied to the amount charged now, in the smallest currency unit. 0 when no code is applied, or for trial/setup checkouts where the discount applies to the first charge after the trial.","type":"integer"}]},"promotion_code_id":{"nullable":true,"anyOf":[{"description":"ID of the applied promotion code, if any. Set even for trial/setup checkouts where discount_amount is 0.","type":"string"},{"type":"null"}]},"currency":{"description":"Three-letter ISO currency code (e.g. ISK)","type":"string"},"status":{"description":"Current status of the checkout session","anyOf":[{"const":"open","type":"string"},{"const":"complete","type":"string"},{"const":"expired","type":"string"}]},"url":{"description":"URL to redirect the customer to for payment","type":"string"},"short_url":{"description":"Short URL for SMS and compact sharing","type":"string"},"success_url":{"nullable":true,"anyOf":[{"description":"URL to redirect to after successful payment","type":"string"},{"type":"null"}]},"cancel_url":{"nullable":true,"anyOf":[{"description":"URL to redirect to if the customer cancels","type":"string"},{"type":"null"}]},"save_payment_method":{"description":"Whether to save the payment method for future use","type":"boolean"},"customer":{"nullable":true,"anyOf":[{"description":"ID of the customer, if linked","type":"string"},{"type":"null"}]},"product":{"nullable":true,"anyOf":[{"description":"ID of the primary product, if this is a product-based checkout","type":"string"},{"type":"null"}]},"subscription":{"nullable":true,"anyOf":[{"description":"ID of the subscription created by this checkout, if applicable","type":"string"},{"type":"null"}]},"payment_intent":{"nullable":true,"anyOf":[{"description":"ID of the payment intent created after payment completes","type":"string"},{"type":"null"}]},"payment_method":{"nullable":true,"anyOf":[{"description":"ID of the saved payment method, if save_payment_method was true","type":"string"},{"type":"null"}]},"customer_email":{"nullable":true,"anyOf":[{"description":"Pre-filled customer email for the checkout form","type":"string"},{"type":"null"}]},"customer_name":{"nullable":true,"anyOf":[{"description":"Pre-filled customer name for the checkout form","type":"string"},{"type":"null"}]},"customer_phone":{"nullable":true,"anyOf":[{"description":"Pre-filled customer phone for the checkout form","type":"string"},{"type":"null"}]},"payment_status":{"description":"Whether the money has arrived. `status: complete` means the buyer finished the checkout; for a bank claim (krafa) that is when the claim is issued, and the session reads `awaiting_claim` until the buyer pays it in their bank (then `paid`, and `payment_intent.captured` fires). `unpaid`: not complete, or the payment failed or was cancelled (e.g. a krafa cancelled at the bank). `no_payment_required`: complete with nothing to pay. Book shipping on `paid`.","anyOf":[{"const":"paid","type":"string"},{"const":"awaiting_claim","type":"string"},{"const":"unpaid","type":"string"},{"const":"no_payment_required","type":"string"}]},"locale":{"nullable":true,"anyOf":[{"description":"Language the checkout is shown in; null when the buyer's browser decides","anyOf":[{"const":"is","type":"string"},{"const":"en","type":"string"}]},{"type":"null"}]},"items":{"description":"Line items in this checkout session. Empty array for simple amount-based checkouts.","type":"array","items":{"description":"A line item in the checkout session","type":"object","required":["id","product_id","variant_id","description","quantity","unit_amount","vat_rate"],"properties":{"id":{"description":"Unique identifier for the line item","type":"string"},"product_id":{"nullable":true,"anyOf":[{"description":"ID of the product this item references, if any","type":"string"},{"type":"null"}]},"variant_id":{"nullable":true,"anyOf":[{"description":"ID of the product variant bought, when the product has variants","type":"string"},{"type":"null"}]},"description":{"description":"Human-readable description of the line item. For a variant it names the choice, e.g. \"Hettupeysa, Stærð: M\"","type":"string"},"quantity":{"description":"Number of units","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Number of units","type":"integer"}]},"unit_amount":{"description":"Price per unit in the smallest currency unit (e.g. ISK integer)","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Price per unit in the smallest currency unit (e.g. ISK integer)","type":"integer"}]},"vat_rate":{"description":"VAT rate as an integer percentage: 0, 11, or 24","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"VAT rate as an integer percentage: 0, 11, or 24","type":"integer"}]}}}},"form_fields":{"description":"Custom form fields to collect during checkout. null = default (name + email), empty array = skip customer info collection. The customer's answers to your own fields are returned in custom_fields.","nullable":true,"anyOf":[{"type":"array","items":{"description":"A form field to collect from the customer during checkout","type":"object","required":["name","type","required"],"properties":{"name":{"description":"Field identifier. Known fields: name, email, phone, nationalId. Others are stored as custom fields.","type":"string"},"type":{"description":"HTML input type: text, email, tel, etc.","type":"string"},"required":{"description":"Whether the field must be filled before continuing","type":"boolean"}}}},{"type":"null"}]},"custom_fields":{"description":"Answers the customer entered for your custom form_fields, keyed by field name (for example {\"Gift message\": \"Happy birthday\"}). Known fields (name, email, phone, nationalId) are not included here; name, email and phone are returned in customer_name, customer_email and customer_phone. Values are always strings. null until the customer submits the customer info step, or when the session has no custom fields.","nullable":true,"anyOf":[{"additionalProperties":{"type":"string"},"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},{"type":"null"}]},"allow_custom_amount":{"description":"Whether the customer can enter a custom amount (pay-what-you-want)","type":"boolean"},"minimum_amount":{"nullable":true,"anyOf":[{"description":"Minimum amount the customer must pay when allow_custom_amount is true","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Minimum amount the customer must pay when allow_custom_amount is true","type":"integer"}]},{"type":"null"}]},"expires_at":{"description":"Unix timestamp when this session expires (24 hours after creation)","type":"number"},"created_at":{"description":"Unix timestamp when this session was created","type":"number"},"metadata":{"description":"Arbitrary key-value metadata attached to the session","nullable":true,"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]}},"required":["id","object","livemode","amount","amount_subtotal","discount_amount","promotion_code_id","currency","status","url","short_url","success_url","cancel_url","save_payment_method","customer","product","subscription","payment_intent","payment_method","customer_email","customer_name","customer_phone","payment_status","locale","items","form_fields","custom_fields","allow_custom_amount","minimum_amount","expires_at","created_at","metadata"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"id":{"description":"Unique identifier for the checkout session","type":"string"},"object":{"const":"checkout.session","type":"string"},"livemode":{"description":"Whether this is a live mode session (true) or test mode (false)","type":"boolean"},"amount":{"description":"Total amount to charge now, in the smallest currency unit, after any discount. 0 for trial/setup checkouts.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Total amount to charge now, in the smallest currency unit, after any discount. 0 for trial/setup checkouts.","type":"integer"}]},"amount_subtotal":{"description":"Amount before any discount, in the smallest currency unit (equals amount + discount_amount).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Amount before any discount, in the smallest currency unit (equals amount + discount_amount).","type":"integer"}]},"discount_amount":{"description":"Discount applied to the amount charged now, in the smallest currency unit. 0 when no code is applied, or for trial/setup checkouts where the discount applies to the first charge after the trial.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Discount applied to the amount charged now, in the smallest currency unit. 0 when no code is applied, or for trial/setup checkouts where the discount applies to the first charge after the trial.","type":"integer"}]},"promotion_code_id":{"nullable":true,"anyOf":[{"description":"ID of the applied promotion code, if any. Set even for trial/setup checkouts where discount_amount is 0.","type":"string"},{"type":"null"}]},"currency":{"description":"Three-letter ISO currency code (e.g. ISK)","type":"string"},"status":{"description":"Current status of the checkout session","anyOf":[{"const":"open","type":"string"},{"const":"complete","type":"string"},{"const":"expired","type":"string"}]},"url":{"description":"URL to redirect the customer to for payment","type":"string"},"short_url":{"description":"Short URL for SMS and compact sharing","type":"string"},"success_url":{"nullable":true,"anyOf":[{"description":"URL to redirect to after successful payment","type":"string"},{"type":"null"}]},"cancel_url":{"nullable":true,"anyOf":[{"description":"URL to redirect to if the customer cancels","type":"string"},{"type":"null"}]},"save_payment_method":{"description":"Whether to save the payment method for future use","type":"boolean"},"customer":{"nullable":true,"anyOf":[{"description":"ID of the customer, if linked","type":"string"},{"type":"null"}]},"product":{"nullable":true,"anyOf":[{"description":"ID of the primary product, if this is a product-based checkout","type":"string"},{"type":"null"}]},"subscription":{"nullable":true,"anyOf":[{"description":"ID of the subscription created by this checkout, if applicable","type":"string"},{"type":"null"}]},"payment_intent":{"nullable":true,"anyOf":[{"description":"ID of the payment intent created after payment completes","type":"string"},{"type":"null"}]},"payment_method":{"nullable":true,"anyOf":[{"description":"ID of the saved payment method, if save_payment_method was true","type":"string"},{"type":"null"}]},"customer_email":{"nullable":true,"anyOf":[{"description":"Pre-filled customer email for the checkout form","type":"string"},{"type":"null"}]},"customer_name":{"nullable":true,"anyOf":[{"description":"Pre-filled customer name for the checkout form","type":"string"},{"type":"null"}]},"customer_phone":{"nullable":true,"anyOf":[{"description":"Pre-filled customer phone for the checkout form","type":"string"},{"type":"null"}]},"payment_status":{"description":"Whether the money has arrived. `status: complete` means the buyer finished the checkout; for a bank claim (krafa) that is when the claim is issued, and the session reads `awaiting_claim` until the buyer pays it in their bank (then `paid`, and `payment_intent.captured` fires). `unpaid`: not complete, or the payment failed or was cancelled (e.g. a krafa cancelled at the bank). `no_payment_required`: complete with nothing to pay. Book shipping on `paid`.","anyOf":[{"const":"paid","type":"string"},{"const":"awaiting_claim","type":"string"},{"const":"unpaid","type":"string"},{"const":"no_payment_required","type":"string"}]},"locale":{"nullable":true,"anyOf":[{"description":"Language the checkout is shown in; null when the buyer's browser decides","anyOf":[{"const":"is","type":"string"},{"const":"en","type":"string"}]},{"type":"null"}]},"items":{"description":"Line items in this checkout session. Empty array for simple amount-based checkouts.","type":"array","items":{"description":"A line item in the checkout session","type":"object","required":["id","product_id","variant_id","description","quantity","unit_amount","vat_rate"],"properties":{"id":{"description":"Unique identifier for the line item","type":"string"},"product_id":{"nullable":true,"anyOf":[{"description":"ID of the product this item references, if any","type":"string"},{"type":"null"}]},"variant_id":{"nullable":true,"anyOf":[{"description":"ID of the product variant bought, when the product has variants","type":"string"},{"type":"null"}]},"description":{"description":"Human-readable description of the line item. For a variant it names the choice, e.g. \"Hettupeysa, Stærð: M\"","type":"string"},"quantity":{"description":"Number of units","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Number of units","type":"integer"}]},"unit_amount":{"description":"Price per unit in the smallest currency unit (e.g. ISK integer)","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Price per unit in the smallest currency unit (e.g. ISK integer)","type":"integer"}]},"vat_rate":{"description":"VAT rate as an integer percentage: 0, 11, or 24","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"VAT rate as an integer percentage: 0, 11, or 24","type":"integer"}]}}}},"form_fields":{"description":"Custom form fields to collect during checkout. null = default (name + email), empty array = skip customer info collection. The customer's answers to your own fields are returned in custom_fields.","nullable":true,"anyOf":[{"type":"array","items":{"description":"A form field to collect from the customer during checkout","type":"object","required":["name","type","required"],"properties":{"name":{"description":"Field identifier. Known fields: name, email, phone, nationalId. Others are stored as custom fields.","type":"string"},"type":{"description":"HTML input type: text, email, tel, etc.","type":"string"},"required":{"description":"Whether the field must be filled before continuing","type":"boolean"}}}},{"type":"null"}]},"custom_fields":{"description":"Answers the customer entered for your custom form_fields, keyed by field name (for example {\"Gift message\": \"Happy birthday\"}). Known fields (name, email, phone, nationalId) are not included here; name, email and phone are returned in customer_name, customer_email and customer_phone. Values are always strings. null until the customer submits the customer info step, or when the session has no custom fields.","nullable":true,"anyOf":[{"additionalProperties":{"type":"string"},"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},{"type":"null"}]},"allow_custom_amount":{"description":"Whether the customer can enter a custom amount (pay-what-you-want)","type":"boolean"},"minimum_amount":{"nullable":true,"anyOf":[{"description":"Minimum amount the customer must pay when allow_custom_amount is true","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Minimum amount the customer must pay when allow_custom_amount is true","type":"integer"}]},{"type":"null"}]},"expires_at":{"description":"Unix timestamp when this session expires (24 hours after creation)","type":"number"},"created_at":{"description":"Unix timestamp when this session was created","type":"number"},"metadata":{"description":"Arbitrary key-value metadata attached to the session","nullable":true,"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]}},"required":["id","object","livemode","amount","amount_subtotal","discount_amount","promotion_code_id","currency","status","url","short_url","success_url","cancel_url","save_payment_method","customer","product","subscription","payment_intent","payment_method","customer_email","customer_name","customer_phone","payment_status","locale","items","form_fields","custom_fields","allow_custom_amount","minimum_amount","expires_at","created_at","metadata"]}},"text/plain":{"schema":{"type":"object","properties":{"id":{"description":"Unique identifier for the checkout session","type":"string"},"object":{"const":"checkout.session","type":"string"},"livemode":{"description":"Whether this is a live mode session (true) or test mode (false)","type":"boolean"},"amount":{"description":"Total amount to charge now, in the smallest currency unit, after any discount. 0 for trial/setup checkouts.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Total amount to charge now, in the smallest currency unit, after any discount. 0 for trial/setup checkouts.","type":"integer"}]},"amount_subtotal":{"description":"Amount before any discount, in the smallest currency unit (equals amount + discount_amount).","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Amount before any discount, in the smallest currency unit (equals amount + discount_amount).","type":"integer"}]},"discount_amount":{"description":"Discount applied to the amount charged now, in the smallest currency unit. 0 when no code is applied, or for trial/setup checkouts where the discount applies to the first charge after the trial.","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Discount applied to the amount charged now, in the smallest currency unit. 0 when no code is applied, or for trial/setup checkouts where the discount applies to the first charge after the trial.","type":"integer"}]},"promotion_code_id":{"nullable":true,"anyOf":[{"description":"ID of the applied promotion code, if any. Set even for trial/setup checkouts where discount_amount is 0.","type":"string"},{"type":"null"}]},"currency":{"description":"Three-letter ISO currency code (e.g. ISK)","type":"string"},"status":{"description":"Current status of the checkout session","anyOf":[{"const":"open","type":"string"},{"const":"complete","type":"string"},{"const":"expired","type":"string"}]},"url":{"description":"URL to redirect the customer to for payment","type":"string"},"short_url":{"description":"Short URL for SMS and compact sharing","type":"string"},"success_url":{"nullable":true,"anyOf":[{"description":"URL to redirect to after successful payment","type":"string"},{"type":"null"}]},"cancel_url":{"nullable":true,"anyOf":[{"description":"URL to redirect to if the customer cancels","type":"string"},{"type":"null"}]},"save_payment_method":{"description":"Whether to save the payment method for future use","type":"boolean"},"customer":{"nullable":true,"anyOf":[{"description":"ID of the customer, if linked","type":"string"},{"type":"null"}]},"product":{"nullable":true,"anyOf":[{"description":"ID of the primary product, if this is a product-based checkout","type":"string"},{"type":"null"}]},"subscription":{"nullable":true,"anyOf":[{"description":"ID of the subscription created by this checkout, if applicable","type":"string"},{"type":"null"}]},"payment_intent":{"nullable":true,"anyOf":[{"description":"ID of the payment intent created after payment completes","type":"string"},{"type":"null"}]},"payment_method":{"nullable":true,"anyOf":[{"description":"ID of the saved payment method, if save_payment_method was true","type":"string"},{"type":"null"}]},"customer_email":{"nullable":true,"anyOf":[{"description":"Pre-filled customer email for the checkout form","type":"string"},{"type":"null"}]},"customer_name":{"nullable":true,"anyOf":[{"description":"Pre-filled customer name for the checkout form","type":"string"},{"type":"null"}]},"customer_phone":{"nullable":true,"anyOf":[{"description":"Pre-filled customer phone for the checkout form","type":"string"},{"type":"null"}]},"payment_status":{"description":"Whether the money has arrived. `status: complete` means the buyer finished the checkout; for a bank claim (krafa) that is when the claim is issued, and the session reads `awaiting_claim` until the buyer pays it in their bank (then `paid`, and `payment_intent.captured` fires). `unpaid`: not complete, or the payment failed or was cancelled (e.g. a krafa cancelled at the bank). `no_payment_required`: complete with nothing to pay. Book shipping on `paid`.","anyOf":[{"const":"paid","type":"string"},{"const":"awaiting_claim","type":"string"},{"const":"unpaid","type":"string"},{"const":"no_payment_required","type":"string"}]},"locale":{"nullable":true,"anyOf":[{"description":"Language the checkout is shown in; null when the buyer's browser decides","anyOf":[{"const":"is","type":"string"},{"const":"en","type":"string"}]},{"type":"null"}]},"items":{"description":"Line items in this checkout session. Empty array for simple amount-based checkouts.","type":"array","items":{"description":"A line item in the checkout session","type":"object","required":["id","product_id","variant_id","description","quantity","unit_amount","vat_rate"],"properties":{"id":{"description":"Unique identifier for the line item","type":"string"},"product_id":{"nullable":true,"anyOf":[{"description":"ID of the product this item references, if any","type":"string"},{"type":"null"}]},"variant_id":{"nullable":true,"anyOf":[{"description":"ID of the product variant bought, when the product has variants","type":"string"},{"type":"null"}]},"description":{"description":"Human-readable description of the line item. For a variant it names the choice, e.g. \"Hettupeysa, Stærð: M\"","type":"string"},"quantity":{"description":"Number of units","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Number of units","type":"integer"}]},"unit_amount":{"description":"Price per unit in the smallest currency unit (e.g. ISK integer)","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Price per unit in the smallest currency unit (e.g. ISK integer)","type":"integer"}]},"vat_rate":{"description":"VAT rate as an integer percentage: 0, 11, or 24","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"VAT rate as an integer percentage: 0, 11, or 24","type":"integer"}]}}}},"form_fields":{"description":"Custom form fields to collect during checkout. null = default (name + email), empty array = skip customer info collection. The customer's answers to your own fields are returned in custom_fields.","nullable":true,"anyOf":[{"type":"array","items":{"description":"A form field to collect from the customer during checkout","type":"object","required":["name","type","required"],"properties":{"name":{"description":"Field identifier. Known fields: name, email, phone, nationalId. Others are stored as custom fields.","type":"string"},"type":{"description":"HTML input type: text, email, tel, etc.","type":"string"},"required":{"description":"Whether the field must be filled before continuing","type":"boolean"}}}},{"type":"null"}]},"custom_fields":{"description":"Answers the customer entered for your custom form_fields, keyed by field name (for example {\"Gift message\": \"Happy birthday\"}). Known fields (name, email, phone, nationalId) are not included here; name, email and phone are returned in customer_name, customer_email and customer_phone. Values are always strings. null until the customer submits the customer info step, or when the session has no custom fields.","nullable":true,"anyOf":[{"additionalProperties":{"type":"string"},"type":"object","patternProperties":{"^(.*)$":{"type":"string"}}},{"type":"null"}]},"allow_custom_amount":{"description":"Whether the customer can enter a custom amount (pay-what-you-want)","type":"boolean"},"minimum_amount":{"nullable":true,"anyOf":[{"description":"Minimum amount the customer must pay when allow_custom_amount is true","anyOf":[{"format":"integer","default":0,"type":"string"},{"description":"Minimum amount the customer must pay when allow_custom_amount is true","type":"integer"}]},{"type":"null"}]},"expires_at":{"description":"Unix timestamp when this session expires (24 hours after creation)","type":"number"},"created_at":{"description":"Unix timestamp when this session was created","type":"number"},"metadata":{"description":"Arbitrary key-value metadata attached to the session","nullable":true,"anyOf":[{"type":"object","patternProperties":{"^(.*)$":{}}},{"type":"null"}]}},"required":["id","object","livemode","amount","amount_subtotal","discount_amount","promotion_code_id","currency","status","url","short_url","success_url","cancel_url","save_payment_method","customer","product","subscription","payment_intent","payment_method","customer_email","customer_name","customer_phone","payment_status","locale","items","form_fields","custom_fields","allow_custom_amount","minimum_amount","expires_at","created_at","metadata"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}},"text/plain":{"schema":{"type":"object","properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}},"required":["error"]}}}}},"operationId":"postV1CheckoutSessions","description":"Create a new checkout session. Provide 'items' for multi-line-item checkout, 'product_id' for single-product checkout, or 'amount' for custom amount checkout.","tags":["Checkout Sessions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"format":"uuid","description":"ID of a product for single-product checkout. Mutually exclusive with 'amount' and 'items'.","type":"string"},"locale":{"description":"Language the checkout is shown in. Without it the buyer's browser decides (cookie, then Accept-Language, then Icelandic). A shop that sells in Icelandic sends \"is\" so a buyer whose browser is set to English still sees Icelandic. A ?locale= on the checkout URL overrides it.","anyOf":[{"const":"is","type":"string"},{"const":"en","type":"string"}]},"variant_id":{"format":"uuid","description":"With product_id: the variant the buyer chose. Required when the product has variants (400 variant_required); its price replaces the product's, and the line's description names the choice. A counted variant with nothing in stock is refused with 409 variant_sold_out.","type":"string"},"amount":{"minimum":1,"maximum":2147483647,"description":"Fixed amount in the smallest currency unit (e.g. ISK integer). Mutually exclusive with 'product_id' and 'items'.","anyOf":[{"format":"integer","default":0,"type":"string"},{"minimum":1,"maximum":2147483647,"description":"Fixed amount in the smallest currency unit (e.g. ISK integer). Mutually exclusive with 'product_id' and 'items'.","type":"integer"}]},"currency":{"minLength":3,"maxLength":3,"default":"ISK","description":"Three-letter ISO currency code. Defaults to ISK.","type":"string"},"items":{"description":"Line items for the checkout. Total amount is computed as sum of (amount * quantity) across all items. Mutually exclusive with top-level 'product_id' and 'amount'.","type":"array","items":{"description":"A line item. Provide either 'product_id' or 'description' + 'amount'.","type":"object","properties":{"product_id":{"format":"uuid","description":"ID of an existing product. Amount and VAT rate are derived from the product. Mutually exclusive with 'amount'.","type":"string"},"variant_id":{"format":"uuid","description":"The variant of product_id the buyer chose (e.g. size M). Required when the product has variants (400 variant_required); the variant's price is used and the description reads \",