> ## Documentation Index > Fetch the complete documentation index at: https://docs.interchange.io/llms.txt > Use this file to discover all available pages before exploring further. # Update seller billing mandate readiness (admin) > Compare-and-swap the readiness projection for the exact current mandate revision. billingMandateReady is necessary mandate evidence only: it grants no complete billing, proposal, Campaign, execution, or spend authority and does not prove a funded or invoice rail. This endpoint performs no payment or invoice execution. Admin-only. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml put /billing-mandates/{mandateUid}/readiness openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: >- REST API for partners to manage Seller Accounts, inventory sources, and billing. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/storefront` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/storefront` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/api/v2/storefront description: Production server security: [] tags: - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Storefront description: Manage storefront and inventory sources - name: Storefront Agents description: List and manage registered sales, signals, and outcomes agents - name: Storefront Activity description: Audit log of configuration and inventory changes on the storefront - name: Storefront Billing description: Payout bank details and billing configuration for Seller Accounts - name: AI Usage description: Seller Account AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /billing-mandates/{mandateUid}/readiness: put: tags: - Storefront Billing summary: Update seller billing mandate readiness (admin) description: >- Compare-and-swap the readiness projection for the exact current mandate revision. billingMandateReady is necessary mandate evidence only: it grants no complete billing, proposal, Campaign, execution, or spend authority and does not prove a funded or invoice rail. This endpoint performs no payment or invoice execution. Admin-only. operationId: updateSellerBillingMandateReadiness parameters: - in: path name: mandateUid schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: true requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSellerBillingMandateReadinessBody' responses: '200': description: Update seller billing mandate readiness (admin) content: application/json: schema: $ref: '#/components/schemas/SellerBillingMandateApiResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: UpdateSellerBillingMandateReadinessBody: type: object properties: idempotencyKey: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ expectedMandateRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 expectedReadinessRevision: type: integer minimum: 0 maximum: 9007199254740991 status: type: string enum: - pending - ready - failed - hold reasonCode: type: string maxLength: 100 pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$ reasonSummary: type: string minLength: 1 maxLength: 500 required: - idempotencyKey - expectedMandateRevision - expectedReadinessRevision - status - reasonCode - reasonSummary additionalProperties: false description: >- Compare-and-swap update to the mandate-readiness projection. Ready is accepted only for the current active/effective mandate and complete current advertiser identities. Caller-authored reason codes and summaries reject payment- or provider-credential-shaped content before persistence. SellerBillingMandateApiResponse: type: object properties: data: $ref: '#/components/schemas/SellerBillingMandate' error: type: string nullable: true enum: - null required: - data - error additionalProperties: false ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response SellerBillingMandate: type: object properties: mandateUid: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ sellerCustomerId: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 storefrontId: type: string pattern: ^[1-9][0-9]*$ revision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 relationshipKind: type: string enum: - seller_self_serve payeeRef: type: string pattern: >- ^seller_payee:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ operator: $ref: '#/components/schemas/SellerBillingMandateOperator' liablePayerRef: type: string pattern: >- ^liable_payer:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ paymentAuthorityHolderRef: type: string pattern: >- ^payment_authority_holder:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ advertiserScopeKind: type: string enum: - exact_advertiser - reviewed_set advertisers: minItems: 1 type: array items: $ref: '#/components/schemas/SellerBillingMandateAdvertiserIdentity' billing: $ref: '#/components/schemas/SellerBillingMandateBilling' terms: $ref: '#/components/schemas/SellerBillingMandateTerms' lifecycleState: type: string enum: - draft - active - revoked - expired effectiveFrom: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ effectiveUntil: nullable: true type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ provenance: $ref: '#/components/schemas/SellerBillingMandateProvenance' reason: type: string authoredAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ readiness: $ref: '#/components/schemas/SellerBillingMandateReadiness' custody: type: object properties: cardControlledBy: type: string enum: - liable_payer_or_payment_authority_holder advertiserOwnsPaymentMethod: type: boolean enum: - false organizationCardReused: type: boolean enum: - false interchangeRole: type: string enum: - no_card_custody_no_media_receivable - clearing_mandate_only_no_rail_claim required: - cardControlledBy - advertiserOwnsPaymentMethod - organizationCardReused - interchangeRole additionalProperties: false required: - mandateUid - sellerCustomerId - storefrontId - revision - relationshipKind - payeeRef - operator - liablePayerRef - paymentAuthorityHolderRef - advertiserScopeKind - advertisers - billing - terms - lifecycleState - effectiveFrom - effectiveUntil - provenance - reason - authoredAt - readiness - custody additionalProperties: false ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object SellerBillingMandateOperator: type: object properties: domain: type: string maxLength: 253 pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ scope: type: string enum: - whole_operator - specific_unit unitId: nullable: true type: string minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]*$ required: - domain - scope - unitId additionalProperties: false description: >- Canonical commercial operator identity. It is supplied from the persisted advertiser identity, never inferred from membership, email, CRM, signup, or hostname. SellerBillingMandateAdvertiserIdentity: type: object properties: advertiserId: type: string pattern: ^[1-9][0-9]*$ advertiserCustomerId: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 brand: type: object properties: domain: type: string maxLength: 253 pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$ id: nullable: true type: string countries: maxItems: 249 type: array items: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW required: - domain - id - countries additionalProperties: false operator: $ref: '#/components/schemas/SellerBillingMandateOperator' fixedCurrency: type: string pattern: ^[A-Z]{3}$ buyerSelectedTimezone: nullable: true type: string minLength: 1 maxLength: 64 sandbox: type: boolean bindingEpoch: type: string pattern: ^(0|[1-9][0-9]*)$ identityFingerprint: type: string pattern: ^sha256:[0-9a-f]{64}$ binding: nullable: true type: object properties: relationshipRef: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ relationshipVersion: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 bindingUid: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ bindingRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 required: - relationshipRef - relationshipVersion - bindingUid - bindingRevision additionalProperties: false required: - advertiserId - advertiserCustomerId - brand - operator - fixedCurrency - buyerSelectedTimezone - sandbox - bindingEpoch - identityFingerprint - binding additionalProperties: false description: >- Complete canonical advertiser identity snapshot. The numeric advertiser ID is only an operational pointer and never substitutes for this tuple. SellerBillingMandateBilling: anyOf: - type: object properties: mode: type: string enum: - seller_direct_invoice party: type: string enum: - seller authorityKind: type: string enum: - invoice_authority authorityRef: type: string pattern: >- ^seller_invoice_authority:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - mode - party - authorityKind - authorityRef additionalProperties: false - type: object properties: mode: type: string enum: - interchange_cleared party: type: string enum: - interchange authorityKind: type: string enum: - invoice_authority authorityRef: type: string pattern: >- ^interchange_invoice_authority:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - mode - party - authorityKind - authorityRef additionalProperties: false - type: object properties: mode: type: string enum: - interchange_cleared party: type: string enum: - interchange authorityKind: type: string enum: - payment_method_authority authorityRef: type: string pattern: >- ^interchange_payment_authority:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - mode - party - authorityKind - authorityRef additionalProperties: false description: >- Commercial billing route and its exact typed internal authority-evidence namespace. Seller invoice, Interchange invoice, and Interchange payment authority are separate strict variants. Raw card, bank, wallet, provider-token, and Organization payment-method references are rejected. SellerBillingMandateTerms: type: object properties: currency: type: string pattern: ^[A-Z]{3}$ paymentTermsDays: nullable: true type: integer minimum: 0 maximum: 365 termsRef: type: string pattern: >- ^commercial_terms:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ perTransactionLimitMinor: nullable: true type: string pattern: ^(0|[1-9][0-9]{0,19})$ aggregateLimitMinor: nullable: true type: string pattern: ^(0|[1-9][0-9]{0,19})$ aggregateLimitPeriodDays: nullable: true type: integer minimum: 1 maximum: 366 required: - currency - paymentTermsDays - termsRef - perTransactionLimitMinor - aggregateLimitMinor - aggregateLimitPeriodDays additionalProperties: false SellerBillingMandateProvenance: oneOf: - type: object properties: kind: type: string enum: - seller_admin_contract reference: type: string pattern: >- ^seller_admin_contract:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - kind - reference additionalProperties: false - type: object properties: kind: type: string enum: - seller_admin_invoice_terms reference: type: string pattern: >- ^seller_admin_invoice_terms:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - kind - reference additionalProperties: false description: >- Typed internal evidence reference for the Seller-admin source that authorized this immutable commercial revision. type: object SellerBillingMandateReadiness: type: object properties: mandateRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 readinessRevision: type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 status: type: string enum: - pending - ready - failed - hold reasonCode: type: string reasonSummary: type: string projectedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ billingMandateReady: type: boolean required: - mandateRevision - readinessRevision - status - reasonCode - reasonSummary - projectedAt - billingMandateReady additionalProperties: false description: >- Mandate readiness projected separately from advertiser access. billingMandateReady reports only necessary mandate evidence for later composition; it grants no complete billing, advertiser, Campaign, seller-admission, capability, payment-rail, invoice-rail, proposal, execution, or spend authority. securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````