{"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"]},"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":{"id":{"type":"string","description":"The contract line. Unique within the contract, even when two lines share a sku; `recurringPrice` entries refer to it as `id`."},"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":["id","sku","name","productType","isMultiseat","quantity"]}},"status":{"type":"string"},"isActive":{"type":"boolean"},"recurringInterval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"recurringTime":{"type":"number"},"recurringPrice":{"type":"array","items":{"$ref":"#/components/schemas/ContractPrice"},"description":"The price schedule, ordered by `from`: for example a discounted introductory period followed by the full price. Empty for contracts that do not recur."},"willCancelAt":{"type":"string","nullable":true},"cancelRequestedAt":{"type":"string","nullable":true},"canceledAt":{"type":"string","nullable":true,"description":"When the contract was actually canceled. Null until it has ended."},"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. Only set for discounts created ad hoc on the contract; unset means it applies from contract start."},"endsAt":{"type":"string","description":"When the discount stops applying. Only set for discounts created ad hoc on the contract. For a discount code the end is recorded on the price instead: read `discount.endsAt` or `recurringPrice`."}},"required":["name","description","id"]}},"discount":{"$ref":"#/components/schemas/ContractDiscount"}},"required":["id","name","userId","createdAt","updatedAt","price","nextBillAt","nextPrice","currency","items","status","isActive","recurringPrice","willCancelAt","cancelRequestedAt","canceledAt","cancelReason","appliedDiscounts","discount"]},"ContractPrice":{"type":"object","properties":{"from":{"type":"string","description":"When this price starts applying."},"to":{"type":"string","nullable":true,"description":"When this price stops applying. Null when it does not end."},"id":{"type":"string","description":"The contract line this price belongs to. Every price of the same line shares it, so it tells the lines of a multi-item contract apart."},"price":{"type":"number","description":"What each bill in this period totals, in `currency`."},"currency":{"type":"string"},"interval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"intervalCount":{"type":"number","description":"Number of intervals between bills. `{ interval: \"MONTH\", intervalCount: 3 }` bills every 3 months."},"discount":{"$ref":"#/components/schemas/ContractPriceDiscount"}},"required":["from","to","price","discount"]},"ContractPriceDiscount":{"type":"object","nullable":true,"properties":{"amount":{"type":"number","nullable":true,"description":"Amount taken off the price, in the contract currency."},"percentage":{"type":"number","nullable":true,"description":"Share taken off the price, as a percentage."},"fullPrice":{"type":"number","nullable":true,"description":"What the price would be without the discount."},"codes":{"type":"array","items":{"$ref":"#/components/schemas/ContractPriceDiscountCode"},"description":"The discount codes that produced this discount. Only recorded for discounts applied through the current discount system, so it is empty for older discounts."}},"required":["amount","percentage","fullPrice","codes"]},"ContractPriceDiscountCode":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"amount":{"type":"number","nullable":true,"description":"Amount this code takes off the price, in the contract currency. Null when the code changes the price in another way, such as a special introductory tranche."}},"required":["code","amount"]},"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"]},"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"]},"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."},"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"]},"ContractPayment":{"type":"object","properties":{"provider":{"type":"string","enum":["BILLOGRAM"]},"method":{"type":"string","enum":["INVOICE"]},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"SE","description":"Country the payment is made from. Decides market and VAT. Defaults to SE."}},"required":["provider","method"]},"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"]},"ManagementAmendment":{"type":"object","properties":{"id":{"type":"string"},"contractId":{"type":"string"},"status":{"type":"string","description":"`PENDING` until confirmed, then `CONFIRMED`, or `SCHEDULED` when it applies later. New values may be added."},"amendmentType":{"type":"string","description":"`DISCOUNT` for a discount code, `ITEMS` for a plan change. New values may be added."},"nextBillAt":{"type":"string","nullable":true,"format":"date-time","description":"When the contract bills next after the amendment. Null when it does not bill again."},"nextPrice":{"type":"number","nullable":true,"description":"What the next bill totals after the amendment, including tax, in major units of `currency`."},"currency":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/AmendmentItem"},"description":"The contract's items after the amendment. Set for plan changes."},"proration":{"$ref":"#/components/schemas/AmendmentProration"},"appliedDiscounts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"status":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true}},"required":["code","status"]}}},"required":["id","contractId","status","amendmentType","nextBillAt","nextPrice","currency","proration","appliedDiscounts"]},"AmendmentItem":{"type":"object","properties":{"id":{"type":"string","description":"The contract item.","example":"item_1"},"sku":{"type":"string","example":"sid:acme-plus-yearly"},"purchaseOptionId":{"type":"string","example":"yearly"}},"required":["id","sku","purchaseOptionId"]},"AmendmentProration":{"type":"object","nullable":true,"properties":{"method":{"type":"string","enum":["IGNORE_CHANGES","POSTPONE","NEXT_PAYMENT","UPFRONT","RESTART_PERIOD"],"description":"How the price difference for the rest of the current period is settled. These are all the methods today, but new ones may be added: for a method you do not know, rely on `amount` and `appliesAt`.\n- `IGNORE_CHANGES`: the plan changes at once and the new price applies from the next bill. Nothing is settled.\n- `POSTPONE`: the plan and price change at the next bill. Nothing changes until then.\n- `NEXT_PAYMENT`: the plan changes at once and `amount` is added to the next bill, as a credit when negative.\n- `UPFRONT`: the plan changes at once and `amount` is charged to the saved payment method on confirm. Upgrades only.\n- `RESTART_PERIOD`: the plan changes at once and a new period starts. `amount` (a full period of the new price, less the unused part of the current one) is charged to the saved payment method on confirm."},"amount":{"type":"number","description":"The price difference settled for the rest of the current period, including tax, in major units of `currency`. Positive is charged, negative is credited. 0 when nothing is settled.","example":41.5},"currency":{"type":"string","example":"SEK"},"appliesAt":{"type":"string","format":"date-time","description":"When the change takes effect.","example":"2026-12-01T00:00:00.000Z"}},"required":["method","amount","currency","appliesAt"],"description":"How the price difference is settled. Set for plan changes, null for other amendments."},"CreateManagementAmendmentRequest":{"type":"object","properties":{"type":{"type":"string","enum":["PLAN_CHANGE"],"description":"The kind of amendment. Only `PLAN_CHANGE` for now; more may be added."},"itemId":{"type":"string","minLength":1,"description":"The contract item to change, from `GET .../upgrade-options`. Only needed when the contract has more than one item.","example":"item_1"},"sku":{"type":"string","minLength":1,"description":"The product to change to, from the `paths` of `GET .../upgrade-options`.","example":"sid:acme-plus-yearly"},"purchaseOptionId":{"type":"string","minLength":1,"description":"The purchase option to change to.","example":"yearly"},"prorationMethod":{"type":"string","enum":["IGNORE_CHANGES","POSTPONE","NEXT_PAYMENT","UPFRONT","RESTART_PERIOD"],"description":"Overrides how the price difference is settled. Defaults to the setting of the upgrade path, then of your account, then `IGNORE_CHANGES`."}},"required":["type","sku","purchaseOptionId"]},"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"]},"ManagementProduct":{"allOf":[{"$ref":"#/components/schemas/Product"},{"type":"object","properties":{"purchaseOptions":{"type":"array","items":{"$ref":"#/components/schemas/ProductPurchaseOption"},"example":[{"id":"acme-monthly","title":"Monthly subscription","purchaseType":"RECURRING","prices":[{"market":"SE","currency":"SEK","amount":149,"amountExcludingTax":140.57,"tax":8.43}],"recurring":{"interval":"MONTH","intervalCount":1},"isForSale":true,"isListed":true}]}},"required":["purchaseOptions"]}]},"ProductPurchaseOption":{"type":"object","properties":{"id":{"type":"string","description":"Use as `purchaseOptionId` in Partner Checkout."},"title":{"type":"string"},"purchaseType":{"type":"string","enum":["LOAN","OWN","FREE","RECURRING","LEASE","SUBSCRIBER","PER_ISSUES"],"description":"How the buyer pays and keeps access. New values may be added."},"prices":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOptionPrice"},"description":"One entry per market."},"recurring":{"$ref":"#/components/schemas/Interval"},"duration":{"allOf":[{"$ref":"#/components/schemas/Interval"},{"description":"How long access lasts. Set on `LEASE` options."}]},"issues":{"type":"integer","description":"Issues delivered per purchase. Set on `PER_ISSUES` options."},"seatsPerUnit":{"type":"integer","description":"Seats granted per billed unit. Set on license products."},"minQuantity":{"type":"integer","description":"Fewest billed units a buyer can purchase."},"maxQuantity":{"type":"integer","description":"Most billed units a buyer can purchase."},"isForSale":{"type":"boolean","description":"False when the vendor has stopped sales of this option. Checkout still checks the product and the buyer’s market, so true does not guarantee a purchase succeeds."},"isListed":{"type":"boolean","description":"False when the option is hidden from listings."}},"required":["id","title","purchaseType","prices","isForSale","isListed"]},"PurchaseOptionPrice":{"type":"object","properties":{"market":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","example":"SE"},"currency":{"type":"string","description":"ISO 4217 currency code.","example":"SEK"},"amount":{"type":"number","description":"Price including tax, in major units of `currency`.","example":149},"amountExcludingTax":{"type":"number","description":"Price excluding tax, in major units of `currency`.","example":140.57},"tax":{"type":"number","description":"Tax included in `amount`, in major units of `currency`.","example":8.43}},"required":["market","currency","amount","amountExcludingTax","tax"]},"Interval":{"type":"object","properties":{"interval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"intervalCount":{"type":"integer","minimum":1,"description":"Number of intervals. `{ interval: \"MONTH\", intervalCount: 3 }` is every 3 months."}},"required":["interval","intervalCount"],"description":"How often the buyer is billed. Set on `RECURRING` options."},"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"]},"UserLogs":{"type":"object","properties":{"logs":{"type":"array","items":{"$ref":"#/components/schemas/UserLog"}},"total":{"type":"integer","minimum":0}},"required":["logs","total"]},"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"]},"UserSessions":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/UserSession"}},"total":{"type":"integer","minimum":0}},"required":["sessions","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"]},"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"]},"CompanyInfo":{"type":"object","properties":{"companyName":{"type":"string"},"vatNr":{"type":"string"},"invoiceEmail":{"type":"string"}}},"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"]}]},"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"]},{"$ref":"#/components/schemas/EntitlementLicenseOrigin"}]},"hasAccess":{"type":"boolean"},"isPaused":{"type":"boolean","description":"Whether the entitlement is currently paused. Paused entitlements grant no access."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","sku","title","type","hasAccess","createdAt","updatedAt"]},"EntitlementType":{"type":"string","enum":["article","audiobook","ebook","bundle","podcast","pass","publication","physical_issue"]},"EntitlementLicenseOrigin":{"type":"object","properties":{"type":{"type":"string","enum":["LICENSE"]},"licenseId":{"type":"string","description":"The Vault license the seat is held on. Omitted for a bundle sub-entitlement"},"contractId":{"type":"string","description":"The multi-seat contract the license belongs to. Use it with GET /management/contracts/{id}/seats/users. Omitted when Vault does not carry it","example":"M-V1StGXR8_Z5jdHi6B-myT"},"role":{"type":"string","enum":["owner","member"],"description":"owner administers the seats, member holds one"}},"required":["type"]},"CheckoutListItem":{"type":"object","properties":{"id":{"type":"string","example":"checkout123"},"status":{"type":"string","enum":["PENDING","WAITING_PAYMENT_CONFIRMATION","COMPLETED","FAILED"]},"type":{"type":"string","example":"RECURRING"},"source":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":"string"},"contractId":{"type":"string","description":"The contract the checkout created, once it has one"},"currency":{"type":"string","example":"SEK"},"country":{"type":"string"},"userId":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"mobilePhone":{"type":"string"},"isBusiness":{"type":"boolean"},"total":{"type":"number","description":"The checkout total in minor units, such as öre or cents","example":14900},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"purchaseOptionId":{"type":"string"},"title":{"type":"string"}},"required":["sku"]}}},"required":["id","status","type","createdAt","updatedAt","currency","items"]},"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"]},"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"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected the paywall the checkout was started from, as returned on the paywall","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected the paywall the checkout was started from, as returned on the paywall","example":"st_abc123"},"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"]},"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"]},"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"]}]},"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},"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},"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"]},"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"]},"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},"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","description":"Paywall template type. Known values: LOGIN for authentication-only, BOXES for subscription options, ARTICLE for single-article purchase. Treat unknown values as unsupported rather than as errors.","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"},"redirectLabel":{"type":"string","description":"Paywall-wide label for the button that takes the visitor back to the publisher, shown on the checkout confirmation page and in the order confirmation email. Used for subscriptions that do not set their own `redirectLabel`.","example":"Go to ACME"},"showPricesExVat":{"type":"boolean","description":"Whether prices are displayed excluding VAT","example":false}}},"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"},"redirectLabel":{"type":"string","description":"Label for the button that takes the visitor back to the publisher after buying this option, shown on the checkout confirmation page and in the order confirmation email. Takes precedence over the paywall-wide `settings.redirectLabel`; when both are omitted the button reads \"Go to {vendor}\".","example":"Start reading ACME Plus"},"discountId":{"type":"string","description":"Identifier of the discount applied to this option","example":"disc_acme_welcome"},"priceMode":{"type":"string","description":"How the prices of this option are determined: `MANUAL` (fixed prices, the default when omitted) or `AUTOMATIC` (resolved dynamically). Kept as a plain string so a value added upstream later does not fail the whole response.","example":"AUTOMATIC"},"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"},"discountId":{"type":"string","description":"Identifier of the discount applied to the single purchase","example":"disc_acme_welcome"}},"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"]},"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"]},"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","description":"Paywall template type. Known values: LOGIN for authentication-only, BOXES for subscription options, ARTICLE for single-article purchase. Treat unknown values as unsupported rather than as errors.","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"},"redirectLabel":{"type":"string","description":"Paywall-wide label for the button that takes the visitor back to the publisher, shown on the checkout confirmation page and in the order confirmation email. Used for subscriptions that do not set their own `redirectLabel`.","example":"Go to ACME"},"showPricesExVat":{"type":"boolean","description":"Whether prices are displayed excluding VAT","example":false}}},"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"},"redirectLabel":{"type":"string","description":"Label for the button that takes the visitor back to the publisher after buying this option, shown on the checkout confirmation page and in the order confirmation email. Takes precedence over the paywall-wide `settings.redirectLabel`; when both are omitted the button reads \"Go to {vendor}\".","example":"Start reading ACME Plus"},"discountId":{"type":"string","description":"Identifier of the discount applied to this option","example":"disc_acme_welcome"},"priceMode":{"type":"string","description":"How the prices of this option are determined: `MANUAL` (fixed prices, the default when omitted) or `AUTOMATIC` (resolved dynamically). Kept as a plain string so a value added upstream later does not fail the whole response.","example":"AUTOMATIC"},"url":{"type":"string","description":"External URL for more information","example":"https://acme.example.com/business"},"pricePeriod":{"type":"object","properties":{"period":{"type":"string","description":"Period unit. Known values: day, week, month, quarter, year.","example":"month"},"time":{"type":"number","description":"Number of period units, an integer of at least 1","example":3}},"required":["period","time"],"description":"Billing period of the recurring `price`","example":{"period":"month","time":1}},"discountPeriod":{"type":"object","properties":{"period":{"type":"string","description":"Period unit. Known values: day, week, month, quarter, year.","example":"month"},"time":{"type":"number","description":"Number of period units, an integer of at least 1","example":3}},"required":["period","time"],"description":"Billing period of the `discountPrice`","example":{"period":"month","time":3}},"discountMonths":{"type":"number","description":"Discount duration in months, when longer than one `discountPeriod`","example":6},"trialDays":{"type":"number","description":"Length of the free trial, in days","example":14}},"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"},"discountId":{"type":"string","description":"Identifier of the discount applied to the single purchase","example":"disc_acme_welcome"}},"required":["enabled"]},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"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}}},"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":["PENDING","ACTIVE","CANCELED","EXPIRED","DELETED"],"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"]},"GrantAddress":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"},"co":{"type":"string"}}},"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":["PENDING","ACTIVE","CANCELED","EXPIRED","DELETED"],"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":["PENDING","ACTIVE","CANCELED","EXPIRED","DELETED"],"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}}},"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"]},"StatsDateRange":{"type":"object","properties":{"fromDate":{"type":"string","example":"2026-01-01"},"toDate":{"type":"string","example":"2026-03-31"}},"required":["fromDate","toDate"]},"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"]},"StatsSeriesPoint":{"type":"object","properties":{"date":{"type":"string","example":"2026-01-01"},"value":{"type":"number","nullable":true}},"required":["date","value"]},"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"]},"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"]},"StatsMoney":{"type":"object","additionalProperties":{"type":"number"},"example":{"SEK":139956,"NOK":198}},"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"]},"ReportTypeList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ReportType"}},"nextCursor":{"type":"string","nullable":true,"description":"Always `null`: every report type is returned at once."}},"required":["items","nextCursor"]},"ReportType":{"type":"object","properties":{"id":{"type":"string","example":"transactions_report"},"name":{"type":"string","example":"Transactions"},"description":{"type":"string"},"category":{"type":"string","nullable":true,"description":"The group the report type is listed under, or `null` when it has none","example":"Finance"},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/ReportParameter"}},"documentation":{"type":"object","nullable":true,"properties":{"businessPurpose":{"type":"string","description":"The questions the report answers"},"grain":{"type":"string","description":"What one row of the file stands for","example":"One active contract at the date"},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name","description"]},"description":"The columns of the file, in order"},"caveats":{"type":"array","items":{"type":"string"}},"exampleQuestions":{"type":"array","items":{"type":"string"}}},"required":["businessPurpose","grain","columns","caveats","exampleQuestions"],"description":"How to read the generated file. Returned by `GET /management/report-types/{id}` only, and `null` for a report type that has none yet."}},"required":["id","name","description","category","parameters"]},"ReportParameter":{"type":"object","properties":{"name":{"type":"string","description":"The key to send the value under in `parameters`","example":"groupBy"},"label":{"type":"string","example":"Group by"},"description":{"type":"string","example":"Summarise the rows instead of listing them one by one."},"type":{"$ref":"#/components/schemas/ReportParameterType"},"isRequired":{"type":"boolean"},"options":{"type":"array","nullable":true,"items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]},"description":"The values the parameter accepts, or `null` when it takes any value of its type. For a `STRING_ARRAY`, every entry must be one of them.","example":[{"value":"none","label":"No grouping"},{"value":"product","label":"Product"}]},"default":{"$ref":"#/components/schemas/ReportParameterValue"}},"required":["name","label","description","type","isRequired","options","default"]},"ReportParameterType":{"type":"string","enum":["STRING","NUMBER","BOOLEAN","DATE","STRING_ARRAY"],"description":"The JSON type a parameter takes: `DATE` is a `YYYY-MM-DD` string and `STRING_ARRAY` an array of strings."},"ReportParameterValue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"nullable":true}],"description":"What the report does when the parameter is left out, for information. `null` when it has no default."},"ReportList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Report"}},"nextCursor":{"type":"string","nullable":true,"description":"Always `null`: every report is returned at once."}},"required":["items","nextCursor"]},"Report":{"type":"object","properties":{"id":{"type":"string","description":"Derived from the report type and parameters, so the same request always names the same report","example":"9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e"},"typeId":{"type":"string","example":"transactions_report"},"name":{"type":"string","example":"Transactions"},"status":{"$ref":"#/components/schemas/ReportStatus"},"parameters":{"$ref":"#/components/schemas/ReportParameters"},"downloadUrl":{"type":"string","nullable":true,"format":"uri","description":"A link to the generated file while `status` is `COMPLETED`, otherwise `null`. It stops working at `downloadUrlExpiresAt`; read the report again for a new one."},"downloadUrlExpiresAt":{"type":"string","nullable":true,"format":"date-time","description":"When `downloadUrl` stops working, or `null` when there is no link"},"createdAt":{"type":"string","format":"date-time","description":"When the report was requested. A failed report run again counts from then."},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","typeId","name","status","parameters","downloadUrl","downloadUrlExpiresAt","createdAt","updatedAt"]},"ReportStatus":{"type":"string","enum":["PENDING","PROCESSING","COMPLETED","FAILED"],"description":"A new report is `PENDING` until a worker picks it up, `PROCESSING` while it runs, and `COMPLETED` once its file can be downloaded. A `FAILED` report is run again when you create it again with the same parameters."},"ReportParameters":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ReportParameterValue"},"description":"Parameter values by the parameter's `name` in the report type. Values are of the parameter's `type`, and one with `options` takes one of their `value`s.","example":{"dateFrom":"2026-01-01","dateTo":"2026-01-31","groupBy":"product"}},"CreateReportRequest":{"type":"object","properties":{"typeId":{"type":"string","minLength":1,"example":"transactions_report"},"parameters":{"$ref":"#/components/schemas/ReportParameters"}},"required":["typeId"]}},"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","pattern":"^[A-Za-z0-9_-]{1,64}$"},"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,"description":"Only bills created at or after this ISO 8601 timestamp","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,"description":"Only bills created at or before this ISO 8601 timestamp","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,"description":"Only bills modified at or after this ISO 8601 timestamp","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,"description":"Only bills modified at or before this ISO 8601 timestamp","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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},"schema":{"$ref":"#/components/schemas/CreateContractRequest"}}}},"responses":{"201":{"description":"The created contract","content":{"application/json":{"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,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","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,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null},"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"message":"Seats can only be set for license products"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","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,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null},"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"message":"Failed to confirm the contract"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The contract is in a status that cannot be confirmed","content":{"application/json":{"example":{"message":"A CANCELED contract cannot be confirmed"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/cancel":{"post":{"tags":["Contracts"],"summary":"Cancel a contract","description":"Cancels a contract on behalf of its customer. By default (`when: \"end\"`) the customer keeps access until the end of the current period and the contract does not renew; `when: \"now\"` cancels at once. Only ACTIVE, OVERDUE and FORTHCOMING contracts can be canceled. An already canceled contract is returned unchanged. Canceling does not refund anything.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"example":{"when":"end","reason":"NOT_USING","comment":"Asked support to cancel"},"schema":{"type":"object","properties":{"when":{"type":"string","enum":["end","now"],"description":"When the cancellation takes effect. `end` (default) is the end of the current period, `now` is immediately."},"reason":{"type":"string","enum":["TOO_EXPENSIVE","NOT_USING","SWITCHED_COMPETITOR","MISSING_FEATURES","TECHNICAL_ISSUES","DUPLICATE","OTHER"],"description":"Why the customer cancels"},"comment":{"type":"string","maxLength":1000,"description":"Free text. Only stored together with `reason`."}}}}}},"responses":{"200":{"description":"The contract after the cancellation","content":{"application/json":{"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,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","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,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The contract is in a status that cannot be canceled","content":{"application/json":{"example":{"message":"A PENDING contract cannot be canceled"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/reactivate":{"post":{"tags":["Contracts"],"summary":"Reactivate a contract","description":"Removes a scheduled cancellation on behalf of the customer, so the contract renews again as before. Only ACTIVE, OVERDUE and CLOSED contracts can be reactivated: a contract that has ended (CANCELED or EXPIRED) has to be bought again. Reactivating a contract that is not set to cancel returns it unchanged.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The contract, no longer set to cancel","content":{"application/json":{"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,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","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,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The contract has ended or is in a status that cannot be reactivated","content":{"application/json":{"example":{"message":"A CANCELED contract cannot be reactivated"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/bills/{billId}/refunds":{"post":{"tags":["Contracts"],"summary":"Refund a bill","description":"Refunds part or all of a paid bill to the original payment method. `amount` is in minor units (öre/cents) and the refund uses the currency of the bill. Does not cancel the contract; use `POST /management/contracts/{id}/cancel` for that. A refund is never retried automatically and there is no idempotency key: if the request times out, check `GET /management/contracts/{id}/bills/{billId}/refunds` before sending it again. Providers without refund support (such as invoices) are refused.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"B-acme-123456"},"required":true,"name":"billId","in":"path"}],"requestBody":{"content":{"application/json":{"example":{"amount":24600,"reason":"Refunded at the customer’s request"},"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Amount to refund in minor units (öre/cents)","example":24600},"reason":{"type":"string","maxLength":500,"description":"Saved with the refund"}},"required":["amount"]}}}},"responses":{"200":{"description":"The refund","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"contractId":{"type":"string"},"status":{"type":"string"},"amount":{"type":"number","description":"Refunded amount in major units"},"currency":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","status","amount"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"get":{"tags":["Contracts"],"summary":"List the refunds of a bill","security":[{"OpenID":["bills:read"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"B-acme-123456"},"required":true,"name":"billId","in":"path"}],"responses":{"200":{"description":"The refunds made on the bill","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"contractId":{"type":"string"},"status":{"type":"string"},"amount":{"type":"number","description":"Refunded amount in major units"},"currency":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","status","amount"]}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"seats":25},"schema":{"$ref":"#/components/schemas/SetContractSeatsBody"}}}},"responses":{"200":{"description":"The contract with its new seats","content":{"application/json":{"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,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","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,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null},"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"message":"Seats are only available for license products"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The contract cannot be changed, or has more users than the requested seats","content":{"application/json":{"example":{"message":"12 seats are in use. Remove users before lowering the seats to 10"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Filter seat users by license item SKU. Omit to list all contract seat users.","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Seats are only available for license products"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"User ID of the seat holder to remove.","name":"userId","in":"path"}],"responses":{"204":{"description":"Seat user removed"},"400":{"description":"Bad Request","content":{"application/json":{"example":{"message":"Seats are only available for license products"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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)"}]}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/UpgradeOption"}}}}},"400":{"description":"Bad Request - The contract cannot be changed (inactive or non-recurring)","content":{"application/json":{"example":{"message":"Cannot upgrade an inactive contract"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/amendments":{"post":{"tags":["Contracts"],"summary":"Create an amendment","description":"Prepares a change to a contract. `PLAN_CHANGE` moves a contract item to another product or purchase option, which must be one of the paths listed by `GET /management/contracts/{id}/upgrade-options`. The amendment is `PENDING` and changes nothing until it is confirmed with `POST /management/contracts/{id}/amendments/{amendmentId}/confirm`, so it doubles as a preview: `nextPrice` and `proration` show what the change costs. Only active recurring contracts that are not set to cancel can change plan. Creating is not idempotent, but an unconfirmed amendment has no effect.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"type":"PLAN_CHANGE","sku":"sid:acme-plus-yearly","purchaseOptionId":"yearly"},"schema":{"$ref":"#/components/schemas/CreateManagementAmendmentRequest"}}}},"responses":{"201":{"description":"The pending amendment","content":{"application/json":{"example":{"id":"amendment123","contractId":"1d78271264b9c76d5842911dd70b4353","status":"PENDING","appliedDiscounts":[],"amendmentType":"ITEMS","nextBillAt":"2026-12-01T00:00:00.000Z","nextPrice":990,"currency":"SEK","items":[{"id":"item_1","sku":"sid:acme-plus-yearly","purchaseOptionId":"yearly"}],"proration":{"method":"NEXT_PAYMENT","amount":41.5,"currency":"SEK","appliesAt":"2026-11-18T10:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/ManagementAmendment"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"message":"The contract cannot change to sid:acme-basic-monthly (monthly). The plans it can change to are listed by upgrade-options"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The plan of the contract cannot be changed in its current state","content":{"application/json":{"example":{"message":"Reactivate the contract before changing its plan"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/contracts/{id}/amendments/{amendmentId}/confirm":{"post":{"tags":["Contracts"],"summary":"Confirm an amendment","description":"Applies a pending amendment. For a plan change, the new plan takes effect at `proration.appliesAt`. With `proration.method` `UPFRONT` or `RESTART_PERIOD`, `proration.amount` is charged to the saved payment method now, and a declined payment answers 400. A plan change cannot be confirmed while the contract is set to cancel: reactivate it first. Confirming an already confirmed amendment returns it unchanged, so a request that timed out can be repeated.","security":[{"OpenID":["contracts:write"]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"amendment123"},"required":true,"name":"amendmentId","in":"path"}],"responses":{"200":{"description":"The confirmed amendment","content":{"application/json":{"example":{"id":"amendment123","contractId":"1d78271264b9c76d5842911dd70b4353","status":"CONFIRMED","appliedDiscounts":[],"amendmentType":"ITEMS","nextBillAt":"2026-12-01T00:00:00.000Z","nextPrice":990,"currency":"SEK","items":[{"id":"item_1","sku":"sid:acme-plus-yearly","purchaseOptionId":"yearly"}],"proration":{"method":"NEXT_PAYMENT","amount":41.5,"currency":"SEK","appliesAt":"2026-11-18T10:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/ManagementAmendment"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The amendment is in a status that cannot be confirmed, or changes the plan of a contract that is set to cancel","content":{"application/json":{"example":{"message":"A CANCELED amendment cannot be confirmed"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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 products with purchase option IDs, market prices, schedules and availability flags.","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/ManagementProduct"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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/ManagementProduct"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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 product by SKU with purchase option IDs, market prices, schedules and availability flags.","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/ManagementProduct"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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/ManagementProduct"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Zero-based page number"},"required":false,"description":"Zero-based page number","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page (maximum 100)"},"required":false,"description":"Items per page (maximum 100)","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":{"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},"schema":{"$ref":"#/components/schemas/UserLogs"}}}},"400":{"description":"Invalid pagination parameters or missing vendor"},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"},{"schema":{"type":"integer","nullable":true,"minimum":0,"default":0,"description":"Zero-based page number"},"required":false,"description":"Zero-based page number","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Items per page (maximum 100)"},"required":false,"description":"Items per page (maximum 100)","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":{"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},"schema":{"$ref":"#/components/schemas/UserSessions"}}}},"400":{"description":"Invalid pagination parameters or missing vendor"},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Search query","name":"q","in":"query"},{"schema":{"type":"string","description":"Number of results to return","example":"10"},"required":false,"description":"Number of results to return","name":"limit","in":"query"},{"schema":{"type":"string","description":"Offset for pagination","example":"0"},"required":false,"description":"Offset for pagination","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":{"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"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/Profile"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"email":"new.user@example.com","firstName":"New","lastName":"User"},"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"]}}}},"responses":{"201":{"description":"User created successfully","content":{"application/json":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"}],"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":{"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"},"schema":{"$ref":"#/components/schemas/Profile"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"}],"requestBody":{"content":{"application/json":{"example":{"firstName":"Jane","lastName":"Smith","nickname":"Janie","mobilePhone":"+9876543210","billingAddress":{"country":"NO","zip":"0150","city":"Oslo","street":"New Street 456"}},"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}]},"description":"User metadata key-value pairs. Set a value to null to delete that key."},"companyInfo":{"type":"object","nullable":true,"properties":{"companyName":{"type":"string"},"vatNr":{"type":"string"},"invoiceEmail":{"type":"string"}},"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}}}}}},"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":{"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"},"schema":{"$ref":"#/components/schemas/Profile"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Allow deletion with one-off purchases. Does not bypass subscription checks.","example":"false"},"required":false,"description":"Allow deletion with one-off purchases. Does not bypass subscription checks.","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":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Cannot delete user with active entitlements"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"}],"requestBody":{"content":{"application/json":{"example":{"email":"new.email@example.com"},"schema":{"type":"object","properties":{"email":{"type":"string","description":"The new email address to use for login","example":"new.email@example.com"}},"required":["email"]}}}},"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":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad request - Email already in use or invalid format","content":{"application/json":{"example":{"message":"Email address is already in use"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"}],"requestBody":{"content":{"application/json":{"example":{"phoneNumber":"+46701234567"},"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"]}}}},"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":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad request - Phone number already in use","content":{"application/json":{"example":{"message":"Phone number is already in use"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"},{"schema":{"type":"string","example":"preferences"},"required":true,"name":"key","in":"path","description":"The key of the metadata entry"}],"requestBody":{"content":{"text/plain":{"example":"premium-user","schema":{"$ref":"#/components/schemas/UserMetadata"}}}},"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":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"},{"schema":{"type":"string","example":"preferences"},"required":true,"name":"key","in":"path","description":"The key of the metadata entry"}],"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":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"user_id","in":"path","description":"The unique identifier of the user"}],"requestBody":{"content":{"application/json":{"example":{"password":"SecurePassword123!"},"schema":{"type":"object","properties":{"password":{"type":"string","minLength":6,"description":"The new password for the user","example":"SecurePassword123!"}},"required":["password"]}}}},"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":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The email address belongs to another account","content":{"application/json":{"example":{"message":"Email address belongs to another user"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":[{"userId":"auth0|61715b8ebe82f0006ab0613b","email":"user@example.com","roles":["PortalFullAccess"]}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"email":"user@example.com","roles":["PortalFullAccess"]},"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"]}}}},"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":{"example":{"userId":"auth0|61715b8ebe82f0006ab0613b","email":"user@example.com","roles":["PortalFullAccess"]},"schema":{"$ref":"#/components/schemas/TeamMember"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"roles":["PortalFullAccess"]},"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"]}}}},"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":{"example":{"userId":"auth0|61715b8ebe82f0006ab0613b","email":"user@example.com","roles":["PortalFullAccess"]},"schema":{"$ref":"#/components/schemas/TeamMember"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"name":"Newsroom CMS","role":"read"},"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"]}}}},"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":{"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"},"schema":{"$ref":"#/components/schemas/CreatedApiKey"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"customerId","in":"path","description":"The unique identifier of the customer"}],"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Search query for entitlements","name":"q","in":"query"},{"schema":{"type":"string","description":"Maximum number of results to return","example":"20"},"required":false,"description":"Maximum number of results to return","name":"limit","in":"query"},{"schema":{"type":"string","description":"Pagination cursor for fetching next page","example":"cursor123"},"required":false,"description":"Pagination cursor for fetching next page","name":"from","in":"query"},{"schema":{"type":"string","description":"Filter entitlements by user ID","example":"user123"},"required":true,"description":"Filter entitlements by user ID","name":"userId","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/EntitlementType"},{"description":"Filter by entitlement type","example":"article"}]},"required":false,"description":"Filter by entitlement type","name":"type","in":"query"},{"schema":{"type":"string","description":"Filter by product SKU","example":"premium-article-123"},"required":false,"description":"Filter by product SKU","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/checkouts":{"get":{"tags":["Checkouts"],"summary":"List a reader's checkouts","description":"Lists the checkouts started with the caller's vendor, newest first. Pass `userId` for one reader's, and `status=PENDING` to find incomplete checkouts. A listed id can return 404 from `GET /management/checkouts/{id}` once the checkout is older than 7 days.","security":[{"OpenID":["checkouts:read"]}],"parameters":[{"schema":{"type":"string","description":"Search query, up to 200 characters and 20 words"},"required":false,"description":"Search query, up to 200 characters and 20 words","name":"q","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only return the checkouts of this reader","example":"auth0|6123456789"},"required":false,"description":"Only return the checkouts of this reader","name":"userId","in":"query"},{"schema":{"type":"string","enum":["PENDING","WAITING_PAYMENT_CONFIRMATION","COMPLETED","FAILED"],"description":"Only return checkouts in this status. PENDING are the incomplete ones"},"required":false,"description":"Only return checkouts in this status. PENDING are the incomplete ones","name":"status","in":"query"},{"schema":{"type":"string","description":"Maximum number of results, 1 to 100. Defaults to 20","example":"20"},"required":false,"description":"Maximum number of results, 1 to 100. Defaults to 20","name":"limit","in":"query"},{"schema":{"type":"string","description":"Offset of the first result, for paging","example":"20"},"required":false,"description":"Offset of the first result, for paging","name":"from","in":"query"}],"responses":{"200":{"description":"A page of checkouts","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/CheckoutListItem"}}}}},"400":{"description":"Bad Request - the vendor could not be resolved","content":{"application/json":{"example":{"message":"Vendor-Id is required"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"id","in":"path","description":"The unique identifier of the checkout"}],"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":{"example":{"message":"Vendor-Id is required"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"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.","name":"status","in":"query"},{"schema":{"$ref":"#/components/schemas/DiscountType"},"required":false,"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.","name":"type","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of items read for a page","example":50},"required":false,"description":"Maximum number of items read for a page","name":"limit","in":"query"},{"schema":{"type":"string","description":"The `nextCursor` of the previous page"},"required":false,"description":"The `nextCursor` of the previous page","name":"cursor","in":"query"}],"responses":{"200":{"description":"The discounts","content":{"application/json":{"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},"schema":{"$ref":"#/components/schemas/DiscountList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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}},"schema":{"$ref":"#/components/schemas/CreateDiscountBody"}}}},"responses":{"201":{"description":"The created discount","content":{"application/json":{"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"},"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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"},"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"endDate":"2027-01-31T23:59:59Z"},"schema":{"$ref":"#/components/schemas/UpdateDiscountBody"}}}},"responses":{"200":{"description":"The updated discount","content":{"application/json":{"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"},"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The discount is not in a status that can be edited","content":{"application/json":{"example":{"message":"Only DRAFT and PAUSED discounts can be edited. This one is ACTIVE"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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"},"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The discount is in a status this action does not apply to","content":{"application/json":{"example":{"message":"Cannot activate a discount that is EXPIRED"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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"},"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The discount is in a status this action does not apply to","content":{"application/json":{"example":{"message":"Cannot pause a discount that is EXPIRED"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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"},"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The discount is in a status this action does not apply to","content":{"application/json":{"example":{"message":"Cannot cancel a discount that is EXPIRED"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Maximum number of items read for a page","name":"limit","in":"query"},{"schema":{"type":"string","description":"The `nextCursor` of the previous page"},"required":false,"description":"The `nextCursor` of the previous page","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Unique identifier of the paywall","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":{"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"},"schema":{"$ref":"#/components/schemas/Paywall"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Grant (purchase) ID","example":"purchase_123abc"},"required":true,"description":"Grant (purchase) ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Grant (purchase) ID","example":"purchase_123abc"},"required":true,"description":"Grant (purchase) ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Access list ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Grant (purchase) ID","example":"purchase_123abc"},"required":true,"description":"Grant (purchase) ID","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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","example":"login.alingsasnytt.se","description":"Full login hostname. Conventionally login.{domain} but never inferred — pass it explicitly."}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"The user ID or fallback ID to fetch diagnostics for","name":"identifier","in":"path"},{"schema":{"type":"string","description":"Maximum number of entries to return (default: 10)","example":"10"},"required":false,"description":"Maximum number of entries to return (default: 10)","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"The user ID or fallback ID to delete diagnostics for","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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"description":"Which metric to return. One of: currentMrr, newMrr, churnMrr, projectedMrr, totalRevenue, totalSales, subscriptionSales, totalSubscribers.","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,"description":"Start of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","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,"description":"End of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","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":{"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}]}]},"schema":{"$ref":"#/components/schemas/StatsMetricSeries"}}}},"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":{"example":{"message":"fromDate must be on or before toDate"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"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.","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,"description":"Start of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","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,"description":"End of the date range, inclusive. ISO 8601 date (YYYY-MM-DD).","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,"description":"Which purchases to report on: `all`, `subscriptions` (recurring only) or `single` (one-off only).","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,"description":"Maximum rows to return, highest revenue first. Defaults to 100, maximum 1000. The response flags whether rows were dropped.","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":{"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},"schema":{"$ref":"#/components/schemas/StatsBreakdown"}}}},"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":{"example":{"message":"fromDate must be on or before toDate"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/report-types":{"get":{"tags":["Reports"],"summary":"List report types","description":"The reports you can create, with the parameters each one takes. Use a type `id` as `typeId` when you create a report.","security":[{"OpenID":["reports:read"]}],"responses":{"200":{"description":"The report types","content":{"application/json":{"example":{"items":[{"id":"transactions_report","name":"Transactions","description":"Every transaction in the date range, with its currency and taxes.","category":"Finance","parameters":[{"name":"dateFrom","label":"From date","description":"The start date of the report in format YYYY-MM-DD","type":"DATE","isRequired":true,"options":null,"default":null},{"name":"dateTo","label":"To date","description":"The end date of the report in format YYYY-MM-DD","type":"DATE","isRequired":true,"options":null,"default":null}]}],"nextCursor":null},"schema":{"$ref":"#/components/schemas/ReportTypeList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/report-types/{id}":{"get":{"tags":["Reports"],"summary":"Get a report type","description":"One report type with its parameters and, where written, `documentation`: what the report answers, what a row stands for and what each column of the file means.","security":[{"OpenID":["reports:read"]}],"parameters":[{"schema":{"type":"string","example":"transactions_report"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The report type","content":{"application/json":{"example":{"id":"transactions_report","name":"Transactions","description":"Every transaction in the date range, with its currency and taxes.","category":"Finance","parameters":[{"name":"dateFrom","label":"From date","description":"The start date of the report in format YYYY-MM-DD","type":"DATE","isRequired":true,"options":null,"default":null},{"name":"dateTo","label":"To date","description":"The end date of the report in format YYYY-MM-DD","type":"DATE","isRequired":true,"options":null,"default":null}]},"schema":{"$ref":"#/components/schemas/ReportType"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/reports":{"get":{"tags":["Reports"],"summary":"List reports","description":"The reports you have created, most recently updated first.","security":[{"OpenID":["reports:read"]}],"parameters":[{"schema":{"type":"string","description":"Only reports of this report type","example":"transactions_report"},"required":false,"description":"Only reports of this report type","name":"typeId","in":"query"}],"responses":{"200":{"description":"The reports","content":{"application/json":{"example":{"items":[{"id":"9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e","typeId":"transactions_report","name":"Transactions","status":"COMPLETED","parameters":{"dateFrom":"2026-01-01","dateTo":"2026-01-31"},"downloadUrl":"https://reports.s3.eu-west-1.amazonaws.com/9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e.csv?X-Amz-Expires=3600","downloadUrlExpiresAt":"2026-02-01T09:00:00.000Z","createdAt":"2026-02-01T07:58:12.000Z","updatedAt":"2026-02-01T08:00:41.000Z"}],"nextCursor":null},"schema":{"$ref":"#/components/schemas/ReportList"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["Reports"],"summary":"Create a report","description":"Asks for a report of a type with the given parameters. The same type and parameters always give the same report, so asking again is safe: you get the existing report back, and one that `FAILED` is run again. A report that is ready is returned with `200`. Otherwise the answer is `202` with the report `PENDING` or `PROCESSING`; poll the `Location` until it is `COMPLETED`.","security":[{"OpenID":["reports:read"]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"typeId":"transactions_report","parameters":{"dateFrom":"2026-01-01","dateTo":"2026-01-31"}},"schema":{"$ref":"#/components/schemas/CreateReportRequest"}}}},"responses":{"200":{"description":"The report, already generated","content":{"application/json":{"example":{"id":"9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e","typeId":"transactions_report","name":"Transactions","status":"COMPLETED","parameters":{"dateFrom":"2026-01-01","dateTo":"2026-01-31"},"downloadUrl":"https://reports.s3.eu-west-1.amazonaws.com/9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e.csv?X-Amz-Expires=3600","downloadUrlExpiresAt":"2026-02-01T09:00:00.000Z","createdAt":"2026-02-01T07:58:12.000Z","updatedAt":"2026-02-01T08:00:41.000Z"},"schema":{"$ref":"#/components/schemas/Report"}}}},"202":{"description":"The report, queued or being generated","headers":{"Location":{"schema":{"type":"string","description":"Where to poll the report","example":"/management/reports/9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e"},"required":true,"description":"Where to poll the report"}},"content":{"application/json":{"example":{"id":"9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e","typeId":"transactions_report","name":"Transactions","status":"PENDING","parameters":{"dateFrom":"2026-01-01","dateTo":"2026-01-31"},"downloadUrl":null,"downloadUrlExpiresAt":null,"createdAt":"2026-02-01T07:58:12.000Z","updatedAt":"2026-02-01T08:00:41.000Z"},"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/management/reports/{id}":{"get":{"tags":["Reports"],"summary":"Get a report","description":"Poll this until `status` is `COMPLETED`, then download the file from `downloadUrl`. Reading the report again gives a fresh link.","security":[{"OpenID":["reports:read"]}],"parameters":[{"schema":{"type":"string","example":"9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The report","content":{"application/json":{"example":{"id":"9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e","typeId":"transactions_report","name":"Transactions","status":"COMPLETED","parameters":{"dateFrom":"2026-01-01","dateTo":"2026-01-31"},"downloadUrl":"https://reports.s3.eu-west-1.amazonaws.com/9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e.csv?X-Amz-Expires=3600","downloadUrlExpiresAt":"2026-02-01T09:00:00.000Z","createdAt":"2026-02-01T07:58:12.000Z","updatedAt":"2026-02-01T08:00:41.000Z"},"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"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"},"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"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"domain","in":"path","description":"Publisher domain (lowercase, no scheme, no trailing dot)"}],"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"domain","in":"path","description":"Publisher domain (lowercase, no scheme, no trailing dot)"}],"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"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,"name":"domain","in":"path","description":"Publisher domain (lowercase, no scheme, no trailing dot)"}],"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":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}}}}