{"openapi":"3.0.0","info":{"version":"1.0.0","title":"API"},"servers":[{"url":"https://api2.sesamy.com","description":"Current environment"}],"security":[{"OpenID":["openid","email","profile"]}],"components":{"securitySchemes":{"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://token.sesamy.com/.well-known/openid-configuration"},"Basic":{"type":"http","scheme":"basic"}},"schemas":{"Vendor":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"logo":{"type":"string"}},"required":["name","id"]},"VendorDetail":{"type":"object","properties":{"id":{"type":"string","example":"acme"},"name":{"type":"string","example":"ACME"},"slug":{"type":"string"},"logo":{"type":"string"},"currency":{"type":"string","description":"The vendor's business currency (ISO 4217). Absent when the profile has none.","example":"SEK"},"country":{"type":"string","description":"ISO 3166-1 alpha-2","example":"SE"},"language":{"type":"string"},"status":{"type":"string","description":"One of DRAFT, PENDING, ACTIVE, TEST or OFF_BOARDED","example":"ACTIVE"},"siteUrl":{"type":"string"},"supportEmail":{"type":"string"},"supportUrl":{"type":"string"},"termsAndConditionsUrl":{"type":"string"}},"required":["id","name"]},"Bill":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"contractId":{"type":"string","example":"a1b2c3d4e5f6g7h8i9j0"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"title":{"type":"string"},"purchaseOptionId":{"type":"string"}},"required":["sku","title"]}},"price":{"type":"number"},"currency":{"type":"string"},"receiptUrl":{"type":"string"},"paymentProvider":{"type":"string"},"paymentMethod":{"type":"string"},"status":{"type":"string"},"updatedAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","contractId","items","price","receiptUrl","paymentProvider","paymentMethod","status","updatedAt","createdAt"]},"ContractDiscount":{"type":"object","nullable":true,"properties":{"endsAt":{"type":"string","nullable":true,"description":"When the discounted price stops applying and `fullPrice` takes over. Null for a discount that does not lapse."},"amount":{"type":"number","nullable":true,"description":"Amount taken off the next bill, in the contract currency."},"percentage":{"type":"number","nullable":true,"description":"Share taken off the next bill, as a percentage."},"fullPrice":{"type":"number","nullable":true,"description":"What the next bill would total without the discount."}},"required":["endsAt","amount","percentage","fullPrice"]},"Contract":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"name":{"type":"string"},"userId":{"type":"string"},"payer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id"],"description":"Who is billed. Only set when that is someone other than the user."},"createdAt":{"type":"string"},"confirmedAt":{"type":"string"},"updatedAt":{"type":"string"},"price":{"type":"number"},"nextBillAt":{"type":"string","nullable":true},"nextPrice":{"type":"number","nullable":true},"currency":{"type":"string"},"manageUrl":{"type":"string"},"contractDuration":{"type":"string","enum":["RECURRING","RENEWABLE","PERPETUAL"]},"issuesRemaining":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"purchaseOptionId":{"type":"string"},"purchaseOptionName":{"type":"string"},"name":{"type":"string"},"cover":{"type":"string"},"productType":{"type":"string","enum":["article","audiobook","ebook","bundle","podcast","pass","publication","physical_issue","license"]},"purchaseType":{"type":"string"},"isMultiseat":{"type":"boolean"},"quantity":{"type":"number","description":"Billed units."},"seats":{"type":"number","description":"Total seats on a multi-seat item. Unset for single-seat items."}},"required":["sku","name","productType","isMultiseat","quantity"]}},"status":{"type":"string"},"isActive":{"type":"boolean"},"recurringInterval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"recurringTime":{"type":"number"},"willCancelAt":{"type":"string","nullable":true},"cancelRequestedAt":{"type":"string","nullable":true},"cancelReason":{"type":"string","nullable":true},"expiresAt":{"type":"string"},"origin":{"type":"object","properties":{"type":{"type":"string","enum":["CHECKOUT","CHECKOUT_LEGACY","MANUAL","IMPORTED","THIRD_PARTY","OFFER"]},"id":{"type":"string","description":"Id of the originating entity, e.g. the checkout id when type is CHECKOUT."}},"required":["type"]},"paymentData":{"type":"object","properties":{"method":{"type":"string"},"description":{"type":"string"},"brand":{"type":"string"},"walletType":{"type":"string"}}},"appliedDiscounts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"status":{"type":"string","enum":["APPLIED","UNAPPLICABLE"]},"startsAt":{"type":"string","description":"When the discount starts applying. Unset means it applies from contract start."},"endsAt":{"type":"string","description":"When the discount stops applying. Unset means it does not lapse — or, on the list endpoint, that the date is not indexed; read `discount.endsAt` there instead."}},"required":["name","description","id"]}},"discount":{"$ref":"#/components/schemas/ContractDiscount"}},"required":["id","name","userId","createdAt","updatedAt","price","nextBillAt","nextPrice","currency","items","status","isActive","willCancelAt","cancelRequestedAt","cancelReason","appliedDiscounts","discount"]},"ContractAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"department":{"type":"string"},"co":{"type":"string"},"street":{"type":"string"},"zip":{"type":"string"},"city":{"type":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"SE"}},"required":["street","zip","city","country"]},"ContractParty":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"A user is created for this email if none exists yet."},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"businessDetails":{"type":"object","properties":{"companyName":{"type":"string"},"vatNr":{"type":"string"}}},"address":{"$ref":"#/components/schemas/ContractAddress"},"deliveryAddress":{"$ref":"#/components/schemas/ContractAddress"}},"required":["email"],"description":"Who gets access. On a multi-seat contract this user administers the seats and holds the first one."},"ContractPayment":{"type":"object","properties":{"provider":{"type":"string","enum":["BILLOGRAM"]},"method":{"type":"string","enum":["INVOICE"]},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"Country the payment is made from. Decides market and VAT. Defaults to SE.","example":"SE"}},"required":["provider","method"]},"CreateContractRequest":{"type":"object","properties":{"sku":{"type":"string","minLength":1},"purchaseOptionId":{"type":"string","minLength":1},"contractType":{"type":"string","enum":["PERSONAL","BUSINESS"],"description":"Defaults to PERSONAL."},"user":{"$ref":"#/components/schemas/ContractParty"},"payer":{"allOf":[{"$ref":"#/components/schemas/ContractParty"},{"description":"Who is billed, when that is someone other than `user`. Bills are addressed to the payer on behalf of the user."}]},"invoice":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Where invoices are sent. Defaults to the billed party's email."},"customerReference":{"type":"string","description":"The customer's reference, printed on the invoice as their reference. For example a purchase order number."},"vendorReference":{"type":"string","maxLength":34,"description":"Your own reference, printed on the invoice as your reference. For example the seller."},"ediNumber":{"type":"string","description":"Delivers the invoice as an e-invoice (EDI/EHF) to this number."}}},"quantity":{"type":"integer","minimum":1,"description":"Billed units. The price is `quantity` × unit price. Defaults to 1."},"seats":{"type":"integer","minimum":1,"description":"Total seats on the contract. Only valid for license products. Defaults to the seats per unit of the purchase option × `quantity`; set it to grant a different number of seats without changing what is billed."},"unitPrice":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Price per unit in the currency of the purchase option, e.g. 9999.00."},"taxIncluded":{"type":"boolean","description":"Whether `amount` includes VAT. Defaults to the purchase option setting."}},"required":["amount"],"description":"Overrides the list price. Applies to every bill on the contract, not only the first."},"discountCodes":{"type":"array","items":{"type":"string","minLength":1}},"payment":{"$ref":"#/components/schemas/ContractPayment"},"startsAt":{"type":"string","format":"date-time","description":"Delays the start. The contract is FORTHCOMING until then, and access is granted when it starts."},"anchorDate":{"type":"string","format":"date-time","description":"Aligns the billing cycle to this date."},"confirm":{"type":"boolean","description":"Confirm the contract in the same call. Defaults to false, which returns a PENDING contract to review and confirm separately. Confirming bills the customer."}},"required":["sku","purchaseOptionId","user","payment"]},"SetContractSeatsBody":{"type":"object","properties":{"seats":{"type":"integer","minimum":1,"description":"The total number of seats the item should have.","example":25},"sku":{"type":"string","description":"The license item to change. Only needed when the contract has more than one license item.","example":"sid:acme-plus-business"}},"required":["seats"]},"AddContractSeatUserBody":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user to assign a seat to.","example":"reader@example.com"}},"required":["email"]},"UpgradeOption":{"type":"object","properties":{"itemId":{"type":"string","description":"The contract item these paths apply to"},"sku":{"type":"string","description":"The current product of the contract item"},"purchaseOptionId":{"type":"string","description":"The current purchase option of the contract item"},"paths":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["UPGRADE","DOWNGRADE","EQUIVALENT"],"description":"How the target relates to the current purchase option"},"sku":{"type":"string","description":"The product the contract item can change to"},"purchaseOptionId":{"type":"string","description":"The purchase option on the target product, if a specific one applies"},"title":{"type":"string","description":"Display name of the target product or purchase option"},"cover":{"type":"string","description":"Cover image URL of the target product"},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"}}},"required":["type","sku"]},"description":"The products and purchase options this item can change to"}},"required":["itemId","sku","purchaseOptionId","paths"]},"Transaction":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"amount":{"type":"number"},"currency":{"type":"string"},"contractId":{"type":"string"},"isRefund":{"type":"boolean"},"userId":{"type":"string"},"billId":{"type":"string"},"updatedAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","amount","contractId","isRefund","userId","billId","updatedAt","createdAt"]},"Product":{"type":"object","properties":{"cover":{"type":"string"},"language":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"sku":{"type":"string"},"title":{"type":"string"},"productType":{"type":"string"},"publisherContentId":{"type":"string"}},"required":["cover","language","createdAt","updatedAt","sku","title","productType"]},"Fulfillment":{"type":"object","properties":{"status":{"type":"string"},"updatedAt":{"type":"string"},"createdAt":{"type":"string"},"deliversAt":{"type":"string"},"sku":{"type":"string"},"title":{"type":"string"}},"required":["status","updatedAt","createdAt","sku","title"]},"UserLog":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string"},"type":{"type":"string"},"description":{"type":"string"},"ip":{"type":"string"},"clientId":{"type":"string"}},"required":["id","date","type"]},"UserLogs":{"type":"object","properties":{"logs":{"type":"array","items":{"$ref":"#/components/schemas/UserLog"}},"total":{"type":"integer","minimum":0}},"required":["logs","total"]},"UserSession":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string"},"lastInteractionAt":{"type":"string"},"expiresAt":{"type":"string"},"idleExpiresAt":{"type":"string"},"revokedAt":{"type":"string"},"lastIp":{"type":"string"},"lastUserAgent":{"type":"string"},"clientIds":{"type":"array","items":{"type":"string"}}},"required":["id","createdAt","lastInteractionAt","clientIds"]},"UserSessions":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/UserSession"}},"total":{"type":"integer","minimum":0}},"required":["sessions","total"]},"CompanyInfo":{"type":"object","properties":{"companyName":{"type":"string"},"vatNr":{"type":"string"},"invoiceEmail":{"type":"string"}}},"Profile":{"type":"object","properties":{"userId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"locale":{"type":"string"},"nickname":{"type":"string"},"picture":{"type":"string"},"name":{"type":"string"},"mobilePhone":{"type":"string"},"workPhone":{"type":"string"},"homePhone":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"user_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"}]}},"billingAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"deliveryAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"companyInfo":{"$ref":"#/components/schemas/CompanyInfo"},"company":{"type":"string","description":"Deprecated: use companyInfo.companyName","deprecated":true},"sub":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"phone_number":{"type":"string"}},"required":["userId","createdAt","updatedAt"]},"UserMetadata":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"TeamMember":{"type":"object","properties":{"userId":{"type":"string","example":"auth0|61715b8ebe82f0006ab0613b"},"email":{"type":"string","example":"user@example.com"},"roles":{"type":"array","items":{"type":"string","enum":["PortalAdmin","PortalFullAccess","PortalDeveloper"]},"example":["PortalFullAccess"]}},"required":["userId","email","roles"]},"ApiKey":{"type":"object","properties":{"clientId":{"type":"string","description":"The OAuth `client_id`. Public — it is not a credential on its own.","example":"apikey_9f2c1d8e4b7a4f1e9c3d5a6b7c8d9e0f"},"name":{"type":"string","example":"Newsroom CMS"},"role":{"type":"string","enum":["read","full"],"description":"Which preset of Management API scopes the key carries. `read` grants every read scope; `full` adds the write scopes. Neither preset can manage team members, portal permissions or other API keys — those stay human-only actions, so a leaked key cannot be used to keep access after it is revoked.","example":"read"},"scopes":{"type":"array","items":{"type":"string"},"description":"The scopes this key can request, expanded from its role.","example":["access-lists:read","bills:read","checkouts:read","contracts:read","domains:read","entitlements:read","products:read","sites:read","stats:views:read","transactions:read","users:read"]},"createdAt":{"type":"string","example":"2026-09-01T09:12:44.000Z"}},"required":["clientId","name","role","scopes"]},"CreatedApiKey":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"clientSecret":{"type":"string","description":"The key secret. Returned by this endpoint only, and never readable again — store it before closing the response. To replace a lost secret, delete the key and create a new one.","example":"k2Jd8sV1pQ7wE4rT6yU9iO0aS3dF5gH8"},"tokenUrl":{"type":"string","description":"The token endpoint this key authenticates against. It is specific to the vendor — posting to the shared issuer host resolves a different tenant and fails.","example":"https://acme.token.sesamy.com/oauth/token"},"audience":{"type":"string","description":"The `audience` to request when minting a token with this key.","example":"urn:sesamy"}},"required":["clientSecret","tokenUrl","audience"]}]},"EntitlementType":{"type":"string","enum":["article","audiobook","ebook","bundle","podcast","pass","publication","physical_issue"]},"Entitlement":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"sku":{"type":"string"},"purchaseOption":{"type":"string"},"cover":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"presentationUrl":{"type":"string"},"publisherContentId":{"type":"string"},"type":{"$ref":"#/components/schemas/EntitlementType"},"origin":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["EXTERNAL"]},"id":{"type":"string"},"listId":{"type":"string"},"name":{"type":"string"}},"required":["type","id"]},{"type":"object","properties":{"type":{"type":"string","enum":["PAYMENTS"]},"contractId":{"type":"string"}},"required":["type"]}]},"hasAccess":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","sku","title","type","hasAccess","createdAt","updatedAt"]},"Attribution":{"type":"object","properties":{"utmSource":{"type":"string"},"utmMedium":{"type":"string"},"utmCampaign":{"type":"string"},"utmTerm":{"type":"string"},"utmContent":{"type":"string"},"source":{"type":"string","enum":["CHECKOUT","PAYWALL","OTHER"]},"sourceId":{"type":"string"},"itemSrc":{"type":"string"},"referrer":{"type":"string"},"publisherContentId":{"type":"string"},"_ga":{"type":"string"},"_gid":{"type":"string"},"_fbp":{"type":"string"},"_fbc":{"type":"string"},"_pk_id":{"type":"string"},"gaSessionId":{"type":"string"}}},"PaymentMethods":{"type":"object","properties":{"provider":{"type":"string"},"methods":{"type":"array","items":{"type":"string"}}},"required":["methods"]},"AppliedDiscountCodes":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["APPLIED","UNAPPLICABLE"]}},"required":["code","status"]},"Checkout":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"url":{"type":"string"},"purchaseOptionId":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"geoRestrictions":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["ALLOW","BLOCK"]}},"required":["countries","type"]}}}},"address":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"businessAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"email":{"type":"string"},"givenName":{"type":"string"},"familyName":{"type":"string"},"birthDate":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"referralEmail":{"type":"string"},"language":{"type":"string"},"redirectUrl":{"type":"string"},"isBusiness":{"type":"boolean"},"price":{"type":"number"},"currency":{"type":"string"},"anonymousUserId":{"type":"string"},"attribution":{"$ref":"#/components/schemas/Attribution"},"paymentData":{"type":"object","properties":{"provider":{"type":"string"},"method":{"type":"string"}},"required":["provider","method"]},"paymentMethodsFilter":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethods"}},"fieldSettings":{"type":"object","properties":{"name":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"phone":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"birthdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"referral":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}},"giftMode":{"type":"boolean"},"requireAddress":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"checkoutUrl":{"type":"string"},"status":{"type":"string","enum":["PENDING","WAITING_PAYMENT_CONFIRMATION","COMPLETED"]},"type":{"type":"string","enum":["RECURRING","SINGLE"]},"itemsOwned":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"purchaseOptionId":{"type":"string"},"title":{"type":"string"}},"required":["sku","purchaseOptionId","title"]}},"appliedDiscountCodes":{"type":"array","items":{"$ref":"#/components/schemas/AppliedDiscountCodes"}},"availablePaymentMethods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethods"}},"payer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["items","id","checkoutUrl","status","type","itemsOwned","appliedDiscountCodes","availablePaymentMethods","createdAt","updatedAt"]},"DiscountStatus":{"type":"string","enum":["DRAFT","PENDING","ACTIVE","PAUSED","EXPIRED","CANCELED","ACTIVATION_ERROR"],"description":"A new discount is a `DRAFT`. Activating it makes it `PENDING`, and it becomes `ACTIVE` once its start date is reached and `EXPIRED` after its end date. Only `DRAFT` and `PAUSED` discounts can be edited or canceled."},"PercentageDiscountParameters":{"type":"object","properties":{"percentage":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":100,"example":20},"numberOfMonths":{"type":"integer","minimum":-1,"description":"How long the discount applies to a subscription: `0` for the first bill only, `-1` forever, or a number of months.","example":3},"curbToMaxAmount":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Never discount more than this amount per bill"},"allowSKUs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these products"},"allowPOs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these purchase options"},"ignoreSKUs":{"type":"array","items":{"type":"string","minLength":1},"description":"Never apply to these products"},"requireVerticals":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these product types"},"ignoreVerticals":{"type":"array","items":{"type":"string","minLength":1},"description":"Never apply to these product types"}},"required":["percentage","numberOfMonths"],"additionalProperties":false},"PercentageDiscountConditions":{"type":"object","properties":{"minimumTotalItems":{"type":"integer","minimum":1,"description":"Minimum number of items in the cart"},"minimumTotalAmount":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Minimum cart total, in the currency of the purchase"},"totalTimesApplicable":{"type":"integer","minimum":1,"description":"How many times the discount can be used in total"},"totalTimesApplicablePerUser":{"type":"integer","minimum":1,"description":"How many times one user can use the discount"}},"default":{},"additionalProperties":false},"FixedAmountDiscountParameters":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Amount to take off, in the currency of the purchase (e.g. `49.5`)","example":50},"numberOfMonths":{"type":"integer","minimum":-1,"description":"How long the discount applies to a subscription: `0` for the first bill only, `-1` forever, or a number of months.","example":3},"curbToMaxAmount":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Never discount more than this amount per bill"},"allowSKUs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these products"},"allowPOs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these purchase options"},"ignoreSKUs":{"type":"array","items":{"type":"string","minLength":1},"description":"Never apply to these products"},"requireVerticals":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these product types"},"ignoreVerticals":{"type":"array","items":{"type":"string","minLength":1},"description":"Never apply to these product types"}},"required":["amount","numberOfMonths"],"additionalProperties":false},"FixedAmountDiscountConditions":{"type":"object","properties":{"minimumTotalItems":{"type":"integer","minimum":1,"description":"Minimum number of items in the cart"},"minimumTotalAmount":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Minimum cart total, in the currency of the purchase"},"totalTimesApplicable":{"type":"integer","minimum":1,"description":"How many times the discount can be used in total"},"totalTimesApplicablePerUser":{"type":"integer","minimum":1,"description":"How many times one user can use the discount"}},"default":{},"additionalProperties":false},"TrialPeriodDiscountParameters":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"description":"Length of the trial","example":14}},"required":["days"],"additionalProperties":false},"TrialPeriodDiscountConditions":{"type":"object","properties":{"skus":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these products"},"purchaseOptionIds":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these purchase options"},"totalTimesApplicable":{"type":"integer","minimum":1,"description":"How many times the discount can be used in total"},"totalTimesApplicablePerUser":{"type":"integer","minimum":1,"description":"How many times one user can use the discount"}},"default":{},"additionalProperties":false},"SpecialPriceTrancheDiscountParameters":{"type":"object","properties":{"period":{"type":"string","enum":["day","week","month","quarter","year"],"description":"Billing period while the special price applies"},"times":{"type":"integer","minimum":1,"description":"Number of periods per bill, e.g. `3` with `month` for quarterly bills","example":1},"forcedPricePerItem":{"type":"number","minimum":0,"description":"Price per item while the tranche applies. Defaults to the regular price"},"forcedPriceTaxIncluded":{"type":"boolean","description":"Whether `forcedPricePerItem` includes tax. Defaults to the item's VAT settings"},"numberOfMonths":{"type":"integer","minimum":-1,"description":"How long the special price applies: `0` for the first bill only, `-1` forever, or a number of months. Defaults to one tranche billing period.","example":3},"allowSKUs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these products"},"allowPOs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these purchase options"}},"required":["period","times"],"additionalProperties":false},"SpecialPriceTrancheDiscountConditions":{"type":"object","properties":{"totalTimesApplicable":{"type":"integer","minimum":1,"description":"How many times the discount can be used in total"},"totalTimesApplicablePerUser":{"type":"integer","minimum":1,"description":"How many times one user can use the discount"}},"default":{},"additionalProperties":false},"DeveloperTestDiscountParameters":{"type":"object","properties":{"allowSKUs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these products"},"allowPOs":{"type":"array","items":{"type":"string","minLength":1},"description":"Only apply to these purchase options"}},"additionalProperties":false},"DeveloperTestDiscountConditions":{"type":"object","properties":{"totalTimesApplicable":{"type":"integer","minimum":1,"description":"How many times the discount can be used in total"}},"default":{},"additionalProperties":false},"Discount":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"id":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"status":{"$ref":"#/components/schemas/DiscountStatus"},"usageCount":{"type":"integer","description":"How many times the discount has been used"},"createdAt":{"type":"string"},"type":{"type":"string","enum":["percentage"]},"parameters":{"$ref":"#/components/schemas/PercentageDiscountParameters"},"conditions":{"$ref":"#/components/schemas/PercentageDiscountConditions"}},"required":["name","code","startDate","endDate","id","status","usageCount","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"id":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"status":{"$ref":"#/components/schemas/DiscountStatus"},"usageCount":{"type":"integer","description":"How many times the discount has been used"},"createdAt":{"type":"string"},"type":{"type":"string","enum":["fixedAmount"]},"parameters":{"$ref":"#/components/schemas/FixedAmountDiscountParameters"},"conditions":{"$ref":"#/components/schemas/FixedAmountDiscountConditions"}},"required":["name","code","startDate","endDate","id","status","usageCount","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"id":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"status":{"$ref":"#/components/schemas/DiscountStatus"},"usageCount":{"type":"integer","description":"How many times the discount has been used"},"createdAt":{"type":"string"},"type":{"type":"string","enum":["trialPeriod"]},"parameters":{"$ref":"#/components/schemas/TrialPeriodDiscountParameters"},"conditions":{"$ref":"#/components/schemas/TrialPeriodDiscountConditions"}},"required":["name","code","startDate","endDate","id","status","usageCount","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"id":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"status":{"$ref":"#/components/schemas/DiscountStatus"},"usageCount":{"type":"integer","description":"How many times the discount has been used"},"createdAt":{"type":"string"},"type":{"type":"string","enum":["specialPriceTranche"]},"parameters":{"$ref":"#/components/schemas/SpecialPriceTrancheDiscountParameters"},"conditions":{"$ref":"#/components/schemas/SpecialPriceTrancheDiscountConditions"}},"required":["name","code","startDate","endDate","id","status","usageCount","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"id":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"status":{"$ref":"#/components/schemas/DiscountStatus"},"usageCount":{"type":"integer","description":"How many times the discount has been used"},"createdAt":{"type":"string"},"type":{"type":"string","enum":["developerTest"]},"parameters":{"$ref":"#/components/schemas/DeveloperTestDiscountParameters"},"conditions":{"$ref":"#/components/schemas/DeveloperTestDiscountConditions"}},"required":["name","code","startDate","endDate","id","status","usageCount","type","parameters"]}]},"DiscountList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Discount"}},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` to get the next page. `null` on the last page. Filters apply after `limit`, so a page can hold fewer discounts than `limit`, or none, while more remain: keep paging until this is `null`."}},"required":["items","nextCursor"]},"DiscountType":{"type":"string","enum":["percentage","fixedAmount","trialPeriod","specialPriceTranche","developerTest"],"description":"`percentage` and `fixedAmount` reduce the price, `trialPeriod` gives free days before the first bill, `specialPriceTranche` sets an introductory price and billing period, and `developerTest` makes a purchase free for testing."},"CreateDiscountBody":{"oneOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"type":{"type":"string","enum":["percentage"]},"parameters":{"$ref":"#/components/schemas/PercentageDiscountParameters"},"conditions":{"$ref":"#/components/schemas/PercentageDiscountConditions"}},"required":["name","startDate","endDate","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"type":{"type":"string","enum":["fixedAmount"]},"parameters":{"$ref":"#/components/schemas/FixedAmountDiscountParameters"},"conditions":{"$ref":"#/components/schemas/FixedAmountDiscountConditions"}},"required":["name","startDate","endDate","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"type":{"type":"string","enum":["trialPeriod"]},"parameters":{"$ref":"#/components/schemas/TrialPeriodDiscountParameters"},"conditions":{"$ref":"#/components/schemas/TrialPeriodDiscountConditions"}},"required":["name","startDate","endDate","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"type":{"type":"string","enum":["specialPriceTranche"]},"parameters":{"$ref":"#/components/schemas/SpecialPriceTrancheDiscountParameters"},"conditions":{"$ref":"#/components/schemas/SpecialPriceTrancheDiscountConditions"}},"required":["name","startDate","endDate","type","parameters"]},{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"type":{"type":"string","enum":["developerTest"]},"parameters":{"$ref":"#/components/schemas/DeveloperTestDiscountParameters"},"conditions":{"$ref":"#/components/schemas/DeveloperTestDiscountConditions"}},"required":["name","startDate","endDate","type","parameters"]}]},"UpdateDiscountBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Welcome offer"},"description":{"type":"string"},"code":{"type":"string","nullable":true,"maxLength":64,"pattern":"^[A-Za-z0-9_-]+$","description":"The code customers enter. Stored in upper case. `null` applies the discount automatically, with no code to enter. `ANY` is reserved.","example":"WELCOME20"},"startDate":{"type":"string","format":"date-time","description":"When the discount starts applying","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the discount stops applying","example":"2026-12-31T23:59:59Z"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"Limit the discount to purchases in this currency","example":"SEK"},"parameters":{"type":"object","additionalProperties":{"nullable":true},"description":"Replaces all of the discount's parameters. Takes the same fields as when creating a discount of its type."},"conditions":{"type":"object","additionalProperties":{"nullable":true},"description":"Replaces all of the discount's conditions. Takes the same fields as when creating a discount of its type."}},"additionalProperties":false},"OneTimeCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string","example":"K7Q2M9XW4D1P"},"status":{"type":"string","enum":["PENDING","ACTIVE","EXPIRED","CANCELED","REDEEMED"]},"startDate":{"type":"string"},"endDate":{"type":"string"},"redeemedBy":{"type":"string","description":"The user who redeemed the code"},"redeemedAt":{"type":"string"}},"required":["id","code","status","startDate","endDate"]},"OneTimeCodeList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OneTimeCode"}},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` to get the next page. `null` on the last page."}},"required":["items","nextCursor"]},"CreateOneTimeCodesBody":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":10000,"description":"How many codes to generate","example":500},"startDate":{"type":"string","format":"date-time","description":"When the codes become usable","example":"2026-10-01T00:00:00Z"},"endDate":{"type":"string","format":"date-time","description":"When the codes stop being usable","example":"2026-12-31T23:59:59Z"}},"required":["count","startDate","endDate"],"additionalProperties":false},"LeakySettings":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the leaky (metered) paywall is enabled","example":true},"count":{"type":"integer","minimum":1,"description":"Number of free articles allowed within the period","example":3},"periodInHours":{"type":"integer","minimum":1,"description":"Length of the metering window, in hours","example":720}},"required":["enabled"]},"PaywallAdmin":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the paywall","example":"aM8o7LqpkGZJ-szyPwe_E"},"vendorId":{"type":"string","description":"Vendor identifier","example":"acme"},"currency":{"type":"string","description":"Currency code for pricing","example":"SEK"},"version":{"type":"number","description":"Paywall version number","example":2},"settings":{"type":"object","properties":{"template":{"type":"string","enum":["LOGIN","BOXES","ARTICLE"],"description":"Paywall template type - LOGIN for authentication-only, BOXES for subscription options","example":"BOXES"},"useDefaultLogo":{"type":"boolean","description":"Whether to use the default vendor logo","example":true},"useDefaultCurrency":{"type":"boolean","description":"Whether to use the default vendor currency","example":true},"useDefaultColor":{"type":"boolean","description":"Whether to use the default vendor color","example":true},"styling":{"type":"object","properties":{"dropShadow":{"type":"boolean","description":"Whether to show drop shadow on paywall elements","example":true},"backgroundColor":{"type":"string","description":"Background color in hex format","example":"#000000"},"showBackground":{"type":"boolean","description":"Whether to show the background","example":false}},"required":["dropShadow","backgroundColor","showBackground"]},"displayOptions":{"type":"object","properties":{"enableGift":{"type":"boolean"},"enableCompany":{"type":"boolean"},"enableLoginButton":{"type":"boolean"}}},"loginFields":{"type":"object","properties":{"name":{"type":"boolean","description":"Whether the login form collects the visitor name","example":true}},"description":"Which extra fields the login template collects"},"leaky":{"$ref":"#/components/schemas/LeakySettings"},"redirectUrl":{"type":"string","description":"Paywall-wide URL the visitor is sent to after completing a purchase. Used for subscriptions that do not set their own `redirectUrl`.","example":"https://acme.example.com/welcome"}}},"showLoginButton":{"type":"boolean","description":"Whether to show a login button. When true, indicates a subscription/entitlement paywall. When false with LOGIN template, indicates a login-only paywall.","example":true},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Subscription identifier","example":"R4gX0YSbSU1WJA7bCrbQw"},"sku":{"type":"string","description":"Product SKU. Omitted for external-link subscriptions.","example":"sid:acme-plus-monthly"},"poId":{"type":"string","description":"Purchase option identifier. Omitted for external-link subscriptions.","example":"VDuH_poxqIPKW638Ok43q"},"title":{"type":"string","description":"Subscription title","example":"ACME Plus monthly"},"description":{"type":"string","description":"Subscription description (rendered from markdown, so it can contain HTML)","example":"<p>Only 720 kr/year - save 20%</p>"},"price":{"type":"number","description":"Regular price","example":99},"discountPrice":{"type":"number","description":"Discounted price if applicable","example":75},"discountCode":{"type":"string","description":"Applied discount code","example":"WELCOME20"},"periodText":{"type":"string","description":"Period rendered next to the headline price, which is `discountPrice` when one is set.","example":"3 months"},"comparePeriodText":{"type":"string","description":"Period rendered next to the struck-through `price` when `discountPrice` is set, for intro offers whose discount covers a different period than the recurring price (99 NOK / 3 months over 199 NOK / month). Renderers fall back to `periodText` when it is omitted.","example":"month"},"tag":{"type":"string","description":"Tag for categorization","example":"Most popular"},"selected":{"type":"boolean","description":"Whether this subscription is pre-selected","example":true},"features":{"type":"array","items":{"type":"string"},"description":"List of features included in this subscription","example":["Daily news","Exclusive interviews"]},"buttonText":{"type":"string","description":"Custom button text","example":"BUY ACCESS"},"readMoreLink":{"type":"string","description":"URL the read more link points at","example":"https://acme.example.com/subscriptions"},"readMoreText":{"type":"string","description":"Read more link text","example":"Read more"},"preferBusiness":{"type":"boolean","description":"Whether this option is preferred for business customers","example":false},"redirectUrl":{"type":"string","description":"URL the visitor is sent to after completing a purchase of this option. Takes precedence over the paywall-wide `settings.redirectUrl`; when both are omitted the renderer falls back to its own component setting.","example":"https://acme.example.com/welcome"},"url":{"type":"string","description":"External URL for more information","example":"https://acme.example.com/business"}},"required":["selected"]}},"subscriptionsUrl":{"type":"string","description":"URL of the subscription list backing this paywall","example":"https://acme.example.com/subscriptions.json"},"features":{"type":"array","items":{"type":"string"},"description":"General features displayed on the paywall","example":["Everything on acme.example.com"]},"mainColor":{"type":"string","description":"Main brand color in hex format","example":"#3377fe"},"headline":{"type":"string","description":"Paywall headline text","example":"Get access to ACME Plus"},"description":{"type":"string","description":"Paywall description. Authored as markdown and returned as rendered HTML by the render route.","example":"<p>Read every article, on every device.</p>"},"logoUrl":{"type":"string","description":"URL to the vendor logo","example":"https://assets.sesamy.com/vendor-assets/acme/logo.svg"},"footerPaymentMethods":{"type":"array","items":{"type":"string"},"description":"Payment methods displayed in the footer","example":["visa","mastercard","google-pay","apple-pay"]},"singlePurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether single purchase is enabled","example":true},"title":{"type":"string","description":"Single purchase option title","example":"Buy Now"},"description":{"type":"string","description":"Single purchase option description","example":"One-time purchase"},"discountCode":{"type":"string","description":"Applied discount code for single purchase","example":"WELCOME20"}},"required":["enabled"]},"name":{"type":"string","description":"Internal name of the paywall, used in the admin list","example":"Article paywall"},"status":{"type":"string","description":"Paywall status","example":"ACTIVE"},"entity":{"type":"string","description":"Entity type discriminator","example":"Paywall"},"createdAt":{"type":"string","description":"ISO timestamp when the paywall was created","example":"2026-01-01T00:00:00.000Z"},"modifiedAt":{"type":"string","description":"ISO timestamp when the paywall was last modified","example":"2026-01-01T00:00:00.000Z"},"previewUrl":{"type":"string","description":"URL to preview the paywall","example":"https://api.sesamy.com/paywall/paywalls/acme/aM8o7LqpkGZJ-szyPwe_E/preview"}},"required":["id","vendorId","currency","settings","showLoginButton","subscriptions","features"]},"Paywall":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the paywall","example":"aM8o7LqpkGZJ-szyPwe_E"},"vendorId":{"type":"string","description":"Vendor identifier","example":"acme"},"currency":{"type":"string","description":"Currency code for pricing","example":"SEK"},"version":{"type":"number","description":"Paywall version number","example":2},"settings":{"type":"object","properties":{"template":{"type":"string","enum":["LOGIN","BOXES","ARTICLE"],"description":"Paywall template type - LOGIN for authentication-only, BOXES for subscription options","example":"BOXES"},"useDefaultLogo":{"type":"boolean","description":"Whether to use the default vendor logo","example":true},"useDefaultCurrency":{"type":"boolean","description":"Whether to use the default vendor currency","example":true},"useDefaultColor":{"type":"boolean","description":"Whether to use the default vendor color","example":true},"styling":{"type":"object","properties":{"dropShadow":{"type":"boolean","description":"Whether to show drop shadow on paywall elements","example":true},"backgroundColor":{"type":"string","description":"Background color in hex format","example":"#000000"},"showBackground":{"type":"boolean","description":"Whether to show the background","example":false}},"required":["dropShadow","backgroundColor","showBackground"]},"displayOptions":{"type":"object","properties":{"enableGift":{"type":"boolean"},"enableCompany":{"type":"boolean"},"enableLoginButton":{"type":"boolean"}}},"loginFields":{"type":"object","properties":{"name":{"type":"boolean","description":"Whether the login form collects the visitor name","example":true}},"description":"Which extra fields the login template collects"},"leaky":{"$ref":"#/components/schemas/LeakySettings"},"redirectUrl":{"type":"string","description":"Paywall-wide URL the visitor is sent to after completing a purchase. Used for subscriptions that do not set their own `redirectUrl`.","example":"https://acme.example.com/welcome"}}},"showLoginButton":{"type":"boolean","description":"Whether to show a login button. When true, indicates a subscription/entitlement paywall. When false with LOGIN template, indicates a login-only paywall.","example":true},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Subscription identifier","example":"R4gX0YSbSU1WJA7bCrbQw"},"sku":{"type":"string","description":"Product SKU. Omitted for external-link subscriptions.","example":"sid:acme-plus-monthly"},"poId":{"type":"string","description":"Purchase option identifier. Omitted for external-link subscriptions.","example":"VDuH_poxqIPKW638Ok43q"},"title":{"type":"string","description":"Subscription title","example":"ACME Plus monthly"},"description":{"type":"string","description":"Subscription description (rendered from markdown, so it can contain HTML)","example":"<p>Only 720 kr/year - save 20%</p>"},"price":{"type":"number","description":"Regular price","example":99},"discountPrice":{"type":"number","description":"Discounted price if applicable","example":75},"discountCode":{"type":"string","description":"Applied discount code","example":"WELCOME20"},"periodText":{"type":"string","description":"Period rendered next to the headline price, which is `discountPrice` when one is set.","example":"3 months"},"comparePeriodText":{"type":"string","description":"Period rendered next to the struck-through `price` when `discountPrice` is set, for intro offers whose discount covers a different period than the recurring price (99 NOK / 3 months over 199 NOK / month). Renderers fall back to `periodText` when it is omitted.","example":"month"},"tag":{"type":"string","description":"Tag for categorization","example":"Most popular"},"selected":{"type":"boolean","description":"Whether this subscription is pre-selected","example":true},"features":{"type":"array","items":{"type":"string"},"description":"List of features included in this subscription","example":["Daily news","Exclusive interviews"]},"buttonText":{"type":"string","description":"Custom button text","example":"BUY ACCESS"},"readMoreLink":{"type":"string","description":"URL the read more link points at","example":"https://acme.example.com/subscriptions"},"readMoreText":{"type":"string","description":"Read more link text","example":"Read more"},"preferBusiness":{"type":"boolean","description":"Whether this option is preferred for business customers","example":false},"redirectUrl":{"type":"string","description":"URL the visitor is sent to after completing a purchase of this option. Takes precedence over the paywall-wide `settings.redirectUrl`; when both are omitted the renderer falls back to its own component setting.","example":"https://acme.example.com/welcome"},"url":{"type":"string","description":"External URL for more information","example":"https://acme.example.com/business"}},"required":["selected"]}},"subscriptionsUrl":{"type":"string","description":"URL of the subscription list backing this paywall","example":"https://acme.example.com/subscriptions.json"},"features":{"type":"array","items":{"type":"string"},"description":"General features displayed on the paywall","example":["Everything on acme.example.com"]},"mainColor":{"type":"string","description":"Main brand color in hex format","example":"#3377fe"},"headline":{"type":"string","description":"Paywall headline text","example":"Get access to ACME Plus"},"description":{"type":"string","description":"Paywall description. Authored as markdown and returned as rendered HTML by the render route.","example":"<p>Read every article, on every device.</p>"},"logoUrl":{"type":"string","description":"URL to the vendor logo","example":"https://assets.sesamy.com/vendor-assets/acme/logo.svg"},"footerPaymentMethods":{"type":"array","items":{"type":"string"},"description":"Payment methods displayed in the footer","example":["visa","mastercard","google-pay","apple-pay"]},"singlePurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether single purchase is enabled","example":true},"title":{"type":"string","description":"Single purchase option title","example":"Buy Now"},"description":{"type":"string","description":"Single purchase option description","example":"One-time purchase"},"discountCode":{"type":"string","description":"Applied discount code for single purchase","example":"WELCOME20"}},"required":["enabled"]}},"required":["id","vendorId","currency","settings","showLoginButton","subscriptions","features"]},"AccessList":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the access list","example":"src_123abc"},"name":{"type":"string","description":"Name of the access list","example":"My Partner API"},"description":{"type":"string","description":"Description of the access list","example":"Purchases from partner system"},"type":{"type":"string","enum":["CSV_FILE_OLD","CSV_FILE","CSV_TRANSACTIONS","CLAIMED","MANUAL","HOOK","BASIC_API"],"description":"Type of access list","example":"MANUAL"},"status":{"type":"string","enum":["DRAFT","ACTIVE","CANCELED"],"description":"Status of the access list","example":"ACTIVE"},"excludeFromStats":{"type":"boolean","description":"Whether to exclude from statistics","example":false}},"required":["id","name","type","status"]},"CreateAccessList":{"type":"object","properties":{"name":{"type":"string","description":"Name of the access list","example":"My Partner API"},"description":{"type":"string","description":"Description of the access list","example":"Purchases from partner system"},"type":{"type":"string","enum":["CSV_FILE_OLD","CSV_FILE","CSV_TRANSACTIONS","CLAIMED","MANUAL","HOOK","BASIC_API"],"description":"Type of access list","example":"MANUAL"},"status":{"type":"string","enum":["DRAFT","ACTIVE","CANCELED"],"description":"Status of the access list","example":"ACTIVE"},"excludeFromStats":{"type":"boolean","description":"Whether to exclude from statistics","example":false}},"required":["name","type","status"]},"UpdateAccessList":{"type":"object","properties":{"name":{"type":"string","description":"Name of the access list","example":"My Partner API"},"description":{"type":"string","description":"Description of the access list","example":"Purchases from partner system"},"type":{"type":"string","enum":["CSV_FILE_OLD","CSV_FILE","CSV_TRANSACTIONS","CLAIMED","MANUAL","HOOK","BASIC_API"],"description":"Type of access list","example":"MANUAL"},"status":{"type":"string","enum":["DRAFT","ACTIVE","CANCELED"],"description":"Status of the access list","example":"ACTIVE"},"excludeFromStats":{"type":"boolean","description":"Whether to exclude from statistics","example":false}}},"GrantAddress":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"},"co":{"type":"string"}}},"Grant":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the grant","example":"grant_123abc"},"source":{"type":"string","description":"Source/access list ID","example":"src_123abc"},"email":{"type":"string","format":"email","description":"Email address of the user","example":"user@example.com"},"userId":{"type":"string","description":"User ID","example":"pub_user_123"},"publisherUserId":{"type":"string","description":"Publisher user ID","example":"pub_user_123"},"sku":{"type":"string","description":"Product SKU","example":"premium-article-123"},"poId":{"type":"string","description":"Purchase option ID","example":"po_123abc"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","CANCELED"],"description":"Status of the grant","example":"ACTIVE"},"startsAt":{"type":"string","format":"date-time","description":"Grant start date","example":"2024-01-01T00:00:00Z"},"endsAt":{"type":"string","format":"date-time","description":"Grant end date","example":"2024-12-31T23:59:59Z"},"firstName":{"type":"string","description":"First name","example":"John"},"lastName":{"type":"string","description":"Last name","example":"Doe"},"phone":{"type":"string","description":"Phone number","example":"+1234567890"},"deliveryAddress":{"$ref":"#/components/schemas/GrantAddress"},"billingAddress":{"$ref":"#/components/schemas/GrantAddress"},"publisherPurchaseId":{"type":"string","description":"Publisher purchase ID","example":"pub_purchase_123"},"notes":{"type":"string","description":"Notes about the grant","example":"Bulk purchase"},"extraFields":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional custom fields","example":{"custom_field":"value"}},"excludeFromStats":{"type":"boolean","description":"Whether to exclude from statistics","example":false}},"required":["id","source","email","sku","poId","status"]},"CreateGrant":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user","example":"user@example.com"},"userId":{"type":"string","description":"User ID","example":"pub_user_123"},"publisherUserId":{"type":"string","description":"Publisher user ID","example":"pub_user_123"},"sku":{"type":"string","minLength":1,"description":"Product SKU (required)","example":"premium-article-123"},"poId":{"type":"string","minLength":1,"description":"Purchase option ID (required)","example":"po_123abc"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","CANCELED"],"description":"Status of the grant","example":"ACTIVE"},"startsAt":{"type":"string","format":"date-time","description":"Grant start date","example":"2024-01-01T00:00:00Z"},"endsAt":{"type":"string","format":"date-time","description":"Grant end date","example":"2024-12-31T23:59:59Z"},"firstName":{"type":"string","description":"First name","example":"John"},"lastName":{"type":"string","description":"Last name","example":"Doe"},"phone":{"type":"string","description":"Phone number","example":"+1234567890"},"deliveryAddress":{"$ref":"#/components/schemas/GrantAddress"},"billingAddress":{"$ref":"#/components/schemas/GrantAddress"},"publisherPurchaseId":{"type":"string","description":"Publisher purchase ID","example":"pub_purchase_123"},"notes":{"type":"string","description":"Notes about the grant","example":"Bulk purchase"},"extraFields":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional custom fields","example":{"custom_field":"value"}},"excludeFromStats":{"type":"boolean","description":"Whether to exclude from statistics","example":false},"source":{"type":"string","description":"Source/access list ID","example":"src_123abc"}},"required":["email","sku","poId","status","source"]},"UpdateGrant":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user","example":"user@example.com"},"userId":{"type":"string","description":"User ID","example":"pub_user_123"},"publisherUserId":{"type":"string","description":"Publisher user ID","example":"pub_user_123"},"sku":{"type":"string","description":"Product SKU","example":"premium-article-123"},"poId":{"type":"string","description":"Purchase option ID","example":"po_123abc"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","CANCELED"],"description":"Status of the grant","example":"ACTIVE"},"startsAt":{"type":"string","format":"date-time","description":"Grant start date","example":"2024-01-01T00:00:00Z"},"endsAt":{"type":"string","format":"date-time","description":"Grant end date","example":"2024-12-31T23:59:59Z"},"firstName":{"type":"string","description":"First name","example":"John"},"lastName":{"type":"string","description":"Last name","example":"Doe"},"phone":{"type":"string","description":"Phone number","example":"+1234567890"},"deliveryAddress":{"$ref":"#/components/schemas/GrantAddress"},"billingAddress":{"$ref":"#/components/schemas/GrantAddress"},"publisherPurchaseId":{"type":"string","description":"Publisher purchase ID","example":"pub_purchase_123"},"notes":{"type":"string","description":"Notes about the grant","example":"Bulk purchase"},"extraFields":{"type":"object","additionalProperties":{"type":"string"},"description":"Additional custom fields","example":{"custom_field":"value"}},"excludeFromStats":{"type":"boolean","description":"Whether to exclude from statistics","example":false}}},"StatsDateRange":{"type":"object","properties":{"fromDate":{"type":"string","example":"2026-01-01"},"toDate":{"type":"string","example":"2026-03-31"}},"required":["fromDate","toDate"]},"StatsSeriesPoint":{"type":"object","properties":{"date":{"type":"string","example":"2026-01-01"},"value":{"type":"number","nullable":true}},"required":["date","value"]},"StatsSeries":{"type":"object","properties":{"key":{"type":"string","description":"What this series counts — usually a product or purchase option.","example":"ACME Plus"},"points":{"type":"array","items":{"$ref":"#/components/schemas/StatsSeriesPoint"}}},"required":["key","points"]},"StatsMetricSeries":{"type":"object","properties":{"vendorId":{"type":"string","example":"acme"},"metric":{"type":"string","enum":["currentMrr","newMrr","churnMrr","projectedMrr","totalRevenue","totalSales","subscriptionSales","totalSubscribers"],"example":"currentMrr"},"dateRange":{"$ref":"#/components/schemas/StatsDateRange"},"title":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string","enum":["currency","count","percent"],"description":"How to read `headline` and each point `value`."},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency when `unit` is `currency`, otherwise null.","example":"SEK"},"headline":{"type":"number","nullable":true,"description":"The single summary figure for the whole range, or null if upstream has none.","example":145680.35},"series":{"type":"array","items":{"$ref":"#/components/schemas/StatsSeries"},"description":"One entry per product. Empty for headline-only metrics such as `totalSales`."}},"required":["vendorId","metric","dateRange","title","description","unit","currency","headline","series"]},"StatsMoney":{"type":"object","additionalProperties":{"type":"number"},"example":{"SEK":139956,"NOK":198}},"StatsBreakdownRow":{"type":"object","properties":{"key":{"type":"string","nullable":true,"description":"The dimension value, or null when the purchase carried no value for this dimension.","example":"newsletter"},"label":{"type":"string","description":"Upstream display label for the row, kept for reference.","example":"newsletter"},"sessions":{"type":"number"},"users":{"type":"number"},"transactions":{"type":"number"},"conversionRate":{"type":"number","description":"Percentage, 0-100.","example":21.59},"revenue":{"$ref":"#/components/schemas/StatsMoney"},"meta":{"type":"object","additionalProperties":{"type":"string"},"description":"Extra context upstream attaches to content dimensions (`item_source`, `section`, `tag`, `author`) — page title, url, author and similar. Absent for the UTM dimensions."}},"required":["key","label","sessions","users","transactions","conversionRate","revenue"]},"StatsBreakdown":{"type":"object","properties":{"vendorId":{"type":"string","example":"acme"},"dimension":{"type":"string","enum":["utm_source","utm_medium","utm_campaign","utm_content","utm_source_medium","referrer","item_source","section","tag","author"],"example":"utm_source"},"subset":{"type":"string","enum":["all","subscriptions","single"],"example":"all"},"dateRange":{"$ref":"#/components/schemas/StatsDateRange"},"title":{"type":"string"},"description":{"type":"string"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/StatsBreakdownRow"},"description":"Sorted by revenue descending, then transactions descending."},"totals":{"type":"object","properties":{"sessions":{"type":"number"},"users":{"type":"number"},"transactions":{"type":"number"},"revenue":{"$ref":"#/components/schemas/StatsMoney"}},"required":["sessions","users","transactions","revenue"],"description":"Summed across the rows that were returned. When `truncated` is true these totals cover the returned rows only."},"rowCount":{"type":"number","description":"Total rows upstream produced, before `limit` was applied."},"truncated":{"type":"boolean","description":"True when `limit` dropped rows from the response."}},"required":["vendorId","dimension","subset","dateRange","title","description","rows","totals","rowCount","truncated"]},"StatsCatalogue":{"type":"object","properties":{"metrics":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"unit":{"type":"string","enum":["currency","count","percent"]}},"required":["key","title","description","unit"]}},"dimensions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}},"required":["key","title","description"]}}},"required":["metrics","dimensions"]}},"parameters":{}},"paths":{"/management/vendors":{"get":{"tags":["Vendors"],"summary":"List the vendors the user can access","description":"Get vendors from organization memberships or global admin:organizations / access:all_organizations grants on the Authhero Management API. Discovery does not grant provisioning rights.","security":[{"OpenID":[]}],"responses":{"200":{"description":"The vendors the user can access","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Vendor"}}}}}}},"post":{"tags":["Vendors"],"security":[{"OpenID":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"website":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2}},"required":["name","id","website","country"]}}}},"responses":{"201":{"description":"Status"}}}},"/management/vendors/{vendorId}":{"get":{"tags":["Vendors"],"summary":"Get a vendor the user can access","description":"Get one vendor, including its business currency. Allowed by organization membership or global admin:organizations / access:all_organizations grants on the Authhero Management API, the same rule as the vendor list.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"acme"},"required":true,"name":"vendorId","in":"path"}],"responses":{"200":{"description":"The vendor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorDetail"}}}},"401":{"description":"Missing authentication token"},"403":{"description":"The user does not administrate this vendor"},"404":{"description":"No such vendor"}}}},"/management/bills":{"get":{"tags":["Bills"],"security":[{"OpenID":["bills:read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","enum":["DRAFT","PENDING","PAID","RETRYING","OVERDUE","CANCELED","EXPIRED","DELETED","VOIDED"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"contractId","in":"query"},{"schema":{"type":"string","format":"date-time","pattern":"(?:Z|[+-]\\d{2}:\\d{2})$","description":"Only bills created at or after this ISO 8601 timestamp","example":"2026-01-01T00:00:00Z"},"required":false,"name":"createdGte","in":"query"},{"schema":{"type":"string","format":"date-time","pattern":"(?:Z|[+-]\\d{2}:\\d{2})$","description":"Only bills created at or before this ISO 8601 timestamp","example":"2026-01-31T23:59:59Z"},"required":false,"name":"createdLte","in":"query"},{"schema":{"type":"string","format":"date-time","pattern":"(?:Z|[+-]\\d{2}:\\d{2})$","description":"Only bills modified at or after this ISO 8601 timestamp","example":"2026-01-01T00:00:00Z"},"required":false,"name":"modifiedGte","in":"query"},{"schema":{"type":"string","format":"date-time","pattern":"(?:Z|[+-]\\d{2}:\\d{2})$","description":"Only bills modified at or before this ISO 8601 timestamp","example":"2026-01-31T23:59:59Z"},"required":false,"name":"modifiedLte","in":"query"}],"responses":{"200":{"description":"Retrieve the users bills","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Bill"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/bills/{id}":{"get":{"tags":["Bills"],"security":[{"OpenID":["bills:read"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the users bills","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts":{"post":{"tags":["Contracts"],"summary":"Create a contract","description":"Creates a contract for a user without a checkout, billed by invoice. The contract is returned as PENDING: priced, but not billed and granting no access. Review it, then confirm it with `POST /management/contracts/{id}/confirm`, or pass `confirm: true` to do both in one call. For a multi-seat contract, use a license product; `quantity` is what is billed and `seats` optionally sets how many seats that buys. Creating is not idempotent: a repeated request creates a second contract.","security":[{"OpenID":["contracts:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContractRequest"},"example":{"sku":"sid:acme-plus-business","purchaseOptionId":"acme-plus-business-yearly","contractType":"BUSINESS","user":{"email":"admin@acme.example","firstName":"Ada","lastName":"Admin","businessDetails":{"companyName":"ACME AB","vatNr":"SE556000000001"},"address":{"street":"Example Street 1","zip":"12345","city":"Stockholm","country":"SE"}},"invoice":{"email":"invoices@acme.example","customerReference":"PO-1042","vendorReference":"Jane Seller"},"quantity":1,"seats":10,"unitPrice":{"amount":9999,"taxIncluded":true},"payment":{"provider":"BILLOGRAM","method":"INVOICE","country":"SE"},"confirm":false}}}},"responses":{"201":{"description":"The created contract","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"},"example":{"id":"1d78271264b9c76d5842911dd70b4353","name":"Premium Subscription","userId":"user123","createdAt":"2023-01-01T12:00:00Z","confirmedAt":"2023-01-01T12:05:00Z","updatedAt":"2023-03-15T09:30:00Z","price":99,"nextBillAt":"2023-04-01T12:00:00Z","willCancelAt":null,"cancelRequestedAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"sku":"premium-monthly","purchaseOptionId":"monthly","purchaseOptionName":"Monthly plan","name":"Premium Subscription","productType":"pass","isMultiseat":false,"quantity":1}],"status":"PENDING","isActive":false,"recurringInterval":"MONTH","recurringTime":1,"appliedDiscounts":[],"discount":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Seats can only be set for license products"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"get":{"tags":["Contracts"],"security":[{"OpenID":["contracts:read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"name":"userId","in":"query"}],"responses":{"200":{"description":"Retrieve the users contracts","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contract"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}":{"get":{"tags":["Contracts"],"security":[{"OpenID":["contracts:read"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the users contracts","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/confirm":{"post":{"tags":["Contracts"],"summary":"Confirm a contract","description":"Confirms a PENDING contract: the customer is billed and access is granted, including the seats of a multi-seat contract. A contract that starts later becomes FORTHCOMING instead of ACTIVE. Confirming an already confirmed contract returns it unchanged.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The confirmed contract","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"},"example":{"id":"1d78271264b9c76d5842911dd70b4353","name":"Premium Subscription","userId":"user123","createdAt":"2023-01-01T12:00:00Z","confirmedAt":"2023-01-01T12:05:00Z","updatedAt":"2023-03-15T09:30:00Z","price":99,"nextBillAt":"2023-04-01T12:00:00Z","willCancelAt":null,"cancelRequestedAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"sku":"premium-monthly","purchaseOptionId":"monthly","purchaseOptionName":"Monthly plan","name":"Premium Subscription","productType":"pass","isMultiseat":false,"quantity":1}],"status":"ACTIVE","isActive":true,"recurringInterval":"MONTH","recurringTime":1,"appliedDiscounts":[],"discount":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to confirm the contract"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - The contract is in a status that cannot be confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"A CANCELED contract cannot be confirmed"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/seats":{"put":{"tags":["Contracts"],"summary":"Set the seats of a contract","description":"Sets how many seats a multi-seat contract grants. It does not change what is billed: the seats are not part of the price. The change applies at once. Setting the seats the contract already has returns it unchanged. Seats cannot be lowered below the number of users holding one.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetContractSeatsBody"},"example":{"seats":25}}}},"responses":{"200":{"description":"The contract with its new seats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"},"example":{"id":"1d78271264b9c76d5842911dd70b4353","name":"Premium Subscription","userId":"user123","createdAt":"2023-01-01T12:00:00Z","confirmedAt":"2023-01-01T12:05:00Z","updatedAt":"2023-03-15T09:30:00Z","price":99,"nextBillAt":"2023-04-01T12:00:00Z","willCancelAt":null,"cancelRequestedAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"sku":"premium-monthly","purchaseOptionId":"monthly","purchaseOptionName":"Monthly plan","name":"Premium Subscription","productType":"pass","isMultiseat":false,"quantity":1}],"status":"ACTIVE","isActive":true,"recurringInterval":"MONTH","recurringTime":1,"appliedDiscounts":[],"discount":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Seats are only available for license products"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - The contract cannot be changed, or has more users than the requested seats","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"12 seats are in use. Remove users before lowering the seats to 10"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/seats/users":{"get":{"tags":["Contracts"],"summary":"List users holding contract seats","description":"Lists the users holding seats across all license items on a multi-seat contract. Removed seats are left out. Filter by sku to list one item.","security":[{"OpenID":["contracts:read"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Filter seat users by license item SKU. Omit to list all contract seat users."},"required":false,"name":"sku","in":"query"}],"responses":{"200":{"description":"Users holding seats on the contract","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID","example":"auth0|123456"},"email":{"type":"string","description":"User email address","example":"user@example.com"},"fullName":{"type":"string","description":"User full name","example":"John Doe"},"sku":{"type":"string","description":"Product SKU","example":"premium-subscription"},"status":{"type":"string","description":"Entitlement status","example":"ACTIVE"},"entitlementId":{"type":"string","description":"Entitlement ID","example":"ent_123456"}},"required":["userId","sku","status","entitlementId"]}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Contracts"],"summary":"Assign a contract seat to a user","description":"Assigns a seat by email. Vault picks the license item with a free seat. The change does not affect billing.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddContractSeatUserBody"}}}},"responses":{"204":{"description":"Seat assigned"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Seats are only available for license products"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"No seat is available on the contract"},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/seats/users/{userId}":{"delete":{"tags":["Contracts"],"summary":"Remove a user from a contract seat","description":"Removes a user from the contract seat license. The change does not affect billing.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"User ID of the seat holder to remove.","example":"auth0|123456"},"required":true,"name":"userId","in":"path"}],"responses":{"204":{"description":"Seat user removed"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Seats are only available for license products"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/licenses":{"get":{"tags":["Contracts"],"deprecated":true,"summary":"List users holding contract seats (deprecated)","description":"Use GET /management/contracts/{id}/seats/users instead.","security":[{"OpenID":["contracts:read"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve users with license entitlements for the contract","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"User ID","example":"auth0|123456"},"email":{"type":"string","description":"User email address","example":"user@example.com"},"fullName":{"type":"string","description":"User full name","example":"John Doe"},"sku":{"type":"string","description":"Product SKU","example":"premium-subscription"},"status":{"type":"string","description":"Entitlement status","example":"ACTIVE"},"entitlementId":{"type":"string","description":"Entitlement ID","example":"ent_123456"}},"required":["userId","sku","status","entitlementId"]}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/upgrade-options":{"get":{"tags":["Contracts"],"summary":"List upgrade options","description":"Lists the products and purchase options each item of the contract can be upgraded, downgraded, or switched to. Returns 400 when the contract cannot be changed (inactive or non-recurring).","security":[{"OpenID":["contracts:read"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The available upgrade and downgrade paths for the contract","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UpgradeOption"}},"example":[{"itemId":"item_1","sku":"sid:acme-plus-monthly","purchaseOptionId":"monthly","paths":[{"type":"UPGRADE","sku":"sid:acme-plus-yearly","purchaseOptionId":"yearly","title":"ACME Plus Yearly","cover":"https://assets.example.com/acme-plus.png"},{"type":"EQUIVALENT","sku":"sid:acme-plus-monthly","purchaseOptionId":"monthly-campaign","title":"ACME Plus Monthly (campaign)"}]}]}}},"400":{"description":"Bad Request - The contract cannot be changed (inactive or non-recurring)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Cannot upgrade an inactive contract"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/transactions":{"get":{"tags":["Transactions"],"security":[{"OpenID":["transactions:read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string"},"required":false,"name":"transactionId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"billId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"contractId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"userId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"dateFrom","in":"query"},{"schema":{"type":"string"},"required":false,"name":"dateTo","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"from","in":"query"}],"responses":{"200":{"description":"A list of transactions","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/products":{"get":{"tags":["Products"],"security":[{"OpenID":["products:read"]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"}],"responses":{"200":{"description":"Retrieve a list of products","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Products"],"security":[{"OpenID":["products:write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["podcast"]},"url":{"type":"string"},"spotifyId":{"type":"string"}},"required":["type","url"]}}}},"responses":{"200":{"description":"A created product","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/products/{sku}":{"get":{"tags":["Products"],"security":[{"OpenID":["products:read"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sku","in":"path"}],"responses":{"200":{"description":"Retrieve a a product by SKU","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"patch":{"tags":["Products"],"security":[{"OpenID":["products:write"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sku","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"externalIds":{"type":"object","properties":{"spotifyId":{"type":"string"}}},"language":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"The updated product","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/products/{sku}/fulfillments":{"get":{"tags":["Products"],"security":[{"OpenID":["products:read"]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"sku","in":"path"}],"responses":{"200":{"description":"Retrieve a a product by SKU","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users/{user_id}/logs":{"get":{"tags":["Users"],"summary":"List user logs","description":"Returns paginated user logs for the authenticated vendor.","security":[{"OpenID":["users:read"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Zero-based page number"},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page (maximum 100)"},"required":false,"name":"per_page","in":"query"}],"responses":{"200":{"description":"User logs and total matching count","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLogs"},"example":{"logs":[{"id":"log_acme_1","date":"2026-09-23T10:00:00Z","type":"s","description":"Successful login","ip":"192.0.2.1","clientId":"acme-web"}],"total":1}}}},"400":{"description":"Invalid pagination parameters or missing vendor"},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users/{user_id}/sessions":{"get":{"tags":["Users"],"summary":"List user sessions","description":"Returns paginated user sessions for the authenticated vendor.","security":[{"OpenID":["users:read"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Zero-based page number"},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page (maximum 100)"},"required":false,"name":"per_page","in":"query"}],"responses":{"200":{"description":"User sessions and total matching count","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSessions"},"example":{"sessions":[{"id":"session_acme_1","createdAt":"2026-09-23T10:00:00Z","lastInteractionAt":"2026-09-23T10:05:00Z","lastIp":"192.0.2.1","lastUserAgent":"Mozilla/5.0","clientIds":["acme-web"]}],"total":1}}}},"400":{"description":"Invalid pagination parameters or missing vendor"},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users":{"get":{"tags":["Users"],"summary":"List users","description":"Returns a list of users with optional filtering.","security":[{"OpenID":["users:read"]}],"parameters":[{"schema":{"type":"string","description":"Search query","example":"john"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Number of results to return","example":"10"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Offset for pagination","example":"0"},"required":false,"name":"from","in":"query"}],"responses":{"200":{"description":"A list of users matching the query parameters","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Profile"}},"example":[{"userId":"user123","email":"john.doe@example.com","picture":"https://example.com/profile.jpg","name":"John Doe","mobilePhone":"+1234567890","billingAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"deliveryAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"createdAt":"2023-01-01T12:00:00Z","updatedAt":"2023-03-15T09:30:00Z"}]}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Users"],"summary":"Create a user","description":"Creates a new user with the specified email and optional name.","security":[{"OpenID":["users:write"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address of the user","example":"new.user@example.com"},"firstName":{"type":"string","description":"First name of the user","example":"New"},"lastName":{"type":"string","description":"Last name of the user","example":"User"}},"required":["email"]},"example":{"email":"new.user@example.com","firstName":"New","lastName":"User"}}}},"responses":{"201":{"description":"User created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"example":{"success":true}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users/{user_id}":{"get":{"tags":["Users"],"summary":"Get a user by ID","description":"Retrieves a specific user's profile by their ID.","security":[{"OpenID":["users:read"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"}],"responses":{"200":{"description":"The requested user profile","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"},"example":{"userId":"user123","email":"john.doe@example.com","picture":"https://example.com/profile.jpg","name":"John Doe","mobilePhone":"+1234567890","billingAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"deliveryAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"createdAt":"2023-01-01T12:00:00Z","updatedAt":"2023-03-15T09:30:00Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"patch":{"tags":["Users"],"summary":"Update a user","description":"Updates a specific user's profile with the provided data.","security":[{"OpenID":["users:write"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","nullable":true,"description":"First name of the user","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the user","example":"Doe"},"nickname":{"type":"string","nullable":true,"description":"Nickname of the user","example":"Johnny"},"mobilePhone":{"type":"string","nullable":true,"description":"Mobile phone number","example":"+1234567890"},"workPhone":{"type":"string","nullable":true,"description":"Work phone number","example":"+1234567891"},"homePhone":{"type":"string","nullable":true,"description":"Home phone number","example":"+1234567892"},"billingAddress":{"type":"object","nullable":true,"properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string","minLength":1,"description":"City. Required when setting an address.","example":"Stockholm"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}},"required":["city"],"description":"Billing address information"},"deliveryAddress":{"type":"object","nullable":true,"properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string","minLength":1,"description":"City. Required when setting an address.","example":"Stockholm"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}},"required":["city"],"description":"Delivery address information"},"user_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true},{"nullable":true}]},"description":"User metadata key-value pairs. Set a value to null to delete that key."},"companyInfo":{"allOf":[{"$ref":"#/components/schemas/CompanyInfo"},{"nullable":true,"description":"Company / business details for invoicing"}]},"given_name":{"type":"string","description":"Deprecated: Use firstName instead","deprecated":true},"family_name":{"type":"string","description":"Deprecated: Use lastName instead","deprecated":true},"phone_number":{"type":"string","nullable":true,"description":"Deprecated: Use mobilePhone instead","deprecated":true}}},"example":{"firstName":"Jane","lastName":"Smith","nickname":"Janie","mobilePhone":"+9876543210","billingAddress":{"country":"NO","zip":"0150","city":"Oslo","street":"New Street 456"}}}}},"responses":{"200":{"description":"The updated user profile","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"},"example":{"userId":"user123","email":"john.doe@example.com","picture":"https://example.com/profile.jpg","name":"John Doe","mobilePhone":"+1234567890","billingAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"deliveryAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"createdAt":"2023-01-01T12:00:00Z","updatedAt":"2023-03-15T09:30:00Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["Users"],"summary":"Delete a user","description":"Deletes a user from the auth server. This action is irreversible. Set allowPurchases=true to allow one-off purchase entitlements. Active subscription entitlements and active, overdue or forthcoming contracts always block deletion.","security":[{"OpenID":["users:write"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Allow deletion with one-off purchases. Does not bypass subscription checks.","example":"false"},"required":false,"name":"allowPurchases","in":"query"}],"responses":{"200":{"description":"User deleted successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"example":{"success":true}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - User has blocking entitlements or an active subscription","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Cannot delete user with active entitlements"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users/{user_id}/change-login-identifier":{"post":{"tags":["Users"],"summary":"Change user login identifier","description":"Changes the email address that a user uses to log in.","security":[{"OpenID":["users:write"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The new email address to use for login","example":"new.email@example.com"}},"required":["email"]},"example":{"email":"new.email@example.com"}}}},"responses":{"200":{"description":"Login identifier changed successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"example":{"success":true}}}},"400":{"description":"Bad request - Email already in use or invalid format","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Email address is already in use"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users/{user_id}/add-phone-identifier":{"post":{"tags":["Users"],"summary":"Add phone login identifier","description":"Creates a new SMS user in Auth0 and links it as an additional login identity to the existing user.","security":[{"OpenID":["users:write"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"The phone number to add as a login identifier (E.164 format)","example":"+46701234567"}},"required":["phoneNumber"]},"example":{"phoneNumber":"+46701234567"}}}},"responses":{"200":{"description":"Phone identifier added successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"example":{"success":true}}}},"400":{"description":"Bad request - Phone number already in use","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Phone number is already in use"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users/{user_id}/user_metadata/{key}":{"put":{"tags":["Users"],"summary":"Set user metadata value","description":"Sets a metadata value for a specific user with the specified key.","security":[{"OpenID":["users:write"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"},{"schema":{"type":"string","example":"preferences"},"required":true,"description":"The key of the metadata entry","name":"key","in":"path"}],"requestBody":{"content":{"text/plain":{"schema":{"$ref":"#/components/schemas/UserMetadata"},"example":"premium-user"}}},"responses":{"200":{"description":"Metadata value set successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"example":{"success":true}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["Users"],"summary":"Delete user metadata value","description":"Deletes a metadata value for a specific user with the specified key.","security":[{"OpenID":["users:write"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"},{"schema":{"type":"string","example":"preferences"},"required":true,"description":"The key of the metadata entry","name":"key","in":"path"}],"responses":{"200":{"description":"Metadata value deleted successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"example":{"success":true}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/users/{user_id}/set-password":{"post":{"tags":["Users"],"summary":"Set user password","description":"Sets or updates the password for a user. Creates a password authentication method if one does not exist.","security":[{"OpenID":["users:write"]}],"parameters":[{"schema":{"type":"string","example":"user123"},"required":true,"description":"The unique identifier of the user","name":"user_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string","minLength":6,"description":"The new password for the user","example":"SecurePassword123!"}},"required":["password"]},"example":{"password":"SecurePassword123!"}}}},"responses":{"200":{"description":"Password set successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"example":{"success":true}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - The email address belongs to another account","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Email address belongs to another user"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/team":{"get":{"tags":["Team"],"summary":"List team members","description":"Returns the list of users with portal access for the current vendor.","security":[{"OpenID":["team:read","profile:permissions:write","profile:permissions:portalread"]}],"responses":{"200":{"description":"A list of team members","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}},"example":[{"userId":"auth0|61715b8ebe82f0006ab0613b","email":"user@example.com","roles":["PortalFullAccess"]}]}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Team"],"summary":"Invite a team member","description":"Adds a new team member identified by email and assigns one or more portal roles.","security":[{"OpenID":["team:write","profile:permissions:write","profile:permissions:portalwrite"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user to add to the team","example":"user@example.com"},"roles":{"type":"array","items":{"type":"string","enum":["PortalAdmin","PortalFullAccess","PortalDeveloper"]},"minItems":1,"description":"Portal roles to assign","example":["PortalFullAccess"]}},"required":["email","roles"]},"example":{"email":"user@example.com","roles":["PortalFullAccess"]}}}},"responses":{"201":{"description":"Team member added successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamMember"},"example":{"userId":"auth0|61715b8ebe82f0006ab0613b","email":"user@example.com","roles":["PortalFullAccess"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/team/{userId}":{"put":{"tags":["Team"],"summary":"Set team member roles","description":"Replaces the portal roles for a team member. Only portal-managed roles are affected; other roles on the user are left untouched. Pass an empty array to remove all portal roles.","security":[{"OpenID":["team:write","profile:permissions:write","profile:permissions:portalwrite"]}],"parameters":[{"schema":{"type":"string","example":"auth0|61715b8ebe82f0006ab0613b"},"required":true,"name":"userId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"roles":{"type":"array","items":{"type":"string","enum":["PortalAdmin","PortalFullAccess","PortalDeveloper"]},"description":"Portal roles the member should have. Replaces the current set.","example":["PortalFullAccess"]}},"required":["roles"]},"example":{"roles":["PortalFullAccess"]}}}},"responses":{"200":{"description":"Roles updated successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamMember"},"example":{"userId":"auth0|61715b8ebe82f0006ab0613b","email":"user@example.com","roles":["PortalFullAccess"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["Team"],"summary":"Remove a team member","description":"Removes all portal-managed role assignments for a user. Other roles on the user are left untouched.","security":[{"OpenID":["team:write","profile:permissions:write","profile:permissions:portalwrite"]}],"parameters":[{"schema":{"type":"string","example":"auth0|61715b8ebe82f0006ab0613b"},"required":true,"name":"userId","in":"path"}],"responses":{"204":{"description":"Team member removed","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/api-keys":{"get":{"tags":["API Keys"],"summary":"List API keys","description":"Returns the vendor's machine-to-machine API keys, newest first. Secrets are never included — a secret is readable only in the response that created it.","security":[{"OpenID":["api-keys:read","profile:permissions:write","profile:permissions:portalread"]}],"responses":{"200":{"description":"The vendor's API keys","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"example":[{"clientId":"apikey_9f2c1d8e4b7a4f1e9c3d5a6b7c8d9e0f","name":"Newsroom CMS","role":"read","scopes":["access-lists:read","bills:read","checkouts:read","contracts:read","domains:read","entitlements:read","products:read","sites:read","stats:views:read","transactions:read","users:read"],"createdAt":"2026-09-01T09:12:44.000Z"}]}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["API Keys"],"summary":"Create an API key","description":"Creates a machine-to-machine key and returns its secret. This is the only response that ever carries the secret. Use the returned `clientId`, `clientSecret`, `tokenUrl` and `audience` in an OAuth 2.0 client-credentials exchange to mint Management API tokens.","security":[{"OpenID":["api-keys:write","profile:permissions:write","profile:permissions:portalwrite"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":140,"description":"What this key is for. Shown in the key list; the only way to tell keys apart.","example":"Newsroom CMS"},"role":{"type":"string","enum":["read","full"],"default":"read","description":"Which preset of Management API scopes the key carries. `read` grants every read scope; `full` adds the write scopes. Neither preset can manage team members, portal permissions or other API keys — those stay human-only actions, so a leaked key cannot be used to keep access after it is revoked.","example":"read"}},"required":["name"]},"example":{"name":"Newsroom CMS","role":"read"}}}},"responses":{"201":{"description":"Key created — the secret is in this response and nowhere else","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedApiKey"},"example":{"clientId":"apikey_9f2c1d8e4b7a4f1e9c3d5a6b7c8d9e0f","name":"Newsroom CMS","role":"read","scopes":["access-lists:read","bills:read","checkouts:read","contracts:read","domains:read","entitlements:read","products:read","sites:read","stats:views:read","transactions:read","users:read"],"createdAt":"2026-09-01T09:12:44.000Z","clientSecret":"k2Jd8sV1pQ7wE4rT6yU9iO0aS3dF5gH8","tokenUrl":"https://acme.token.sesamy.com/oauth/token","audience":"urn:sesamy"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/api-keys/{clientId}":{"delete":{"tags":["API Keys"],"summary":"Revoke an API key","description":"Revokes the key immediately and irreversibly. Tokens already minted with it keep working until they expire — the key can mint no new ones. Only API keys can be deleted here; a client id belonging to a site is reported as not found.","security":[{"OpenID":["api-keys:write","profile:permissions:write","profile:permissions:portalwrite"]}],"parameters":[{"schema":{"type":"string","example":"apikey_9f2c1d8e4b7a4f1e9c3d5a6b7c8d9e0f"},"required":true,"name":"clientId","in":"path"}],"responses":{"204":{"description":"Key revoked","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/mc/customers/{customerId}":{"get":{"tags":["Compatibility"],"summary":"Get customer information","description":"Returns customer information in XML format for Mediaconnect compatibility.","security":[{"OpenID":["user:read","users:read"],"Basic":["user:read","users:read"]}],"parameters":[{"schema":{"type":"string","example":"958280"},"required":true,"description":"The unique identifier of the customer","name":"customerId","in":"path"}],"responses":{"200":{"description":"Customer information in XML format","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/xml":{"schema":{"type":"string","description":"Customer information in XML format","example":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<customer>\n  <customerNumber>958280</customerNumber>\n  <firstName>TEST</firstName>\n  <middleName>TEST</middleName>\n  <lastName>TEST</lastName>\n  <street>GRUBBEGATA</street>\n  <streetNumber>4</streetNumber>\n  <postalCode>0871</postalCode>\n  <postalPlace>OSLO</postalPlace>\n  <postalAddressPostalCode>0871</postalAddressPostalCode>\n  <postalAddressPostalPlace>OSLO</postalAddressPostalPlace>\n  <countryCode>NO</countryCode>\n  <phoneNumbers>\n    <phoneNumber type=\"private\">+4794326445</phoneNumber>\n  </phoneNumbers>\n  <recurringProducts>\n    <recurringProduct>\n      <productCode>KONDIS</productCode>\n      <status>passive</status>\n    </recurringProduct>\n  </recurringProducts>\n</customer>"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/entitlements":{"get":{"tags":["Entitlements"],"security":[{"OpenID":["entitlements:read"]}],"parameters":[{"schema":{"type":"string","description":"Search query for entitlements","example":"premium article"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","description":"Maximum number of results to return","example":"20"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor for fetching next page","example":"cursor123"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","description":"Filter entitlements by user ID","example":"user123"},"required":true,"name":"userId","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/EntitlementType"},{"description":"Filter by entitlement type","example":"article"}]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","description":"Filter by product SKU","example":"premium-article-123"},"required":false,"name":"sku","in":"query"}],"responses":{"200":{"description":"List of entitlements","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/checkouts/{id}":{"get":{"tags":["Checkouts"],"summary":"Get a checkout by id","description":"Fetches a single checkout belonging to the caller's vendor. Primarily used to hydrate a `checkout.1#confirm` webhook event, which carries only a `checkoutId`.","security":[{"OpenID":["checkouts:read"]}],"parameters":[{"schema":{"type":"string","example":"checkout123"},"required":true,"description":"The unique identifier of the checkout","name":"id","in":"path"}],"responses":{"200":{"description":"The checkout","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"Bad Request - the vendor could not be resolved","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Vendor-Id is required"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - no such checkout, or it belongs to another vendor","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/discounts":{"get":{"tags":["Discounts"],"summary":"List discounts","security":[{"OpenID":["discounts:read"]}],"parameters":[{"schema":{"$ref":"#/components/schemas/DiscountStatus"},"required":false,"name":"status","in":"query"},{"schema":{"$ref":"#/components/schemas/DiscountType"},"required":false,"name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of items read for a page","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The `nextCursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"The discounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountList"},"example":{"items":[{"id":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11","type":"percentage","status":"ACTIVE","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1},"usageCount":42,"createdAt":"2026-09-28T09:00:00.000Z"}],"nextCursor":null}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Discounts"],"summary":"Create a discount","description":"Creates a discount as a `DRAFT`. It applies to nothing until it is activated with `POST /management/discounts/{id}/activate`. `parameters` and `conditions` depend on `type`. Creating is not idempotent: a repeated request creates a second discount.","security":[{"OpenID":["discounts:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDiscountBody"},"example":{"type":"percentage","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1}}}}},"responses":{"201":{"description":"The created discount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"},"example":{"id":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11","type":"percentage","status":"DRAFT","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1},"usageCount":0,"createdAt":"2026-09-28T09:00:00.000Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/discounts/{id}":{"get":{"tags":["Discounts"],"summary":"Get a discount","security":[{"OpenID":["discounts:read"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The discount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"},"example":{"id":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11","type":"percentage","status":"ACTIVE","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1},"usageCount":42,"createdAt":"2026-09-28T09:00:00.000Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"patch":{"tags":["Discounts"],"summary":"Update a discount","description":"Changes the fields sent and leaves the rest. `parameters` and `conditions` are replaced whole when sent. Only `DRAFT` and `PAUSED` discounts can be edited: pause an active discount first. The type cannot be changed.","security":[{"OpenID":["discounts:write"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDiscountBody"},"example":{"endDate":"2027-01-31T23:59:59Z"}}}},"responses":{"200":{"description":"The updated discount","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"},"example":{"id":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11","type":"percentage","status":"ACTIVE","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1},"usageCount":42,"createdAt":"2026-09-28T09:00:00.000Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - The discount is not in a status that can be edited","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Only DRAFT and PAUSED discounts can be edited. This one is ACTIVE"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/discounts/{id}/activate":{"post":{"tags":["Discounts"],"summary":"Activate a discount","description":"Schedules a `DRAFT` or `PAUSED` discount. It becomes `PENDING`, and `ACTIVE` once its start date is reached. Activating an already `PENDING` or `ACTIVE` discount returns it unchanged.","security":[{"OpenID":["discounts:write"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The discount with its new status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"},"example":{"id":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11","type":"percentage","status":"ACTIVE","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1},"usageCount":42,"createdAt":"2026-09-28T09:00:00.000Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - The discount is in a status this action does not apply to","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Cannot activate a discount that is EXPIRED"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/discounts/{id}/pause":{"post":{"tags":["Discounts"],"summary":"Pause a discount","description":"Stops a `PENDING` or `ACTIVE` discount from applying to new purchases until it is activated again. A paused discount can be edited. Subscriptions that already have it keep it.","security":[{"OpenID":["discounts:write"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The discount with its new status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"},"example":{"id":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11","type":"percentage","status":"ACTIVE","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1},"usageCount":42,"createdAt":"2026-09-28T09:00:00.000Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - The discount is in a status this action does not apply to","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Cannot pause a discount that is EXPIRED"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/discounts/{id}/cancel":{"post":{"tags":["Discounts"],"summary":"Cancel a discount","description":"Retires a `DRAFT` or `PAUSED` discount for good. Pause an active discount first. Subscriptions that already have it keep it.","security":[{"OpenID":["discounts:write"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The discount with its new status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"},"example":{"id":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11","type":"percentage","status":"ACTIVE","name":"Welcome offer","code":"WELCOME20","startDate":"2026-10-01T00:00:00Z","endDate":"2026-12-31T23:59:59Z","parameters":{"percentage":20,"numberOfMonths":3,"allowSKUs":["sid:acme-plus-monthly"]},"conditions":{"totalTimesApplicablePerUser":1},"usageCount":42,"createdAt":"2026-09-28T09:00:00.000Z"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"409":{"description":"Conflict - The discount is in a status this action does not apply to","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Cannot cancel a discount that is EXPIRED"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/discounts/{id}/codes":{"get":{"tags":["Discounts"],"summary":"List one-time codes","description":"Lists the single-use codes generated for a discount.","security":[{"OpenID":["discounts:read"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of items read for a page","example":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"The `nextCursor` of the previous page"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"The codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneTimeCodeList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Discounts"],"summary":"Generate one-time codes","description":"Generates single-use codes that each apply the discount once. Not idempotent: a repeated request generates another batch.","security":[{"OpenID":["discounts:write"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOneTimeCodesBody"}}}},"responses":{"201":{"description":"The generated codes","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OneTimeCode"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["Discounts"],"summary":"Cancel one-time codes","description":"Cancels every code of the discount that has not been redeemed. Redeemed codes are kept.","security":[{"OpenID":["discounts:write"]}],"parameters":[{"schema":{"type":"string","example":"6f1c1f0e-2b8e-4f8a-9d9c-2f7c1b1e0a11"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"The unredeemed codes were canceled"},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/paywalls":{"get":{"tags":["Paywalls"],"summary":"List paywalls","description":"Lists all paywalls configured for the authenticated vendor.","security":[{"OpenID":[]}],"responses":{"200":{"description":"The list of paywalls for the vendor","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaywallAdmin"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/paywalls/{paywallId}":{"get":{"tags":["Paywalls"],"summary":"Get paywall by ID","description":"Retrieves the paywall configuration and settings for the specified paywall ID. This resolves the rendered paywall, so — unlike the list route — the response does not carry the admin-only `name`, `status`, `entity`, `createdAt`, `modifiedAt` or `previewUrl` fields.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Unique identifier of the paywall","example":"pw123456"},"required":true,"name":"paywallId","in":"path"}],"responses":{"200":{"description":"The paywall information and configuration","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Paywall"},"example":{"currency":"USD","settings":{"useDefaultLogo":true,"useDefaultCurrency":true,"useDefaultColor":true},"subscriptions":[{"discountCode":"","price":9.99,"periodText":"Monthly","description":"Monthly access","tag":"","id":"sub123","sku":"premium-monthly","title":"Premium Monthly","poId":"po123","selected":true}],"showLoginButton":true,"vendorId":"vendor123","features":["Feature 1","Feature 2"],"mainColor":"#FF0000","headline":"Premium Content Access","singlePurchase":{"description":"One-time purchase","title":"Buy Now","discountCode":"","enabled":true},"footerPaymentMethods":["visa","mastercard"],"version":1,"logoUrl":"https://example.com/logo.png"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/access-lists":{"get":{"tags":["Access-Lists"],"security":[{"OpenID":["access-lists:read"]}],"responses":{"200":{"description":"Retrieve a list of access lists","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AccessList"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Access-Lists"],"security":[{"OpenID":["access-lists:write"]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccessList"}}}},"responses":{"201":{"description":"Access list created successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/access-lists/{id}":{"get":{"tags":["Access-Lists"],"security":[{"OpenID":["access-lists:read"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve an access list by ID","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"put":{"tags":["Access-Lists"],"security":[{"OpenID":["access-lists:write"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccessList"}}}},"responses":{"200":{"description":"Access list updated successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"patch":{"tags":["Access-Lists"],"security":[{"OpenID":["access-lists:write"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccessList"}}}},"responses":{"200":{"description":"Access list patched successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/access-lists/{id}/grants":{"get":{"tags":["Grants"],"security":[{"OpenID":["access-lists:read"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve a list of grants for an access list","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Grant"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Grants"],"security":[{"OpenID":["access-lists:write"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGrant"}}}},"responses":{"201":{"description":"Grant created successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/access-lists/{id}/grants/{grantId}":{"get":{"tags":["Grants"],"security":[{"OpenID":["access-lists:read"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Grant (purchase) ID","example":"purchase_123abc"},"required":true,"name":"grantId","in":"path"}],"responses":{"200":{"description":"Retrieve a grant by ID","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"put":{"tags":["Grants"],"security":[{"OpenID":["access-lists:write"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Grant (purchase) ID","example":"purchase_123abc"},"required":true,"name":"grantId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGrant"}}}},"responses":{"200":{"description":"Grant updated successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Grant"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["Grants"],"security":[{"OpenID":["access-lists:write"]}],"parameters":[{"schema":{"type":"string","description":"Access list ID","example":"src_123abc"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Grant (purchase) ID","example":"purchase_123abc"},"required":true,"name":"grantId","in":"path"}],"responses":{"204":{"description":"Grant deleted successfully"},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/sites":{"get":{"tags":["Sites"],"summary":"List all sites for the calling vendor","description":"Returns every site with per-capability status. Each upstream is read once per vendor, so a vendor with 200 sites costs the same round-trips as one with a single site. A failing upstream degrades only its own capability to `failed` rather than failing the whole response.","security":[{"OpenID":["sites:read"]}],"responses":{"200":{"description":"All sites registered under this vendor","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","example":"alingsasnytt.se"},"clientId":{"type":"string","example":"alingsasnytt"},"loginDomain":{"type":"string","example":"login.alingsasnytt.se"},"template":{"type":"string"},"sesamyJsVersion":{"type":"string","nullable":true},"sesamyComponentsVersion":{"type":"string","nullable":true},"capabilities":{"type":"object","properties":{"scraper":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"active":{"type":"boolean"},"brand":{"type":"string"},"error":{"type":"string"}},"required":["status"]},"client":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"error":{"type":"string"}},"required":["status"]},"auth":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"customDomain":{"type":"string"},"error":{"type":"string"}},"required":["status"]},"capsule":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"error":{"type":"string"}},"required":["status"]}},"required":["scraper","client","auth","capsule"]},"observedAt":{"type":"string","description":"When this snapshot was read. Capability status is computed per request, not stored, so it reflects the upstreams as of this moment rather than a single transactional instant."}},"required":["domain","capabilities","observedAt"]}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/sites/{domain}":{"get":{"tags":["Sites"],"summary":"Get a single site","security":[{"OpenID":["sites:read"]}],"parameters":[{"schema":{"type":"string","example":"alingsasnytt.se"},"required":true,"name":"domain","in":"path"}],"responses":{"200":{"description":"The site, with resolved content selectors and capsule config","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","example":"alingsasnytt.se"},"clientId":{"type":"string","example":"alingsasnytt"},"loginDomain":{"type":"string","example":"login.alingsasnytt.se"},"template":{"type":"string"},"sesamyJsVersion":{"type":"string","nullable":true},"sesamyComponentsVersion":{"type":"string","nullable":true},"capabilities":{"type":"object","properties":{"scraper":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"active":{"type":"boolean"},"brand":{"type":"string"},"error":{"type":"string"}},"required":["status"]},"client":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"error":{"type":"string"}},"required":["status"]},"auth":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"customDomain":{"type":"string"},"error":{"type":"string"}},"required":["status"]},"capsule":{"type":"object","properties":{"status":{"type":"string","enum":["ok","pending","failed","not_configured"]},"error":{"type":"string"}},"required":["status"]}},"required":["scraper","client","auth","capsule"]},"observedAt":{"type":"string","description":"When this snapshot was read. Capability status is computed per request, not stored, so it reflects the upstreams as of this moment rather than a single transactional instant."},"content":{"type":"array","items":{"nullable":true}},"jwksUri":{"type":"string"},"signingKeyPem":{"type":"string"}},"required":["domain","capabilities","observedAt"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"put":{"tags":["Sites"],"summary":"Provision or update a site","description":"Every block is optional and provisioning is strictly opt-in per capability — omitted blocks are left untouched. Legs run least-live-first (client → content → login domain → scrape origin) and each is attempted independently, so one failure does not abandon the rest. Returns 207 when some legs succeeded and others failed; retry should target only the failed ones.","security":[{"OpenID":["sites:write"]}],"parameters":[{"schema":{"type":"string","example":"alingsasnytt.se"},"required":true,"name":"domain","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scraper":{"type":"object","properties":{"brand":{"type":"string"},"requestHeaders":{"type":"object","additionalProperties":{"type":"string"}},"active":{"type":"boolean","description":"Set false to take the domain out of service. Prefer this over deletion."}}},"auth":{"type":"object","properties":{"customDomain":{"type":"string","description":"Full login hostname. Conventionally login.{domain} but never inferred — pass it explicitly.","example":"login.alingsasnytt.se"}},"required":["customDomain"]},"content":{"type":"object","properties":{"clientId":{"type":"string"},"template":{"type":"string","enum":["wordpress","labrador"]},"overrides":{"type":"object","properties":{"selectors":{"type":"object","additionalProperties":{"type":"object","properties":{"selector":{"type":"string"},"attribute":{"type":"string"}},"required":["selector"]}}}}}}}}}}},"responses":{"200":{"description":"All requested capabilities provisioned","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"outcome":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","failed"]},"error":{"type":"string"}},"required":["status"]}}},"required":["domain","outcome"]}}}},"207":{"description":"Partial success — see per-capability outcome","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"outcome":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","failed"]},"error":{"type":"string"}},"required":["status"]}}},"required":["domain","outcome"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"502":{"description":"Every requested capability failed — see per-capability outcome","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"outcome":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","failed"]},"error":{"type":"string"}},"required":["status"]}}},"required":["domain","outcome"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["Sites"],"summary":"Delete a site","description":"Removes the site from every upstream it was provisioned into. Destructive and not reversible: the AuthHero client is deleted, so re-provisioning mints a new client_id and every end-user session and the installed snippet break with it. Prefer PUT with `scraper.active: false` to take a domain out of service. Legs run most-live-first (scrape origin -> capsule -> login domain -> content config -> client) and each is attempted independently, so a teardown that stops halfway leaves the site inert rather than scraped with a dead client. Only legs with something to remove are reported. The request carries no body, so a retry re-runs every applicable leg rather than a chosen subset; legs whose upstream resource is already absent report ok, so a retry after a partial teardown converges. Returns 207 when some legs failed and 502 when all did.","security":[{"OpenID":["sites:write"]}],"parameters":[{"schema":{"type":"string","example":"alingsasnytt.se"},"required":true,"name":"domain","in":"path"}],"responses":{"200":{"description":"Every leg torn down","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"outcome":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","failed"]},"error":{"type":"string"}},"required":["status"]}}},"required":["domain","outcome"]}}}},"207":{"description":"Partial teardown - see per-leg outcome","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"outcome":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","failed"]},"error":{"type":"string"}},"required":["status"]}}},"required":["domain","outcome"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"502":{"description":"Every leg failed - see per-leg outcome","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"outcome":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["ok","failed"]},"error":{"type":"string"}},"required":["status"]}}},"required":["domain","outcome"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/diagnostics/{identifier}":{"get":{"tags":["diagnostics"],"summary":"Get user diagnostics","description":"Retrieve diagnostics entries for a user by their user ID or fallback ID. Returns the most recent entries.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"The user ID or fallback ID to fetch diagnostics for","example":"user_123"},"required":true,"name":"identifier","in":"path"},{"schema":{"type":"string","description":"Maximum number of entries to return (default: 10)","example":"10"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of diagnostics entries","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","description":"The authenticated user ID (sub)"},"fallbackId":{"type":"string","description":"A fallback identifier for unauthenticated users"},"timestamp":{"type":"string","description":"ISO 8601 timestamp when diagnostics were collected"},"pageUrl":{"type":"string","description":"The page URL where diagnostics were collected"},"pageTitle":{"type":"string","description":"The page title where diagnostics were collected"},"profile":{"type":"object","additionalProperties":{"nullable":true},"description":"User profile data"},"entitlements":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"User entitlements"},"contracts":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"User contracts"},"tags":{"type":"array","items":{"type":"string"},"description":"User tags"},"tallies":{"type":"object","additionalProperties":{"nullable":true},"description":"User tallies"},"browser":{"type":"object","properties":{"userAgent":{"type":"string"},"platform":{"type":"string"},"language":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"cookiesEnabled":{"type":"boolean"},"onLine":{"type":"boolean"},"hardwareConcurrency":{"type":"number"},"deviceMemory":{"type":"number"},"maxTouchPoints":{"type":"number"},"vendor":{"type":"string"},"viewportWidth":{"type":"number"},"viewportHeight":{"type":"number"},"screenWidth":{"type":"number"},"screenHeight":{"type":"number"},"pixelRatio":{"type":"number"},"colorDepth":{"type":"number"},"timezone":{"type":"string"},"timezoneOffset":{"type":"number"}},"description":"Browser and device information"},"detection":{"type":"object","properties":{"adBlockEnabled":{"type":"boolean"},"incognitoMode":{"type":"boolean"},"inAppBrowser":{"type":"boolean"}},"description":"Detection results (adblock, incognito, etc.)"},"localStorage":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"redacted":{"type":"boolean"}},"required":["key","value"]},"description":"Sesamy-related localStorage entries"},"sessionStorage":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"redacted":{"type":"boolean"}},"required":["key","value"]},"description":"Sesamy-related sessionStorage entries"},"sdkVersion":{"type":"string","description":"Sesamy-js SDK version"},"clientId":{"type":"string","description":"The client ID / vendor ID"},"errors":{"type":"array","items":{"type":"string"},"description":"Errors encountered during diagnostics collection"},"storedAt":{"type":"string","description":"ISO 8601 timestamp when diagnostics were stored"},"requestId":{"type":"string","description":"Request ID for tracking"}},"required":["timestamp","storedAt"]}},"count":{"type":"number"}},"required":["items","count"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["diagnostics"],"summary":"Delete user diagnostics","description":"Delete all diagnostics entries for a user by their user ID or fallback ID.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"The user ID or fallback ID to delete diagnostics for","example":"user_123"},"required":true,"name":"identifier","in":"path"}],"responses":{"200":{"description":"Diagnostics deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"deletedCount":{"type":"number"}},"required":["success","deletedCount"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/stats/series/{metric}":{"get":{"tags":["Stats"],"summary":"Get a metric over time","description":"Returns one metric for the vendor across a date range: a headline figure plus a per-product daily series. Monetary values are in major units (e.g. kronor) with the currency named in `currency`.","security":[{"OpenID":["stats:views:read"]}],"parameters":[{"schema":{"type":"string","enum":["currentMrr","newMrr","churnMrr","projectedMrr","totalRevenue","totalSales","subscriptionSales","totalSubscribers"],"description":"Which metric to return. One of: currentMrr, newMrr, churnMrr, projectedMrr, totalRevenue, totalSales, subscriptionSales, totalSubscribers.","example":"currentMrr"},"required":true,"name":"metric","in":"path"},{"schema":{"type":"string","format":"date","description":"Start of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","example":"2026-01-01"},"required":true,"name":"fromDate","in":"query"},{"schema":{"type":"string","format":"date","description":"End of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","example":"2026-03-31"},"required":true,"name":"toDate","in":"query"}],"responses":{"200":{"description":"The metric over the requested range","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsMetricSeries"},"example":{"vendorId":"acme","metric":"currentMrr","dateRange":{"fromDate":"2026-01-01","toDate":"2026-01-02"},"title":"Current MRR","description":"Monthly recurring revenue as of each day in the range, split per product.","unit":"currency","currency":"SEK","headline":145680.35,"series":[{"key":"ACME Plus","points":[{"date":"2026-01-01","value":81945.27},{"date":"2026-01-02","value":82023.81}]}]}}}},"400":{"description":"Bad Request - invalid path or query parameters (unknown metric or dimension, non-ISO date, or fromDate after toDate) or a missing vendor","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"fromDate must be on or before toDate"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/stats/breakdown/{dimension}":{"get":{"tags":["Stats"],"summary":"Get purchases attributed to a tracking dimension","description":"Returns a checkout-attribution table for the vendor, grouped by one tracking dimension (UTM tags, referrer, or the content the visit came from). Each row carries sessions, users, transactions, conversion rate and revenue per currency. Rows whose purchases carried no value for the dimension have a null `key`.","security":[{"OpenID":["stats:views:read"]}],"parameters":[{"schema":{"type":"string","enum":["utm_source","utm_medium","utm_campaign","utm_content","utm_source_medium","referrer","item_source","section","tag","author"],"description":"Attribution dimension to group by. One of: utm_source, utm_medium, utm_campaign, utm_content, utm_source_medium, referrer, item_source, section, tag, author.","example":"utm_source"},"required":true,"name":"dimension","in":"path"},{"schema":{"type":"string","format":"date","description":"Start of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","example":"2026-01-01"},"required":true,"name":"fromDate","in":"query"},{"schema":{"type":"string","format":"date","description":"End of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","example":"2026-03-31"},"required":true,"name":"toDate","in":"query"},{"schema":{"type":"string","enum":["all","subscriptions","single"],"default":"all","description":"Which purchases to report on: `all`, `subscriptions` (recurring only) or `single` (one-off only).","example":"all"},"required":false,"name":"subset","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":1000,"default":100,"description":"Maximum rows to return, highest revenue first. Defaults to 100, maximum 1000. The response flags whether rows were dropped.","example":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"The attribution breakdown for the requested range","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsBreakdown"},"example":{"vendorId":"acme","dimension":"utm_source","subset":"all","dateRange":{"fromDate":"2026-01-01","toDate":"2026-03-31"},"title":"Metrics by UTM source","description":"Groups purchases by the `utm_source` tag on the originating visit.","rows":[{"key":"newsletter","label":"newsletter","sessions":10216,"users":4896,"transactions":2206,"conversionRate":21.59,"revenue":{"SEK":139956,"NOK":198}}],"totals":{"sessions":10216,"users":4896,"transactions":2206,"revenue":{"SEK":139956,"NOK":198}},"rowCount":1,"truncated":false}}}},"400":{"description":"Bad Request - invalid path or query parameters (unknown metric or dimension, non-ISO date, or fromDate after toDate) or a missing vendor","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"fromDate must be on or before toDate"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/stats/catalogue":{"get":{"tags":["Stats"],"summary":"List the available metrics and dimensions","description":"Returns every metric `/series/{metric}` accepts and every dimension `/breakdown/{dimension}` accepts, with a title and description for each. Static — it makes no upstream call — so a client can discover the surface instead of hard-coding it.","security":[{"OpenID":["stats:views:read"]}],"responses":{"200":{"description":"The metrics and dimensions this API exposes","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsCatalogue"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/create-signed-link":{"post":{"tags":["Links"],"summary":"Create a signed link for content access","description":"Creates a signed token that grants access to encrypted content. Optionally appends it to a URL. Use for share links, email campaigns, gift access, or temporary tier access.","security":[{"OpenID":["links:create"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The URL to sign. If provided, token will be appended as query parameter.","example":"https://example.com/article/123"},"sku":{"type":"string","description":"The product SKU that grants access to this content","example":"premium-subscription"},"scopes":{"type":"array","items":{"type":"string","minLength":1},"description":"Unlock scopes the token grants, e.g. the page's `url:<hash>` scope. The `sku`, if given, is always included. A token with scopes unlocks only those scopes; without any, it is bound to the article its url/publisherContentId names.","example":["url:acme-article-hash"]},"purchaseOption":{"type":"string","description":"Optional purchase option variant","example":"monthly"},"publisherContentId":{"type":"string","description":"Publisher's content identifier","example":"article-2024-01-15-news"},"userId":{"type":"string","description":"User/purchaser ID for attribution","example":"user-456"},"maxUses":{"type":"number","description":"Maximum number of uses (undefined = unlimited)","example":1000},"expiresIn":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"Token validity duration (e.g., \"1h\", \"24h\", \"7d\", \"30d\" or seconds)","example":"7d"},"meta":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"description":"Optional custom metadata","example":{"campaign":"twitter","source":"share-button"}}},"required":["expiresIn"]}}}},"responses":{"200":{"description":"The signed link/token","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"signedUrl":{"type":"string","description":"The URL with token appended (only if url was provided in request)"},"token":{"type":"string","description":"The signed token"},"tokenId":{"type":"string","description":"Unique token ID for tracking/revocation"},"expiresAt":{"type":"string","description":"Token expiration time (ISO 8601)"},"sku":{"type":"string","description":"The SKU this token grants access for (if specified)"},"scopes":{"type":"array","items":{"type":"string"},"description":"The unlock scopes this token grants (if any)"},"publisherContentId":{"type":"string","description":"The content ID this token unlocks (if specific content)"}},"required":["token","tokenId","expiresAt"]},"example":{"signedUrl":"https://example.com/article/123?sesamy_token=eyJhbGciOiJFZERTQSJ9...","token":"eyJhbGciOiJFZERTQSJ9...","tokenId":"tok_abc123","expiresAt":"2026-02-20T12:00:00.000Z","sku":"premium-subscription","publisherContentId":"article-2024-01-15-news"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/domains":{"get":{"tags":["Domains"],"summary":"List trusted publisher domains for the calling vendor","security":[{"OpenID":["domains:read"]}],"responses":{"200":{"description":"All trusted publisher domains registered under this vendor","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"signingKeyPem":{"type":"string"},"jwksUri":{"type":"string"},"allowedResourceIds":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"pattern":{"type":"string"}},"required":["pattern"]}]}},"signingKeyKids":{"type":"array","items":{"type":"string"},"description":"kids of the publisher signing keys currently cached for this domain. jwksUri entries only — these are what unlock verification matches against."},"keysRefreshedAt":{"type":"string","description":"When the cached signing keys were last resolved from jwksUri (ISO 8601)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"updatedBy":{"type":"string"}},"required":["domain","createdAt","updatedAt","updatedBy"]}}},"required":["domains"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/domains/{domain}":{"get":{"tags":["Domains"],"summary":"Get a single trusted publisher domain","security":[{"OpenID":["domains:read"]}],"parameters":[{"schema":{"type":"string","example":"example.wordpress.com"},"required":true,"description":"Publisher domain (lowercase, no scheme, no trailing dot)","name":"domain","in":"path"}],"responses":{"200":{"description":"The trusted publisher domain entry","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"signingKeyPem":{"type":"string"},"jwksUri":{"type":"string"},"allowedResourceIds":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"pattern":{"type":"string"}},"required":["pattern"]}]}},"signingKeyKids":{"type":"array","items":{"type":"string"},"description":"kids of the publisher signing keys currently cached for this domain. jwksUri entries only — these are what unlock verification matches against."},"keysRefreshedAt":{"type":"string","description":"When the cached signing keys were last resolved from jwksUri (ISO 8601)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"updatedBy":{"type":"string"}},"required":["domain","createdAt","updatedAt","updatedBy"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"put":{"tags":["Domains"],"summary":"Register or update a trusted publisher domain","description":"Upserts a trusted publisher domain entry under the calling vendor. Provide exactly one of `signingKeyPem` (pinned ES256) or `jwksUri` (HTTPS URL whose hostname matches {domain}). Idempotent: re-registration replaces the entry and advances `updatedAt`.","security":[{"OpenID":["domains:write"]}],"parameters":[{"schema":{"type":"string","example":"example.wordpress.com"},"required":true,"description":"Publisher domain (lowercase, no scheme, no trailing dot)","name":"domain","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signingKeyPem":{"type":"string","description":"Pinned ES256 (P-256) public key in PEM format. Mutually exclusive with jwksUri."},"jwksUri":{"type":"string","format":"uri","description":"HTTPS URL serving the publisher JWKS. Hostname must match {domain}. Mutually exclusive with signingKeyPem."},"allowedResourceIds":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"pattern":{"type":"string"}},"required":["pattern"]}]},"description":"Optional list of resourceIds (or { pattern }) this publisher may sign for. Currently informational; not enforced at unlock time."}}}}}},"responses":{"200":{"description":"Domain updated","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"signingKeyPem":{"type":"string"},"jwksUri":{"type":"string"},"allowedResourceIds":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"pattern":{"type":"string"}},"required":["pattern"]}]}},"signingKeyKids":{"type":"array","items":{"type":"string"},"description":"kids of the publisher signing keys currently cached for this domain. jwksUri entries only — these are what unlock verification matches against."},"keysRefreshedAt":{"type":"string","description":"When the cached signing keys were last resolved from jwksUri (ISO 8601)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"updatedBy":{"type":"string"},"probe":{"type":"object","properties":{"ok":{"type":"boolean"},"activeKeys":{"type":"number"},"error":{"type":"string"}},"required":["ok"]}},"required":["domain","createdAt","updatedAt","updatedBy"]}}}},"201":{"description":"Domain created","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"signingKeyPem":{"type":"string"},"jwksUri":{"type":"string"},"allowedResourceIds":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"pattern":{"type":"string"}},"required":["pattern"]}]}},"signingKeyKids":{"type":"array","items":{"type":"string"},"description":"kids of the publisher signing keys currently cached for this domain. jwksUri entries only — these are what unlock verification matches against."},"keysRefreshedAt":{"type":"string","description":"When the cached signing keys were last resolved from jwksUri (ISO 8601)."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"updatedBy":{"type":"string"},"probe":{"type":"object","properties":{"ok":{"type":"boolean"},"activeKeys":{"type":"number"},"error":{"type":"string"}},"required":["ok"]}},"required":["domain","createdAt","updatedAt","updatedBy"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["Domains"],"summary":"Remove a trusted publisher domain","security":[{"OpenID":["domains:write"]}],"parameters":[{"schema":{"type":"string","example":"example.wordpress.com"},"required":true,"description":"Publisher domain (lowercase, no scheme, no trailing dot)","name":"domain","in":"path"}],"responses":{"204":{"description":"Domain removed (or did not exist)","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Forbidden"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"example":{"message":"Not Found"}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}}}}