{"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":{}},"paths":{"/health":{"get":{"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"}}},"get":{"tags":["Organizations"],"description":"List organizations","responses":{"200":{"description":"Default Response"}}}},"/api/v1/organizations/{id}":{"get":{"tags":["Organizations"],"description":"Get organization by ID","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"tags":["Organizations"],"description":"Update an organization","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"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"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/stores/{id}":{"get":{"tags":["Stores"],"description":"Get a store by ID","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"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},"is_active":{"type":"boolean","description":"Deactivate a store without deleting it"}}}}}},"parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code"},"settings":{"type":"object","additionalProperties":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/customers":{"post":{"tags":["Customers"],"description":"Create a new customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"store_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_marketing":{"type":"boolean","default":false},"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"},"merchant_id":{"type":"string","format":"uuid"},"store_id":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_marketing":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"get":{"tags":["Customers"],"description":"List customers with cursor pagination","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"store_id","required":false},{"schema":{"type":"string","format":"email"},"in":"query","name":"email","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"},"merchant_id":{"type":"string","format":"uuid"},"store_id":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_marketing":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/customers/{id}":{"get":{"tags":["Customers"],"description":"Get a customer by ID","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"store_id":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_marketing":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"patch":{"tags":["Customers"],"description":"Update a customer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_marketing":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"store_id":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","format":"email"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_marketing":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"delete":{"tags":["Customers"],"description":"Delete a customer","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Customer deleted"},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/customers/{id}/addresses":{"get":{"tags":["Customers"],"description":"List addresses for a customer","parameters":[{"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"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address_line_1":{"type":"string"},"address_line_2":{"type":"string"},"city":{"type":"string"},"state_province":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"id":{"type":"string","format":"uuid"},"is_default":{"type":"boolean"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address_line_1":{"type":"string"},"address_line_2":{"type":"string"},"city":{"type":"string"},"state_province":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"is_default":{"type":"boolean","default":false},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address_line_1":{"type":"string"},"address_line_2":{"type":"string"},"city":{"type":"string"},"state_province":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address_line_1":{"type":"string"},"address_line_2":{"type":"string"},"city":{"type":"string"},"state_province":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"},"is_default":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address_line_1":{"type":"string"},"address_line_2":{"type":"string"},"city":{"type":"string"},"state_province":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2"},"phone":{"type":"string"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"delete":{"tags":["Customers"],"description":"Delete a customer address","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Address deleted"},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/customers/{id}/payment-methods":{"get":{"tags":["Customers"],"description":"List payment methods for a customer","parameters":[{"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"},"method_type":{"type":"string","enum":["card","bank_account","wallet"]},"card_brand":{"type":"string","nullable":true},"card_last_four":{"type":"string","nullable":true},"is_default":{"type":"boolean"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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"},"processor_token":{"type":"string"},"method_type":{"type":"string","enum":["card","bank_account","wallet"]},"card_brand":{"type":"string"},"card_last_four":{"type":"string"},"card_exp_month":{"type":"integer"},"card_exp_year":{"type":"integer"},"is_default":{"type":"boolean","default":false},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"method_type":{"type":"string"},"card_brand":{"type":"string","nullable":true},"card_last_four":{"type":"string","nullable":true},"is_default":{"type":"boolean"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/customers/{customerId}/payment-methods/{id}":{"delete":{"tags":["Customers"],"description":"Delete a customer payment method","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Payment method deleted"},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/carts":{"post":{"tags":["Carts"],"description":"Create a new cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"store_id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"currency":{"type":"string","default":"USD"},"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}":{"get":{"tags":["Carts"],"description":"Get a cart by ID (includes line items)","parameters":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"patch":{"tags":["Carts"],"description":"Update a cart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","format":"uuid"},"billing_address":{"type":"object","additionalProperties":true},"shipping_address":{"type":"object","additionalProperties":true},"notes":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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"],"properties":{"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom"],"default":"product"},"reference_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"unit_price":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","minimum":1,"default":1},"tax_amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"image_url":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"unit_price":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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","properties":{"quantity":{"type":"integer","minimum":1},"unit_price":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"tax_amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"unit_price":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Carts"],"description":"Remove a line item from a cart","parameters":[{"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":"Checkout a cart (creates an order from the cart)","parameters":[{"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 order","properties":{"id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft"]},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"In cents"},"total":{"type":"integer","description":"In cents"},"cart_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/carts/{id}/merge":{"post":{"parameters":[{"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","required":["code"],"properties":{"code":{"type":"string"}}}}}},"parameters":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}/discount":{"delete":{"tags":["Carts"],"description":"Remove discount code from a cart","parameters":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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","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":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Carts"],"description":"Clear the selected shipping method from a cart","parameters":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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","required":["lines"],"properties":{"lines":{"type":"array","items":{"type":"object","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":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Carts"],"description":"Clear all tax lines from a cart","parameters":[{"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"},"merchantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid","nullable":true},"customerId":{"type":"string","format":"uuid","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)"},"discountCode":{"type":"string","nullable":true},"selectedShipping":{"anyOf":[{"type":"object","properties":{"methodId":{"type":"string"},"displayName":{"type":"string"},"rateAmount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"carrier":{"type":"string"},"serviceCode":{"type":"string"},"estimatedDeliveryDays":{"type":"integer"}}},{"type":"null"}]},"taxLines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"jurisdictionCode":{"type":"string"},"jurisdictionName":{"type":"string","nullable":true},"taxType":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","nullable":true}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"createdAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/carts/{id}/events":{"get":{"tags":["Carts"],"description":"List audit events for a cart","parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/shipping-tax/config":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/quote-tokens":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/quote-tokens/{tokenId}":{"delete":{"parameters":[{"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"}}}},"/api/v1/shipping-tax/config/publish":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/quotes":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/v1/shipping-tax/carts/{cartId}/calculate":{"post":{"parameters":[{"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"}}}},"/api/v1/orders":{"post":{"tags":["Orders"],"description":"Create a new order (draft)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"store_id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"currency":{"type":"string","default":"USD"},"source":{"type":"string","enum":["web","mobile","pos","api"],"default":"api"},"billing_address":{"type":"object","additionalProperties":true},"shipping_address":{"type":"object","additionalProperties":true},"notes":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"line_items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["product","subscription","service","ticket","donation","custom"],"default":"product"},"reference_id":{"type":"string","description":"Merchant's external ID (SKU, plan ID, etc.)"},"name":{"type":"string"},"description":{"type":"string"},"unit_price":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"quantity":{"type":"integer","minimum":1,"default":1},"tax_amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","default":0},"discount_amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)","default":0},"image_url":{"type":"string","format":"uri"},"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"get":{"tags":["Orders"],"description":"List orders with cursor pagination","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"customer_id","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"store_id","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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}":{"get":{"tags":["Orders"],"description":"Get an order by ID (includes line items)","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"patch":{"tags":["Orders"],"description":"Update order fields (addresses, notes, metadata)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"billing_address":{"type":"object","additionalProperties":true},"shipping_address":{"type":"object","additionalProperties":true},"notes":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/checkout":{"post":{"tags":["Orders"],"description":"Initiate checkout (draft -> pending)","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/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":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/cancel":{"post":{"tags":["Orders"],"description":"Cancel an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/orders/{id}/complete":{"post":{"tags":["Orders"],"description":"Complete an order (processing -> completed)","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/orders/{id}/close":{"post":{"tags":["Orders"],"description":"Close a completed order","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["draft","pending","processing","partially_fulfilled","completed","cancelled","closed"]},"type":{"type":"string","enum":["one_time","recurring","mixed"]},"payment_status":{"type":"string","enum":["pending","authorized","captured","partially_refunded","refunded","failed","voided"]},"fulfillment_status":{"type":"string","enum":["unfulfilled","partially_fulfilled","fulfilled","not_applicable"]},"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)"},"tax_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"discount_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"shipping_total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"total":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/payments":{"post":{"tags":["Payments"],"description":"Create a payment for an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"processor":{"type":"string","default":"manual"},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","default":"USD"},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"],"default":"manual"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"get":{"tags":["Payments"],"description":"List payments for an order","parameters":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{id}/payments/{paymentId}":{"get":{"tags":["Payments"],"description":"Get a specific payment for an order","parameters":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/payments/{id}/transactions":{"get":{"tags":["Payments"],"description":"List transactions for a payment","parameters":[{"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"},"payment_id":{"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"]},"processor_response":{"type":"object","additionalProperties":true,"nullable":true},"idempotency_key":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/payments":{"get":{"summary":"List payments for the calling merchant.","tags":["Payments"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"method","required":false},{"schema":{"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}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payments/{id}":{"get":{"summary":"Get a payment by id.","tags":["Payments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{id}/refund":{"post":{"tags":["Orders"],"description":"Refund the captured payment on an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Partial refund amount (defaults to full amount)"}}}}}},"parameters":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/payments/{id}/authorize":{"post":{"tags":["Payments"],"description":"Authorize a payment (pending -> authorized)","parameters":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/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":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/payments/{id}/void":{"post":{"tags":["Payments"],"description":"Void an authorized payment","parameters":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/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)"}}}}}},"parameters":[{"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"},"order_id":{"type":"string","format":"uuid"},"processor":{"type":"string"},"processor_transaction_id":{"type":["null","string"]},"processor_response":{"type":["null","object"],"additionalProperties":true},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","authorized","captured","failed","voided","refunded","partially_refunded"]},"method":{"type":"string","enum":["card","bank_transfer","wallet","cash","external","manual","net30"]},"authorized_at":{"type":["null","string"],"format":"date-time"},"captured_at":{"type":["null","string"],"format":"date-time"},"voided_at":{"type":["null","string"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/payments/{id}/invoice-pdf":{"get":{"summary":"Get a signed download URL for a Net30 invoice PDF.","tags":["Payments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/orders/{orderId}/fulfillments":{"post":{"tags":["Fulfillments"],"description":"Create a fulfillment for an order","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","lineItemIds"],"properties":{"type":{"type":"string","enum":["shipment","digital","access_grant","service","in_person","custom"]},"lineItemIds":{"type":"array","items":{"type":"object","required":["lineItemId","quantity"],"properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1}}}},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"get":{"tags":["Fulfillments"],"description":"List fulfillments for an order","parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}":{"get":{"tags":["Fulfillments"],"description":"Get a fulfillment by ID (includes type-specific details)","parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/processing":{"post":{"tags":["Fulfillments"],"description":"Mark fulfillment as processing","parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/complete":{"post":{"tags":["Fulfillments"],"description":"Mark fulfillment as completed","parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/cancel":{"post":{"tags":["Fulfillments"],"description":"Cancel a fulfillment","parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/shipment":{"patch":{"tags":["Fulfillments"],"description":"Update shipment details for a fulfillment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrier":{"type":"string","description":"e.g. fedex, ups, usps, dhl"},"service_level":{"type":"string","description":"e.g. ground, express, overnight"},"tracking_number":{"type":"string"},"tracking_url":{"type":"string","format":"uri"},"label_url":{"type":"string","format":"uri"},"shipping_cost":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"estimated_delivery":{"type":"string","format":"date-time"},"shipped_at":{"type":"string","format":"date-time"},"external_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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},"shippingCost":{"type":"integer","nullable":true,"description":"In cents"},"estimatedDelivery":{"type":"string","format":"date-time","nullable":true},"shippedAt":{"type":"string","format":"date-time","nullable":true},"externalId":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/digital":{"patch":{"tags":["Fulfillments"],"description":"Update digital delivery details","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delivery_method":{"type":"string","enum":["download","email","license_key","api_access"]},"download_url":{"type":"string","format":"uri"},"download_expiry":{"type":"string","format":"date-time"},"download_limit":{"type":"integer"},"license_key":{"type":"string"},"delivered_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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},"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/access":{"patch":{"tags":["Fulfillments"],"description":"Update access grant details","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resource_type":{"type":"string","description":"e.g. course, software, membership, content, api"},"resource_id":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"granted_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/orders/{orderId}/fulfillments/{id}/service":{"patch":{"tags":["Fulfillments"],"description":"Update service delivery details","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"service_type":{"type":"string"},"provider_name":{"type":"string"},"scheduled_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"location":{"type":"string"},"duration_minutes":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/subscriptions":{"post":{"tags":["Subscriptions"],"description":"Create a new subscription","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customerId","planReference","interval","amount","currentPeriodStart","currentPeriodEnd"],"properties":{"store_id":{"type":"string","format":"uuid"},"customer_id":{"type":"string","format":"uuid"},"plan_reference":{"type":"string"},"plan_name":{"type":"string"},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string","default":"USD"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"trial_end":{"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"},"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"plan_reference":{"type":"string"},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"failure_count":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"get":{"tags":["Subscriptions"],"description":"List subscriptions with cursor pagination","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"customer_id","required":false},{"schema":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"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"},"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"plan_reference":{"type":"string"},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"failure_count":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/subscriptions/{id}":{"get":{"tags":["Subscriptions"],"description":"Get a subscription by ID","parameters":[{"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"},"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"plan_reference":{"type":"string"},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"failure_count":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"patch":{"tags":["Subscriptions"],"description":"Update a subscription (plan change, amount, interval)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_reference":{"type":"string"},"plan_name":{"type":"string"},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents"},"metadata":{"type":"object","additionalProperties":true}}}}}},"parameters":[{"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"},"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"plan_reference":{"type":"string"},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"failure_count":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/subscriptions/{id}/pause":{"post":{"tags":["Subscriptions"],"description":"Pause an active subscription","parameters":[{"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"},"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"plan_reference":{"type":"string"},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"failure_count":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/subscriptions/{id}/resume":{"post":{"tags":["Subscriptions"],"description":"Resume a paused subscription","parameters":[{"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"},"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"plan_reference":{"type":"string"},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"failure_count":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/subscriptions/{id}/cancel":{"post":{"tags":["Subscriptions"],"description":"Cancel a subscription (immediately or at period end)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"atPeriodEnd":{"type":"boolean","default":false,"description":"If true, cancels at the end of the current billing period"}}}}}},"parameters":[{"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"},"customer_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","paused","cancelled","past_due","trialing"]},"plan_reference":{"type":"string"},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","enum":["weekly","monthly","quarterly","yearly"]},"amount":{"type":"integer","description":"Amount in cents (e.g. 1999 = $19.99)"},"currency":{"type":"string"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"failure_count":{"type":"integer"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/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":{"store_id":{"type":"string","format":"uuid"},"code":{"type":"string","description":"Leave empty for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount","free_shipping","buy_x_get_y"]},"value":{"type":"integer","description":"Percentage (1000 = 10.00%) or fixed amount in cents"},"conditions":{"type":"object","additionalProperties":true,"description":"e.g. { min_order: 5000 }"},"usage_limit":{"type":"integer"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"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","free_shipping","buy_x_get_y"]},"value":{"type":"integer","description":"Percentage (1000 = 10.00%) or fixed amount in cents"},"conditions":{"type":"object","additionalProperties":true},"usage_limit":{"type":"integer","nullable":true},"usage_count":{"type":"integer"},"is_active":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"get":{"tags":["Discounts"],"description":"List discounts with cursor pagination","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false,"description":"Number of items per page"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"store_id","required":false},{"schema":{"type":"boolean"},"in":"query","name":"is_active","required":false},{"schema":{"type":"string"},"in":"query","name":"code","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"},"code":{"type":"string","nullable":true,"description":"Null for automatic discounts"},"name":{"type":"string"},"type":{"type":"string","enum":["percentage","fixed_amount","free_shipping","buy_x_get_y"]},"value":{"type":"integer","description":"Percentage (1000 = 10.00%) or fixed amount in cents"},"conditions":{"type":"object","additionalProperties":true},"usage_limit":{"type":"integer","nullable":true},"usage_count":{"type":"integer"},"is_active":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/discounts/{id}":{"get":{"tags":["Discounts"],"description":"Get a discount by ID","parameters":[{"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","free_shipping","buy_x_get_y"]},"value":{"type":"integer","description":"Percentage (1000 = 10.00%) or fixed amount in cents"},"conditions":{"type":"object","additionalProperties":true},"usage_limit":{"type":"integer","nullable":true},"usage_count":{"type":"integer"},"is_active":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"patch":{"tags":["Discounts"],"description":"Update a discount","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"integer"},"conditions":{"type":"object","additionalProperties":true},"usage_limit":{"type":"integer"},"is_active":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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","free_shipping","buy_x_get_y"]},"value":{"type":"integer","description":"Percentage (1000 = 10.00%) or fixed amount in cents"},"conditions":{"type":"object","additionalProperties":true},"usage_limit":{"type":"integer","nullable":true},"usage_count":{"type":"integer"},"is_active":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Discounts"],"description":"Delete a discount","parameters":[{"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)"}}}}}},"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","free_shipping","buy_x_get_y"]},"value":{"type":"integer","description":"Percentage (1000 = 10.00%) or fixed amount in cents"},"conditions":{"type":"object","additionalProperties":true},"usage_limit":{"type":"integer","nullable":true},"usage_count":{"type":"integer"},"is_active":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"error":{"type":"string"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/webhooks":{"post":{"tags":["Webhooks"],"description":"Register a new webhook","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"}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"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)"},"is_active":{"type":"boolean"},"description":{"type":"string","nullable":true},"failure_count":{"type":"integer"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"get":{"tags":["Webhooks"],"description":"List all webhooks 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"},"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)"},"is_active":{"type":"boolean"},"description":{"type":"string","nullable":true},"failure_count":{"type":"integer"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/webhooks/{id}":{"get":{"tags":["Webhooks"],"description":"Get a webhook by ID","parameters":[{"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"},"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)"},"is_active":{"type":"boolean"},"description":{"type":"string","nullable":true},"failure_count":{"type":"integer"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"patch":{"tags":["Webhooks"],"description":"Update a webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"description":{"type":"string"},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"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)"},"is_active":{"type":"boolean"},"description":{"type":"string","nullable":true},"failure_count":{"type":"integer"},"last_triggered_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}},"delete":{"tags":["Webhooks"],"description":"Delete a webhook","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"}}}},"/api/v1/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"description":"List delivery attempts for a webhook","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"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}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"webhook_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","success","failed","dead_letter"]},"attempt_count":{"type":"integer"},"response_status":{"type":"integer","nullable":true},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/webhooks/{webhookId}/deliveries/{id}/retry":{"post":{"tags":["Webhooks"],"description":"Retry a failed webhook delivery","parameters":[{"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"},"webhook_id":{"type":"string","format":"uuid"},"event_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","success","failed","dead_letter"]},"attempt_count":{"type":"integer"},"response_status":{"type":"integer","nullable":true},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"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":500},"version":{"type":"string"},"author":{"type":"string"},"icon_url":{"type":"string","format":"uri"},"homepage_url":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Permission scopes the extension requires"},"config_schema":{"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"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"icon_url":{"type":"string","format":"uri","nullable":true},"homepage_url":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"config_schema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"get":{"tags":["Extensions"],"description":"List available extensions","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"in":"query","name":"limit","required":false,"description":"Number of items per page"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"icon_url":{"type":"string","format":"uri","nullable":true},"homepage_url":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"config_schema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/extensions/{id}":{"get":{"tags":["Extensions"],"description":"Get extension by ID","parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"icon_url":{"type":"string","format":"uri","nullable":true},"homepage_url":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"config_schema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"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"},"icon_url":{"type":"string","format":"uri"},"homepage_url":{"type":"string","format":"uri"},"scopes":{"type":"array","items":{"type":"string"}},"config_schema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"}}}}}},"parameters":[{"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"},"merchant_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"author":{"type":"string","nullable":true},"icon_url":{"type":"string","format":"uri","nullable":true},"homepage_url":{"type":"string","format":"uri","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"config_schema":{"type":"object","additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}},"delete":{"tags":["Extensions"],"description":"Delete an extension","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/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":{"config":{"type":"object","additionalProperties":true,"description":"Configuration values for this installation"}}}}}},"parameters":[{"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"},"extension_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"api_key_id":{"type":"string","format":"uuid","nullable":true},"installed_at":{"type":"string","format":"date-time"},"uninstalled_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"},"api_key":{"type":"string","description":"Raw API key (shown once)"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/extensions/{id}/uninstall":{"post":{"tags":["Extensions"],"description":"Uninstall an extension (deactivates API key and webhooks)","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/extensions/{id}/suspend":{"post":{"tags":["Extensions"],"description":"Suspend an installed extension (deactivates API key and webhooks, can be reinstalled)","parameters":[{"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"},"extension_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"api_key_id":{"type":"string","format":"uuid","nullable":true},"installed_at":{"type":"string","format":"date-time"},"uninstalled_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/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":[{"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"},"extension_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"api_key_id":{"type":"string","format":"uuid","nullable":true},"installed_at":{"type":"string","format":"date-time"},"uninstalled_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/installations":{"get":{"tags":["Extensions"],"description":"List installed extensions for the organization","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"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"},"extension_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","suspended","uninstalled"]},"config":{"type":"object","additionalProperties":true},"api_key_id":{"type":"string","format":"uuid","nullable":true},"installed_at":{"type":"string","format":"date-time"},"uninstalled_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary key-value metadata"},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/events/{id}":{"get":{"tags":["Events"],"description":"Get a single event by ID","parameters":[{"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"},"entity_type":{"type":"string","description":"e.g. order, payment, customer"},"entity_id":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true},"previous_data":{"type":"object","additionalProperties":true,"nullable":true},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"}}}}}}}}}}},"/api/v1/events":{"get":{"tags":["Events"],"description":"List events (immutable audit log)","parameters":[{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for pagination (last item ID)"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"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":"entity_type","required":false,"description":"Filter by entity type"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"entity_id","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"},"entity_type":{"type":"string","description":"e.g. order, payment, customer"},"entity_id":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true},"previous_data":{"type":"object","additionalProperties":true,"nullable":true},"created_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}}}}}}},"/api/v1/checkout/sessions":{"post":{"tags":["Checkout Sessions"],"description":"Create a new hosted checkout session","responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout/sessions/{id}":{"get":{"tags":["Checkout Sessions"],"description":"Get a checkout session by ID","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["Checkout Sessions"],"description":"Cancel a checkout session","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"204":{"description":"Default Response"}}}},"/api/v1/checkout/sessions/{id}/complete":{"post":{"tags":["Checkout Sessions"],"description":"Complete a checkout session","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/checkout-sessions/{id}/complete":{"post":{"tags":["Checkout Sessions"],"description":"Public buyer-facing complete","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/providers/{provider}/webhooks/{connectionId}":{"post":{"parameters":[{"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/{connectionId}":{"post":{"parameters":[{"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"},"allowedMethods":{"type":"array","items":{"type":"string","minLength":1},"description":"Optional session-level payment method allowlist. null = no filter, [] = block all."}}}}}},"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"},"hosted_url":{"type":"string"},"embed_url":{"type":"string"}}},"meta":{"type":"object"}}}}}}}}},"/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":[{"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":{"embed_token":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"gr4vy_id":{"type":"string"}}},"meta":{"type":"object"}}}}}}}}},"/api/v1/api-keys":{"get":{"summary":"List API keys for the calling merchant","tags":["API Keys"],"responses":{"200":{"description":"Default Response"}}},"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","enum":["*","orders:read","orders:write","payments:read","payments:write","customers:read","customers:write","carts:read","carts:write","discounts:read","discounts:write","subscriptions:read","subscriptions:write","fulfillments:read","fulfillments:write","webhooks:read","webhooks:write","connectors:read","connectors:write","stores:read","stores:write","merchant:read","merchant:write"]}}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/api-keys/{id}":{"delete":{"summary":"Revoke (soft-delete) an API key","tags":["API Keys"],"parameters":[{"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"}}},"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"}}}},"/api/v1/checkout-sessions/{id}/payment-methods":{"get":{"summary":"List payment methods available for a checkout session (public)","tags":["Checkout Sessions"],"parameters":[{"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"}}},"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":{"oneOf":[{"type":"string"},{"type":"boolean"},{"type":"number"}]}}}},"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"}}}},"/api/v1/connectors/available":{"get":{"summary":"List available connector types","tags":["Connectors"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/connectors/{id}":{"get":{"summary":"Get a configured connector by id","tags":["Connectors"],"parameters":[{"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":{"oneOf":[{"type":"string"},{"type":"boolean"},{"type":"number"}]}}}},"acceptedCountries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}},"acceptedCurrencies":{"type":"array","items":{"type":"string","minLength":3,"maxLength":3}},"active":{"type":"boolean"}}}}}},"parameters":[{"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":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/payment-methods":{"get":{"summary":"List active payment methods derived from configured connectors","tags":["Payment Methods"],"parameters":[{"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"}}}},"/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"}}}},"/api/v1/bigcommerce/connections/{id}/retry":{"post":{"summary":"Retry webhook registration for a setup_failed connection","tags":["BigCommerce"],"parameters":[{"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":[{"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"}}},"post":{"summary":"Create an outbound webhook endpoint","tags":["Webhooks: Outbound"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","enabled_events"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"enabled_events":{"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.expired","cart.merged","order.created","order.updated","order.cancelled","order.sync_failed","order.sync_conflict","payment.pending","payment.authorized","payment.authorization_failed","payment.captured","payment.capture_failed","payment.failed","payment.voided","payment.void_failed","payment.refunded","payment.partially_refunded","payment.refund_failed","fulfillment.created","fulfillment.completed","fulfillment.cancelled","fulfillment.shipment.shipped","fulfillment.shipment.delivered","subscription.created","subscription.activated","subscription.updated","subscription.paused","subscription.resumed","subscription.cancelled","subscription.renewed","subscription.past_due","subscription.payment_failed","discount.applied","discount.removed","customer.created","customer.updated","customer.deleted","customer.payment_method_added","customer.payment_method_removed","invoice.past_due","payment.disputed","payment.dispute_cleared"]},"minItems":1,"uniqueItems":true}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-endpoints/{id}":{"patch":{"summary":"Update a webhook endpoint (URL, events, or active flag)","tags":["Webhooks: Outbound"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"enabled_events":{"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.expired","cart.merged","order.created","order.updated","order.cancelled","order.sync_failed","order.sync_conflict","payment.pending","payment.authorized","payment.authorization_failed","payment.captured","payment.capture_failed","payment.failed","payment.voided","payment.void_failed","payment.refunded","payment.partially_refunded","payment.refund_failed","fulfillment.created","fulfillment.completed","fulfillment.cancelled","fulfillment.shipment.shipped","fulfillment.shipment.delivered","subscription.created","subscription.activated","subscription.updated","subscription.paused","subscription.resumed","subscription.cancelled","subscription.renewed","subscription.past_due","subscription.payment_failed","discount.applied","discount.removed","customer.created","customer.updated","customer.deleted","customer.payment_method_added","customer.payment_method_removed","invoice.past_due","payment.disputed","payment.dispute_cleared"]},"minItems":1,"uniqueItems":true},"is_active":{"type":"boolean"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Deactivate a webhook endpoint","tags":["Webhooks: Outbound"],"parameters":[{"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)","tags":["Webhooks: Outbound"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"endpoint_id","required":false},{"schema":{"type":"string"},"in":"query","name":"order_id","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/webhook-endpoints/{id}/test":{"post":{"summary":"Send a synthetic, signed test delivery to this endpoint.","tags":["Webhooks: Outbound"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"event_type":{"type":"string","enum":["order.created","payment.captured","payment.refunded","payment.failed","subscription.renewed","fulfillment.shipment.shipped","discount.applied"]}}}}}},"parameters":[{"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":[{"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"}}}},"/api/v1/merchants/me/finish-onboarding":{"post":{"summary":"Mark the merchant as having finished the onboarding wizard.","tags":["Merchant"],"responses":{"200":{"description":"Default Response"}}}},"/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":1,"maximum":365},"termsText":{"type":["string","null"],"maxLength":5000}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/api/v1/merchants/me/logo":{"post":{"summary":"Upload a merchant logo (multipart/form-data, field: logo).","tags":["Merchant"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/audit-log":{"get":{"summary":"Recent admin actions taken on this merchant","tags":["Audit"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/fulfillments/{id}/digital/upload":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/fulfillments/{id}/digital/download":{"get":{"parameters":[{"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"}}},"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":1,"maximum":365},"termsText":{"type":["string","null"],"maxLength":5000},"maxOrderTotal":{"type":["number","null"],"minimum":0},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/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":1,"maximum":365},"termsText":{"type":["string","null"],"maxLength":5000},"maxOrderTotal":{"type":["number","null"],"minimum":0},"enabled":{"type":"boolean"}}}}}},"parameters":[{"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":[{"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"}}},"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"}}}},"/api/v1/net30/eligible-customers/{customerId}":{"delete":{"summary":"Remove a customer from the Net30 eligible allowlist","tags":["Connectors"],"parameters":[{"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":[{"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":[{"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":[{"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"}}}},"/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":{"allowed_origins":{"type":"array","items":{"type":"string"}},"primary_color":{"type":["null","string"]},"logo_url":{"type":["null","string"]},"merchant_name":{"type":["null","string"]}}}}}}}}}},"put":{"summary":"Update the merchant embed config","tags":["Embed"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"allowed_origins":{"type":"array","items":{"type":"string","minLength":1},"maxItems":20,"uniqueItems":true},"primary_color":{"type":"string"},"logo_url":{"type":"string","format":"uri"},"merchant_name":{"type":"string","minLength":1,"maxLength":100}}}}}},"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"}}}},"/graphql":{"get":{"parameters":[{"schema":{"type":"string"},"in":"query","name":"query","required":false},{"schema":{"type":"boolean"},"in":"query","name":"persisted","required":false},{"schema":{"type":["string","null"]},"in":"query","name":"operationName","required":false},{"schema":{"type":"string"},"in":"query","name":"variables","required":false},{"schema":{"type":"string"},"in":"query","name":"extensions","required":false}],"responses":{"2XX":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":["null","object"],"additionalProperties":true},"errors":{"type":"array","items":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"locations":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"column":{"type":"integer"}}}},"path":{"type":"array","items":{"type":"string"}},"extensions":{"type":"object","properties":{"code":{"type":"string"}},"additionalProperties":true}}}},"extensions":{"type":"object","additionalProperties":true}}}}}}}},"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"persisted":{"type":"boolean"},"operationName":{"type":["string","null"]},"variables":{"type":["object","null"]},"extensions":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":["null","object"],"additionalProperties":true},"errors":{"type":"array","items":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"locations":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"column":{"type":"integer"}}}},"path":{"type":"array","items":{"type":"string"}},"extensions":{"type":"object","properties":{"code":{"type":"string"}},"additionalProperties":true}}}},"extensions":{"type":"object","additionalProperties":true}}}}}}}}}},"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"}]}