{"openapi":"3.1.0","info":{"title":"Throttle Commerce API","description":"Managed commerce API and event system. Handles order lifecycle, customer identity, payments (manual), fulfillments, subscriptions, discounts, and webhook delivery.","version":"0.1.0"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"X-API-Key","in":"header","description":"API key for server-to-server authentication"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ErrorEnvelope":{"type":"object","title":"ErrorEnvelope","description":"The single error shape used by every Throttle endpoint. Match on `error.code`, which is stable; `error.message` is human-readable and may be reworded.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable, machine-readable identifier for what went wrong (e.g. `quote_not_found`, `insufficient_scopes`, `starting_number_already_used`). Safe to branch on.","examples":["insufficient_scopes"]},"message":{"type":"string","description":"Human-readable explanation of this specific failure. Wording is not part of the contract — do not parse it.","examples":["This API key is missing the quotes:write scope."]},"details":{"type":"object","additionalProperties":true,"description":"Optional structured context — e.g. the offending field names on a validation error."}},"required":["code","message"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid","description":"Quote this when reporting a problem; it identifies the exact request."}}}},"required":["error"]}},"parameters":{"EnvironmentIdHeader":{"name":"X-Throttle-Environment-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional workspace environment id for dashboard-session, Clerk JWT, and extension-session requests. API keys are already pinned to one workspace environment."}}},"paths":{"/health":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/ready":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/internal/sentry-smoke":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/unsubscribe":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/unsubscribe/apply":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/organizations":{"post":{"tags":["Organizations"],"description":"Create an organization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"settings":{"type":"object"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Organizations"],"description":"List organizations","responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/organizations/{id}":{"get":{"tags":["Organizations"],"description":"Get organization by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"tags":["Organizations"],"description":"Update an organization","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/stores":{"post":{"tags":["Stores"],"description":"Create a new store under the organization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string"},"slug":{"type":"string","pattern":"^[a-z0-9-]+$","description":"URL-safe identifier, unique per organization"},"currency":{"type":"string","default":"USD","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Stores"],"description":"List all stores for the organization","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/stores/{id}":{"get":{"tags":["Stores"],"description":"Get a store by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Stores"],"description":"Update a store (name, currency, settings, active status)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"isActive":{"type":"boolean","description":"Deactivate a store without deleting it"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/customers":{"post":{"tags":["Customers"],"description":"Create a new customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"applicationId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"externalId":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"company":{"type":"string","maxLength":200,"nullable":true},"acceptsMarketing":{"type":"boolean","default":false},"netN":{"type":"integer","minimum":1,"maximum":365,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"externalId":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"acceptsMarketing":{"type":"boolean"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"401":{"description":"Missing or invalid credentials. Send a valid `X-API-Key` or `Authorization: Bearer` token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Customers"],"description":"List customers with cursor pagination","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"applicationId","required":false},{"schema":{"type":"string","format":"email"},"in":"query","name":"email","required":false},{"schema":{"type":"string","enum":["linked","unlinked"]},"in":"query","name":"identity","required":false},{"schema":{"type":"string"},"in":"query","name":"q","required":false,"description":"Search email, name, phone, external ids, or metadata."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdAfter","required":false,"description":"ISO 8601 lower bound on creation time, EXCLUSIVE (created_at > value)."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdBefore","required":false,"description":"ISO 8601 upper bound on creation time, EXCLUSIVE (created_at < value)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"externalId":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"acceptsMarketing":{"type":"boolean"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/customers/{id}":{"get":{"tags":["Customers"],"description":"Get a customer by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"externalId":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"acceptsMarketing":{"type":"boolean"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Customers"],"description":"Update a customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"externalId":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"company":{"type":"string","maxLength":200,"nullable":true},"acceptsMarketing":{"type":"boolean"},"netN":{"type":"integer","minimum":1,"maximum":365,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"externalId":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"acceptsMarketing":{"type":"boolean"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Customers"],"description":"Delete a customer","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Customer deleted"},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/customers/by-external/{externalId}":{"get":{"tags":["Customers"],"description":"Look up a customer by the merchant's own externalId (set when the customer was created). Useful for merchant backends that key their user table off their own IDs and don't store the throttle customerId.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"externalId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{id}/anonymize":{"post":{"summary":"Anonymize a customer (soft GDPR delete): tombstone the customer + address PII in place while keeping order/payment/subscription history. Irreversible.","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{id}/addresses":{"get":{"tags":["Customers"],"description":"List addresses for a customer","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"id":{"type":"string","format":"uuid"},"isDefault":{"type":"boolean"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"post":{"tags":["Customers"],"description":"Add an address to a customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["addressLine1","city","countryCode"],"properties":{"label":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"isDefault":{"type":"boolean","default":false},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"label":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/customers/{customerId}/addresses/{id}":{"patch":{"tags":["Customers"],"description":"Update a customer address","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"isDefault":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"label":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Customers"],"description":"Delete a customer address","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Address deleted"},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/customers/{id}/payment-methods":{"get":{"tags":["Customers"],"description":"List payment methods for a customer","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"methodType":{"type":"string","enum":["card","bank_account","wallet"]},"cardBrand":{"type":"string","nullable":true},"cardLastFour":{"type":"string","nullable":true},"cardExpMonth":{"type":"integer","nullable":true},"cardExpYear":{"type":"integer","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"post":{"tags":["Customers"],"description":"Add a payment method to a customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["processor","processorToken","methodType"],"properties":{"processor":{"type":"string"},"processorToken":{"type":"string"},"methodType":{"type":"string","enum":["card","bank_account","wallet"]},"cardBrand":{"type":"string"},"cardLastFour":{"type":"string"},"cardExpMonth":{"type":"integer"},"cardExpYear":{"type":"integer"},"isDefault":{"type":"boolean","default":false},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"methodType":{"type":"string","enum":["card","bank_account","wallet"]},"cardBrand":{"type":"string","nullable":true},"cardLastFour":{"type":"string","nullable":true},"cardExpMonth":{"type":"integer","nullable":true},"cardExpYear":{"type":"integer","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/customers/{customerId}/payment-methods/{id}":{"get":{"tags":["Customers"],"description":"Get a customer payment method","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"methodType":{"type":"string","enum":["card","bank_account","wallet"]},"cardBrand":{"type":"string","nullable":true},"cardLastFour":{"type":"string","nullable":true},"cardExpMonth":{"type":"integer","nullable":true},"cardExpYear":{"type":"integer","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Customers"],"description":"Update a customer payment method","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"isDefault":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"methodType":{"type":"string","enum":["card","bank_account","wallet"]},"cardBrand":{"type":"string","nullable":true},"cardLastFour":{"type":"string","nullable":true},"cardExpMonth":{"type":"integer","nullable":true},"cardExpYear":{"type":"integer","nullable":true},"isDefault":{"type":"boolean"},"isActive":{"type":"boolean"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Customers"],"description":"Delete a customer payment method","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Payment method deleted"},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/customers/{customerId}/payment-methods/{id}/pause":{"post":{"tags":["Customers"],"description":"Pause a customer payment method","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/customers/{customerId}/payment-methods/{id}/resume":{"post":{"tags":["Customers"],"description":"Resume a customer payment method","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/payment-methods/client-token":{"post":{"summary":"Mint a customer-scoped client token for browser payment-method management","tags":["Payment Methods"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customerId"],"additionalProperties":false,"properties":{"customerId":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/me/payment-methods":{"get":{"summary":"List the authenticated customer's saved payment methods","tags":["Payment Methods"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/me/payment-methods/{id}":{"patch":{"summary":"Set a saved payment method as default","tags":["Payment Methods"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["isDefault"],"additionalProperties":false,"properties":{"isDefault":{"type":"boolean","enum":[true]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove a saved payment method","tags":["Payment Methods"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/me/payment-methods/embed-token":{"post":{"summary":"Mint a Gr4vy add-only vault embed token scoped to the authenticated customer","tags":["Payment Methods"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"currency":{"type":"string","minLength":3,"maxLength":3}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/me/payment-methods/confirm":{"post":{"summary":"Record a card vaulted via the add-card embed","tags":["Payment Methods"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transactionId"],"additionalProperties":false,"properties":{"transactionId":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/carts":{"post":{"tags":["Carts"],"description":"Create a new cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"applicationId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"customerEmail":{"type":"string","format":"email"},"currency":{"type":"string"},"netN":{"type":"integer","minimum":1,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","minLength":4,"maxLength":20,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/carts/{id}":{"get":{"tags":["Carts"],"description":"Get a cart by ID (includes line items)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Carts"],"description":"Update a cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"customerId":{"type":"string","format":"uuid"},"customerEmail":{"type":"string","format":"email","nullable":true},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},"notes":{"type":"string"},"netN":{"type":"integer","minimum":1,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","minLength":4,"maxLength":20,"nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}/items":{"post":{"tags":["Carts"],"description":"Add a line item to a cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","unitPrice"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom"],"default":"product"},"referenceId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","minimum":1,"default":1},"taxAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","description":"Product image. Accepts an absolute http(s) URL or a relative path (e.g. \"/images/x.png\"); relative paths are resolved against the application storefront base URL (PUT /v1/embed-config { storefrontBaseUrl }, falling back to the first allowedOrigin)."},"requiresShipping":{"type":"boolean","description":"Whether this item is physically shippable. For external/ad-hoc catalogs with no Throttle product behind the item. Omit to infer from `type` (everything except `service` ships); set explicitly to force-include or force-exclude the item from `calculated` shipping."},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"],"description":"What this item needs before it counts as delivered. Omit to resolve from `type` and `metadata`. `digital` and `access_grant` are delivered automatically on payment capture; `none` means there is nothing to deliver."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"],"description":"What this item needs before it counts as delivered. Omit to resolve from `type` and `metadata`. `digital` and `access_grant` are delivered automatically on payment capture; `none` means there is nothing to deliver."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{cartId}/items/{id}":{"patch":{"tags":["Carts"],"description":"Update a line item","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"quantity":{"type":"integer","minimum":1},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"cartId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"],"description":"What this item needs before it counts as delivered. Omit to resolve from `type` and `metadata`. `digital` and `access_grant` are delivered automatically on payment capture; `none` means there is nothing to deliver."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Carts"],"description":"Remove a line item from a cart","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"cartId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"}}}},"/api/v1/carts/{id}/checkout":{"post":{"tags":["Carts"],"description":"Convert the cart to a draft order. Legacy alias for /finalize — same handler, identical semantics. New integrations should call /finalize instead.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"The created draft order","properties":{"id":{"type":"string","format":"uuid"},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"In cents"},"total":{"type":"integer","description":"In cents"},"cartId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/carts/{id}/finalize":{"post":{"tags":["Carts"],"description":"Finalize a cart by converting it to a draft order (status=draft). To collect payment, mint a checkout session against the resulting order afterwards.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"The created draft order","properties":{"id":{"type":"string","format":"uuid"},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"In cents"},"total":{"type":"integer","description":"In cents"},"cartId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/carts/{id}/merge":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/carts/{id}/apply-discount":{"post":{"tags":["Carts"],"description":"Apply a discount code to a cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code"],"properties":{"code":{"type":"string"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}/discount":{"delete":{"tags":["Carts"],"description":"Remove discount code from a cart","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}/shipping":{"post":{"tags":["Carts"],"description":"Select a shipping method for a cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["methodId","displayName","rateAmount"],"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer","minimum":0}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Carts"],"description":"Clear the selected shipping method from a cart","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}/tax-lines":{"put":{"tags":["Carts"],"description":"Replace all tax lines on a cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["lines"],"properties":{"lines":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["lineItemId","jurisdictionCode","taxType","rate","amount"],"properties":{"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string"},"taxType":{"type":"string","enum":["sales","vat","gst","pst","hst","service","excise","other"]},"rate":{"type":"number","minimum":0,"maximum":1},"amount":{"type":"integer","minimum":0},"currency":{"type":"string"}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Carts"],"description":"Clear all tax lines from a cart","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customerEmail":{"type":"string","nullable":true},"status":{"type":"string","enum":["open","checkout","converted","abandoned"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"billingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"additionalProperties":true,"required":["addressLine1","city","countryCode"]},{"type":"null"}]},"discountCode":{"type":"string","nullable":true},"appliedDiscount":{"anyOf":[{"type":"object","properties":{"discountId":{"type":"string","format":"uuid","nullable":true},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"freeShipping":{"type":"boolean"},"validUntil":{"type":"string","format":"date-time","nullable":true},"snapshotHash":{"type":"string"}}},{"type":"null"}]},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}/events":{"get":{"tags":["Carts"],"description":"List audit events for a cart","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":0},"in":"query","name":"sinceSequence","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"sequence":{"type":"integer"},"payload":{"type":"object","additionalProperties":true},"actorType":{"type":"string"},"actorId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/abandoned-carts":{"get":{"summary":"List abandoned carts (most-recently abandoned first).","tags":["Carts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/abandoned-carts/summary":{"get":{"summary":"Abandoned-cart summary metrics over a trailing window.","tags":["Carts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":365},"in":"query","name":"sinceDays","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/cart-sessions":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/cart-sessions/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/cart-sessions/{id}/items":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/cart-sessions/{id}/items/{itemId}":{"patch":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/cart-sessions/{id}/shipping":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/cart-sessions/{id}/discount":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/cart-sessions/{id}/checkout-session":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/config":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/quote-tokens":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/quote-tokens/{tokenId}":{"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"tokenId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/config/draft":{"put":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/config/publish":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/quotes":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/carts/{cartId}/calculate":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/external-snapshots":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/shipping-providers/available":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/tax-providers/available":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/shipping-providers":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/tax-providers":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/tax-providers/referral-click":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/shipping-providers/{id}/verify":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/tax-providers/{id}/verify":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/shipping-providers/{id}/primary":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/tax-providers/{id}/primary":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/shipping-providers/{id}":{"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/tax-providers/{id}":{"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/documents":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/entity-use-codes":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/documents/{id}/retry":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders":{"post":{"tags":["Orders"],"description":"Create a new order (draft)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid"},"currency":{"type":"string","default":"USD"},"source":{"type":"string","enum":["web","mobile","pos","api"],"default":"api"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}}},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}}},"notes":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"lineItems":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom"],"default":"product"},"referenceId":{"type":"string","description":"Merchant's external ID (SKU, plan ID, etc.)"},"name":{"type":"string"},"description":{"type":"string"},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","minimum":1,"default":1},"taxAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","default":0},"discountAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","default":0},"imageUrl":{"type":"string","description":"Product image. Accepts an absolute http(s) URL or a relative path (e.g. \"/images/x.png\"); relative paths are resolved against the application storefront base URL (PUT /v1/embed-config { storefrontBaseUrl }, falling back to the first allowedOrigin)."},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"],"description":"What this item needs before it counts as delivered. Omit to resolve from `type` and `metadata`. `digital` and `access_grant` are delivered automatically on payment capture; `none` means there is nothing to deliver."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}},"required":["name","unitPrice"]}}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Orders"],"description":"List orders with cursor pagination","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"in":"query","name":"paymentStatus","required":false},{"schema":{"type":"string","enum":["one_time","recurring","mixed"]},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"in":"query","name":"source","required":false},{"schema":{"type":"string"},"in":"query","name":"q","required":false,"description":"Search order id, number, source, status, or metadata."},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"customerId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"subscriptionId","required":false,"description":"Return only the orders this subscription billed (exact match on the order metadata `subscription_id` pointer). Covers renewals, plan-change charges and the signup order."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdAfter","required":false,"description":"ISO 8601 lower bound on creation time, EXCLUSIVE (created_at > value)."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdBefore","required":false,"description":"ISO 8601 upper bound on creation time, EXCLUSIVE (created_at < value)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/export.csv":{"get":{"summary":"Export orders (respecting list filters) as a CSV attachment. Capped at 10,000 rows.","tags":["Orders"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/orders/{id}":{"get":{"tags":["Orders"],"description":"Get an order by ID (includes line items)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Orders"],"description":"Update order fields (addresses, notes, metadata)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}}},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}}},"notes":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/checkout":{"post":{"tags":["Orders"],"description":"Initiate checkout (draft -> pending)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{id}/authorize":{"post":{"tags":["Orders"],"description":"Mark payment as authorized (pending -> processing)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentId"],"properties":{"paymentId":{"type":"string","format":"uuid"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/capture":{"post":{"tags":["Orders"],"description":"Mark payment as captured (pending -> processing)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentId"],"properties":{"paymentId":{"type":"string","format":"uuid"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/cancel":{"post":{"tags":["Orders"],"description":"Cancel an order. Authorized payments are always voided; captured payments are refunded when refundCapturedPayments is true.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"refundCapturedPayments":{"type":"boolean"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"paymentActions":{"type":"array","description":"Payment settlement performed by the cancel: voids of open authorizations (always) and refunds of captured payments (opt-in). Failures never undo the cancel.","items":{"type":"object","properties":{"paymentId":{"type":"string"},"action":{"type":"string","enum":["void","refund"]},"status":{"type":"string","enum":["succeeded","failed"]},"error":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{id}/status":{"post":{"tags":["Orders"],"description":"Move an order to any lifecycle status. Both directions are allowed — this is the merchant override, not a state-machine step. Side effects already applied are never rewound. Moving to `cancelled` additionally requires the `order_cancellations:write` scope and voids the order's live authorizations, exactly as `POST /orders/{id}/cancel` does; captured payments are left alone.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"reason":{"type":"string","maxLength":500}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{id}/status-history":{"get":{"tags":["Orders"],"description":"Append-only record of every status change on this order, oldest first.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromStatus":{"type":"string","nullable":true},"toStatus":{"type":"string"},"actorType":{"type":"string","enum":["user","system","integration"]},"actorId":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"source":{"type":"string","enum":["manual","state_machine","fulfillment","payment","migration"]},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{id}/close":{"post":{"tags":["Orders"],"description":"Close a fulfilled order (archive it from active views)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"discountId":{"type":"string","format":"uuid","nullable":true},"discountCode":{"type":"string","nullable":true},"orderNumber":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","fulfilled","cancelled","closed"]},"displayStatus":{"type":"string"},"fulfillmentSummary":{"type":"object","nullable":true,"properties":{"itemsTotal":{"type":"integer"},"itemsFulfilled":{"type":"integer"},"itemsRemaining":{"type":"integer"}}},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided"]},"source":{"type":"string","enum":["web","mobile","pos","api","subscription_engine"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"taxTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shippingTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"customerId":{"type":"string","format":"uuid","nullable":true},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"closedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/payments":{"post":{"tags":["Payments"],"description":"Create a payment for an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"processor":{"type":"string","default":"manual"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","default":"USD"},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"],"default":"manual"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"get":{"tags":["Payments"],"description":"List payments for an order","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/payments/{paymentId}":{"get":{"tags":["Payments"],"description":"Get a specific payment for an order","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"paymentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/payments/{id}/transactions":{"get":{"tags":["Payments"],"description":"List transactions for a payment","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"paymentId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["authorize","capture","refund","void"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["success","failed","pending"]},"processorResponse":{"type":"object","additionalProperties":true,"nullable":true},"idempotencyKey":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/payments":{"get":{"summary":"List payments for the calling merchant.","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"method","required":false},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","enum":["0_30","31_60","61_90","90_plus"]},"in":"query","name":"aging","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"order_id","required":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"due_from","required":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"due_to","required":false},{"schema":{"type":"string","pattern":"^\\d+$"},"in":"query","name":"amount_min","required":false},{"schema":{"type":"string","pattern":"^\\d+$"},"in":"query","name":"amount_max","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}":{"get":{"summary":"Get a payment by id.","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/refund":{"post":{"tags":["Orders"],"description":"Refund the captured payment on an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Partial refund amount (defaults to full amount)"},"reason":{"type":"string","maxLength":500}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/payments/{id}/authorize":{"post":{"tags":["Payments"],"description":"Authorize a payment (pending -> authorized)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/payments/{id}/capture":{"post":{"tags":["Payments"],"description":"Capture a payment (authorized -> captured)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Partial capture amount (defaults to full amount)"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/payments/{id}/void":{"post":{"tags":["Payments"],"description":"Void an authorized payment","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/payments/{id}/refund":{"post":{"tags":["Payments"],"description":"Refund a captured payment (full or partial)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Partial refund amount (defaults to full amount)"},"reason":{"type":"string","maxLength":500}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processorTransactionId":{"type":["null","string"]},"processorResponse":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"capturedAmount":{"type":["null","integer"],"description":"Amount actually captured. May be less than `amount` on a partial capture; null until captured."},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"netN":{"type":"integer","minimum":0,"maximum":365},"netNSource":{"type":"string","enum":["customer_override","cart_override","global_default"]},"authorizedAt":{"type":["null","string"],"format":"date-time"},"capturedAt":{"type":["null","string"],"format":"date-time"},"voidedAt":{"type":["null","string"],"format":"date-time"},"disputed":{"type":"boolean"},"disputeReason":{"type":["null","string"]},"disputeOpenedAt":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/payments/{id}/invoice/resend":{"post":{"summary":"Resend the Net-N invoice email to the customer.","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}/invoice-pdf":{"get":{"summary":"Get a signed download URL for a Net30 invoice PDF.","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/invoices":{"get":{"summary":"List invoices","tags":["Customer Invoices"],"description":"List all invoices for the application across all customers and payment source types. Requires invoices:read scope.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Pagination cursor"},{"schema":{"type":"integer","default":20,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"sort","required":false},{"schema":{"type":"string","enum":["paid","open","refunded","partially_refunded","void"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["order","net30","subscription"]},"in":"query","name":"type","required":false},{"schema":{"type":"string"},"in":"query","name":"sourceId","required":false,"description":"Filter to invoices for a specific source: the payment id for order/net30 invoices, or the subscription invoice id for subscription invoices."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{customerId}/invoices":{"get":{"summary":"List invoices for a customer","tags":["Customer Invoices"],"description":"List all invoices scoped to a specific customer. Requires invoices:read scope.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Pagination cursor"},{"schema":{"type":"integer","default":20,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"in":"query","name":"sort","required":false},{"schema":{"type":"string","enum":["paid","open","refunded","partially_refunded","void"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["order","net30","subscription"]},"in":"query","name":"type","required":false},{"schema":{"type":"string"},"in":"query","name":"sourceId","required":false,"description":"Filter to invoices for a specific source: the payment id for order/net30 invoices, or the subscription invoice id for subscription invoices."},{"schema":{"type":"string"},"in":"path","name":"customerId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/invoices/{id}":{"get":{"summary":"Get invoice","tags":["Customer Invoices"],"description":"Fetch a single invoice by ID. Requires invoices:read scope.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/invoices/{id}/download":{"get":{"summary":"Download invoice PDF","tags":["Customer Invoices"],"description":"Returns a 302 redirect to a short-lived signed S3 URL for the invoice PDF. Pass ?format=json to receive the URL as JSON instead. Requires invoices:read scope.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","enum":["json"]},"in":"query","name":"format","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{orderId}/fulfillments":{"post":{"tags":["Fulfillments"],"description":"Create a fulfillment for an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","lineItemIds"],"properties":{"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"lineItemIds":{"type":"array","items":{"type":"object","required":["lineItemId","quantity"],"properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"detail":{"type":"object","additionalProperties":true,"nullable":true}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"get":{"tags":["Fulfillments"],"description":"List fulfillments for an order","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"detail":{"type":"object","additionalProperties":true,"nullable":true}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}":{"get":{"tags":["Fulfillments"],"description":"Get a fulfillment by ID (includes type-specific details)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"detail":{"type":"object","additionalProperties":true,"nullable":true}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/processing":{"post":{"tags":["Fulfillments"],"description":"Mark fulfillment as processing","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"detail":{"type":"object","additionalProperties":true,"nullable":true}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/complete":{"post":{"tags":["Fulfillments"],"description":"Mark fulfillment as completed","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"detail":{"type":"object","additionalProperties":true,"nullable":true}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/cancel":{"post":{"tags":["Fulfillments"],"description":"Cancel a fulfillment","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"detail":{"type":"object","additionalProperties":true,"nullable":true}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/shipment":{"patch":{"tags":["Fulfillments"],"description":"Update shipment details for a fulfillment","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fulfillmentId":{"type":"string","format":"uuid"},"carrier":{"type":"string","nullable":true},"serviceLevel":{"type":"string","nullable":true},"trackingNumber":{"type":"string","nullable":true},"trackingUrl":{"type":"string","format":"uri","nullable":true},"labelUrl":{"type":"string","format":"uri","nullable":true},"shipFromAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shipToAddress":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string","description":"Optional. Business name for B2B addresses."},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"email":{"type":"string","format":"email"}},"nullable":true},"shippingCost":{"type":"integer","nullable":true,"description":"In cents"},"estimatedDelivery":{"type":"string","format":"date-time","nullable":true},"shippedAt":{"type":"string","format":"date-time","nullable":true},"externalId":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/digital":{"patch":{"tags":["Fulfillments"],"description":"Update digital delivery details","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fulfillmentId":{"type":"string","format":"uuid"},"deliveryMethod":{"type":"string","enum":["download","email","license_key","api_access"]},"downloadUrl":{"type":"string","format":"uri","nullable":true},"downloadStorageKey":{"type":"string","nullable":true},"downloadExpiry":{"type":"string","format":"date-time","nullable":true},"downloadLimit":{"type":"integer","nullable":true},"downloadCount":{"type":"integer"},"licenseKey":{"type":"string","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/access":{"patch":{"tags":["Fulfillments"],"description":"Update access grant details","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fulfillmentId":{"type":"string","format":"uuid"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"grantedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/service":{"patch":{"tags":["Fulfillments"],"description":"Update service delivery details","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fulfillmentId":{"type":"string","format":"uuid"},"serviceType":{"type":"string","nullable":true},"providerName":{"type":"string","nullable":true},"scheduledAt":{"type":"string","format":"date-time","nullable":true},"completedAt":{"type":"string","format":"date-time","nullable":true},"location":{"type":"string","nullable":true},"durationMinutes":{"type":"integer","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/subscriptions":{"post":{"tags":["Subscriptions"],"description":"Create a new subscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["customerId","planReference","interval","amount","currentPeriodStart","currentPeriodEnd"],"properties":{"applicationId":{"type":"string","format":"uuid","description":"Optional application ID override (resolved from auth context when absent)"},"customerId":{"type":"string","format":"uuid","description":"ID of the customer to subscribe"},"planReference":{"type":"string","minLength":1,"description":"Your plan identifier (e.g. \"pro_monthly\")"},"planName":{"type":"string","description":"Human-readable plan name shown on invoices"},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"],"description":"Billing interval"},"amount":{"type":"integer","minimum":0,"description":"Subscription amount in the smallest currency unit (e.g. cents)"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code (defaults to USD)"},"currentPeriodStart":{"format":"date-time","description":"ISO 8601 start of the current billing period"},"currentPeriodEnd":{"format":"date-time","description":"ISO 8601 end of the current billing period"},"trialEnd":{"format":"date-time","description":"ISO 8601 date-time when the trial ends (omit if no trial)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata stored with the subscription"},"orderId":{"type":"string","format":"uuid","description":"The order that paid for the first period. Links the two by stamping `subscription_id` on that order's metadata, which is what the order detail page and the orders `subscriptionId` filter read. Use this when you charged the signup yourself and created the subscription afterwards. 404 if the order does not exist in this application and environment."}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Subscriptions"],"description":"List subscriptions with cursor pagination","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"customerId","required":false},{"schema":{"type":"string"},"in":"query","name":"externalCustomerId","required":false,"description":"Filter by the merchant's own customer ID (the value passed as externalId on customer creation). Server resolves to the throttle customerId before filtering. Mutually exclusive with customerId."},{"schema":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"in":"query","name":"interval","required":false},{"schema":{"type":"string"},"in":"query","name":"q","required":false,"description":"Search subscription id, customer id, plan reference, plan name, status, interval, and metadata."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdAfter","required":false,"description":"ISO 8601 lower bound on creation time, EXCLUSIVE (created_at > value)."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdBefore","required":false,"description":"ISO 8601 upper bound on creation time, EXCLUSIVE (created_at < value)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/subscriptions/{id}":{"get":{"tags":["Subscriptions"],"description":"Get a subscription by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Subscriptions"],"description":"Update a subscription (plan change, amount, interval)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"planReference":{"type":"string"},"planName":{"type":"string"},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents"},"taxAddress":{"type":["object","null"],"properties":{"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}}},"metadata":{"type":"object","additionalProperties":true}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/subscriptions/{id}/invoices":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/subscriptions/{id}/pause":{"post":{"tags":["Subscriptions"],"description":"Pause an active subscription","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/subscriptions/{id}/resume":{"post":{"tags":["Subscriptions"],"description":"Resume a paused subscription","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/subscriptions/{id}/change-plan":{"post":{"tags":["Subscriptions"],"description":"Schedule or apply a plan change on a subscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["planReference","interval","amount","effective"],"properties":{"planReference":{"type":"string","minLength":1,"description":"Your plan identifier for the new plan"},"planName":{"type":"string","description":"Human-readable name for the new plan"},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"],"description":"Billing interval for the new plan"},"amount":{"type":"integer","minimum":0,"description":"Amount in the smallest currency unit (e.g. cents)"},"effective":{"type":"string","enum":["now","period_end"],"description":"When the plan change takes effect"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"proration":{"type":"object","properties":{"creditCents":{"type":"integer"},"chargedCents":{"type":"integer"},"fullAmount":{"type":"integer"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/subscriptions/{id}/change-quantity":{"post":{"tags":["Subscriptions"],"description":"Change the seat quantity on a subscription (immediate prorated, or deferred to period end)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["quantity","effective"],"properties":{"quantity":{"type":"integer","minimum":1,"description":"New seat count"},"effective":{"type":"string","enum":["now","period_end"],"description":"When the seat change takes effect"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"proration":{"type":"object","properties":{"creditCents":{"type":"integer"},"chargedCents":{"type":"integer"},"fullAmount":{"type":"integer"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/subscriptions/{id}/pending-change":{"delete":{"tags":["Subscriptions"],"description":"Cancel a pending scheduled plan change on a subscription","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/subscriptions/{id}/cancel":{"post":{"tags":["Subscriptions"],"description":"Cancel a subscription (immediately or at period end)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"atPeriodEnd":{"type":"boolean","default":false,"description":"If true, cancels at the end of the current billing period"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"},"failureCount":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"taxAddressSnapshot":{"type":["null","object"],"additionalProperties":true},"taxAddressSource":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"pendingPlanReference":{"type":["null","string"]},"pendingPlanName":{"type":["null","string"]},"pendingInterval":{"type":["null","string"]},"pendingAmount":{"type":["null","integer"]},"customer":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/subscriptions/{id}/usage":{"post":{"tags":["Subscriptions"],"description":"Record (upsert) a usage item for the subscription's current billing period.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","minLength":1,"maxLength":64},"unitCount":{"type":"integer","minimum":0},"unitPriceCents":{"type":"integer","minimum":0}},"required":["kind","unitCount","unitPriceCents"]}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"tags":["Subscriptions"],"description":"List usage items for the subscription's current billing period.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/subscriptions/eligibility-check":{"post":{"tags":["Subscriptions"],"description":"Pre-flight check whether a payment method is eligible for a free trial on this merchant. Card fingerprint match against any prior subscription with a trialEnd blocks the trial.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"paymentMethodId":{"type":"string","format":"uuid","description":"customerPaymentMethods row id. Must belong to the authenticated merchant. The server resolves the card fingerprint internally."}},"required":["paymentMethodId"]}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/discounts":{"post":{"tags":["Discounts"],"description":"Create a new discount","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","type","value"],"properties":{"code":{"type":"string","description":"Leave empty for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer","description":"Percentage as a whole number (25 = 25%) or fixed amount in minor units"},"conditions":{"type":"object","additionalProperties":true,"description":"e.g. { minOrder: 5000 }"},"usageLimit":{"type":"integer"},"maxRedemptionsPerCustomer":{"type":["integer","null"],"minimum":1,"default":1,"description":"Per-customer redemption limit. Use null for unlimited."},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","nullable":true,"description":"Null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer","description":"Percentage as a whole number (25 = 25%) or fixed amount in minor units"},"conditions":{"type":"object","additionalProperties":true},"usageLimit":{"type":"integer","nullable":true},"usageCount":{"type":"integer"},"maxRedemptionsPerCustomer":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"startsAt":{"type":"string","format":"date-time","nullable":true},"endsAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Discounts"],"description":"List discounts with cursor pagination","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"boolean"},"in":"query","name":"isActive","required":false},{"schema":{"type":"string"},"in":"query","name":"code","required":false},{"schema":{"type":"string","enum":["percentage","fixed_amount"]},"in":"query","name":"type","required":false},{"schema":{"type":"string"},"in":"query","name":"q","required":false,"description":"Search discount code, name, type, or metadata."},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"sort","required":false,"description":"Sort by creation time."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdAfter","required":false,"description":"ISO 8601 lower bound on creation time, EXCLUSIVE (created_at > value)."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdBefore","required":false,"description":"ISO 8601 upper bound on creation time, EXCLUSIVE (created_at < value)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","nullable":true,"description":"Null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer","description":"Percentage as a whole number (25 = 25%) or fixed amount in minor units"},"conditions":{"type":"object","additionalProperties":true},"usageLimit":{"type":"integer","nullable":true},"usageCount":{"type":"integer"},"maxRedemptionsPerCustomer":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"startsAt":{"type":"string","format":"date-time","nullable":true},"endsAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/discounts/{id}":{"get":{"tags":["Discounts"],"description":"Get a discount by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","nullable":true,"description":"Null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer","description":"Percentage as a whole number (25 = 25%) or fixed amount in minor units"},"conditions":{"type":"object","additionalProperties":true},"usageLimit":{"type":"integer","nullable":true},"usageCount":{"type":"integer"},"maxRedemptionsPerCustomer":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"startsAt":{"type":"string","format":"date-time","nullable":true},"endsAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Discounts"],"description":"Update a discount","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":["string","null"],"description":"Leave null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer"},"conditions":{"type":"object","additionalProperties":true},"usageLimit":{"type":["integer","null"]},"maxRedemptionsPerCustomer":{"type":["integer","null"],"minimum":1,"description":"Per-customer redemption limit. Use null for unlimited."},"isActive":{"type":"boolean"},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","nullable":true,"description":"Null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer","description":"Percentage as a whole number (25 = 25%) or fixed amount in minor units"},"conditions":{"type":"object","additionalProperties":true},"usageLimit":{"type":"integer","nullable":true},"usageCount":{"type":"integer"},"maxRedemptionsPerCustomer":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"startsAt":{"type":"string","format":"date-time","nullable":true},"endsAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Discounts"],"description":"Delete a discount","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"}}}},"/api/v1/discounts/validate":{"post":{"tags":["Discounts"],"description":"Validate a discount code against an order total","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","orderTotal"],"properties":{"code":{"type":"string"},"orderTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"customerId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"discount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","nullable":true,"description":"Null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer","description":"Percentage as a whole number (25 = 25%) or fixed amount in minor units"},"conditions":{"type":"object","additionalProperties":true},"usageLimit":{"type":"integer","nullable":true},"usageCount":{"type":"integer"},"maxRedemptionsPerCustomer":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"startsAt":{"type":"string","format":"date-time","nullable":true},"endsAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"error":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/discounts/preview":{"post":{"tags":["Discounts"],"description":"Preview a discount code against a subtotal without mutating a cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","currency","subtotal"],"properties":{"code":{"type":"string"},"currency":{"type":"string","minLength":3,"maxLength":3},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"customerId":{"type":"string","format":"uuid"},"lineItems":{"type":"array","items":{"type":"object","required":["quantity","unitPrice"],"properties":{"id":{"type":"string"},"quantity":{"type":"integer","minimum":1},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"}}}}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean"},"code":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer"},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discountTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","nullable":true,"description":"Null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount"]},"value":{"type":"integer","description":"Percentage as a whole number (25 = 25%) or fixed amount in minor units"},"conditions":{"type":"object","additionalProperties":true},"usageLimit":{"type":"integer","nullable":true},"usageCount":{"type":"integer"},"maxRedemptionsPerCustomer":{"type":"integer","nullable":true},"isActive":{"type":"boolean"},"startsAt":{"type":"string","format":"date-time","nullable":true},"endsAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"message":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/quotes":{"get":{"tags":["Quotes"],"description":"List quotes with cursor pagination","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string"},"in":"query","name":"status","required":false,"description":"Comma-separated status filter, e.g. proposed,accepted"},{"schema":{"type":"string"},"in":"query","name":"q","required":false,"description":"Search quote number, customer email, or buyer reference"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"assignedMemberId","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"customerId","required":false},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdAfter","required":false,"description":"ISO 8601 lower bound on creation time, EXCLUSIVE (created_at > value)."},{"schema":{"type":"string","anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"in":"query","name":"createdBefore","required":false,"description":"ISO 8601 upper bound on creation time, EXCLUSIVE (created_at < value)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid credentials. Send a valid `X-API-Key` or `Authorization: Bearer` token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["Quotes"],"description":"Create a quote (draft, or requested for RFQ intake)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["draft","requested"]},"customerId":{"type":["string","null"],"format":"uuid"},"customerEmail":{"type":["string","null"],"format":"email"},"buyerReference":{"type":["string","null"]},"source":{"type":"string","enum":["dashboard","api"]},"assignedMemberId":{"type":["string","null"],"format":"uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"internalNotes":{"type":["string","null"]},"items":{"type":"array","maxItems":200,"items":{"type":"object","required":["name","unitPrice"],"properties":{"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom"]},"referenceId":{"type":["string","null"]},"sku":{"type":["string","null"]},"name":{"type":"string"},"description":{"type":["string","null"]},"unitPrice":{"type":"integer","minimum":0},"quantity":{"type":"integer","minimum":1},"taxAmount":{"type":"integer","minimum":0},"discountAmount":{"type":"integer","minimum":0},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["string","null"]},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true}}}},"paymentTerms":{"type":"object","required":["mode"],"description":"pay_in_full | net_terms (netN 1-365) | deposit_balance (deposit percent/fixed + balanceNetN)","properties":{"mode":{"type":"string","enum":["pay_in_full","net_terms","deposit_balance"]},"netN":{"type":"integer","minimum":1,"maximum":365},"balanceNetN":{"type":"integer","minimum":1,"maximum":365},"deposit":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["percent","fixed"]},"value":{"type":"number"}}}}},"expiresAt":{"description":"ISO 8601 date-time, or null to clear"},"buyerNote":{"type":["string","null"]},"leadTime":{"type":["string","null"]},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["integer","null"],"minimum":0},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"revision":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"state":{"type":"string","enum":["working","issued","superseded"]},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"pdfStorageKey":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid credentials. Send a valid `X-API-Key` or `Authorization: Bearer` token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/quotes/{id}":{"get":{"tags":["Quotes"],"description":"Get a quote with revisions, comments, and timeline (merchant view)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"revisions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"state":{"type":"string","enum":["working","issued","superseded"]},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"pdfStorageKey":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionId":{"type":["null","string"]},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorMemberId":{"type":["null","string"]},"authorName":{"type":["null","string"]},"authorEmail":{"type":["null","string"]},"body":{"type":"string"},"visibility":{"type":"string","enum":["shared","internal"]},"createdAt":{"type":"string","format":"date-time"}}}},"timeline":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"type":{"type":"string"},"actorType":{"type":"string","enum":["buyer","merchant","system"]},"actorId":{"type":["null","string"]},"data":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Quotes"],"description":"Update quote assignment, linkage, internal notes, or archive it","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignedMemberId":{"type":["string","null"],"format":"uuid"},"customerId":{"type":["string","null"],"format":"uuid"},"customerEmail":{"type":["string","null"],"format":"email"},"buyerReference":{"type":["string","null"]},"internalNotes":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"status":{"type":"string","enum":["archived"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quotes/{id}/revisions":{"post":{"tags":["Quotes"],"description":"Start a new working revision cloned from the latest issued revision","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"state":{"type":"string","enum":["working","issued","superseded"]},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"pdfStorageKey":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quotes/{id}/revisions/{revId}":{"patch":{"tags":["Quotes"],"description":"Edit the working revision (items, terms, expiry, notes)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","maxItems":200,"items":{"type":"object","required":["name","unitPrice"],"properties":{"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom"]},"referenceId":{"type":["string","null"]},"sku":{"type":["string","null"]},"name":{"type":"string"},"description":{"type":["string","null"]},"unitPrice":{"type":"integer","minimum":0},"quantity":{"type":"integer","minimum":1},"taxAmount":{"type":"integer","minimum":0},"discountAmount":{"type":"integer","minimum":0},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["string","null"]},"position":{"type":"integer","minimum":0},"metadata":{"type":"object","additionalProperties":true}}}},"paymentTerms":{"type":"object","required":["mode"],"description":"pay_in_full | net_terms (netN 1-365) | deposit_balance (deposit percent/fixed + balanceNetN)","properties":{"mode":{"type":"string","enum":["pay_in_full","net_terms","deposit_balance"]},"netN":{"type":"integer","minimum":1,"maximum":365},"balanceNetN":{"type":"integer","minimum":1,"maximum":365},"deposit":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["percent","fixed"]},"value":{"type":"number"}}}}},"expiresAt":{"description":"ISO 8601 date-time, or null to clear"},"buyerNote":{"type":["string","null"]},"leadTime":{"type":["string","null"]},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["integer","null"],"minimum":0},"metadata":{"type":"object","additionalProperties":true},"changeSummary":{"type":["string","null"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"revId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revision":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"state":{"type":"string","enum":["working","issued","superseded"]},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"pdfStorageKey":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quotes/{id}/issue":{"post":{"tags":["Quotes"],"description":"Freeze the working revision, supersede the prior one, and propose the quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"revision":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"state":{"type":"string","enum":["working","issued","superseded"]},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"pdfStorageKey":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quotes/{id}/rotate-link":{"post":{"tags":["Quotes"],"description":"Rotate the buyer link token (invalidates the old link)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"shareToken":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quotes/{id}/comments":{"post":{"tags":["Quotes"],"description":"Add a merchant comment (shared with the buyer, or internal)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"visibility":{"type":"string","enum":["shared","internal"],"default":"shared"},"revisionId":{"type":["string","null"],"format":"uuid"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionId":{"type":["null","string"]},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorMemberId":{"type":["null","string"]},"authorName":{"type":["null","string"]},"authorEmail":{"type":["null","string"]},"body":{"type":"string"},"visibility":{"type":"string","enum":["shared","internal"]},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/carts/{id}/request-quote":{"post":{"tags":["Quotes"],"description":"Snapshot a cart's lines into a requested quote (the cart is unchanged)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerReference":{"type":["string","null"]},"note":{"type":["string","null"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"revision":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"state":{"type":"string","enum":["working","issued","superseded"]},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string","enum":["none","flat","checkout_calculated","free"]},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"pdfStorageKey":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionId":{"type":"string","format":"uuid"},"type":{"type":"string"},"referenceId":{"type":["null","string"]},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"priceSource":{"type":"string","enum":["catalog","override","custom"]},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quotes/{id}/accept":{"post":{"tags":["Quotes"],"description":"Record a rep-given acceptance (phone/email deal) and start checkout (spec §8, §9)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revisionId","acceptedByName","acceptedByEmail"],"properties":{"revisionId":{"type":"string","format":"uuid"},"acceptedByName":{"type":"string"},"acceptedByEmail":{"type":"string","format":"email"},"buyerReference":{"type":["string","null"]},"itemSelections":{"type":"array","maxItems":200,"items":{"type":"object","required":["itemId"],"properties":{"itemId":{"type":"string","format":"uuid"},"selected":{"type":"boolean"},"quantity":{"type":"integer","minimum":1}}}},"reason":{"type":["string","null"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["draft","requested","under_review","proposed","revision_requested","accepted","converted","declined","expired","archived"]},"customerId":{"type":["null","string"]},"customerEmail":{"type":["null","string"]},"buyerReference":{"type":["null","string"]},"source":{"type":"string","enum":["dashboard","api","cart","request_form"]},"sourceCartId":{"type":["null","string"]},"assignedMemberId":{"type":["null","string"]},"currency":{"type":"string"},"currentRevisionId":{"type":["null","string"]},"acceptedRevisionId":{"type":["null","string"]},"acceptedAt":{"type":["null","string"],"format":"date-time"},"checkoutSessionId":{"type":["null","string"]},"orderId":{"type":["null","string"]},"declinedAt":{"type":["null","string"],"format":"date-time"},"declinedReason":{"type":["null","string"]},"expiresAt":{"type":["null","string"],"format":"date-time"},"shareToken":{"type":"string","description":"qtl_ capability token — the buyer link is /q/{shareToken}"},"shareTokenPrefix":{"type":"string"},"firstViewedAt":{"type":["null","string"],"format":"date-time"},"lastViewedAt":{"type":["null","string"],"format":"date-time"},"internalNotes":{"type":["null","string"]},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"environmentId":{"type":"string","format":"uuid"},"total":{"type":["null","integer"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"checkoutUrl":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"410":{"description":"This resource is gone and will not come back (e.g. an expired or revoked link).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"A dependency this route needs is not configured or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-links/{token}":{"get":{"tags":["Quotes"],"description":"Get a quote by its buyer link token (public, buyer-shaped)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["in_progress","ready","being_revised","accepted","ordered","declined","expired"]},"buyerReference":{"type":["null","string"]},"currency":{"type":"string"},"expiresAt":{"type":["null","string"],"format":"date-time"},"currentRevision":{"type":["null","object"],"properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}},"revisionHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorName":{"type":["null","string"]},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"orderId":{"type":["null","string"]},"branding":{"type":["null","object"],"properties":{"logoUrl":{"type":["null","string"]},"primaryColor":{"type":["null","string"]},"merchantName":{"type":["null","string"]}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-links/{token}/view":{"post":{"tags":["Quotes"],"description":"Record a buyer view of the quote link (throttled quote.viewed webhook)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["in_progress","ready","being_revised","accepted","ordered","declined","expired"]},"buyerReference":{"type":["null","string"]},"currency":{"type":"string"},"expiresAt":{"type":["null","string"],"format":"date-time"},"currentRevision":{"type":["null","object"],"properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}},"revisionHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorName":{"type":["null","string"]},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"orderId":{"type":["null","string"]},"branding":{"type":["null","object"],"properties":{"logoUrl":{"type":["null","string"]},"primaryColor":{"type":["null","string"]},"merchantName":{"type":["null","string"]}}}}},"expiredVisit":{"type":"boolean"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-links/{token}/comments":{"post":{"tags":["Quotes"],"description":"Add a buyer comment (always shared)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"authorName":{"type":["string","null"]},"authorEmail":{"type":["string","null"],"format":"email"},"body":{"type":"string"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorName":{"type":["null","string"]},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-links/{token}/request-revision":{"post":{"tags":["Quotes"],"description":"Ask for changes instead of accepting the current proposal","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"authorName":{"type":["string","null"]},"authorEmail":{"type":["string","null"],"format":"email"},"message":{"type":["string","null"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["in_progress","ready","being_revised","accepted","ordered","declined","expired"]},"buyerReference":{"type":["null","string"]},"currency":{"type":"string"},"expiresAt":{"type":["null","string"],"format":"date-time"},"currentRevision":{"type":["null","object"],"properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}},"revisionHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorName":{"type":["null","string"]},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"orderId":{"type":["null","string"]},"branding":{"type":["null","object"],"properties":{"logoUrl":{"type":["null","string"]},"primaryColor":{"type":["null","string"]},"merchantName":{"type":["null","string"]}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-links/{token}/decline":{"post":{"tags":["Quotes"],"description":"Decline the quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"authorName":{"type":["string","null"]},"authorEmail":{"type":["string","null"],"format":"email"},"reason":{"type":["string","null"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["in_progress","ready","being_revised","accepted","ordered","declined","expired"]},"buyerReference":{"type":["null","string"]},"currency":{"type":"string"},"expiresAt":{"type":["null","string"],"format":"date-time"},"currentRevision":{"type":["null","object"],"properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}},"revisionHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorName":{"type":["null","string"]},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"orderId":{"type":["null","string"]},"branding":{"type":["null","object"],"properties":{"logoUrl":{"type":["null","string"]},"primaryColor":{"type":["null","string"]},"merchantName":{"type":["null","string"]}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-links/{token}/accept":{"post":{"tags":["Quotes"],"description":"Accept the quote and start checkout (spec §8)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revisionId","acceptedByName","acceptedByEmail"],"properties":{"revisionId":{"type":"string","format":"uuid"},"acceptedByName":{"type":"string"},"acceptedByEmail":{"type":"string","format":"email"},"buyerReference":{"type":["string","null"]},"itemSelections":{"type":"array","maxItems":200,"items":{"type":"object","required":["itemId"],"properties":{"itemId":{"type":"string","format":"uuid"},"selected":{"type":"boolean"},"quantity":{"type":"integer","minimum":1}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["in_progress","ready","being_revised","accepted","ordered","declined","expired"]},"buyerReference":{"type":["null","string"]},"currency":{"type":"string"},"expiresAt":{"type":["null","string"],"format":"date-time"},"currentRevision":{"type":["null","object"],"properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}},"revisionHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"revisionNumber":{"type":"integer"},"issuedAt":{"type":["null","string"],"format":"date-time"},"expiresAt":{"type":["null","string"],"format":"date-time"},"subtotal":{"type":"integer"},"taxTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"total":{"type":"integer"},"shippingMode":{"type":"string"},"shippingFlatAmount":{"type":["null","integer"]},"paymentTerms":{"type":"object","additionalProperties":true,"description":"{ mode: 'pay_in_full' } | { mode: 'net_terms', netN } | { mode: 'deposit_balance', deposit: { type, value }, balanceNetN }"},"depositAmount":{"type":["null","integer"]},"buyerNote":{"type":["null","string"]},"changeSummary":{"type":["null","string"]},"leadTime":{"type":["null","string"]},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"sku":{"type":["null","string"]},"name":{"type":"string"},"description":{"type":["null","string"]},"unitPrice":{"type":"integer"},"quantity":{"type":"integer"},"subtotal":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"},"optional":{"type":"boolean"},"optionalSelected":{"type":"boolean"},"qtyEditable":{"type":"boolean"},"imageUrl":{"type":["null","string"]},"position":{"type":"integer"}}}}}}},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"authorType":{"type":"string","enum":["buyer","merchant","system"]},"authorName":{"type":["null","string"]},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"orderId":{"type":["null","string"]},"branding":{"type":["null","object"],"properties":{"logoUrl":{"type":["null","string"]},"primaryColor":{"type":["null","string"]},"merchantName":{"type":["null","string"]}}}}},"checkoutUrl":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"410":{"description":"This resource is gone and will not come back (e.g. an expired or revoked link).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"A dependency this route needs is not configured or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-links/{token}/pdf":{"get":{"tags":["Quotes"],"description":"Download the quote PDF (302 redirect to a short-lived signed URL; lazy-rendered from the frozen issued revision)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"302":{"description":"Redirect to a short-lived signed URL for the rendered PDF"},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"A dependency this route needs is not configured or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-request-forms":{"post":{"tags":["Quotes"],"description":"Create a hosted RFQ intake form (token revealed once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","minLength":1,"maxLength":64},"title":{"type":["string","null"]},"introText":{"type":["string","null"]},"successMessage":{"type":["string","null"]},"redirectUrl":{"type":["string","null"],"description":"Must be http(s)"},"fields":{"type":"object","properties":{"companyName":{"type":"boolean"},"phone":{"type":"boolean"},"buyerReference":{"type":"boolean"},"lineItems":{"type":"boolean","description":"Item rows on the hosted form (default true)"},"targetPrice":{"type":"boolean","description":"Let the buyer name a target price (default false)"},"requireTurnstile":{"type":"boolean"}}}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"form":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"tokenPrefix":{"type":"string","description":"First 10 chars of the qrf_ token — the full token is shown once at create/rotate"},"isActive":{"type":"boolean"},"title":{"type":["null","string"]},"introText":{"type":["null","string"]},"successMessage":{"type":["null","string"]},"redirectUrl":{"type":["null","string"]},"fields":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"formToken":{"type":"string","description":"The raw qrf_ token — REVEAL-ONCE; hash-only stored. The hosted form URL is /q/request/{formToken}."}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Quotes"],"description":"List RFQ intake forms for the application + environment","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"tokenPrefix":{"type":"string","description":"First 10 chars of the qrf_ token — the full token is shown once at create/rotate"},"isActive":{"type":"boolean"},"title":{"type":["null","string"]},"introText":{"type":["null","string"]},"successMessage":{"type":["null","string"]},"redirectUrl":{"type":["null","string"]},"fields":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/quote-request-forms/{id}":{"patch":{"tags":["Quotes"],"description":"Update an RFQ intake form (activate/deactivate, texts, fields)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isActive":{"type":"boolean"},"title":{"type":["string","null"]},"introText":{"type":["string","null"]},"successMessage":{"type":["string","null"]},"redirectUrl":{"type":["string","null"],"description":"Must be http(s)"},"fields":{"type":"object","properties":{"companyName":{"type":"boolean"},"phone":{"type":"boolean"},"buyerReference":{"type":"boolean"},"lineItems":{"type":"boolean","description":"Item rows on the hosted form (default true)"},"targetPrice":{"type":"boolean","description":"Let the buyer name a target price (default false)"},"requireTurnstile":{"type":"boolean"}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"tokenPrefix":{"type":"string","description":"First 10 chars of the qrf_ token — the full token is shown once at create/rotate"},"isActive":{"type":"boolean"},"title":{"type":["null","string"]},"introText":{"type":["null","string"]},"successMessage":{"type":["null","string"]},"redirectUrl":{"type":["null","string"]},"fields":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-request-forms/{id}/rotate-token":{"post":{"tags":["Quotes"],"description":"Rotate the form token (old URL 404s immediately; new token revealed once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"form":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"tokenPrefix":{"type":"string","description":"First 10 chars of the qrf_ token — the full token is shown once at create/rotate"},"isActive":{"type":"boolean"},"title":{"type":["null","string"]},"introText":{"type":["null","string"]},"successMessage":{"type":["null","string"]},"redirectUrl":{"type":["null","string"]},"fields":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"formToken":{"type":"string","description":"The raw qrf_ token — REVEAL-ONCE; hash-only stored. The hosted form URL is /q/request/{formToken}."}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-request-forms/{token}/public":{"get":{"tags":["Quotes"],"description":"Public form config for the hosted RFQ page (token-authenticated)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":["null","string"]},"introText":{"type":["null","string"]},"successMessage":{"type":["null","string"]},"redirectUrl":{"type":["null","string"]},"fields":{"type":"object","properties":{"companyName":{"type":"boolean"},"phone":{"type":"boolean"},"buyerReference":{"type":"boolean"},"lineItems":{"type":"boolean"},"targetPrice":{"type":"boolean"},"requireTurnstile":{"type":"boolean"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/quote-requests":{"post":{"tags":["Quotes"],"description":"Public RFQ submission (honeypot + min-fill-time + rate limit + optional Turnstile)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["formToken","email"],"properties":{"formToken":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]},"companyName":{"type":["string","null"]},"phone":{"type":["string","null"]},"buyerReference":{"type":["string","null"]},"message":{"type":["string","null"]},"items":{"type":"array","maxItems":100,"description":"Lines the buyer is asking about. Seeded into the quote's working revision unpriced — targetUnitPrice is the buyer's ask, never the quoted price.","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1},"sku":{"type":["null","string"]},"referenceId":{"type":["null","string"]},"quantity":{"type":"integer","minimum":1},"note":{"type":["null","string"]},"targetUnitPrice":{"type":["null","integer"]},"imageUrl":{"type":["null","string"]}}}},"cartId":{"type":["string","null"],"description":"A cart the buyer already filled; its lines join the request. Resolved inside the form's own application + environment."},"website":{"type":["string","null"],"description":"Honeypot — must be empty"},"formLoadedAt":{"type":"number","description":"Client mount time (ms epoch); min fill time enforced"},"turnstileToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"submitted":{"type":"boolean"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"submitted":{"type":"boolean"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"A dependency this route needs is not configured or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/webhooks":{"post":{"tags":["Webhooks"],"description":"Register a new webhook. DEPRECATED — use POST /api/v1/webhook-endpoints (signed, Stripe-style) instead. This legacy endpoint no longer delivers events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event types (e.g. [\"order.created\", \"payment.captured\"])"},"secret":{"type":"string","description":"HMAC secret (auto-generated if omitted)"},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"deprecated":true,"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to listen for (e.g. order.created, payment.captured, or * for all)"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"failureCount":{"type":"integer"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Webhooks"],"description":"List all webhooks for the organization. DEPRECATED — use POST /api/v1/webhook-endpoints (signed, Stripe-style) instead. This legacy endpoint no longer delivers events.","deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to listen for (e.g. order.created, payment.captured, or * for all)"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"failureCount":{"type":"integer"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/webhooks/{id}":{"get":{"tags":["Webhooks"],"description":"Get a webhook by ID. DEPRECATED — use POST /api/v1/webhook-endpoints (signed, Stripe-style) instead. This legacy endpoint no longer delivers events.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to listen for (e.g. order.created, payment.captured, or * for all)"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"failureCount":{"type":"integer"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Webhooks"],"description":"Update a webhook. DEPRECATED — use POST /api/v1/webhook-endpoints (signed, Stripe-style) instead. This legacy endpoint no longer delivers events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Event types to listen for (e.g. order.created, payment.captured, or * for all)"},"isActive":{"type":"boolean"},"description":{"type":"string","nullable":true},"failureCount":{"type":"integer"},"lastTriggeredAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Webhooks"],"description":"Delete a webhook. DEPRECATED — use POST /api/v1/webhook-endpoints (signed, Stripe-style) instead. This legacy endpoint no longer delivers events.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"204":{"description":"Default Response"}}}},"/api/v1/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"description":"List delivery attempts for a webhook. DEPRECATED — use POST /api/v1/webhook-endpoints (signed, Stripe-style) instead. This legacy endpoint no longer delivers events.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","enum":["pending","success","failed","dead_letter"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"webhookId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","success","failed","dead_letter"]},"attemptCount":{"type":"integer"},"responseStatus":{"type":"integer","nullable":true},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/webhooks/{webhookId}/deliveries/{id}/retry":{"post":{"tags":["Webhooks"],"description":"Retry a failed webhook delivery. DEPRECATED — use POST /api/v1/webhook-endpoints (signed, Stripe-style) instead. This legacy endpoint no longer delivers events.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"webhookId","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"deprecated":true,"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"webhookId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","success","failed","dead_letter"]},"attemptCount":{"type":"integer"},"responseStatus":{"type":"integer","nullable":true},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/extensions":{"post":{"tags":["Extensions"],"description":"Register a new extension","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug","scopes"],"properties":{"name":{"type":"string","maxLength":100},"slug":{"type":"string","pattern":"^[a-z0-9-]+$","maxLength":100},"description":{"type":"string","maxLength":5000},"version":{"type":"string"},"author":{"type":"string"},"iconUrl":{"type":"string","format":"uri"},"homepageUrl":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Permission scopes the extension requires"},"eventSubscriptions":{"type":"array","items":{"type":"string"},"description":"Webhook event types the extension subscribes to"},"iframeUrl":{"type":"string","format":"uri","description":"HTTPS URL to embed as an iframe panel in the dashboard"},"webhookUrl":{"type":"string","format":"uri","description":"HTTPS endpoint that receives subscribed events"},"configSchema":{"type":"object","additionalProperties":true,"description":"JSON Schema defining accepted configuration"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"iconUrl":{"type":"string","format":"uri","nullable":true},"homepageUrl":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Extensions"],"description":"List available extensions","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","maxLength":100},"in":"query","name":"q","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"installable","required":false},{"schema":{"type":"string","enum":["draft","private","public"]},"in":"query","name":"lifecycle","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"iconUrl":{"type":"string","format":"uri","nullable":true},"homepageUrl":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/extensions/{id}":{"get":{"tags":["Extensions"],"description":"Get extension by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"iconUrl":{"type":"string","format":"uri","nullable":true},"homepageUrl":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Extensions"],"description":"Update extension metadata","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"author":{"type":"string"},"iconUrl":{"type":"string","format":"uri"},"homepageUrl":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri"},"webhookUrl":{"type":"string","format":"uri"},"configSchema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"iconUrl":{"type":"string","format":"uri","nullable":true},"homepageUrl":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Extensions"],"description":"Delete an extension","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/extensions/{id}/versions":{"post":{"tags":["Extensions"],"description":"Create a new draft version of an extension by snapshotting the current working-copy manifest","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["version"],"properties":{"version":{"type":"string","maxLength":50,"description":"Semantic version string, e.g. \"1.2.0\""},"changelog":{"type":"string","maxLength":2000,"description":"Human-readable changelog for this version"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","published"]},"changelog":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"publishedBy":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Extensions"],"description":"List versions for an extension, ordered newest first","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","published"]},"changelog":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"publishedBy":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}}},"required":["versions"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/extensions/{id}/versions/{vid}/publish":{"post":{"tags":["Extensions"],"description":"Publish a draft version of an extension","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"vid","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"version":{"type":"string"},"status":{"type":"string","enum":["draft","published"]},"changelog":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"publishedBy":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/extensions/{id}/lifecycle":{"post":{"tags":["Extensions"],"description":"Update the lifecycle state of an extension (draft → private → public)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lifecycle"],"properties":{"lifecycle":{"type":"string","enum":["draft","private","public"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"iconUrl":{"type":"string","format":"uri","nullable":true},"homepageUrl":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"eventSubscriptions":{"type":"array","items":{"type":"string"}},"iframeUrl":{"type":"string","format":"uri","nullable":true},"webhookUrl":{"type":"string","format":"uri","nullable":true},"configSchema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/extensions/{id}/install":{"post":{"tags":["Extensions"],"description":"Install an extension for the organization. Returns a one-time API key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"versionId":{"type":"string","format":"uuid","description":"Specific version to pin. Omit to use the latest published version."},"config":{"type":"object","additionalProperties":true,"description":"Configuration values for this installation"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"extensionName":{"type":"string","nullable":true},"extensionSlug":{"type":"string","nullable":true},"extensionIconUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"environmentSlug":{"type":"string","nullable":true},"environmentKind":{"type":"string","enum":["production","non_production"],"nullable":true},"providerEnvironment":{"type":"string","enum":["production","sandbox"],"nullable":true},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"installSequence":{"type":"integer"},"installedAt":{"type":"string","format":"date-time"},"uninstalledAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"},"apiKey":{"type":"string","description":"Raw API key (shown once)"},"webhookSigningSecret":{"type":"string","description":"Raw webhook signing secret (shown once when a managed webhook endpoint is created)","nullable":true}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/extensions/{id}/uninstall":{"post":{"tags":["Extensions"],"description":"Uninstall an extension (deactivates API key and webhooks)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/extensions/{id}/suspend":{"post":{"tags":["Extensions"],"description":"Suspend an installed extension (deactivates API key and webhooks, can be reinstalled)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"extensionName":{"type":"string","nullable":true},"extensionSlug":{"type":"string","nullable":true},"extensionIconUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"environmentSlug":{"type":"string","nullable":true},"environmentKind":{"type":"string","enum":["production","non_production"],"nullable":true},"providerEnvironment":{"type":"string","enum":["production","sandbox"],"nullable":true},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"installSequence":{"type":"integer"},"installedAt":{"type":"string","format":"date-time"},"uninstalledAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/installations/{id}/config":{"patch":{"tags":["Extensions"],"description":"Update configuration for an installed extension","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["config"],"properties":{"config":{"type":"object","additionalProperties":true}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"extensionName":{"type":"string","nullable":true},"extensionSlug":{"type":"string","nullable":true},"extensionIconUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"environmentSlug":{"type":"string","nullable":true},"environmentKind":{"type":"string","enum":["production","non_production"],"nullable":true},"providerEnvironment":{"type":"string","enum":["production","sandbox"],"nullable":true},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"installSequence":{"type":"integer"},"installedAt":{"type":"string","format":"date-time"},"uninstalledAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/installations":{"get":{"tags":["Extensions"],"description":"List installed extensions for the organization","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","enum":["active","suspended","uninstalled"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"extensionName":{"type":"string","nullable":true},"extensionSlug":{"type":"string","nullable":true},"extensionIconUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"environmentSlug":{"type":"string","nullable":true},"environmentKind":{"type":"string","enum":["production","non_production"],"nullable":true},"providerEnvironment":{"type":"string","enum":["production","sandbox"],"nullable":true},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"installSequence":{"type":"integer"},"installedAt":{"type":"string","format":"date-time"},"uninstalledAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/installations/{id}/upgrade":{"post":{"tags":["Extensions"],"description":"Upgrade an installation to a target version. Returns 409 if the new version adds scopes that require consent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetVersionId"],"properties":{"targetVersionId":{"type":"string","format":"uuid","description":"ID of the target extension version to upgrade to"},"acknowledgedNewScopes":{"type":"boolean","description":"Set to true to consent to new scopes added by the target version"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"extensionName":{"type":"string","nullable":true},"extensionSlug":{"type":"string","nullable":true},"extensionIconUrl":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"environmentId":{"type":"string","format":"uuid"},"environmentSlug":{"type":"string","nullable":true},"environmentKind":{"type":"string","enum":["production","non_production"],"nullable":true},"providerEnvironment":{"type":"string","enum":["production","sandbox"],"nullable":true},"apiKeyId":{"type":"string","format":"uuid","nullable":true},"installSequence":{"type":"integer"},"installedAt":{"type":"string","format":"date-time"},"uninstalledAt":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The request was well-formed but cannot be processed as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/installations/{id}/launch-token":{"post":{"tags":["Extensions"],"description":"Mint a short-lived RS256 session JWT for an iframe extension. The token carries full installation context and expires in 10 minutes. Re-calling this endpoint refreshes the token (no separate refresh route).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string","description":"RS256-signed session JWT"},"expiresAt":{"type":"string","format":"date-time","description":"UTC expiry timestamp"}},"required":["token","expiresAt"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"A dependency this route needs is not configured or is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/installations/{id}/webhook-secret":{"get":{"summary":"Read this installation's webhook signing secret","tags":["Extensions"],"description":"Returns the signing secret for the installation's managed webhook endpoint, so an extension can verify delivery signatures without a human copying the secret out of the dashboard. Requires authentication but no particular scope: the caller must present the installation's own API key or extension session token, or be a dashboard user permitted to manage installs. The secret is stable across uninstall/reinstall.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"installationId":{"type":"string","format":"uuid"},"installSequence":{"type":"integer"},"endpointId":{"type":"string","format":"uuid"},"url":{"type":"string"},"enabledEvents":{"type":"array","items":{"type":"string"}},"signingSecret":{"type":"string"}},"required":["installationId","endpointId","url","signingSecret"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/installations/{id}/deliveries":{"get":{"tags":["Extensions"],"description":"List webhook deliveries for an extension installation (most recent first)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"endpointId":{"type":"string","format":"uuid"},"eventId":{"type":"string","format":"uuid"},"eventType":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed","dead_letter"]},"attemptCount":{"type":"integer"},"lastStatus":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true},"deliveredAt":{"type":"string","format":"date-time","nullable":true},"environmentId":{"type":"string","format":"uuid"},"replayOf":{"type":"string","format":"uuid","nullable":true},"payload":{"type":"object","additionalProperties":true},"createdAt":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["items","total","limit","offset","hasMore"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/installations/{id}/deliveries/{deliveryId}/replay":{"post":{"tags":["Extensions"],"description":"Replay a webhook delivery for an extension installation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"deliveryId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid"},"status":{"type":"string"},"responseStatus":{"type":"integer","nullable":true},"lastError":{"type":"string","nullable":true}},"required":["deliveryId","status"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/installations/{id}/test":{"post":{"tags":["Extensions"],"description":"Send a verification ping to an extension installation webhook endpoint","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"integer","nullable":true},"error":{"type":"string","nullable":true}},"required":["ok"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/extensions/{id}/listing":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/extensions/{id}/readiness":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/extensions/{id}/reviews":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/extensions/{id}/reviews/{sid}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/extensions/{id}/reviews/{sid}/comments":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/extensions/{id}/reviews/{sid}/withdraw":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/publisher/terms":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/publisher/accept-terms":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/extensions/domains":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/extensions/domains/{id}/verify":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/affiliates/me/code":{"get":{"summary":"Get or create affiliate code","tags":["Affiliates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/affiliates/me/code/regenerate":{"post":{"summary":"Regenerate affiliate code","tags":["Affiliates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/affiliates/me/stats":{"get":{"summary":"Get affiliate stats","tags":["Affiliates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/affiliates/me/signups":{"get":{"summary":"List referred signups","tags":["Affiliates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner/applications":{"post":{"summary":"Apply for partner status","tags":["Partners"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner/me/profile":{"get":{"summary":"Get partner profile","tags":["Partners"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner/me/referrals":{"get":{"summary":"List partner referrals","tags":["Partners"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner/me/seats":{"get":{"summary":"List partner seats in client workspaces","tags":["Partners"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner/me/commissions":{"get":{"summary":"Get commission stats","tags":["Partners"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner/trials":{"post":{"summary":"Create trial for client","tags":["Partners"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner/trials/{referralId}/promote":{"post":{"summary":"Hand off client workspace to client ownership","tags":["Partners"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"referralId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/partner/trials/{referralId}/claim-billing":{"post":{"summary":"Partner claims billing responsibility","tags":["Partners"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"referralId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/partner-seats":{"get":{"summary":"List partner seats on this workspace","tags":["Partner Seats"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/partner-seats/{id}":{"patch":{"summary":"Update seat permissions","tags":["Partner Seats"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Remove a partner seat","tags":["Partner Seats"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/events/{id}":{"get":{"tags":["Events"],"description":"Get a single event by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","description":"e.g. order.created, payment.captured"},"entityType":{"type":"string","description":"e.g. order, payment, customer"},"entityId":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true},"previousData":{"type":"object","additionalProperties":true,"nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/events":{"get":{"tags":["Events"],"description":"List events (immutable audit log)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string"},"in":"query","name":"type","required":false,"description":"Filter by event type"},{"schema":{"type":"string"},"in":"query","name":"entityType","required":false,"description":"Filter by entity type"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"entityId","required":false,"description":"Filter by entity ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","description":"e.g. order.created, payment.captured"},"entityType":{"type":"string","description":"e.g. order, payment, customer"},"entityId":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true},"previousData":{"type":"object","additionalProperties":true,"nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/scopes":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/event-types":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/whoami":{"get":{"summary":"Identify the calling credential","tags":["API Keys"],"description":"Returns the credential type, granted scopes, and the workspace, application and environment the credential is pinned to. Requires authentication but no particular scope.","responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/.well-known/extension-jwks.json":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/.well-known/oauth-authorization-server":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/.well-known/oauth-protected-resource":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/oauth/clients/{clientId}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"clientId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout/sessions":{"post":{"tags":["Checkout Sessions"],"description":"Create a new hosted checkout session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["applicationId","returnUrl","cancelUrl"],"description":"Provide exactly one of `cartId` (native Throttle cart) or `externalCartId` (external cart provider). For plan-based / free-trial subscriptions the cart may be empty — pass the plan in `recurring`.","properties":{"applicationId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid"},"externalCartId":{"type":"string"},"customerEmail":{"type":"string","format":"email"},"customer":{"type":"object","additionalProperties":true,"properties":{"customerId":{"type":"string","format":"uuid"},"externalCustomerId":{"type":"string"},"email":{"type":"string","format":"email"},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"shippingAddress":{"type":"object","additionalProperties":true},"billingAddress":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true}}},"returnUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"},"allowedMethods":{"type":"array","items":{"type":"string"}},"paymentTerms":{"type":"object","additionalProperties":true,"properties":{"netN":{"type":["integer","null"],"minimum":1,"maximum":365}}},"recurring":{"type":"object","additionalProperties":true,"required":["plan","interval"],"properties":{"plan":{"type":"string"},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","minimum":0},"trialDays":{"type":"integer","minimum":0,"maximum":365},"planName":{"type":"string"},"create":{"type":"string","enum":["auto","manual"]}}},"collect":{"type":"object","additionalProperties":true,"properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"metadata":{"type":"object","additionalProperties":true},"discountCode":{"type":"string"},"clientContext":{"type":"object","additionalProperties":true}}}}},"description":"Provide exactly one of `cartId` (native Throttle cart) or `externalCartId` (external cart provider). For plan-based / free-trial subscriptions the cart may be empty — pass the plan in `recurring`."},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/checkout/sessions/{id}":{"get":{"tags":["Checkout Sessions"],"description":"Get a checkout session by ID","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Checkout Sessions"],"description":"Cancel a checkout session","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/{id}":{"get":{"tags":["Checkout Sessions"],"description":"Get a customer-facing checkout session by ID (public)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/{id}/embed-config":{"get":{"tags":["Checkout Sessions"],"description":"Get customer-facing embed config by checkout session ID (public)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/{id}/cart":{"get":{"tags":["Checkout Sessions"],"description":"Get a customer-facing checkout session cart by session ID (public)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/{id}/calculate":{"post":{"tags":["Checkout Sessions"],"description":"Calculate customer-facing checkout session totals by session ID (public)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/{id}/discount":{"post":{"tags":["Checkout Sessions"],"description":"Apply a customer-facing checkout discount by session ID (public)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Checkout Sessions"],"description":"Remove a customer-facing checkout discount by session ID (public)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout/sessions/{id}/complete":{"post":{"tags":["Checkout Sessions"],"description":"Complete a checkout session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["paymentMethod"],"properties":{"email":{"type":"string","format":"email"},"shippingAddress":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"}}},"billingAddress":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"}}},"billingSameAsShipping":{"type":"boolean"},"paymentMethod":{"type":"string","enum":["net30","card","embedded"]},"netDays":{"type":"integer","minimum":0,"maximum":365},"termsAccepted":{"type":"boolean"},"termsSnapshot":{"type":"string"},"invoiceNumber":{"type":"string"},"net30Acceptance":{"type":"object","additionalProperties":true,"properties":{"termsHash":{"type":"string"},"acceptedAt":{"type":"string"},"companyName":{"type":"string"},"billingEmail":{"type":"string","format":"email"}}},"paymentToken":{"type":"string"},"processorCheckoutSessionId":{"type":"string"},"processorTransactionId":{"type":"string"},"clientContext":{"type":"object","additionalProperties":true}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/{id}/complete":{"post":{"tags":["Checkout Sessions"],"description":"Public customer-facing complete","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["paymentMethod"],"properties":{"email":{"type":"string","format":"email"},"shippingAddress":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"}}},"billingAddress":{"type":"object","additionalProperties":true,"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"stateProvince":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string"},"phone":{"type":"string"}}},"billingSameAsShipping":{"type":"boolean"},"paymentMethod":{"type":"string","enum":["net30","card","embedded"]},"netDays":{"type":"integer","minimum":0,"maximum":365},"termsAccepted":{"type":"boolean"},"termsSnapshot":{"type":"string"},"invoiceNumber":{"type":"string"},"net30Acceptance":{"type":"object","additionalProperties":true,"properties":{"termsHash":{"type":"string"},"acceptedAt":{"type":"string"},"companyName":{"type":"string"},"billingEmail":{"type":"string","format":"email"}}},"paymentToken":{"type":"string"},"processorCheckoutSessionId":{"type":"string"},"processorTransactionId":{"type":"string"},"clientContext":{"type":"object","additionalProperties":true}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/providers/{provider}/webhooks/{connectionId}":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"provider","required":true},{"schema":{"type":"string"},"in":"path","name":"connectionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payment-providers/{provider}/webhooks":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"provider","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payment-providers/{provider}/webhooks/{connectionId}":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"provider","required":true},{"schema":{"type":"string"},"in":"path","name":"connectionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/embed-token":{"post":{"tags":["Payments"],"description":"Mint a Gr4vy Embed token for card capture. The token is scoped to a server-side checkout session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","description":"Amount in minor units (e.g. cents)"},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code"},"externalCartId":{"type":"string","description":"Optional external cart reference"},"buyerExternalIdentifier":{"type":"string","minLength":1,"description":"Optional Gr4vy buyer external identifier. When set, Gr4vy associates the resulting stored payment method with this buyer so future charges can reference it by id. Required for the platform-billing card-vault flow; omitted for one-shot checkout sessions."},"recurring":{"type":"boolean","description":"When true, this embed captures a card for recurring/merchant-initiated billing: the Gr4vy widget is rendered with paymentSource=recurring + store=true (card-only, vaulted) and the buyer is pinned for re-mint. Requires buyerExternalIdentifier. Defaults to false (one-shot payment showing all enabled methods)."},"addCard":{"type":"boolean","description":"When true (with recurring), the embed is a pure add-a-card flow: checkout-web renders the Gr4vy widget with display='addOnly' (just a new-card form, no stored methods, no checkout framing) and stores the card for the pinned buyer. Use for 'manage payment methods → add card'. Defaults to false."}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"embedToken":{"type":"string"},"checkoutSessionId":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"processorInstanceId":{"type":"string"},"merchantAccountId":{"type":"string"},"environment":{"type":"string"},"hostedUrl":{"type":"string"},"embedUrl":{"type":"string"}}},"meta":{"type":"object"}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/checkout-sessions/{id}/embed-token":{"get":{"tags":["Payments"],"description":"Re-mint a Gr4vy Embed JWT for an existing throttle checkout session. Anonymous; the session id is the only secret needed.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"embedToken":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"processorInstanceId":{"type":"string"},"merchantAccountId":{"type":"string"},"processorCheckoutSessionId":{"type":"string"},"environment":{"type":"string","enum":["sandbox","production"]},"buyerExternalIdentifier":{"type":"string"}}},"meta":{"type":"object"}}}}}}}}},"/api/v1/api-keys":{"get":{"summary":"List API keys for the calling merchant","tags":["API Keys"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"summary":"Create a new API key (Clerk JWT only)","tags":["API Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","scopes"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"scopes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","minLength":1}}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/api-keys/{id}":{"delete":{"summary":"Revoke (soft-delete) an API key","tags":["API Keys"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/api-keys/{id}/rotate":{"post":{"summary":"Rotate an API key with an overlap window (Clerk JWT only)","tags":["API Keys"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"overlapHours":{"type":"integer","minimum":1,"maximum":168,"default":24}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/oauth/authorize":{"post":{"summary":"Approve an OAuth authorization request and mint a code (Clerk JWT only)","tags":["OAuth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientId","redirectUri","scope","codeChallenge","state","workspaceId","applicationId","environmentId"],"additionalProperties":false,"properties":{"clientId":{"type":"string","minLength":1},"redirectUri":{"type":"string","minLength":1},"scope":{"type":"string","minLength":1},"codeChallenge":{"type":"string","minLength":1},"state":{"type":"string","minLength":1},"workspaceId":{"type":"string","minLength":1},"applicationId":{"type":"string","minLength":1},"environmentId":{"type":"string","minLength":1},"applicationIds":{"type":"array","maxItems":200,"items":{"type":"string","minLength":1}}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/oauth-grants":{"get":{"summary":"List OAuth grants (Connected Apps) for the caller workspace","tags":["OAuth"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/oauth-grants/{id}":{"delete":{"summary":"Revoke an OAuth grant (Connected Apps)","tags":["OAuth"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/merchants/me":{"get":{"summary":"Get current merchant","tags":["Merchants"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"patch":{"summary":"Update merchant display name. Pass `logoUrl: null` to clear the logo. To set a logo, use POST /v1/merchants/me/logo.","tags":["Merchant"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"logoUrl":{"type":"null"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/checkout-sessions/{id}/payment-methods":{"get":{"summary":"List payment methods available for a checkout session (public)","tags":["Checkout Sessions"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/connectors":{"get":{"summary":"List configured connectors for the calling merchant","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"summary":"Create a new connector for the calling merchant","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentServiceDefinitionId","displayName","fields"],"additionalProperties":false,"properties":{"paymentServiceDefinitionId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1,"maxLength":200},"fields":{"type":"array","items":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"value":{}}}},"acceptedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}},"acceptedCurrencies":{"type":"array","items":{"type":"string","minLength":3,"maxLength":3}},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/connectors/available":{"get":{"summary":"List available connector types","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/connectors/{id}":{"get":{"summary":"Get a configured connector by id","tags":["Connectors"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Update a connector for the calling merchant","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"paymentServiceDefinitionId":{"type":"string","minLength":1},"displayName":{"type":"string","minLength":1,"maxLength":200},"fields":{"type":"array","items":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string"},"value":{}}}},"acceptedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}},"acceptedCurrencies":{"type":"array","items":{"type":"string","minLength":3,"maxLength":3}},"active":{"type":"boolean"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a connector for the calling merchant","tags":["Connectors"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payment-routing":{"get":{"summary":"Get the card-transaction routing config","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"put":{"summary":"Replace the card-transaction routing config","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rules","defaultCascade"],"additionalProperties":false,"properties":{"defaultCascade":{"type":"array","items":{"type":"string","minLength":1}},"rules":{"type":"array","items":{"type":"object","required":["conditions","cascade"],"additionalProperties":false,"properties":{"conditions":{"type":"array","items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"enum":["country","cardScheme","cardSource","cardType","amount","currency","metadata","cardCountry","paymentSource"]},"op":{"type":"string"},"values":{"type":"array","items":{"type":"string","minLength":1}},"currency":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"key":{"type":"string"}}}},"cascade":{"type":"array","items":{"type":"string","minLength":1}}}}}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/routing-connectors":{"get":{"summary":"List connectors eligible for a routing cascade","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/routing-payment-methods":{"get":{"summary":"List Gr4vy payment methods available to routing/decline rules","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/other-routing":{"get":{"summary":"Get the non-card (redirect-transaction) routing config","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"put":{"summary":"Replace the non-card routing config","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rules"],"additionalProperties":false,"properties":{"rules":{"type":"array","items":{"type":"object","required":["method","connections"],"additionalProperties":false,"properties":{"method":{"type":"string","minLength":1},"conditions":{"type":"array","items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"enum":["country","cardScheme","cardSource","cardType","amount","metadata","currency","paymentMethod","cardCountry"]},"op":{"type":"string"},"values":{"type":"array","items":{"type":"string","minLength":1}},"currency":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"key":{"type":"string"}}}},"connections":{"type":"array","items":{"type":"string","minLength":1}}}}}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/card-decline":{"get":{"summary":"Get the card-transaction decline rules","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"put":{"summary":"Replace the card-transaction decline rules","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rules"],"additionalProperties":false,"properties":{"rules":{"type":"array","items":{"type":"object","required":["conditions"],"additionalProperties":false,"properties":{"conditions":{"type":"array","items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"enum":["country","cardScheme","cardSource","cardType","amount","metadata","currency","paymentMethod","cardCountry"]},"op":{"type":"string"},"values":{"type":"array","items":{"type":"string","minLength":1}},"currency":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"key":{"type":"string"}}}},"errorCode":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/other-decline":{"get":{"summary":"Get the non-card (other) decline rules","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"put":{"summary":"Replace the non-card (other) decline rules","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rules"],"additionalProperties":false,"properties":{"rules":{"type":"array","items":{"type":"object","required":["conditions"],"additionalProperties":false,"properties":{"conditions":{"type":"array","items":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"enum":["country","cardScheme","cardSource","cardType","amount","metadata","currency","paymentMethod","cardCountry"]},"op":{"type":"string"},"values":{"type":"array","items":{"type":"string","minLength":1}},"currency":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"key":{"type":"string"}}}},"errorCode":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/connectors/stripe/install-link":{"post":{"summary":"Begin Stripe one-click connect","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/connectors/stripe/connect-key":{"post":{"summary":"Complete Stripe connect by pasting the restricted key","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["secretKey"],"additionalProperties":false,"properties":{"secretKey":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/connectors/stripe/readiness":{"get":{"summary":"Raw-card (PCI) readiness for the live Stripe connection","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/connectors/stripe/connect-oauth":{"post":{"summary":"Complete Stripe connect from an OAuth authorization code","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","state"],"additionalProperties":false,"properties":{"code":{"type":"string","minLength":1},"state":{"type":"string","minLength":1}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/connectors/stripe/finalize":{"post":{"summary":"Finalize Stripe one-click connect","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accountId","stripeUserId","state","installSignature","livemode"],"additionalProperties":false,"properties":{"accountId":{"type":"string","minLength":1},"stripeUserId":{"type":"string","minLength":1},"state":{"type":"string","minLength":1},"installSignature":{"type":"string","minLength":1},"livemode":{"type":"boolean"},"extraFields":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/stripe-app/webhooks":{"post":{"summary":"Inbound Stripe App webhook (uninstall handling)","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/payment-methods":{"get":{"summary":"List active payment methods derived from configured connectors","tags":["Payment Methods"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"customerId","required":false},{"schema":{"type":"integer"},"in":"query","name":"cartTotal","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/bigcommerce/connections":{"get":{"summary":"List BigCommerce connections for the calling merchant","tags":["BigCommerce"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/bigcommerce/connect":{"post":{"summary":"Connect a BC store via static credentials","tags":["BigCommerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["storeHash","accessToken"],"additionalProperties":false,"properties":{"storeHash":{"type":"string","minLength":4,"maxLength":64},"accessToken":{"type":"string","minLength":10}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/bigcommerce/connections/{id}/retry":{"post":{"summary":"Retry webhook registration for a setup_failed connection","tags":["BigCommerce"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/bigcommerce/connections/{id}":{"delete":{"summary":"Disconnect a BC store (soft-delete; 90-day cron hard-deletes after retention)","tags":["BigCommerce"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-endpoints":{"get":{"summary":"List configured outbound webhook endpoints","tags":["Webhooks: Outbound"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"summary":"Create an outbound webhook endpoint","tags":["Webhooks: Outbound"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","enabledEvents"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"enabledEvents":{"type":"array","items":{"type":"string","enum":["cart.created","cart.updated","cart.item_added","cart.item_updated","cart.item_removed","cart.shipping_selected","cart.shipping_cleared","cart.discount_applied","cart.discount_removed","cart.tax_recomputed","cart.checkout_started","cart.converted","cart.abandoned","cart.merged","order.created","order.updated","order.fulfilled","order.cancelled","order.closed","order.sync_failed","order.sync_conflict","return.created","return.updated","quote.requested","quote.proposed","quote.viewed","quote.comment_added","quote.revision_requested","quote.declined","quote.accepted","quote.converted","quote.expired","payment.pending","payment.authorized","payment.captured","payment.failed","payment.voided","payment.refunded","payment.partially_refunded","payment.refund_failed","payment.vaulted","payment.disputed","payment.dispute_cleared","fulfillment.created","fulfillment.completed","fulfillment.cancelled","fulfillment.shipment.shipped","fulfillment.shipment.delivered","fulfillment.digital.delivered","subscription.created","subscription.activated","subscription.updated","subscription.plan_changed","subscription.plan_change_scheduled","subscription.paused","subscription.resumed","subscription.cancelled","subscription.renewed","subscription.past_due","subscription.payment_failed","subscription.backup_pm_used","subscription.create_failed","subscription.trial_blocked","discount.applied","discount.removed","customer.created","customer.updated","customer.deleted","customer.payment_method_added","customer.payment_method_removed","invoice.past_due","shipping_tax.provider_connection.unhealthy","workspace.payment_method.added","workspace.payment_method.removed","workspace.payment_method.default_changed","workspace.payment_method.backup_set","workspace.payment_method.backup_used","workspace.platform_charge.succeeded","workspace.platform_charge.failed","workspace.trial_expired","cart.expired","extension.review.submitted","extension.review.approved","extension.review.changes_requested","extension.review.rejected","extension.review.comment_added","extension.review.auto_approved","extension.published_public","extension.unpublished","payment.authorization_failed","payment.capture_failed","payment.void_failed","order.completed"]},"minItems":1,"uniqueItems":true}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/webhook-endpoints/coverage":{"get":{"summary":"Event types emitted recently with no active subscriber","tags":["Webhooks: Outbound"],"description":"Reports subscribable event types this application emitted in the lookback window that no active webhook endpoint is subscribed to. Use it to catch handlers wired up for events that can never arrive.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"in":"query","name":"days","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-endpoints/{id}":{"patch":{"summary":"Update a webhook endpoint (URL, events, or active flag)","tags":["Webhooks: Outbound"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"enabledEvents":{"type":"array","items":{"type":"string","enum":["cart.created","cart.updated","cart.item_added","cart.item_updated","cart.item_removed","cart.shipping_selected","cart.shipping_cleared","cart.discount_applied","cart.discount_removed","cart.tax_recomputed","cart.checkout_started","cart.converted","cart.abandoned","cart.merged","order.created","order.updated","order.fulfilled","order.cancelled","order.closed","order.sync_failed","order.sync_conflict","return.created","return.updated","quote.requested","quote.proposed","quote.viewed","quote.comment_added","quote.revision_requested","quote.declined","quote.accepted","quote.converted","quote.expired","payment.pending","payment.authorized","payment.captured","payment.failed","payment.voided","payment.refunded","payment.partially_refunded","payment.refund_failed","payment.vaulted","payment.disputed","payment.dispute_cleared","fulfillment.created","fulfillment.completed","fulfillment.cancelled","fulfillment.shipment.shipped","fulfillment.shipment.delivered","fulfillment.digital.delivered","subscription.created","subscription.activated","subscription.updated","subscription.plan_changed","subscription.plan_change_scheduled","subscription.paused","subscription.resumed","subscription.cancelled","subscription.renewed","subscription.past_due","subscription.payment_failed","subscription.backup_pm_used","subscription.create_failed","subscription.trial_blocked","discount.applied","discount.removed","customer.created","customer.updated","customer.deleted","customer.payment_method_added","customer.payment_method_removed","invoice.past_due","shipping_tax.provider_connection.unhealthy","workspace.payment_method.added","workspace.payment_method.removed","workspace.payment_method.default_changed","workspace.payment_method.backup_set","workspace.payment_method.backup_used","workspace.platform_charge.succeeded","workspace.platform_charge.failed","workspace.trial_expired","cart.expired","extension.review.submitted","extension.review.approved","extension.review.changes_requested","extension.review.rejected","extension.review.comment_added","extension.review.auto_approved","extension.published_public","extension.unpublished","payment.authorization_failed","payment.capture_failed","payment.void_failed","order.completed"]},"minItems":1,"uniqueItems":true},"isActive":{"type":"boolean"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Soft-delete a webhook endpoint (sets deletedAt; excludes from list and dispatch)","tags":["Webhooks: Outbound"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-endpoints/{id}/rotate-secret":{"post":{"summary":"Rotate the signing secret for a webhook endpoint (reveal-once).","tags":["Webhooks: Outbound"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-deliveries":{"get":{"summary":"Recent webhook delivery attempts (debug / audit log). Paginated via limit + offset.","tags":["Webhooks: Outbound"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"endpointId","required":false},{"schema":{"type":"string"},"in":"query","name":"orderId","required":false},{"schema":{"type":"string","enum":["pending","delivered","failed","dead_letter"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"eventType","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-deliveries/{id}":{"get":{"summary":"Fetch a single webhook delivery (full envelope + signature scheme) for debugging.","tags":["Webhooks: Outbound"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-endpoints/{id}/test":{"post":{"summary":"Send a synthetic, signed test delivery to this endpoint.","tags":["Webhooks: Outbound"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"eventType":{"type":"string","enum":["cart.created","cart.updated","cart.item_added","cart.item_updated","cart.item_removed","cart.shipping_selected","cart.shipping_cleared","cart.discount_applied","cart.discount_removed","cart.tax_recomputed","cart.checkout_started","cart.converted","cart.abandoned","cart.merged","order.created","order.updated","order.fulfilled","order.cancelled","order.closed","order.sync_failed","order.sync_conflict","return.created","return.updated","quote.requested","quote.proposed","quote.viewed","quote.comment_added","quote.revision_requested","quote.declined","quote.accepted","quote.converted","quote.expired","payment.pending","payment.authorized","payment.captured","payment.failed","payment.voided","payment.refunded","payment.partially_refunded","payment.refund_failed","payment.vaulted","payment.disputed","payment.dispute_cleared","fulfillment.created","fulfillment.completed","fulfillment.cancelled","fulfillment.shipment.shipped","fulfillment.shipment.delivered","fulfillment.digital.delivered","subscription.created","subscription.activated","subscription.updated","subscription.plan_changed","subscription.plan_change_scheduled","subscription.paused","subscription.resumed","subscription.cancelled","subscription.renewed","subscription.past_due","subscription.payment_failed","subscription.backup_pm_used","subscription.create_failed","subscription.trial_blocked","discount.applied","discount.removed","customer.created","customer.updated","customer.deleted","customer.payment_method_added","customer.payment_method_removed","invoice.past_due","shipping_tax.provider_connection.unhealthy","workspace.payment_method.added","workspace.payment_method.removed","workspace.payment_method.default_changed","workspace.payment_method.backup_set","workspace.payment_method.backup_used","workspace.platform_charge.succeeded","workspace.platform_charge.failed","workspace.trial_expired"]},"data":{"type":"object","additionalProperties":true}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-deliveries/{id}/replay":{"post":{"summary":"Replay a delivery (re-fires same payload with new signature).","tags":["Webhooks: Outbound"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/merchants/me/external-cart-ack":{"post":{"summary":"Mark this merchant as a non-BC (\"external cart\") merchant so onboarding can complete.","tags":["Merchant"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/merchants/me/finish-onboarding":{"post":{"summary":"Mark the merchant as having finished the onboarding wizard.","tags":["Merchant"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/merchants/me/settings/net30":{"patch":{"summary":"Update Net30 invoice billing settings.","tags":["Merchant"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"invoicePrefix":{"type":"string","minLength":3,"maxLength":10,"pattern":"^[A-Z0-9]+$"},"defaultNetDays":{"type":"integer","minimum":0,"maximum":365},"termsText":{"type":["string","null"],"maxLength":5000}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/merchants/me/logo":{"post":{"summary":"Upload a merchant logo (multipart/form-data, field: logo).","tags":["Merchant"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/workspaces/{workspaceId}/applications/{applicationId}/logo":{"post":{"summary":"Upload an application logo.","tags":["Applications"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete an application logo.","tags":["Applications"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/email/asset-upload":{"post":{"summary":"Upload an image asset for inline use in an email template (multipart, field: file).","tags":["Email Templates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/extensions/icon-upload":{"post":{"summary":"Upload an extension icon (multipart/form-data, field: file).","tags":["Extensions"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/extensions/screenshot-upload":{"post":{"summary":"Upload a marketplace listing screenshot (multipart/form-data, field: file).","tags":["Extensions"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/assets/{*}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/audit-log":{"get":{"summary":"Recent admin actions taken on this merchant","tags":["Audit"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"environmentId","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/fulfillments/{id}/digital/upload":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/fulfillments/{id}/digital/download":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}/invoice/download":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/net30/connection":{"get":{"summary":"Get the calling merchant's Net30 connection","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"summary":"Create the calling merchant's Net30 connection","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invoicePrefix","defaultNetDays","enabled"],"additionalProperties":false,"properties":{"invoicePrefix":{"type":"string","minLength":3,"maxLength":10,"pattern":"^[A-Z0-9]{3,10}$"},"defaultNetDays":{"type":"integer","minimum":0,"maximum":365},"termsText":{"type":["string","null"],"maxLength":5000},"maxOrderTotal":{"type":["number","null"],"minimum":0},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/net30/connection/{id}":{"patch":{"summary":"Update the calling merchant's Net30 connection","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"invoicePrefix":{"type":"string","minLength":3,"maxLength":10,"pattern":"^[A-Z0-9]{3,10}$"},"defaultNetDays":{"type":"integer","minimum":0,"maximum":365},"termsText":{"type":["string","null"],"maxLength":5000},"maxOrderTotal":{"type":["number","null"],"minimum":0},"enabled":{"type":"boolean"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Soft-delete (disable) the calling merchant's Net30 connection","tags":["Connectors"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/net30/eligible-customers":{"get":{"summary":"List the calling merchant's Net30 eligible customers","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"summary":"Add a customer to the Net30 eligible allowlist","tags":["Connectors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customerId"],"additionalProperties":false,"properties":{"customerId":{"type":"string","format":"uuid"},"notes":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/net30/eligible-customers/{customerId}":{"delete":{"summary":"Remove a customer from the Net30 eligible allowlist","tags":["Connectors"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"customerId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}/notes":{"patch":{"summary":"Update free-text notes on a payment (5000 char max).","tags":["Payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["notes"],"additionalProperties":false,"properties":{"notes":{"type":["string","null"],"maxLength":5000}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}/dispute":{"post":{"summary":"Open a dispute on a Net30 payment.","tags":["Payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"additionalProperties":false,"properties":{"reason":{"type":"string","minLength":1,"maxLength":500}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}/dispute/clear":{"post":{"summary":"Clear an open dispute on a payment (leaves reason + opened_at for audit).","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}/backdate-due-date":{"post":{"summary":"Backdate metadata.dueDate so a Net-N invoice falls into a specific aging bucket. Demo/test tool only.","tags":["Payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["daysPastDue"],"additionalProperties":false,"properties":{"daysPastDue":{"type":"integer","minimum":1,"maximum":365}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/invoices/aging":{"get":{"summary":"AR aging report: outstanding Net30 payments bucketed by days past due.","tags":["Payments"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/analytics/orders-timeseries":{"get":{"summary":"Order count + captured gross revenue over a date range, bucketed by day/week/month in a requested timezone (default trailing 30 days, UTC, daily).","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."},{"schema":{"type":"string","enum":["previous_period","previous_year","none"]},"in":"query","name":"compareTo","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/analytics/business-summary":{"get":{"summary":"Business summary: orders/revenue, subscription MRR, receivables, quotes — week/month/quarter, compared to the prior period of equal length.","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"period","required":false},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/analytics/attention-digest":{"get":{"summary":"Point-in-time digest: open disputes, subscriptions in dunning, overdue invoices, and webhooks with degraded delivery health.","tags":["Analytics"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/analytics/products":{"get":{"summary":"Best-selling products over a date range, by revenue or units sold. Product identity is the external reference id when the merchant sent one, the line item name otherwise.","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."},{"schema":{"type":"string"},"in":"query","name":"by","required":false,"description":"Sort key: revenue or units. Defaults to revenue."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Max rows to return. Defaults to 20."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/analytics/customers":{"get":{"summary":"Customer growth over a date range: signups per day/week/month, new-vs-returning order split, and the highest-value customers in the window.","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."},{"schema":{"type":"string"},"in":"query","name":"topBy","required":false,"description":"Sort key for top customers: revenue or orders. Defaults to revenue."},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"in":"query","name":"topLimit","required":false,"description":"Max top-customers rows to return. Defaults to 10."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/analytics/revenue-breakdown":{"get":{"summary":"Revenue split by one dimension over a date range — payment method, order source, or currency. Amounts are gross; refunds are not deducted.","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."},{"schema":{"type":"string"},"in":"query","name":"dimension","required":false,"description":"Required. Breakdown dimension: paymentMethod, source, or currency."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/analytics/funnel":{"get":{"summary":"Checkout funnel over a date range: carts created, checkout sessions started, orders completed, with the drop-off between each stage.","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/analytics/subscriptions":{"get":{"summary":"Subscription movement over a date range: new subscriptions, cancellations, and net MRR change per bucket (day/week/month).","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/analytics/discounts":{"get":{"summary":"Discount code performance over a date range: redemption count, revenue on discounted orders, and total discount given per code.","tags":["Analytics"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"query","name":"from","required":false,"description":"ISO 8601 start of range (exclusive lower bound)."},{"schema":{"type":"string"},"in":"query","name":"to","required":false,"description":"ISO 8601 end of range (exclusive upper bound). Defaults to now."},{"schema":{"type":"string"},"in":"query","name":"days","required":false,"description":"Shorthand for from = to - days. Ignored when from is set."},{"schema":{"type":"string"},"in":"query","name":"timezone","required":false,"description":"IANA timezone name or UTC offset (e.g., America/New_York, +05:30) for bucket boundaries. Defaults to UTC."},{"schema":{"type":"string","enum":["day","week","month"]},"in":"query","name":"groupBy","required":false,"description":"Bucket size. Defaults to day."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Max rows to return. Defaults to 20."}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/returns":{"post":{"summary":"Open a return (RMA) against an order for a subset of its line items.","tags":["Returns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["lineItemId","quantity"],"properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1}}}},"reason":{"type":"string","maxLength":1000},"restock":{"type":"boolean"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["requested","approved","rejected","received","completed","cancelled"]},"reason":{"type":["null","string"]},"restock":{"type":"boolean"},"refundAmount":{"type":"integer"},"refundPaymentId":{"type":["null","string"]},"notes":{"type":["null","string"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string"},"quantity":{"type":"integer"},"amount":{"type":"integer"}}}}}}}}}}}}},"get":{"summary":"List an order's returns.","tags":["Returns"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["requested","approved","rejected","received","completed","cancelled"]},"reason":{"type":["null","string"]},"restock":{"type":"boolean"},"refundAmount":{"type":"integer"},"refundPaymentId":{"type":["null","string"]},"notes":{"type":["null","string"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string"},"quantity":{"type":"integer"},"amount":{"type":"integer"}}}}}}}}}}}}}}},"/api/v1/returns/{id}":{"get":{"summary":"Get a return and its items.","tags":["Returns"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["requested","approved","rejected","received","completed","cancelled"]},"reason":{"type":["null","string"]},"restock":{"type":"boolean"},"refundAmount":{"type":"integer"},"refundPaymentId":{"type":["null","string"]},"notes":{"type":["null","string"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string"},"quantity":{"type":"integer"},"amount":{"type":"integer"}}}}}}}}}}}}}},"/api/v1/returns/{id}/transition":{"post":{"summary":"Transition a return: approve | reject | receive | complete | cancel.","tags":["Returns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"type":"string","enum":["approve","reject","receive","complete","cancel"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["requested","approved","rejected","received","completed","cancelled"]},"reason":{"type":["null","string"]},"restock":{"type":"boolean"},"refundAmount":{"type":"integer"},"refundPaymentId":{"type":["null","string"]},"notes":{"type":["null","string"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string"},"quantity":{"type":"integer"},"amount":{"type":"integer"}}}}}}}}}}}}}},"/api/v1/returns/{id}/exchange":{"post":{"summary":"Complete a return as an exchange: create a replacement order for the swapped items and settle the price difference (charge if more, refund if less).","tags":["Returns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"items":{"type":"object","additionalProperties":false,"required":["name","unitPrice","quantity"],"properties":{"referenceId":{"type":"string"},"name":{"type":"string","minLength":1},"unitPrice":{"type":"integer","minimum":0},"quantity":{"type":"integer","minimum":1},"type":{"type":"string"}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/line-items":{"patch":{"summary":"Add, update, or remove line items on an order. On a captured order the total delta is charged (increase) or refunded (decrease) automatically.","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"add":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","unitPrice","quantity"],"properties":{"referenceId":{"type":"string"},"name":{"type":"string","minLength":1},"unitPrice":{"type":"integer","minimum":0},"quantity":{"type":"integer","minimum":1},"type":{"type":"string"},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"],"description":"What this item needs before it counts as delivered. Omit to resolve from `type` and `metadata`. `digital` and `access_grant` are delivered automatically on payment capture; `none` means there is nothing to deliver."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"update":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["lineItemId"],"properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"unitPrice":{"type":"integer","minimum":0}}}},"remove":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/embed-config":{"get":{"summary":"Get the merchant embed config (allowlisted parent origins + branding)","tags":["Embed"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"allowedOrigins":{"type":"array","items":{"type":"string"}},"primaryColor":{"type":["null","string"]},"logoUrl":{"type":["null","string"]},"merchantName":{"type":["null","string"]},"storefrontBaseUrl":{"type":["null","string"]},"cartRecoveryUrlTemplate":{"type":["null","string"]},"cartAbandonmentThresholdMinutes":{"type":["null","integer"]},"checkoutLinkBaseUrl":{"type":["null","string"]}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"put":{"summary":"Update the merchant embed config","tags":["Embed"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"allowedOrigins":{"type":"array","items":{"type":"string","minLength":1},"maxItems":20,"uniqueItems":true},"primaryColor":{"type":"string"},"logoUrl":{"type":"string","format":"uri"},"merchantName":{"type":"string","minLength":1,"maxLength":100},"storefrontBaseUrl":{"type":["string","null"],"description":"Absolute base URL of your storefront (e.g. \"https://yourstore.com\"). Relative line-item imageUrls are resolved against it. Pass null to clear; when unset, the first allowedOrigin is used."},"cartRecoveryUrlTemplate":{"type":["string","null"],"description":"Absolute https URL template used to build the recovery link in abandoned-cart emails. Must contain a \"{cartId}\" placeholder, e.g. \"https://yourstore.com/cart?c={cartId}\". Pass null to clear; when unset, abandoned carts are recovered via the cart.abandoned webhook only (no recovery email)."},"cartAbandonmentThresholdMinutes":{"type":["integer","null"],"description":"Minutes of inactivity before an open/checkout cart is treated as abandoned by the sweep. Range 15–129600 (90 days). Pass null to clear; when unset, the platform default of 1440 (24h) applies."},"checkoutLinkBaseUrl":{"type":["string","null"],"description":"Absolute https URL your buyers land on for quote links and cart recovery links, e.g. \"https://yourstore.com\". Throttle appends its own path (\"/q/{shareToken}\", \"/r/{cartSessionToken}\"), so host those routes with the Throttle SDKs. Pass null to clear; when unset, links point at Throttle-hosted checkout."}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/tracking-settings":{"get":{"summary":"Get per-environment analytics tracking settings (secrets masked)","tags":["Tracking"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ga4MeasurementId":{"type":["null","string"]},"metaPixelId":{"type":["null","string"]},"ga4ApiSecret":{"type":["null","string"],"description":"Masked (last 4)"},"metaCapiAccessToken":{"type":["null","string"],"description":"Masked (last 4)"},"serverSideEnabled":{"type":"boolean"},"requireConsent":{"type":"boolean"}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"put":{"summary":"Update per-environment analytics tracking settings. Omitted fields are unchanged; empty string clears a field.","tags":["Tracking"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ga4MeasurementId":{"type":["string","null"]},"metaPixelId":{"type":["string","null"]},"ga4ApiSecret":{"type":["string","null"]},"metaCapiAccessToken":{"type":["string","null"]},"serverSideEnabled":{"type":"boolean"},"requireConsent":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ga4MeasurementId":{"type":["null","string"]},"metaPixelId":{"type":["null","string"]},"ga4ApiSecret":{"type":["null","string"],"description":"Masked (last 4)"},"metaCapiAccessToken":{"type":["null","string"],"description":"Masked (last 4)"},"serverSideEnabled":{"type":"boolean"},"requireConsent":{"type":"boolean"}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/clerk/webhooks/user-created":{"post":{"summary":"Clerk user.created webhook (Svix-verified)","tags":["Webhooks: Inbound"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/mcp":{"get":{"responses":{"200":{"description":"Default Response"}}},"head":{"responses":{"200":{"description":"Default Response"}}},"trace":{"responses":{"200":{"description":"Default Response"}}},"delete":{"responses":{"200":{"description":"Default Response"}}},"options":{"responses":{"200":{"description":"Default Response"}}},"patch":{"responses":{"200":{"description":"Default Response"}}},"put":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/oauth/token":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/resend/webhooks":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/email/templates":{"get":{"summary":"List all email template definitions with merchant overrides","tags":["Email Templates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/email/templates/{key}":{"get":{"summary":"Get a single email template definition with merchant override","tags":["Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Upsert a merchant override for an email template","tags":["Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete merchant override for an email template (reset to default)","tags":["Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/email/templates/{key}/preview":{"post":{"summary":"Render a template with sample data for preview","tags":["Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/email/test-send":{"post":{"summary":"Send a test email to the authenticated admin (bypasses opt-out + cooldown)","tags":["Email Templates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/applications/{applicationId}/email/templates":{"get":{"summary":"List application email template definitions with application overrides","tags":["Application Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/applications/{applicationId}/email/templates/{key}":{"get":{"summary":"Get an application email template definition with application override","tags":["Application Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"summary":"Upsert an application override for an email template","tags":["Application Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete application override for an email template","tags":["Application Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/applications/{applicationId}/email/templates/{key}/preview":{"post":{"summary":"Render an application template with sample data for preview","tags":["Application Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true},{"schema":{"type":"string"},"in":"path","name":"key","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/applications/{applicationId}/email/test-send":{"post":{"summary":"Send an application-scoped test email to the authenticated admin","tags":["Application Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/applications/{applicationId}/email/messages":{"get":{"summary":"List recent email messages for the application","tags":["Application Email Templates"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/email/messages":{"get":{"summary":"List recent email messages for the merchant","tags":["Email Templates"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/merchants/me/email-settings":{"patch":{"summary":"Update workspace email settings","tags":["Email Settings"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"summary":"Get workspace email settings","tags":["Email Settings"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/merchants/me/members/{id}/preferences":{"patch":{"summary":"Update per-member email preferences","tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/applications/{applicationId}/email-settings":{"get":{"summary":"Get application email settings","tags":["Application Email Settings"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Update application email settings","tags":["Application Email Settings"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/email/sender-domain":{"post":{"summary":"Register a custom sending domain via Resend","tags":["Email Settings"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"summary":"Get the current custom sending domain state","tags":["Email Settings"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"delete":{"summary":"Disconnect and remove the custom sending domain","tags":["Email Settings"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/email/sender-domain/verify":{"post":{"summary":"Trigger a domain verification check via Resend","tags":["Email Settings"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/applications/{applicationId}/email/sender-domain":{"post":{"summary":"Register an application custom sending domain via Resend","tags":["Application Email Settings"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Get the current application custom sending domain state","tags":["Application Email Settings"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Disconnect and remove the application custom sending domain","tags":["Application Email Settings"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/applications/{applicationId}/email/sender-domain/verify":{"post":{"summary":"Trigger an application domain verification check via Resend","tags":["Application Email Settings"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/merchants/me/invites":{"post":{"summary":"[legacy] Invite a team member (delegates to team-service)","tags":["Team"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"summary":"[legacy] List merchant team members","tags":["Team"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/merchants/me/invites/{id}/resend":{"post":{"summary":"[legacy] Resend an invite","tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/merchants/me/invites/{id}/revoke":{"post":{"summary":"[legacy] Revoke an invite or remove a member","tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{workspaceId}/invites":{"post":{"summary":"Create a team invite","tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{workspaceId}/invites/{id}/resend":{"post":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{workspaceId}/invites/{id}/revoke":{"post":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/invites/accept":{"post":{"tags":["Team"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/invites/pending":{"get":{"tags":["Team"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/workspaces/{workspaceId}/members":{"get":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{workspaceId}/members/me":{"get":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{workspaceId}/members/{memberId}":{"patch":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"memberId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"memberId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{workspaceId}/members/{memberId}/applications/{applicationId}":{"delete":{"tags":["Team"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"memberId","required":true},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/auth/permissions":{"get":{"tags":["Auth"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/notifications/unread-count":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/notifications":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/notifications/{id}/read":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/notifications/{id}/unread":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/notifications/{id}/archive":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/notifications/read-all":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/me/preferences":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"patch":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/workspaces/{wsId}/support/tickets":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{wsId}/support/tickets/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{wsId}/support/tickets/{id}/comments":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{wsId}/support/tickets/{id}/read":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{wsId}/support/unread-count":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{wsId}/support/attachments/presign":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{wsId}/support/attachments/{attachmentId}/confirm":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"wsId","required":true},{"schema":{"type":"string"},"in":"path","name":"attachmentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/support/dispatch-webhook":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/workspaces":{"post":{"tags":["Workspaces"],"description":"Create a new workspace; the calling user becomes owner","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","pattern":"^[a-z0-9-]+$","description":"URL-safe identifier, globally unique"},"email":{"type":"string","description":"Owner email (used for member row); falls back to empty string if omitted"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"tags":["Workspaces"],"description":"List workspaces the authenticated user is a member of","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"workspaceRole":{"type":"string","enum":["owner","workspace_admin","member"]},"accessSource":{"type":"string","enum":["direct","partner_seat"]}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/workspaces/{workspaceId}":{"get":{"tags":["Workspaces"],"description":"Get a single workspace by ID (must be a member)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Workspaces"],"description":"Update workspace name or slug (must be a member)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Workspaces"],"description":"Delete a workspace (must be a member; pass ?force=true to cascade-delete applications)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"force","required":false},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"204":{"description":"Default Response"},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceId}/environments":{"get":{"tags":["Workspace Environments"],"description":"List workspace environments","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"includeArchived","required":false},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["production","non_production"]},"providerEnvironment":{"type":"string","enum":["production","sandbox"]},"status":{"type":"string","enum":["active","archived"]},"isSystem":{"type":"boolean"},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"tags":["Workspace Environments"],"description":"Create a custom non-production sandbox environment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["slug","name"],"properties":{"slug":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":120}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["production","non_production"]},"providerEnvironment":{"type":"string","enum":["production","sandbox"]},"status":{"type":"string","enum":["active","archived"]},"isSystem":{"type":"boolean"},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceId}/environments/{environmentId}":{"delete":{"tags":["Workspace Environments"],"description":"Archive a custom workspace environment","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"environmentId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["production","non_production"]},"providerEnvironment":{"type":"string","enum":["production","sandbox"]},"status":{"type":"string","enum":["active","archived"]},"isSystem":{"type":"boolean"},"archivedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{id}/go-live":{"post":{"summary":"Flip a sandbox workspace to production. Multi-precondition gated.","tags":["Workspace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["acceptedProductionTermsAt"],"properties":{"acceptedProductionTermsAt":{"type":"string","format":"date-time"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/workspaces/{workspaceId}/applications":{"post":{"tags":["Applications"],"description":"Create a new application in a workspace (must be a member)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name","slug"],"properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","pattern":"^[a-z0-9-]+$","description":"URL-safe identifier, unique within the workspace"},"currency":{"type":"string","default":"USD"},"displayName":{"type":["string","null"],"minLength":1,"maxLength":100},"brandColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"allowedOrigins":{"type":"array","items":{"type":"string","minLength":1},"maxItems":20,"uniqueItems":true}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string"},"isActive":{"type":"boolean"},"displayName":{"type":["null","string"]},"logoUrl":{"type":["null","string"]},"brandColor":{"type":["null","string"]},"allowedOrigins":{"type":"array","items":{"type":"string"}},"timezone":{"type":["null","string"],"description":"IANA zone the merchant reads this store in; null means UTC."},"quoteNumberPrefix":{"type":"string"},"nextQuoteSeq":{"type":"integer"},"orderNumberPrefix":{"type":"string"},"nextOrderSeq":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Applications"],"description":"List applications in a workspace (must be a member)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string"},"isActive":{"type":"boolean"},"displayName":{"type":["null","string"]},"logoUrl":{"type":["null","string"]},"brandColor":{"type":["null","string"]},"allowedOrigins":{"type":"array","items":{"type":"string"}},"timezone":{"type":["null","string"],"description":"IANA zone the merchant reads this store in; null means UTC."},"quoteNumberPrefix":{"type":"string"},"nextQuoteSeq":{"type":"integer"},"orderNumberPrefix":{"type":"string"},"nextOrderSeq":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/workspaces/{workspaceId}/applications/{applicationId}":{"get":{"tags":["Applications"],"description":"Get a single application by ID (must be a workspace member)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string"},"isActive":{"type":"boolean"},"displayName":{"type":["null","string"]},"logoUrl":{"type":["null","string"]},"brandColor":{"type":["null","string"]},"allowedOrigins":{"type":"array","items":{"type":"string"}},"timezone":{"type":["null","string"],"description":"IANA zone the merchant reads this store in; null means UTC."},"quoteNumberPrefix":{"type":"string"},"nextQuoteSeq":{"type":"integer"},"orderNumberPrefix":{"type":"string"},"nextOrderSeq":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Applications"],"description":"Update application identity, branding, timezone, or document numbering (must be a workspace member). Timezone and numbering are per workspace environment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"currency":{"type":"string"},"isActive":{"type":"boolean"},"displayName":{"type":["string","null"],"minLength":1,"maxLength":100},"brandColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"allowedOrigins":{"type":"array","items":{"type":"string","minLength":1},"maxItems":20,"uniqueItems":true},"timezone":{"type":["string","null"],"description":"IANA timezone name (e.g. \"America/Los_Angeles\"). null resets to UTC. Applies to rendered surfaces only — API timestamps stay ISO 8601 UTC."},"quoteNumberPrefix":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,11}$"},"nextQuoteSeq":{"type":"integer","minimum":1,"maximum":2147483647},"orderNumberPrefix":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,11}$"},"nextOrderSeq":{"type":"integer","minimum":1,"maximum":2147483647}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string"},"isActive":{"type":"boolean"},"displayName":{"type":["null","string"]},"logoUrl":{"type":["null","string"]},"brandColor":{"type":["null","string"]},"allowedOrigins":{"type":"array","items":{"type":"string"}},"timezone":{"type":["null","string"],"description":"IANA zone the merchant reads this store in; null means UTC."},"quoteNumberPrefix":{"type":"string"},"nextQuoteSeq":{"type":"integer"},"orderNumberPrefix":{"type":"string"},"nextOrderSeq":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Conflict with the current state of the resource — the request was not applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Applications"],"description":"Delete an application (must be a workspace member)","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"workspaceId","required":true},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"204":{"description":"Default Response"},"403":{"description":"Authenticated but not permitted — the credential lacks the scope or role this route requires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/billing/state":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/subscribe":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"paymentMethodToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/cancel":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/resume":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/payment-methods":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentMethodToken"],"additionalProperties":false,"properties":{"paymentMethodToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/payment-methods/{id}":{"patch":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["primary","backup"]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/billing/gr4vy-embed-token":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/provider-status":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/invoices":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/invoices/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/billing/invoices/{id}/receipt.pdf":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/billing/plan-history":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/overview":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/billing/platform-revenue":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/platform-billing/run-renewal":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/platform-billing/run-dunning":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/workspaces":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/workspaces/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/extend-trial":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/promote-partner":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/partner-applications":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/partner-applications/{id}/reject":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/demote-partner":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/force-tier-override":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/refund-charge":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/cancel-immediately":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/bring-legacy-into-billing":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/suspend":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/reactivate":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/audit-log":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/me/staff-status":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/staff":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/staff/{email}":{"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"email","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/payment-methods":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/invoices":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/usage":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/subscription-timeline":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/members":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/workspaces/{id}/members/{memberId}":{"patch":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"memberId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"memberId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/admin/extensions/reviews/{sid}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews/{sid}/claim":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews/{sid}/comments":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews/{sid}/install-candidate":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews/{sid}/uninstall-candidate":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews/{sid}/approve":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews/{sid}/request-changes":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/reviews/{sid}/reject":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sid","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/admin/extensions/{id}/unpublish":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"http://localhost:3000","description":"Local development"}],"security":[{"apiKey":[]},{"bearerAuth":[]}],"tags":[{"name":"Organizations","description":"Organization management"},{"name":"Stores","description":"Store management (multi-store per organization)"},{"name":"Customers","description":"Customer CRUD, addresses, payment methods"},{"name":"Carts","description":"Shopping carts, line items, checkout"},{"name":"Orders","description":"Order lifecycle and state machine"},{"name":"Payments","description":"Payment creation and manual marking (authorize, capture, void, refund)"},{"name":"Fulfillments","description":"Fulfillment management (shipment, digital, access, service, in-person)"},{"name":"Subscriptions","description":"Subscription lifecycle management"},{"name":"Discounts","description":"Discount codes and validation"},{"name":"Webhooks","description":"Webhook registration, delivery tracking, retries"},{"name":"Events","description":"Immutable audit log of all state changes"},{"name":"Extensions","description":"Extension marketplace, installation, and configuration"},{"name":"API Keys","description":"Self-serve API key CRUD (Clerk-authed)"},{"name":"Merchants","description":"Merchant identity and config"},{"name":"Webhooks: Inbound","description":"External webhooks consumed by throttle"},{"name":"Connectors","description":"Per-merchant payment connector CRUD (Gr4vy proxy)"},{"name":"Payment Methods","description":"Aggregated view of payment methods enabled by configured connectors"},{"name":"BigCommerce","description":"BigCommerce store connection (CLI-driven)"},{"name":"Webhooks: Outbound","description":"Per-merchant outbound webhook endpoints + delivery audit log"}]}