{"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","description":"Quote this when reporting a problem; it identifies the exact request. Either `req_<uuid>` or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."}}}},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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},"subscriptionId":{"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/me/subscriptions/{id}":{"get":{"summary":"One of the authenticated customer's subscriptions, with the card that renews it","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/subscriptions/{id}/retry-charge":{"post":{"summary":"Charge a past-due subscription now, against the card it renews on","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/subscriptions/{id}/payment-method":{"patch":{"summary":"Set the card this subscription renews on (the customer's default card stays as it is)","tags":["Payment Methods"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["paymentMethodId"],"properties":{"paymentMethodId":{"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/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":1,"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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":1,"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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,"maximum":10000,"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."},"recurring":{"type":"object","additionalProperties":false,"required":["plan"],"description":"Makes this line a subscription (type is forced to `subscription`). One subscription is created per line when the checkout completes; at most 10 per cart. Send `interval`, or `intervalUnit` + `intervalCount` (1 hour to 1 year). `totalPayments` (2-60) makes it an installment plan; `trialDays` (0-365) adds a free trial and cannot be combined with `totalPayments`. A trial line is stored with `unitPrice` 0 and the price you send on `recurring.amount`. `schedule` (2-60 payments) makes it an installment plan whose payments differ: row 0 is the unitPrice charged today; each later row has amount + intervalUnit + intervalCount. Exclusive with interval/totalPayments/trialDays unless they agree. Terms cannot be changed later; remove the line and add it again.","properties":{"plan":{"type":"string"},"planName":{"type":["string","null"],"maxLength":255},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"number"},"totalPayments":{"type":["integer","null"]},"trialDays":{"type":["integer","null"]},"scheduleUnitTotal":{"type":["number","null"]},"schedule":{"type":["array","null"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["string","null"]},"intervalCount":{"type":["number","null"]}}}}}},"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"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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,"maximum":10000},"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"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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)"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"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."},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"subscriptionId":{"type":"string","format":"uuid","nullable":true,"description":"The subscription this line created. Null until the checkout completes."},"imageUrl":{"type":"string","nullable":true},"position":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}},"netN":{"type":"integer","minimum":0,"maximum":365,"nullable":true},"buyerVatNumber":{"type":"string","nullable":true},"taxReverseCharge":{"type":"boolean"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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"},"vatCode":{"type":"string","nullable":true},"taxName":{"type":"string","nullable":true},"rateTypeCode":{"type":"string","nullable":true},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"}}},"patch":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/cart-sessions/{id}/summary":{"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/capabilities":{"get":{"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/companies":{"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}":{"patch":{"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/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/tax-codes":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/locations":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/validate-address":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/documents/customs":{"post":{"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/tax-classifications":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/tax-classifications/{id}":{"patch":{"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/ecm/test-connection":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/customers/{id}/exemption-certificates":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{id}/exemption-certificates/{certificateId}/download":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"certificateId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{id}/exemption-certificates/request":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{id}/exemption-certificates/{certificateId}":{"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"certificateId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/ecm/exempt-reasons":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/ecm/exposure-zones":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/provider-calls":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/provider-calls/stats":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/shipping-tax/provider-calls/{id}":{"get":{"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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","disputed","expired","charged_back"]},"in":"query","name":"paymentStatus","required":false},{"schema":{"type":"string","enum":["one_time","recurring","mixed"]},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["not_shipped","in_transit","delivered","returned"]},"in":"query","name":"delivery","required":false,"description":"Where the goods are. Derived from shipment and return records, not an order column: `not_shipped` = nothing has left yet on an order that still owes goods (status `processing` or `partially_fulfilled`, no returns), `in_transit` = something shipped and something has not arrived, `delivered` = every shipment arrived, `returned` = any items came back (a partial return included)."},{"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 linked to this subscription: through one of their lines (every subscription a checkout creates), `subscriptionId`, or the legacy `metadata.subscription_id` pointer. Covers the signup order, renewals and plan-change charges."},{"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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"],"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","processing","disputed","expired","charged_back"]},"in":"query","name":"paymentStatus","required":false},{"schema":{"type":"string","enum":["one_time","recurring","mixed"]},"in":"query","name":"type","required":false},{"schema":{"type":"string","enum":["not_shipped","in_transit","delivered","returned"]},"in":"query","name":"delivery","required":false,"description":"Where the goods are. Derived from shipment and return records, not an order column: `not_shipped` = nothing has left yet on an order that still owes goods (status `processing` or `partially_fulfilled`, no returns), `in_transit` = something shipped and something has not arrived, `delivered` = every shipment arrived, `returned` = any items came back (a partial return included)."},{"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 linked to this subscription: through one of their lines (every subscription a checkout creates), `subscriptionId`, or the legacy `metadata.subscription_id` pointer. Covers the signup order, renewals and plan-change charges."},{"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"}}}},"/api/v1/orders/{id}":{"get":{"tags":["Orders"],"description":"Get an order by ID (includes line items, plus `capturedAmount` and `refundedAmount`)","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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"capturedAmount":{"type":"integer","description":"What this order actually collected, before refunds. Not the same as `total` on a partially-paid order."},"refundedAmount":{"type":"integer","description":"How much of the captured money went back. `paymentStatus: \"refunded\"` says a full refund happened; this says how much it was."}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"}}}}}}},"/api/v1/orders/{id}/cancel":{"post":{"tags":["Orders"],"description":"Cancel an order. Authorized payments and unpaid Net-N invoices (`method: net30`, status `authorized` or `pending`) 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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"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 and unpaid Net-N invoices (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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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 and unpaid Net-N invoices, 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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/comp":{"post":{"tags":["Orders"],"description":"Write off the order's remaining balance. Money already captured stays captured; the buyer is never charged and no processor is contacted. `compAmount` is set to the balance outstanding; `total` is NOT reduced, because the order is still a sale of that size — the comp is a credit recorded against it. What the buyer owes is `total - compAmount`, so `paymentStatus` settles at `captured` and `displayStatus` reads \"… · Comped\".","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"additionalProperties":false,"properties":{"reason":{"type":"string","minLength":3,"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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"paymentActions":{"type":"array","description":"Payment settlement performed by the comp: voids of anything still claiming the waived balance — open authorizations, and unpaid Net-N invoices, whose buyers are also emailed. Captured money is never touched. Failures never undo the comp.","items":{"type":"object","properties":{"paymentId":{"type":"string"},"action":{"type":"string","enum":["void"]},"status":{"type":"string","enum":["succeeded","failed"]},"error":{"type":"string"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/comp/reverse":{"post":{"tags":["Orders"],"description":"Undo a comp. The order owes what it owed again: `compAmount` returns to 0 (`total` never moved) and `paymentStatus` falls back out of `captured` on its own. Side effects of the comp are NOT rewound: an authorization voided at the processor cannot be un-voided, so collecting the restored balance needs a new payment, and a tax document voided or returned at the provider needs a manual re-file (`POST /v1/tax-documents/{id}/retry`).","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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/hold":{"post":{"tags":["Orders"],"description":"Freeze an order operationally. A hold is a flag, not a stage: `status`, `paymentStatus` and `displayStatus` are unchanged, and nothing about money or delivery moves. Holdable while the order is still live (`pending`, `processing`, `partially_fulfilled`, `fulfilled`); a draft, cancelled or closed order answers 422 `order_not_holdable`. Re-holding with the same reason is a no-op and does not restart `heldAt`; a new reason overwrites it. `heldBy` comes from the caller's credentials and cannot be supplied.","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","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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/hold/release":{"post":{"tags":["Orders"],"description":"Lift a hold. All four hold columns are cleared together. An order that is not held answers 422 `order_not_on_hold`.","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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/timeline":{"get":{"tags":["Orders"],"description":"Everything that happened to this order, newest first: status changes, payment attempts (including declines, which write no status-history row), and fulfillment events. One row shape for every source.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","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","required":["id","at","kind","title","source"],"properties":{"id":{"type":"string"},"at":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["status","payment","fulfillment","hold"]},"title":{"type":"string"},"detail":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"source":{"type":"string","enum":["manual","state_machine","fulfillment","payment","migration","provider"]},"actorType":{"type":"string","enum":["user","system","integration","api_key"]},"actorName":{"type":"string"},"reason":{"type":"string"},"subscriptionId":{"type":"string"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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/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","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionIds":{"type":"array","items":{"type":"string","format":"uuid"}},"subscriptionId":{"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"},"lineItems":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","cheque","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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/payments/record":{"post":{"tags":["Payments"],"description":"Record money that arrived outside Throttle — cash, a bank transfer to the merchant's own account, a cheque. The payment is created already captured, so the order advances exactly as a processor capture would. Excluded from billable GMV. When the order's balance is on an unpaid Net-N invoice (`method: net30`, status `authorized` or `pending`), the payment goes to that invoice: an amount equal to the invoice settles it — the invoice payment itself is captured, as marking it paid does (`payment.captured`), the recorded method/reference/note are kept in its `metadata.recordedPayment`, and that payment is returned; a smaller amount is recorded as its own payment and the invoice then bills what is left; a larger amount is refused with 422 `amount_exceeds_invoice`, a payment in another currency than the invoice with 422 `currency_mismatch`. If the invoice changes while the payment is being recorded (a concurrent payment, edit or cancellation, or the same full payment submitted twice), the call answers 409 `invoice_changed` and records nothing; send an `Idempotency-Key` to make retries safe.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","method"],"additionalProperties":false,"properties":{"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"method":{"type":"string","enum":["cash","bank_transfer","cheque","external"]},"receivedAt":{"type":"string","format":"date-time"},"reference":{"type":"string","maxLength":120},"note":{"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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"409":{"description":"`invoice_changed`: the unpaid Net-N invoice changed while the payment was being recorded (a concurrent payment, edit or cancellation, or a double submit). Nothing was recorded; reload and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"`invalid_order_state` (the order is cancelled or closed), `amount_exceeds_invoice` (more than the unpaid Net-N invoice the balance is on; record the invoice amount, then any excess) or `currency_mismatch` (not the invoice currency).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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 an order. Spread across its captured payments, newest capture first, when the order was paid in instalments.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Partial refund amount (defaults to everything still refundable on the order)"},"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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"}}}}}}},"/api/v1/payments/{id}/void":{"post":{"tags":["Payments"],"description":"Void an authorized payment, or cancel an unpaid Net-N invoice (`method: net30`, status `authorized` or `pending`). A pending card payment is still in flight at the processor and cannot be voided; captured money must be refunded.","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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/mark-failed":{"post":{"tags":["Payments"],"description":"Record that a payment failed with no processor involved — a cheque that bounced, a wire that never arrived, a buyer who abandoned a 3DS challenge. Only `pending` and `processing` payments can be marked failed: captured money must be refunded, and a live authorization must be voided so the hold is released.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Why the money never arrived. Stored on the payment and shown in the timeline."}}}}}},"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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}}}}}}}}}},"422":{"description":"The request was well-formed but cannot be processed as asked.","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","processing","captured","failed","voided","expired","refunded","partially_refunded"]},"errorCode":{"type":["null","string"]},"errorMessage":{"type":["null","string"],"description":"Why the payment failed. For a manually-marked failure this is the reason the merchant gave."},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","cheque","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"},"disputeOutcome":{"type":["null","string"],"enum":["won","lost",null]},"disputeClosedAt":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"shipment":{"type":"object","description":"Shipment detail to seed at creation; only accepted when type is 'shipment'. A trackingNumber here fires fulfillment.shipment.shipped right after fulfillment.created, exactly as the first PATCH .../shipment that sets one would. Omit it to record tracking later.","properties":{"carrier":{"type":"string"},"serviceLevel":{"type":"string"},"trackingNumber":{"type":"string"},"trackingUrl":{"type":"string","format":"uri"},"labelUrl":{"type":"string","format":"uri"},"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"}}},"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"}}},"weightValue":{"type":"number"},"weightUnit":{"type":"string"},"shippingCost":{"type":"integer","minimum":0,"description":"In cents"},"estimatedDelivery":{"description":"ISO 8601 date-time"},"shippedAt":{"description":"ISO 8601 date-time. Defaults to now when a trackingNumber is supplied."},"externalId":{"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":"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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/fulfillments/{id}/delivered":{"post":{"tags":["Fulfillments"],"description":"Record that a shipment arrived. Writes `shipments.actualDelivery`, which surfaces as the order's `Delivered` label and fires `fulfillment.shipment.delivered`. Refuses with `422 fulfillment_not_shipped` before carrier handoff and `409 already_delivered` on a second call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"deliveredAt":{"type":"string","format":"date-time","description":"When the parcel arrived. Defaults to now."}}}}}},"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"},"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},"actualDelivery":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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/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},"actualDelivery":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","currentPeriodStart"],"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","description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":"string","description":"Cadence unit. Send with intervalCount instead of, or together with, interval."},"intervalCount":{"type":"number","description":"Cadence count: every N units. At most one year (8760 hours, 365 days, 52 weeks, 12 months)."},"totalPayments":{"type":"integer","description":"Makes this an installment plan of exactly this many payments (2 to 60). Cannot be combined with trialEnd or changed later."},"amount":{"type":"integer","minimum":0,"description":"Subscription amount in the smallest currency unit (e.g. cents). Required unless `schedule` is sent."},"schedule":{"type":"array","description":"A custom installment plan: 2–60 payments. Row 0 is charged now and has no gap; each later row has amount + intervalUnit + intervalCount (its gap after the previous payment, 1 hour to 1 year). Exclusive with interval, totalPayments and trialEnd. amount (if sent) must equal schedule[0].amount; currentPeriodEnd is derived.","items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"number"}}}},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 currency code (defaults to USD). Normalised to upper case; must match the application’s configured currency (422 currency_mismatch otherwise)."},"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. Must be after currentPeriodStart and in the future (a small clock-skew grace is allowed) — a past currentPeriodEnd is never renewed."},"trialEnd":{"format":"date-time","description":"ISO 8601 date-time when the trial ends (omit if no trial). Cannot be before currentPeriodStart."},"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 in both directions: the order gets `subscriptionId` (and the legacy `metadata.subscription_id`), and this subscription's first invoice gets `orderId`. 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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","unpaid","completed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"]},"in":"query","name":"interval","required":false,"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},{"schema":{"type":"boolean"},"in":"query","name":"installment","required":false,"description":"true: only installment plans; false: only ongoing subscriptions"},{"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":"string","description":"Cadence unit. Send with intervalCount instead of, or together with, interval."},"intervalCount":{"type":"number","description":"Cadence count: every N units. At most one year (8760 hours, 365 days, 52 weeks, 12 months)."},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/invoices/{invoiceId}/refund":{"post":{"tags":["Subscriptions"],"description":"Refund one of a subscription's billing cycles","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["intent"],"properties":{"amount":{"type":"integer","description":"Minor units. Omit to refund everything still outstanding on the cycle."},"reason":{"type":"string"},"intent":{"type":"string","enum":["money_only","refund_and_cancel"],"description":"`money_only` returns the money and keeps billing; `refund_and_cancel` also ends the subscription immediately. Required — there is no default."}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"invoiceId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/subscriptions/{id}/payment-method":{"patch":{"tags":["Subscriptions"],"description":"Set the saved card this one subscription renews on. The customer's default card and their other subscriptions stay as they are.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["paymentMethodId"],"properties":{"paymentMethodId":{"type":"string","format":"uuid","description":"One of the subscription customer's saved cards in this environment: active, in date, and vaulted for merchant-initiated charges."}}}}}},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"}}}}}}},"/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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/retry-charge":{"post":{"tags":["Subscriptions"],"description":"Retry a past-due subscription's failed renewal charge immediately","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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/waive-period":{"post":{"tags":["Subscriptions"],"description":"Forgive a past-due subscription's current period — settle it at zero and advance","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"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","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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","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","description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":"string","description":"Cadence unit. Send with intervalCount instead of, or together with, interval."},"intervalCount":{"type":"number","description":"Cadence count: every N units. At most one year (8760 hours, 365 days, 52 weeks, 12 months)."},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}},"proration":{"type":"object","properties":{"creditCents":{"type":"integer"},"chargedCents":{"type":"integer"},"fullAmount":{"type":"integer"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}},"proration":{"type":"object","properties":{"creditCents":{"type":"integer"},"chargedCents":{"type":"integer"},"fullAmount":{"type":"integer"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"refund":{"type":"string","enum":["none","prorated","last_cycle"],"default":"none","description":"Money to return alongside an immediate cancellation. `prorated` credits the unused part of the current period, capped at what was actually paid for it — if nothing was taken for the current period the subscription is still cancelled, with a refund of 0. `last_cycle` returns the whole last paid cycle. Rejected when atPeriodEnd is true, and with 409 invalid_state on a subscription that is already cancelled or completed."}}}}}},"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","unpaid","completed"]},"planReference":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","biweekly","monthly","quarterly","yearly","custom"],"description":"A named interval, or \"custom\" when intervalUnit/intervalCount describe any other cadence"},"intervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit: every intervalCount of these. A named interval carries its shorthand (monthly → month)."},"intervalCount":{"type":["null","integer"]},"billingAnchorAt":{"type":["null","string"],"format":"date-time"},"totalPayments":{"type":["null","integer"],"description":"Installment plans only: the fixed number of payments. null for an ongoing subscription."},"paymentsMade":{"type":"integer","description":"Installment plans only: payments counted so far (charges and waived periods)."},"completedAt":{"type":["null","string"],"format":"date-time"},"pendingIntervalUnit":{"type":["null","string"],"enum":["hour","day","week","month",null],"nullable":true,"description":"Cadence unit of the scheduled plan change; null when none is scheduled."},"pendingIntervalCount":{"type":["null","integer"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","description":"#688 — number of seats. Per-seat price is amount; the period charge is amount × quantity."},"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},"paymentMethodId":{"type":["null","string"],"format":"uuid","description":"The saved card renewals, retries and plan-change charges try first (the card used at checkout). Null = the customer's default card. A charge that cannot use it falls back to the default card."},"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}}},"taxCategory":{"type":"string","nullable":true,"description":"The tax category frozen from the checkout line that created this subscription (its `metadata.taxCategory`). Every renewal is quoted and filed with it, and it survives plan changes. Null when the line had none: renewals then use the default category."},"paymentSchedule":{"type":["null","array"],"description":"Installment plans only: every payment, in order. Equal plans are synthesized. dueAt is an estimate and moves after a late payment or a pause.","items":{"type":"object","properties":{"index":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"net":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","integer"]},"status":{"type":"string","enum":["paid","due","upcoming"]},"dueAt":{"type":["null","string"],"format":"date-time"}}}},"scheduleTotal":{"type":["null","integer"],"description":"Installment plans only: the sum of every payment, after discount, before tax."},"nextPaymentAmount":{"type":["null","integer"],"description":"The next payment after discount, before tax; null when nothing more will be charged."},"renewalIssue":{"type":["null","object"],"additionalProperties":false,"description":"Read-only. Set by the renewal job when renewals are failing (system_error — including charge_unverified, a charge that has no final answer yet and is read back on each run), when a card was charged but the renewal could not be recorded (orphan_charge), or when a charge has had no final answer for 12 hours (payment_review). Charges are paused while orphan_charge or payment_review is set, and the manual retry, waive and immediate-change actions also refuse while a charge is unverified.","properties":{"kind":{"type":"string","enum":["system_error","orphan_charge","payment_review"]},"reason":{"type":"string","enum":["tax_quote_failed","internal_error","period_not_advanced","charge_unverified","config_error","record_failed","charge_unresolved"],"description":"Stable code for what went wrong: tax_quote_failed, internal_error, period_not_advanced, charge_unverified or config_error (system_error), record_failed (orphan_charge), charge_unresolved (payment_review). `message` is a fixed sentence for it."},"count":{"type":"integer"},"firstAt":{"type":"string","format":"date-time"},"lastAt":{"type":"string","format":"date-time"},"message":{"type":"string"},"alertedAt":{"type":["null","string"],"format":"date-time"},"charge":{"type":"object","additionalProperties":false,"properties":{"transactionId":{"type":["null","string"]},"amount":{"type":"integer"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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},"recurring":{"type":["object","null"],"additionalProperties":false,"required":["plan"],"description":"Makes this line a subscription (type is forced to subscription). Send interval, or intervalUnit + intervalCount (1 hour to 1 year). totalPayments (2-60) makes it an installment plan; trialDays (0-365) adds a free trial, not combinable with totalPayments. At most 10 per quote, card pay-in-full quotes only (enforced at issue).","properties":{"plan":{"type":"string"},"planName":{"type":["string","null"],"maxLength":255},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"number"},"totalPayments":{"type":["integer","null"]},"trialDays":{"type":["integer","null"]},"schedule":{"type":["array","null"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["string","null"]},"intervalCount":{"type":["number","null"]}}}}}}}}},"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},"collect":{"type":"object","description":"Address steps the hosted checkout shows after acceptance. Omit to leave unchanged; null on a flag restores the derived default.","properties":{"shippingAddress":{"type":["boolean","null"]},"billingAddress":{"type":["boolean","null"]}}},"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"]},"collectShipping":{"type":["null","boolean"]},"collectBilling":{"type":["null","boolean"]},"collect":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"collectDefault":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"]},"collectShipping":{"type":["null","boolean"]},"collectBilling":{"type":["null","boolean"]},"collect":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"collectDefault":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","declined"]},"declinedReason":{"type":["string","null"],"description":"With status 'declined': the reason shown to the buyer."}}}}}},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"]},"collectShipping":{"type":["null","boolean"]},"collectBilling":{"type":["null","boolean"]},"collect":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"collectDefault":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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},"recurring":{"type":["object","null"],"additionalProperties":false,"required":["plan"],"description":"Makes this line a subscription (type is forced to subscription). Send interval, or intervalUnit + intervalCount (1 hour to 1 year). totalPayments (2-60) makes it an installment plan; trialDays (0-365) adds a free trial, not combinable with totalPayments. At most 10 per quote, card pay-in-full quotes only (enforced at issue).","properties":{"plan":{"type":"string"},"planName":{"type":["string","null"],"maxLength":255},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"number"},"totalPayments":{"type":["integer","null"]},"trialDays":{"type":["integer","null"]},"schedule":{"type":["array","null"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["string","null"]},"intervalCount":{"type":["number","null"]}}}}}}}}},"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},"collect":{"type":"object","description":"Address steps the hosted checkout shows after acceptance. Omit to leave unchanged; null on a flag restores the derived default.","properties":{"shippingAddress":{"type":["boolean","null"]},"billingAddress":{"type":["boolean","null"]}}},"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"]},"collectShipping":{"type":["null","boolean"]},"collectBilling":{"type":["null","boolean"]},"collect":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"collectDefault":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"]},"collectShipping":{"type":["null","boolean"]},"collectBilling":{"type":["null","boolean"]},"collect":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"collectDefault":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"}}}},"422":{"description":"The request was well-formed but cannot be processed as asked.","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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"]},"collectShipping":{"type":["null","boolean"]},"collectBilling":{"type":["null","boolean"]},"collect":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"collectDefault":{"type":"object","properties":{"shippingAddress":{"type":"boolean"},"billingAddress":{"type":"boolean"}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}}},"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"]},"orderTotals":{"type":["null","object"],"properties":{"orderNumber":{"type":["null","string"]},"paymentStatus":{"type":["null","string"]},"subtotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"taxTotal":{"type":"integer"},"total":{"type":"integer"},"taxIncludedInTotal":{"type":"integer"}}},"checkoutUrl":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}}},"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"]},"orderTotals":{"type":["null","object"],"properties":{"orderNumber":{"type":["null","string"]},"paymentStatus":{"type":["null","string"]},"subtotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"taxTotal":{"type":"integer"},"total":{"type":"integer"},"taxIncludedInTotal":{"type":"integer"}}},"checkoutUrl":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}}},"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"]},"orderTotals":{"type":["null","object"],"properties":{"orderNumber":{"type":["null","string"]},"paymentStatus":{"type":["null","string"]},"subtotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"taxTotal":{"type":"integer"},"total":{"type":"integer"},"taxIncludedInTotal":{"type":"integer"}}},"checkoutUrl":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}}},"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"]},"orderTotals":{"type":["null","object"],"properties":{"orderNumber":{"type":["null","string"]},"paymentStatus":{"type":["null","string"]},"subtotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"taxTotal":{"type":"integer"},"total":{"type":"integer"},"taxIncludedInTotal":{"type":"integer"}}},"checkoutUrl":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}},"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"},"recurring":{"type":["null","object"],"description":"Subscription terms, or null for a one-time line. Paying the accepted quote creates one subscription per line, quantity = seats. unitPrice is the renewal price; a line with trialDays > 0 counts 0 toward the total due at acceptance.","properties":{"plan":{"type":"string"},"planName":{"type":["null","string"]},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"integer"},"totalPayments":{"type":["null","integer"]},"trialDays":{"type":"integer"},"schedule":{"type":["null","array"],"items":{"type":"object","properties":{"amount":{"type":"number"},"intervalUnit":{"type":["null","string"]},"intervalCount":{"type":["null","number"]}}}}}}}}}}}},"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"]},"orderTotals":{"type":["null","object"],"properties":{"orderNumber":{"type":["null","string"]},"paymentStatus":{"type":["null","string"]},"subtotal":{"type":"integer"},"discountTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"taxTotal":{"type":"integer"},"total":{"type":"integer"},"taxIncludedInTotal":{"type":"integer"}}},"checkoutUrl":{"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/checkout":{"post":{"tags":["Quotes"],"description":"Return an accepted quote to a live checkout session (spec §8.2)","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":{"checkoutUrl":{"type":"string"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"}}}},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"hasClientCredentials":{"type":"boolean"},"installCallbackUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"hasClientCredentials":{"type":"boolean"},"installCallbackUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"hasClientCredentials":{"type":"boolean"},"installCallbackUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"hasClientCredentials":{"type":"boolean"},"installCallbackUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/client-credentials":{"post":{"summary":"Issue (or rotate) client credentials for a catalog extension","tags":["Extensions"],"description":"Generates a new clientId/clientSecret pair so the extension can fetch its own per-install credentials with no human copy-pasting secrets. Only the secret's SHA-256 digest is stored — the raw secret is returned here once and never again. Calling this again on an extension that already has credentials rotates them (the previous secret stops verifying immediately). Dashboard-only: requires `extensions:write` plus the develop permission check, and is not on the extension_client allow-list.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"installCallbackUrl":{"type":"string","format":"uri","description":"HTTPS endpoint that receives the signed install callback. Plain http:// is refused."}}}}}},"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":{"clientId":{"type":"string"},"clientSecret":{"type":"string","description":"Raw client secret (shown once)"},"installCallbackUrl":{"type":"string","nullable":true}},"required":["clientId","clientSecret"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"}}}},"422":{"description":"The request was well-formed but cannot be processed as asked.","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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/scripts":{"get":{"summary":"List an extension's buyer-facing scripts","tags":["Extensions"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create or replace a buyer-facing script on an extension","tags":["Extensions"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/extensions/{id}/scripts/{scriptId}":{"patch":{"summary":"Update a buyer-facing script","tags":["Extensions"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"scriptId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a buyer-facing script","tags":["Extensions"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"scriptId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"hasClientCredentials":{"type":"boolean"},"installCallbackUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"acknowledgedNewScripts":{"type":"boolean","description":"Consent for scripts the target version adds or escalates (new script, dom tier, wider consent category, higher PII grade, or a new external domain)."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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, the extension's own client credential (Basic clientId:clientSecret), 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"},"previousSecretExpiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["installationId","endpointId","url","signingSecret"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/rotate-webhook-secret":{"post":{"summary":"Rotate this installation's webhook signing secret","tags":["Extensions"],"description":"Mints a new signing secret for the installation's managed webhook endpoint and returns it once. For `graceSeconds` (default 86400, max 604800) every delivery is signed with both the outgoing and the new secret — one `v1=` digest each, new last — so a receiver that verifies against every digest never fails a delivery, and one that keeps only the last digest verifies from the moment it holds the new secret. `graceSeconds: 0` revokes the old secret immediately (use for a leaked secret). A signed `extension.webhook_secret_rotated` event is delivered to the endpoint. Same authorization as reading the secret: the installation's own API key or session token, the extension's own client credential (Basic clientId:clientSecret) — the intended path for an extension rotating a secret it believes has leaked — or a dashboard user permitted to manage installs. A session token and an extension-client credential both require the installation to still be `active`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"graceSeconds":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}}}}},"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"},"endpointId":{"type":"string","format":"uuid"},"signingSecret":{"type":"string"},"previousSecretExpiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["installationId","endpointId","signingSecret","previousSecretExpiresAt"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/api-key":{"post":{"summary":"Mint a fresh API key for this installation and grace-expire its predecessor","tags":["Extensions"],"description":"API keys are hashed at rest, so there is nothing to read back — this issues a NEW key with the scopes of the installation's pinned version and returns the raw value once. The key it replaces keeps working for `graceSeconds` (default 86400, max 604800) via `api_keys.expires_at`, so an extension that restarts mid-delivery never locks itself out. Same authorization as the webhook-secret routes: the installation's own extension-client credential, or a dashboard user permitted to manage installs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"graceSeconds":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}}}}},"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"},"apiKey":{"type":"string"},"keyPrefix":{"type":"string"},"previousKeyExpiresAt":{"type":"string","format":"date-time","nullable":true}},"required":["installationId","apiKey","keyPrefix","previousKeyExpiresAt"]},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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/me/installations":{"get":{"summary":"List this extension's own installations","tags":["Extensions"],"description":"Lets an extension enumerate its own installs with no human copy-pasting secrets. This is the recovery path if an install callback is dropped, never configured, or the extension loses its datastore. `extension_client`-only: any other credential gets 404, not 403 — we do not confirm this route exists to a credential with no business here.","parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"installationId":{"type":"string","format":"uuid"},"extensionId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"installSequence":{"type":"integer"},"versionId":{"type":"string","format":"uuid","nullable":true},"installedAt":{"type":"string","format":"date-time","nullable":true}},"required":["installationId","extensionId","workspaceId","applicationId","environmentId","status","installSequence"]}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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/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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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}/revoke-handoff":{"post":{"summary":"Undo a handoff while the client ownership invite is outstanding","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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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/openai-apps-challenge":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/.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"],"properties":{"plan":{"type":"string"},"interval":{"type":"string"},"intervalUnit":{"type":"string"},"intervalCount":{"type":"number"},"totalPayments":{"type":"integer","description":"Makes this an installment plan of exactly this many payments (2 to 60)."},"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":"query","name":"parentOrigin","required":false,"description":"Origin of the page embedding the checkout. When sent, the response adds `parentOriginAllowed`: whether that origin is on the application's allowed origins, wildcard entries included."},{"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}/validate-address":{"post":{"tags":["Checkout Sessions"],"description":"Validate a customer-facing checkout address 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"],"description":"`embedded` completes a card payment taken by the payment embed; `net30` issues an invoice on terms. `card` names the card category in `allowedMethods` but is not a completion rail: it is rejected with 422 `payment_method_not_supported`. Use `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"}}},"paymentMethodId":{"type":"string","description":"Charge a card the customer already saved instead of collecting a new one. Ownership is verified against this session's customer before anything is charged; a card belonging to anyone else is refused."},"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","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"redirectUrl":{"type":["null","string"]},"orderId":{"type":["null","string"]},"paymentId":{"type":["null","string"]},"paymentStatus":{"type":["null","string"]},"subscriptionId":{"type":["null","string"],"description":"Set only when the checkout created exactly one subscription."},"subscriptionIds":{"type":"array","items":{"type":"string"},"description":"Every subscription this checkout created, in line order."}}}}}}}}},"/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"],"description":"`embedded` completes a card payment taken by the payment embed; `net30` issues an invoice on terms. `card` names the card category in `allowedMethods` but is not a completion rail: it is rejected with 422 `payment_method_not_supported`. Use `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"}}},"paymentMethodId":{"type":"string","description":"Charge a card the customer already saved instead of collecting a new one. Ownership is verified against this session's customer before anything is charged; a card belonging to anyone else is refused."},"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","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"redirectUrl":{"type":["null","string"]},"orderId":{"type":["null","string"]},"paymentId":{"type":["null","string"]},"paymentStatus":{"type":["null","string"]},"subscriptionId":{"type":["null","string"],"description":"Set only when the checkout created exactly one subscription."},"subscriptionIds":{"type":"array","items":{"type":"string"},"description":"Every subscription this checkout created, in line order."}}}}}}}}},"/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/checkout-sessions/{id}/card-session":{"post":{"summary":"Start a Secure Fields card session for a checkout session","tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"Start a Secure Fields card session (hosted checkout, no API key)","tags":["Checkout"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/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},"resource":{"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"}]}},"/v1/storefront/auth/register":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320},"password":{"type":"string","minLength":1,"maxLength":256}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accessToken":{"type":"string"},"expiresAt":{"type":"string"},"refreshToken":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"}}}}}}}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited. Slow down and retry after the interval in the response headers.","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"}]}},"/v1/storefront/auth/login":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320},"password":{"type":"string","minLength":1,"maxLength":256}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accessToken":{"type":"string"},"expiresAt":{"type":"string"},"refreshToken":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"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"}}}},"429":{"description":"Rate limited. Slow down and retry after the interval in the response headers.","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"}]}},"/v1/storefront/auth/refresh":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refreshToken"],"additionalProperties":false,"properties":{"refreshToken":{"type":"string","minLength":1,"maxLength":512}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accessToken":{"type":"string"},"expiresAt":{"type":"string"},"refreshToken":{"type":"string"},"customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"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"}}}},"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"}]}},"/v1/storefront/auth/logout":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/auth/logout-all":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/auth/verify-email":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"additionalProperties":false,"properties":{"token":{"type":"string","minLength":8,"maxLength":512}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"emailVerified":{"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"}]}},"/v1/storefront/auth/verify-email/resend":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/auth/forgot-password":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320}}}}}},"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"}}}}}}}},"429":{"description":"Rate limited. Slow down and retry after the interval in the response headers.","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"}]}},"/v1/storefront/auth/reset-password":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","password"],"additionalProperties":false,"properties":{"token":{"type":"string","minLength":8,"maxLength":512},"password":{"type":"string","minLength":1,"maxLength":256}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"}}}}}}}},"400":{"description":"Invalid request — the body, query, or path failed validation. See `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited. Slow down and retry after the interval in the response headers.","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"}]}},"/v1/storefront/auth/step-up":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"additionalProperties":false,"properties":{"password":{"type":"string","minLength":1,"maxLength":256}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stepUpToken":{"type":"string"},"expiresIn":{"type":"number"}}}}}}}},"401":{"description":"Missing or invalid credentials. Send a valid `X-API-Key` or `Authorization: Bearer` token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limited. Slow down and retry after the interval in the response headers.","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"}]}},"/v1/storefront/me/change-password":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"additionalProperties":false,"properties":{"password":{"type":"string","minLength":1,"maxLength":256}}}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"}}}}}}}},"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"}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/me":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"patch":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"firstName":{"type":"string","maxLength":100},"lastName":{"type":"string","maxLength":100},"phone":{"type":"string","maxLength":40},"company":{"type":["string","null"],"maxLength":200},"acceptsMarketing":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/me/sessions":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/me/sessions/{id}":{"delete":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/addresses":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["addressLine1","city","countryCode"],"additionalProperties":false,"properties":{"label":{"type":"string","maxLength":100},"firstName":{"type":"string","maxLength":100},"lastName":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":200},"addressLine1":{"type":"string","minLength":1,"maxLength":200},"addressLine2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"stateProvince":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":32},"countryCode":{"type":"string","minLength":2,"maxLength":2},"phone":{"type":"string","maxLength":40},"isDefault":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/me/addresses/{id}":{"patch":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"additionalProperties":false,"properties":{"label":{"type":"string","maxLength":100},"firstName":{"type":"string","maxLength":100},"lastName":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":200},"addressLine1":{"type":"string","minLength":1,"maxLength":200},"addressLine2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"stateProvince":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":32},"countryCode":{"type":"string","minLength":2,"maxLength":2},"phone":{"type":"string","maxLength":40},"isDefault":{"type":"boolean"}},"minProperties":1}}}},"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"}}}},"/v1/storefront/me/payment-methods":{"get":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/me/payment-methods/{id}":{"patch":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["isDefault"],"properties":{"isDefault":{"enum":[true,false]}}}}}},"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"}}}},"/v1/storefront/me/payment-methods/embed-token":{"post":{"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/v1/storefront/me/payment-methods/confirm":{"post":{"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"}]}},"/v1/storefront/me/carts/{cartId}/claim":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{},"nullable":true}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/orders":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/orders/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/invoices":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","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"},"number":{"type":"string","description":"The number printed on the invoice PDF."},"status":{"type":"string","enum":["open","paid","void","refunded","partially_refunded"]},"sourceType":{"type":"string","nullable":true,"enum":["order","net30","subscription",null]},"lineItems":{"type":"array","description":"The lines billed, frozen at issue.","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"quantity":{"type":"integer"},"unitPrice":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"}}}},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"The order's subtotal, in minor units."},"taxTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"total":{"type":"integer","description":"What this invoice bills, in minor units. For a Net-N invoice, the amount due; for a receipt, the amount paid. Less than the order total when `orderTotal` is set."},"orderTotal":{"type":"integer","nullable":true,"description":"Set when the invoice bills less than the order (a Net-N balance after a deposit, what is left after a comp, a deposit receipt): the order total the itemised rows add up to. Null when the invoice bills the whole order."},"amountPaid":{"type":"integer","nullable":true,"description":"Net-N invoices: paid on the order before this invoice (e.g. the deposit). Null when nothing was."},"compWaived":{"type":"integer","nullable":true,"description":"Net-N invoices: waived by a comp. Null when nothing was."},"balanceDue":{"type":"integer","nullable":true,"description":"Deposit receipts: the order's balance still due, billed on the Net-N invoice. Null otherwise."},"amountRefunded":{"type":"integer"},"issuedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time","nullable":true},"periodStart":{"type":"string","format":"date-time","nullable":true},"periodEnd":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}}}},"/v1/storefront/me/invoices/{id}":{"get":{"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"},"number":{"type":"string","description":"The number printed on the invoice PDF."},"status":{"type":"string","enum":["open","paid","void","refunded","partially_refunded"]},"sourceType":{"type":"string","nullable":true,"enum":["order","net30","subscription",null]},"lineItems":{"type":"array","description":"The lines billed, frozen at issue.","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"quantity":{"type":"integer"},"unitPrice":{"type":"integer"},"taxAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"total":{"type":"integer"}}}},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"The order's subtotal, in minor units."},"taxTotal":{"type":"integer"},"shippingTotal":{"type":"integer"},"discountTotal":{"type":"integer"},"total":{"type":"integer","description":"What this invoice bills, in minor units. For a Net-N invoice, the amount due; for a receipt, the amount paid. Less than the order total when `orderTotal` is set."},"orderTotal":{"type":"integer","nullable":true,"description":"Set when the invoice bills less than the order (a Net-N balance after a deposit, what is left after a comp, a deposit receipt): the order total the itemised rows add up to. Null when the invoice bills the whole order."},"amountPaid":{"type":"integer","nullable":true,"description":"Net-N invoices: paid on the order before this invoice (e.g. the deposit). Null when nothing was."},"compWaived":{"type":"integer","nullable":true,"description":"Net-N invoices: waived by a comp. Null when nothing was."},"balanceDue":{"type":"integer","nullable":true,"description":"Deposit receipts: the order's balance still due, billed on the Net-N invoice. Null otherwise."},"amountRefunded":{"type":"integer"},"issuedAt":{"type":"string","format":"date-time"},"dueAt":{"type":"string","format":"date-time","nullable":true},"periodStart":{"type":"string","format":"date-time","nullable":true},"periodEnd":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"orderId":{"type":"string","format":"uuid","nullable":true,"description":"The order this invoice billed; null when it cannot be resolved."},"orderNumber":{"type":"string","nullable":true},"subscriptionId":{"type":"string","format":"uuid","nullable":true}}}}}}}},"404":{"description":"No such resource, or it belongs to another workspace, application, or environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/storefront/me/subscriptions":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","maxLength":512},"in":"query","name":"cursor","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/subscriptions/{id}":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/invoices/{id}/pdf":{"get":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/subscriptions/{id}/pause":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/subscriptions/{id}/resume":{"post":{"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/subscriptions/{id}/cancel":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"nullable":true,"properties":{"atPeriodEnd":{"enum":[true,false]}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/subscriptions/{id}/payment-method":{"patch":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["paymentMethodId"],"properties":{"paymentMethodId":{"type":"string","format":"uuid"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/orders/{id}/cancel":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"nullable":true,"properties":{"reason":{"type":"string","maxLength":500}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/storefront/me/orders/{id}/return-request":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"reason":{"type":"string","maxLength":500},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["lineItemId","quantity"],"properties":{"lineItemId":{"type":"string","maxLength":64},"quantity":{"type":"integer","minimum":1}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/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.comped","order.comp_reversed","order.held","order.hold_released","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.processing","payment.captured","payment.failed","payment.voided","payment.expired","payment.recorded","payment.refunded","payment.partially_refunded","payment.refund_failed","payment.vaulted","payment.disputed","payment.dispute_cleared","payment.dispute_lost","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.completed","subscription.invoice_refunded","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","customer.registered","customer.email_verified","customer.password_changed","customer.sessions_revoked","invoice.past_due","import.completed","script.loaded","script.blocked","script.error","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","extension.uninstalled","extension.webhook_secret_rotated","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","nullable":true,"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.comped","order.comp_reversed","order.held","order.hold_released","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.processing","payment.captured","payment.failed","payment.voided","payment.expired","payment.recorded","payment.refunded","payment.partially_refunded","payment.refund_failed","payment.vaulted","payment.disputed","payment.dispute_cleared","payment.dispute_lost","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.completed","subscription.invoice_refunded","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","customer.registered","customer.email_verified","customer.password_changed","customer.sessions_revoked","invoice.past_due","import.completed","script.loaded","script.blocked","script.error","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","extension.uninstalled","extension.webhook_secret_rotated","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"],"description":"Mints a new signing secret and returns it once. For `graceSeconds` (default 86400, max 604800) every delivery carries two `v1=` digests — the outgoing secret first, the new one last — so a receiver that checks every digest never fails a delivery, and one that keeps only the last digest verifies from the moment it holds the new secret. `graceSeconds: 0` revokes the old secret immediately.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"graceSeconds":{"type":"integer","minimum":0,"maximum":604800,"default":86400}}}}}},"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"],"description":"Sends a synthetic, signed delivery of one event type. The endpoint must be subscribed to that type (an endpoint subscribed to all events accepts any type); otherwise the call fails with 400 validation_error naming the allowed types.","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.comped","order.comp_reversed","order.held","order.hold_released","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.processing","payment.captured","payment.failed","payment.voided","payment.expired","payment.recorded","payment.refunded","payment.partially_refunded","payment.refund_failed","payment.vaulted","payment.disputed","payment.dispute_cleared","payment.dispute_lost","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.completed","subscription.invoice_refunded","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","customer.registered","customer.email_verified","customer.password_changed","customer.sessions_revoked","invoice.past_due","import.completed","script.loaded","script.blocked","script.error","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","extension.uninstalled","extension.webhook_secret_rotated"]},"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"],"description":"Accepts PNG, JPEG, WebP or SVG up to 2 MB and returns the public `iconUrl` to set on the extension. Any credential holding `extensions:write` may call it: a secret API key or a dashboard session.","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"],"description":"Accepts PNG, JPEG or WebP up to 5 MB and returns the public `screenshotUrl` to include in the listing `screenshots` array. Any credential holding `extensions:write` may call it: a secret API key or a dashboard session.","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/imports":{"post":{"summary":"Start a bulk import: creates the import record and returns a presigned PUT the browser uploads the file to directly.","tags":["Imports"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"get":{"summary":"Imports for this application and environment, newest first.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/imports/{id}/inspect":{"post":{"summary":"Sniff the uploaded file: dialect, headers, a 20-row sample, the matched template and a suggested target field per header.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/imports/{id}/mapping":{"patch":{"summary":"Save the column-to-field mapping the merchant confirmed on the mapping screen.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/imports/{id}/validate":{"post":{"summary":"Queue a dry run: reads the whole file under the saved mapping, reports what it would create, update, skip and reject, and writes nothing.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/imports/{id}/commit":{"post":{"summary":"Queue the real import. Requires a completed dry run: an import that has not been validated is refused.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/imports/{id}/undo":{"post":{"summary":"Queue the deletion of the rows this import created. Rows it only matched, and rows another record now depends on, are kept and reported on the import row.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/imports/{id}":{"get":{"summary":"One import, with its counters and derived progress.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/imports/{id}/errors":{"get":{"summary":"The row-level error report for an import, as a re-importable CSV plus the rows behind it. 404 when the import recorded no failures.","tags":["Imports"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","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; on an order with an outstanding Net-N invoice, the invoice amount takes the delta instead.","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":"The edit was applied and any money delta settled.","content":{"application/json":{"schema":{"type":"object","description":"The edit was applied and any money delta settled.","required":["data"],"properties":{"data":{"type":"object","description":"The order as stored after the edit, with every line item, the money settled for it, and any tax warnings.","required":["id","items","adjustment"],"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"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"paymentStatus":{"type":"string","enum":["pending","authorized","captured","partially_paid","partially_refunded","refunded","failed","voided","processing","disputed","expired","charged_back"]},"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"},"taxProviderMessages":{"type":"array","items":{"type":"object","properties":{"summary":{"type":"string"},"details":{"type":"string"},"citationCode":{"type":"string"},"refersTo":{"type":"string"},"severity":{"type":"string"},"source":{"type":"string"},"lineNumbers":{"type":"array","items":{"type":"string"}},"lineItemIds":{"type":"array","items":{"type":"string"}}}}},"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)"},"compAmount":{"type":"integer","description":"Balance written off. A credit against the order, not a re-pricing of it: `total` is unchanged, and what the buyer owes is `total - compAmount`."},"compReason":{"type":"string","nullable":true},"compedAt":{"type":"string","format":"date-time","nullable":true},"compedBy":{"type":"string","nullable":true},"onHold":{"type":"boolean"},"holdReason":{"type":"string","nullable":true},"heldAt":{"type":"string","format":"date-time","nullable":true},"heldBy":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"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},"shippingMethod":{"type":"object","nullable":true,"properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"carrier":{"type":"string","nullable":true},"serviceCode":{"type":"string","nullable":true},"amount":{"type":"integer"}}},"customerId":{"type":"string","format":"uuid","nullable":true},"applicationId":{"type":"string","format":"uuid"},"environmentId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"externalId":{"type":"string","nullable":true,"description":"The source platform's own order id, for an order that arrived by import; null otherwise."},"externalCustomerId":{"type":"string","nullable":true,"description":"The source platform's customer id, for an order that arrived by import; null otherwise."},"importId":{"type":"string","format":"uuid","nullable":true,"description":"The import that created this order; null otherwise."},"ipAddress":{"type":"string","nullable":true,"description":"The buyer's IP address recorded at checkout."},"userAgent":{"type":"string","nullable":true,"description":"The buyer's user agent recorded at checkout."},"clientContext":{"type":"object","nullable":true,"additionalProperties":true,"description":"Attribution snapshot copied from the checkout session when the order was created."},"subscriptionId":{"type":"string","format":"uuid","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"},"items":{"type":"array","description":"Every line item on the order after the edit, not only the ones changed.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom","usage"]},"referenceId":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string","nullable":true},"unitPrice":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"subtotal":{"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)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"imageUrl":{"type":"string","nullable":true},"deliveryMethod":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom","none"]},"subscriptionId":{"type":"string","format":"uuid","nullable":true},"recurring":{"type":"object","nullable":true,"description":"Subscription terms. A merchant-declared subscription line carries `plan`; the plan line Throttle adds for a session `recurring` intent carries only the cadence and `count`. `amount` is the renewal unit price, set only on a trial line (whose `unitPrice` is 0).","properties":{"plan":{"type":"string"},"planName":{"type":"string","nullable":true},"interval":{"type":"string"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true},"totalPayments":{"type":"integer","nullable":true},"trialDays":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true},"count":{"type":"integer","nullable":true},"schedule":{"type":"array","nullable":true,"items":{"type":"object","properties":{"amount":{"type":"integer"},"intervalUnit":{"type":"string","nullable":true},"intervalCount":{"type":"integer","nullable":true}}}},"scheduleUnitTotal":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","nullable":true}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"workspaceId":{"type":"string","format":"uuid"},"applicationId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"cartId":{"type":"string","format":"uuid","nullable":true},"position":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"adjustment":{"type":"object","description":"The money the edit settled.","required":["delta","previousTotal","newTotal"],"properties":{"delta":{"type":"integer","description":"Change in what the buyer owes, in minor units. On an order with an outstanding Net-N invoice it is billed on that invoice (see `invoice`). Otherwise, on an order with a captured payment a positive delta was charged to the stored card and a negative one refunded; otherwise no money moved."},"previousTotal":{"type":"integer","description":"The order total before the edit, in minor units."},"newTotal":{"type":"integer","description":"The order total after the edit, in minor units."},"chargedPaymentId":{"type":"string","nullable":true,"description":"The payment that charged a positive delta; null when nothing was charged."},"refundedPaymentId":{"type":"string","nullable":true,"description":"The payment a negative delta was refunded on; null when nothing was refunded."},"refundError":{"type":"object","nullable":true,"description":"Set when refunding a negative delta failed. The line items were still changed; retry the refund from the order.","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"invoice":{"type":"object","nullable":true,"description":"Set when the order's balance is on an outstanding Net-N invoice. The delta is billed on that invoice instead of a card: an increase raises its amount, a decrease lowers it, and only a decrease larger than the invoice carries is refunded from money already collected. An invoice left owing nothing is voided. The buyer is not emailed; resend the invoice to send them the new amount. Null when there is no outstanding invoice.","required":["paymentId","previousAmount","newAmount","voided"],"properties":{"paymentId":{"type":"string","description":"The Net-N invoice payment."},"invoiceNumber":{"type":"string","nullable":true,"description":"The invoice's number."},"previousAmount":{"type":"integer","description":"What the invoice billed before the edit, in minor units."},"newAmount":{"type":"integer","description":"What it bills now, in minor units. 0 means it owes nothing and was voided."},"voided":{"type":"boolean","description":"True when the invoice owed nothing after the edit and was voided."},"voidError":{"type":"object","nullable":true,"description":"Set when voiding an invoice left owing nothing failed. The line items were still changed; void the invoice from the order.","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"warnings":{"type":"array","description":"Present only when there is something to report. Notes from re-quoting tax with the tax provider (`taxMode: \"app_based\"`, e.g. Avalara) under the lenient tax fallback policy: `provider_fallback` (the provider could not answer, so your native tax rules priced the edit), `tax_address_missing` (there is no address to tax from, so no tax was charged), `tax_zero_from_provider` (the provider returned no tax for the address). Under the strict policy the same failures refuse the edit instead (503 / 422).","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"400":{"description":"The edit was refused before anything changed: `validation_error` (the body), `application_required`, `no_changes` (empty add/update/remove), `invalid_line_item` (a `lineItemId` or `remove` id that is not on this order), or `empty_order` (the edit would remove every line item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid credentials (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"`payment_failed`: charging a positive delta to the stored card failed. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential lacks the `orders:write` scope or the role to edit orders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"`not_found`: no such order in this application and environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The order cannot take this edit, and nothing was changed: `order_not_editable` (the order is cancelled, refunded or voided), `subscription_order_not_editable` (change the subscription plan instead), or `no_customer` (a positive delta on a captured order with no customer to charge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Tax for the edited order cannot be calculated with the tax provider (`taxMode: \"app_based\"`), so the order was not changed. The code names the reason: `tax_origin_missing` (the application has no origin address), or `tax_address_missing` (the order has no address to tax from, under the strict fallback policy).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"501":{"description":"`not_implemented`: a positive delta on a captured order, on a server with no stored-card charging configured. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"`tax_provider_unavailable`: the tax provider (`taxMode: \"app_based\"`) could not answer and the tax fallback policy is strict, so the order was not changed and nothing was charged or refunded. Retry once the provider is reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/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"]},"verifyPath":{"type":["null","string"]},"resetPath":{"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."},"verifyPath":{"type":["string","null"],"description":"Path on your storefront that handles email-verification links, e.g. \"/auth/confirm\". Defaults to \"/account/verify\" (where the SDK component ships). Pass null to clear."},"resetPath":{"type":["string","null"],"description":"Path on your storefront that handles password-reset links, e.g. \"/auth/new-password\". Defaults to \"/account/reset\". Pass null to clear."},"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"}]}},"/api/v1/application-scripts":{"get":{"summary":"List this environment’s merchant-authored scripts","tags":["Scripts"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]},"post":{"summary":"Create a merchant-authored script","tags":["Scripts"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/application-scripts/{id}":{"patch":{"summary":"Update a merchant-authored script","tags":["Scripts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Soft-delete a merchant-authored script","tags":["Scripts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/application-scripts/kill-switch":{"put":{"summary":"Disable or re-enable every script in this environment","tags":["Scripts"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/application-scripts/app-inventory":{"get":{"summary":"Every marketplace-app script active in this environment (read-only)","tags":["Scripts"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/application-scripts/installs/{installId}":{"get":{"summary":"One installed app's scripts, with the merchant's per-install controls","tags":["Scripts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"installId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/application-scripts/health":{"get":{"summary":"Last 24h load outcomes per script","tags":["Scripts"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/storefront/scripts":{"get":{"summary":"Resolve this application/environment's storefront scripts (publishable key)","tags":["Scripts"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/storefront/script-frame-policy/{id}":{"get":{"summary":"Origins permitted to frame a script sandbox (public)","tags":["Scripts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/storefront/script-assets/{id}/{sha256}":{"get":{"summary":"Fetch a buyer-facing script by id and content hash (public, immutable)","tags":["Scripts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"sha256","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/storefront/script-events/{sessionId}":{"post":{"summary":"Record buyer-side script load outcomes for a checkout session","tags":["Scripts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/storefront/script-events":{"post":{"summary":"Record buyer-side script load outcomes for a storefront or quote page","tags":["Scripts"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"}]}},"/api/v1/storefront/script-events/quote/{token}":{"post":{"summary":"Record buyer-side script load outcomes for a hosted quote page","tags":["Scripts"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/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/applications/{applicationId}/auth-settings":{"get":{"summary":"Get buyer-auth settings for an application","tags":["Applications"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Update buyer-auth settings for an application","tags":["Applications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"enabled":{"type":"boolean"}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/applications/{applicationId}/quote-settings":{"get":{"summary":"Get quote notification settings for an application","tags":["Quotes"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Update quote notification settings for an application","tags":["Quotes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["notificationEmails"],"properties":{"notificationEmails":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":254}}}}}}},"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"applicationId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/auth-summary":{"get":{"summary":"Account state for a page of customers","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string","minLength":1,"maxLength":4000},"in":"query","name":"ids","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{customerId}/auth":{"get":{"summary":"Buyer account detail for one customer","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"customerId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/customers/{customerId}/auth/sign-out-all":{"post":{"summary":"Revoke every session for a customer","tags":["Customers"],"parameters":[{"$ref":"#/components/parameters/EnvironmentIdHeader"},{"schema":{"type":"string"},"in":"path","name":"customerId","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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"]},"billedByWorkspaceId":{"type":"string","format":"uuid","nullable":true,"description":"Workspace paying for this one (a partner that claimed billing), or null when the workspace pays for itself"}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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","description":"`req_<uuid>`, or a client-supplied id matching `^[A-Za-z0-9_-]{8,128}$`."},"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"},"verificationTransactionId":{"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"}]}