{"openapi":"3.0.0","info":{"title":"Cart AI","version":"1.0.0","description":""},"servers":[{"url":"https://api.cartai.ai"}],"paths":{"/checkout":{"post":{"summary":"Create Checkout Task","tags":[],"description":"This API creates an asynchronous AI-powered checkout task that manages the entire purchase lifecycle — from cart assembly and shipping selection to payment processing and order confirmation — across one or many merchants in a single call.","parameters":[{"in":"header","name":"X-Api-Key","schema":{"type":"string"},"required":true}],"responses":{"201":{"description":"Checkout tasks submitted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"message":{"type":"string","example":"Checkout tasks submitted"},"groupId":{"type":"string","description":"Identifier grouping all tasks submitted in this request"},"tasks":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"executionId":{"type":"string"},"status":{"type":"string","example":"queued"},"merchant":{"type":"string"},"liveUrl":{"type":"string","format":"uri","description":"Live preview URL for watching the checkout run"}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","message":"Checkout tasks submitted","groupId":"01a1f857-0a5b-7371-a70e-0513656b448e","tasks":[{"taskId":"01a1f857-0a68-7233-abf2-faec6856e343","executionId":"01a1f857-0a68-7233-abf2-fad75e4b2d81","status":"queued","merchant":"aloyoga.com","liveUrl":"https://web.cartai.ai/v2/live-preview?id=eyJ0aWQiOiAiMDFhMWY4NTctMGE2OC03MjMzLWFiZjItZmFlYzY4NTZlMzQzIiwgImV4ZWN1dGlvbl9pZCI6ICIwMWExZjg1Ny0wYTY4LTcyMzMtYWJmMi1mYWQ3NWU0YjJkODEifQ=="}]}}}}}},"400":{"description":"Bad Request"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer","tasks"],"properties":{"customer":{"type":"object","properties":{"contact":{"type":"object","properties":{"lastName":{"type":"string"},"firstName":{"type":"string"},"phone":{"type":"string","pattern":"^[+0-9\\- ]{7,20}$"},"email":{"type":"string","format":"email"}}},"shippingAddress":{"type":"object","properties":{"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9\\- ]{3,10}$"},"country":{"type":"string"}}},"billingAddress":{"type":"object","properties":{"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9\\- ]{3,10}$"},"country":{"type":"string"}}},"shippingMethod":{"type":"object","properties":{"strategy":{"type":"string"}}},"payment":{"type":"object","properties":{"provider":{"type":"string"},"data":{"type":"object","properties":{"cvv":{"type":"string"},"name":{"type":"string"},"cardNumber":{"type":"string"},"expiryYear":{"type":"string"},"expiryMonth":{"type":"string"}}}}}}},"tasks":{"type":"array","items":{"type":"object","required":["url","quantity"],"properties":{"url":{"type":"string","format":"uri"},"quantity":{"type":"integer","minimum":1},"selectedVariant":{"type":"object","properties":{"color":{"type":"string"},"size":{"type":"string"}}}}}},"options":{"type":"object","properties":{"verifyBeforePlacement":{"type":"boolean","default":false,"description":"Agent asks for confirmation just before placing the order"},"useSavedCredentialToLogin":{"type":"boolean","default":false,"description":"Agent signs in using the stored credentials created with the Create Credential Vault Session API"},"useGuestCheckoutIfLoginFails":{"type":"boolean","default":false,"description":"If the stored credentials do not work, the agent falls back to guest checkout when the merchant offers it"},"allowInteraction":{"type":"boolean","default":false,"description":"Enables the interactive flow instead of fire-and-forget; the agent can request additional input if it needs it"},"allowPartialCheckout":{"type":"boolean","default":false,"description":"If some items fail (e.g. out of stock), the agent still completes checkout for the remaining items"}}},"addons":{"type":"object","properties":{"couponCode":{"type":"array","items":{"type":"string"}}}}}},"examples":{"New Example":{"summary":"New Example","value":{"customer":{"contact":{"lastName":"Sturka","firstName":"Carol","phone":"+12144444444","email":"john.doe@example.com"},"shippingAddress":{"addressLine1":"609 Royal Crest Dr","addressLine2":"","city":"Richardson","province":"TX","postalCode":"75081","country":"US"},"billingAddress":{"addressLine1":"609 Royal Crest Dr","addressLine2":"","city":"Richardson","province":"TX","postalCode":"75081","country":"US"},"shippingMethod":{"strategy":"cheapest"},"payment":{"data":{"cvv":"444","name":"Carol Sturka","cardNumber":"4242424242424242","expiryYear":"2034","expiryMonth":"12"},"provider":"test"}},"tasks":[{"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","quantity":1,"selectedVariant":{"color":"Ivory","size":"S"}}],"options":{"verifyBeforePlacement":false,"useSavedCredentialToLogin":false,"useGuestCheckoutIfLoginFails":false,"allowInteraction":false,"allowPartialCheckout":true},"addons":{"couponCode":["SUMMER15"]}}}}}}}}},"/search-checkout":{"post":{"summary":"Create Search Checkout Task","tags":[],"operationId":"create_search_checkout","description":"Creates an asynchronous AI-powered checkout task from product names instead of product URLs. Provide the merchant and a list of item names — the agent searches the merchant's catalog, resolves each item (and any selected variant), assembles the cart, and completes shipping, payment and order confirmation in a single call.","parameters":[{"in":"header","name":"X-Api-Key","schema":{"type":"string"},"required":true}],"responses":{"201":{"description":"Checkout tasks submitted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"message":{"type":"string","example":"Checkout tasks submitted"},"groupId":{"type":"string","description":"Identifier grouping all tasks submitted in this request"},"tasks":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"executionId":{"type":"string"},"status":{"type":"string","example":"queued"},"merchant":{"type":"string"},"liveUrl":{"type":"string","format":"uri","description":"Live preview URL for watching the checkout run"}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","message":"Checkout tasks submitted","groupId":"01a1f857-0a5b-7371-a70e-0513656b448e","tasks":[{"taskId":"01a1f857-0a68-7233-abf2-faec6856e343","executionId":"01a1f857-0a68-7233-abf2-fad75e4b2d81","status":"queued","merchant":"aloyoga.com","liveUrl":"https://web.cartai.ai/v2/live-preview?id=eyJ0aWQiOiAiMDFhMWY4NTctMGE2OC03MjMzLWFiZjItZmFlYzY4NTZlMzQzIiwgImV4ZWN1dGlvbl9pZCI6ICIwMWExZjg1Ny0wYTY4LTcyMzMtYWJmMi1mYWQ3NWU0YjJkODEifQ=="}]}}}}}},"400":{"description":"Bad Request"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer","merchant","itemList"],"properties":{"customer":{"type":"object","properties":{"contact":{"type":"object","properties":{"lastName":{"type":"string"},"firstName":{"type":"string"},"phone":{"type":"string","pattern":"^[+0-9\\- ]{7,20}$"},"email":{"type":"string","format":"email"}}},"shippingAddress":{"type":"object","properties":{"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9\\- ]{3,10}$"},"country":{"type":"string"}}},"billingAddress":{"type":"object","properties":{"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9\\- ]{3,10}$"},"country":{"type":"string"}}},"shippingMethod":{"type":"object","properties":{"strategy":{"type":"string"}}},"payment":{"type":"object","properties":{"provider":{"type":"string"},"data":{"type":"object","properties":{"cvv":{"type":"string"},"name":{"type":"string"},"cardNumber":{"type":"string"},"expiryYear":{"type":"string"},"expiryMonth":{"type":"string"}}}}}}},"merchant":{"type":"string","format":"uri","description":"Merchant website URL to search and check out from"},"itemList":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Product name to search for on the merchant's site"},"quantity":{"type":"integer","minimum":1,"default":1},"selectedVariant":{"type":"object","description":"Variant options as key/value pairs, using the option names shown on the merchant's site (e.g. Shade, Color, Size)","additionalProperties":{"type":"string"}}}}},"options":{"type":"object","properties":{"verifyBeforePlacement":{"type":"boolean","default":false,"description":"Agent asks for confirmation just before placing the order"},"useSavedCredentialToLogin":{"type":"boolean","default":false,"description":"Agent signs in using the stored credentials created with the Create Credential Vault Session API"},"useGuestCheckoutIfLoginFails":{"type":"boolean","default":false,"description":"If the stored credentials do not work, the agent falls back to guest checkout when the merchant offers it"},"allowInteraction":{"type":"boolean","default":false,"description":"Enables the interactive flow instead of fire-and-forget; the agent can request additional input if it needs it"},"allowPartialCheckout":{"type":"boolean","default":false,"description":"If some items fail (e.g. out of stock), the agent still completes checkout for the remaining items"}}},"addons":{"type":"object","properties":{"couponCode":{"type":"array","items":{"type":"string"}}}}}},"examples":{"New Example":{"summary":"New Example","value":{"customer":{"contact":{"lastName":"Sturka","firstName":"Carol","phone":"+12144444444","email":"john.doe@example.com"},"shippingAddress":{"addressLine1":"609 Royal Crest Dr","addressLine2":"","city":"Richardson","province":"TX","postalCode":"75081","country":"US"},"billingAddress":{"addressLine1":"609 Royal Crest Dr","addressLine2":"","city":"Richardson","province":"TX","postalCode":"75081","country":"US"},"shippingMethod":{"strategy":"cheapest"},"payment":{"data":{"cvv":"444","name":"Carol Sturka","cardNumber":"4242424242424242","expiryYear":"2034","expiryMonth":"12"},"provider":"test"}},"merchant":"https://kyliecosmetics.com/","itemList":[{"name":"Velvet Brew Eau De Parfum Pen Spray","quantity":1},{"name":"Face Brush Trio"},{"name":"Blush Wood Eau De Parfum","quantity":2},{"name":"Plumping Matte Lip Kit","quantity":1,"selectedVariant":{"Shade":"candy k"}}],"options":{"verifyBeforePlacement":false,"useSavedCredentialToLogin":false,"useGuestCheckoutIfLoginFails":false,"allowInteraction":false,"allowPartialCheckout":true},"addons":{"couponCode":["SUMMER15"]}}}}}}}}},"/checkout/{taskId}":{"get":{"summary":"Get Checkout Task","tags":[],"operationId":"get_checkout-taskid","description":"Retrieves the full state of an existing checkout task — including its current status, execution history, derived pricing and shipping details, and the original customer and product data. Use this endpoint to track the progress of an asynchronous checkout task created via POST /checkout.","parameters":[{"in":"path","name":"taskId","schema":{"type":"string"},"required":true,"description":"Task Id returned in Create Checkout Task API should be used as Path Params. "},{"in":"header","name":"X-Api-Key","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"addons":{"type":"object","properties":{"couponCode":{"type":"array","items":{"type":"string"}}}}}},"examples":{"OK":{"summary":"OK","value":{"tid":"019bd5c5-2824-76d1-aa7a-01db5c4d7065","executionId":"019bd5d7-aba0-7080-95e0-8b183f4eca0b","executionNumber":3,"isLatest":true,"status":"FAILED","createdAt":"2026-01-19 10:40:39.608994","groupId":"019bd5c5-2824-76d1-aa7a-01c54a48e75e","merchant":"saltiebeauty.com","tasks":[{"url":"https://saltiebeauty.com/products/seaweed-hydrating-shampoo","quantity":1,"selectedVariant":{"color":"","size":"","fit":""},"options":null,"metadata":{"title":"SEAWEED HYDRATING SHAMPOO","description":"","primaryImage":"","price":""}}],"derivedDetails":{"pricing":null,"shippingMethod":null,"selectedShippingOption":null},"customer":{"contact":{"firstName":"Mauroki","lastName":"Wabrom","email":"wabrommauroki@gmail.com","phone":"+12144444444"},"shippingAddress":{"addressLine1":"3221 Robert Dr","addressLine2":"","city":"Richardson","province":"TX","postalCode":"75082","country":"United States"},"billingAddress":{"city":"Richardson","country":"United States","province":"TX","postalCode":"75082","addressLine1":"3221 Robert Dr","addressLine2":""},"shippingMethod":{"strategy":"cheapest"},"payment":{"data":{"cvv":"***","name":"Carol Sturka","cardNumber":"************4242","expiryYear":"2034","expiryMonth":"12"},"provider":"test"}},"iterations":[{"executionId":"019bd5c5-2824-76d1-aa7a-01e28ef271ed","executionNumber":1,"createdDate":"2026-01-19 10:20:26.532269"},{"executionId":"019bd5d0-ba19-7cd2-8902-e99e729e5b25","executionNumber":2,"createdDate":"2026-01-19 10:33:04.518568"},{"executionId":"019bd5d7-aba0-7080-95e0-8b183f4eca0b","executionNumber":3,"createdDate":"2026-01-19 10:40:39.608994"}],"addons":{"couponCode":["SUMMER15"]}}}}}}},"400":{"description":"Bad Request"}}},"delete":{"summary":"Cancel Checkout Task","tags":[],"operationId":"cancel_checkout","description":"Cancels an existing checkout task. This will stop any ongoing checkout processes and prevent further execution.","parameters":[{"in":"path","name":"taskId","schema":{"type":"string"},"required":true,"description":"The ID of the checkout task to cancel"},{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Checkout task cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"description":"Bad Request"}}}},"/checkout/{taskId}/status-history":{"get":{"summary":"Get Status History","tags":[],"operationId":"get_status_history","description":"Retrieves the complete status history for a checkout task, including all execution steps with their statuses, timestamps, and credits consumed.","parameters":[{"in":"path","name":"taskId","schema":{"type":"string"},"required":true,"description":"The ID of the checkout task"},{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Status history retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"taskId":{"type":"string"},"executionId":{"type":"string"},"status":{"type":"string"},"systemStatus":{"type":"string"},"createdAt":{"type":"string"},"isFailed":{"type":"boolean"},"note":{"type":"string"},"creditsConsumed":{"type":"number"},"retryCount":{"type":"integer"}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"SUCCESS","message":"History retrieved successfully","data":[{"id":19772,"taskId":"019e4a66-f86f-7eb0-ad9f-2aa1f149c03c","executionId":"019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367","status":"ORDER_CONFIRMED","systemStatus":"FAILED","createdAt":"2026-05-21 12:04:53.639675","isFailed":false,"note":null,"creditsConsumed":0.79,"retryCount":1},{"id":19771,"taskId":"019e4a66-f86f-7eb0-ad9f-2aa1f149c03c","executionId":"019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367","status":"CREDIT_CARD_INPUT","systemStatus":"IN_PROGRESS","createdAt":"2026-05-21 12:03:39.117765","isFailed":false,"note":null,"creditsConsumed":0.38,"retryCount":1}]}}}}}},"400":{"description":"Bad Request"}}}},"/checkout/{taskId}/{intent}":{"post":{"summary":"Send Interactive Inputs","tags":[],"operationId":"send_interactive_inputs","description":"Sends input from the customer to a checkout task that is paused and waiting for it. Right now the only supported input is an MFA/OTP code.","parameters":[{"in":"path","name":"taskId","schema":{"type":"string","format":"uuid"},"required":true,"description":"ID of the checkout task that is waiting for input"},{"in":"path","name":"intent","schema":{"type":"string","enum":["mfa"]},"required":true,"description":"Type of input being sent. Supported: mfa"},{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["otp"],"properties":{"otp":{"type":"string","minLength":4,"maxLength":8,"description":"The OTP/MFA code, 4–8 characters. Spaces at either end are trimmed. No other fields are allowed. Required when intent is mfa."}}},"examples":{"MFA":{"summary":"MFA / OTP code","value":{"otp":"482913"}}}}}},"responses":{"201":{"description":"Input submitted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"tasks":{"type":"array","items":{"type":"object","properties":{"taskId":{"type":"string"},"executionId":{"type":"string"},"status":{"type":"string"}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","message":"OTP submitted.","tasks":[{"taskId":"0193f2a1-7c4e-7b2a-9d1f-3e5a6b7c8d90","executionId":"0193f2a1-8d5f-7c3b-8e2a-4f6b7c8d9e01","status":"mfa_received"}]}}}}}},"400":{"description":"intent isn't supported, otp is missing or the wrong length, or the body has extra fields"},"403":{"description":"The task doesn't belong to the caller, or the task is past the stage where it accepts an OTP"},"404":{"description":"The task wasn't found"},"409":{"description":"An OTP was already submitted for this task"},"500":{"description":"Unexpected server error"}}}},"/product/details":{"post":{"summary":"Get Product Details","tags":[],"operationId":"get_product_details","description":"Retrieves detailed product information for a given product URL, including product metadata, available dimensions, and variant-level details such as pricing, availability, images, and attributes.","parameters":[{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The product page URL to fetch details for"},"allVariants":{"type":"boolean","description":"When true, returns all available variants for the product"}}},"examples":{"Example":{"summary":"Example","value":{"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","allVariants":true}}}}}},"responses":{"200":{"description":"Product found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"product":{"type":"object","properties":{"name":{"type":"string"},"brand":{"type":"string"},"retailer":{"type":"string"},"image":{"type":"string"},"url":{"type":"string"}}},"directUrl":{"type":"string"},"canCheckout":{"type":"object","description":"Checkout modes supported by the retailer","properties":{"login":{"type":"boolean"},"guest":{"type":"boolean"}}},"dimensions":{"type":"array","items":{"type":"string"},"description":"List of variant dimension names (e.g. Color, Band, Cup)"},"variants":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"price":{"type":"number"},"available":{"type":"boolean"},"image":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Key-value map of dimension name to value"},"url":{"type":"string"},"monetizationUrl":{"type":"string"}}}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","message":"Product found","data":{"product":{"name":"Semi Sheer Mock Neck Oasis Tank - Ivory","brand":"Alo Yoga","retailer":"Aloyoga","image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_03299_b2_s1_a2_dFA26_m18.jpg?v=1791487924","url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory"},"directUrl":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","canCheckout":{"login":true,"guest":true},"dimensions":["Color","Size"],"variants":[{"variantId":"50662297960807","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_03299_b2_s1_a2_dFA26_m18.jpg?v=1791487924","attributes":{"Color":"Ivory","Size":"XXS"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7a78827c73ef&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7a78827c73ef%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662297993575","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_03299_b2_s1_a2_dFA26_m18.jpg?v=1791487924","attributes":{"Color":"Ivory","Size":"XS"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7a8eb0282c05&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7a8eb0282c05%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662298026343","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_03299_b2_s1_a2_dFA26_m18.jpg?v=1791487924","attributes":{"Color":"Ivory","Size":"S"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7a9c13db6d09&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7a9c13db6d09%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662298059111","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_03299_b2_s1_a2_dFA26_m18.jpg?v=1791487924","attributes":{"Color":"Ivory","Size":"M"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7aaa72bc5996&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7aaa72bc5996%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662298091879","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_03299_b2_s1_a2_dFA26_m18.jpg?v=1791487924","attributes":{"Color":"Ivory","Size":"L"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7ab263bdcb3d&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7ab263bdcb3d%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662297796967","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_01_b1_s1_a50_dFA26_m161.jpg?v=1791488052","attributes":{"Color":"Black","Size":"XXS"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7acf310f8b61&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7acf310f8b61%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662297829735","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_01_b1_s1_a50_dFA26_m161.jpg?v=1791488052","attributes":{"Color":"Black","Size":"XS"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7ad2115199cb&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7ad2115199cb%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662297862503","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_01_b1_s1_a50_dFA26_m161.jpg?v=1791488052","attributes":{"Color":"Black","Size":"S"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6560-7a70-9035-7ae9c6c08181&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6560-7a70-9035-7ae9c6c08181%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662297895271","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_01_b1_s1_a50_dFA26_m161.jpg?v=1791488052","attributes":{"Color":"Black","Size":"M"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6561-7472-9841-92963c319f58&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6561-7472-9841-92963c319f58%26source%3Dcartai_sandbox_2%26status%3Dfail"},{"variantId":"50662297928039","price":64,"available":true,"image":"//cdn.shopify.com/s/files/1/2185/2813/files/W1518R_01_b1_s1_a50_dFA26_m161.jpg?v=1791488052","attributes":{"Color":"Black","Size":"L"},"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","monetizationUrl":"https://r.v2i8b.com/api/v1/bid/redirect?campaign_id=01KVGP6THTZDYF2QVW1RR7CMZJ&url=https%3A%2F%2Fwww.aloyoga.com%2Fproducts%2Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory&cid=CLK_sandbox_2_01a1633f-6561-7472-9841-92a0b3968683&source=cartai_sandbox_2&fb=https%3A%2F%2Fapi.cartai.ai%2Fcatalog%2Fredirect%3Furl%3Dhttps%253A%252F%252Fwww.aloyoga.com%252Fproducts%252Fw1518r-semi-sheer-mock-neck-oasis-tank-ivory%26dom%3Daloyoga.com%26cid%3DCLK_sandbox_2_01a1633f-6561-7472-9841-92a0b3968683%26source%3Dcartai_sandbox_2%26status%3Dfail"}]}}}}}}},"400":{"description":"Bad Request"}}}},"/product/search":{"post":{"summary":"Search Products","tags":[],"operationId":"search_products","description":"Searches for products by name across one or more merchants. Optionally prioritize results to a specific merchant. Returns a ranked list of matching products with pricing, imagery, and direct purchase links.","parameters":[{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Product name or search query"},"merchant":{"type":"string","description":"Optional merchant name to prioritize results for specific merchant (other retailers are still returned)"}}},"examples":{"With Merchant":{"summary":"With Merchant","value":{"name":"jeans","merchant":"Macy's"}},"Without Merchant":{"summary":"Without Merchant","value":{"name":"jeans"}}}}}},"responses":{"200":{"description":"Search complete","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"brand":{"type":"string"},"merchant":{"type":"string"},"image":{"type":"string"},"priceFrom":{"type":"number"},"currency":{"type":"string"},"directUrl":{"type":"string"}}}},"targetMerchant":{"type":"string","description":"The merchant filter applied to the search, if any"},"targetMatchCount":{"type":"integer","description":"Number of results matching the target merchant"}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","message":"Search complete","data":{"products":[{"name":"Dkny Jeans Women's High-Rise Jeans - Clifton","brand":"Dkny Jeans","merchant":"Macy's","image":"https://slimages.macysassets.com/is/image/MCY/products/0/optimized/35661058_fpx.tif?wid=1200&fmt=jpeg&qlt=100","priceFrom":26.63,"currency":"USD","directUrl":"https://www.macys.com/shop/product/dkny-jeans-womens-high-rise-jeans?ID=24996759"},{"name":"Nautica Jeans Women's Demi Bootcut Jeans - Sailor","brand":"Nautica Jeans","merchant":"Macy's","image":"https://slimages.macysassets.com/is/image/MCY/products/6/optimized/33148130_fpx.tif?wid=1200&fmt=jpeg&qlt=100","priceFrom":44.52,"currency":"USD","directUrl":"https://www.macys.com/shop/product/nautica-jeans-womens-demi-bootcut-jeans?ID=22497871"},{"name":"Slink Jeans Women's Modern Style Jean - Hydro","brand":"Slink Jeans","merchant":"Macy's","image":"https://slimages.macysassets.com/is/image/MCY/products/6/optimized/34981616_fpx.tif?wid=1200&fmt=jpeg&qlt=100","priceFrom":98,"currency":"USD","directUrl":"https://www.macys.com/shop/product/slink-jeans-womens-modern-style-jean?ID=25142822"},{"name":"Alison Low Rise Flared Jeans","brand":"edikted","merchant":"edikted","image":"https://cdn.shopify.com/s/files/1/0467/4148/7783/files/Edikted_Lookbook_01_29_2025159187_9adb6437-1053-4194-a011-6c3197a43454.jpg","priceFrom":36.8,"currency":"USD","directUrl":"https://edikted.com/products/s18683_blue?variant=46410352951463"}],"targetMerchant":"Macy's","targetMatchCount":5}}}}}}},"400":{"description":"Bad Request"}}}},"/checkout-estimates":{"post":{"summary":"Get Checkout Estimates","tags":[],"operationId":"get_checkout_estimates","description":"Computes a pre-checkout cost estimate for a given merchant, destination, and list of items — including subtotal, shipping, tax, and total. Useful for surfacing accurate pricing to users before initiating a full checkout.","parameters":[{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchant","destination","items"],"properties":{"merchant":{"type":"string","description":"Name of the merchant to estimate costs for"},"destination":{"type":"object","required":["zip"],"properties":{"zip":{"type":"string","description":"Destination ZIP code"}}},"items":{"type":"array","items":{"type":"object","required":["url","quantity","unitPrice","category"],"properties":{"url":{"type":"string","format":"uri","description":"Product page URL"},"quantity":{"type":"integer","minimum":1},"unitPrice":{"type":"number","description":"Price per unit"},"category":{"type":"string","description":"Product category (e.g. clothing)"}}}}}},"examples":{"Example":{"summary":"Example","value":{"merchant":"Alo Yoga","destination":{"zip":"75001"},"items":[{"url":"https://www.aloyoga.com/products/w1518r-semi-sheer-mock-neck-oasis-tank-ivory","quantity":1,"unitPrice":64,"category":"clothing"}]}}}}}},"responses":{"200":{"description":"Estimate computed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"currency":{"type":"string"},"merchant":{"type":"string"},"destination":{"type":"object","properties":{"zip":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"}}},"subtotal":{"type":"number"},"shipping":{"type":"number"},"shippingKnown":{"type":"boolean","description":"Whether the shipping cost was successfully determined"},"tax":{"type":"number"},"taxKnown":{"type":"boolean","description":"Whether the tax amount was successfully determined"},"total":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"unitPrice":{"type":"number"},"quantity":{"type":"integer"},"lineSubtotal":{"type":"number"},"tax":{"type":"number"}}}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","message":"Estimate computed","data":{"currency":"USD","merchant":"Alo Yoga","destination":{"zip":"75001","state":"TX","country":"US"},"subtotal":64,"shipping":0,"shippingKnown":true,"tax":5.28,"taxKnown":true,"total":69.28,"items":[{"category":"clothing","unitPrice":64,"quantity":1,"lineSubtotal":64,"tax":5.28}]}}}}}}},"400":{"description":"Bad Request"}}}},"/payment/session":{"post":{"summary":"Create Payment Session","tags":[],"operationId":"create_payment_session","description":"Creates a hosted payment session that generates a secure URL for embedding in your web application. The session initiates Visa Intelligent Commerce or Mastercard Agent Pay based on the customer's card. Share the returned URL with the customer to complete payment.","parameters":[{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","price","purpose"],"properties":{"email":{"type":"string","format":"email","description":"Customer's email address"},"price":{"type":"string","description":"Payment amount in USD"},"purpose":{"type":"string","description":"Description of what the payment is for (e.g. agent name or product)"}}},"examples":{"Example":{"summary":"Example","value":{"email":"customer@example.com","price":"700","purpose":"Carol's Purchase Agent"}}}}}},"responses":{"200":{"description":"Payment session created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"url":{"type":"string","description":"Hosted payment URL to embed in your web application. Starts Visa Intelligent Commerce or Mastercard Agent Pay based on the customer's card."},"sessionId":{"type":"string"},"mode":{"type":"string","enum":["production","test"]},"created_at":{"type":"string","format":"date-time"},"authorization":{"type":"object","properties":{"price":{"type":"string"},"currency":{"type":"string"},"purpose":{"type":"string"},"expiry":{"type":"string","format":"date-time"}}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","code":200,"message":"Payment session created successfully","data":{"url":"https://wallet.cartai.ai?token=<jwt_token>&type=bt&mode=p","sessionId":"019ed477-7954-7d92-8884-d442d1f91549","mode":"production","created_at":"2026-06-17T07:24:20.497354","authorization":{"price":"700","currency":"USD","purpose":"Carol's Purchase Agent","expiry":"2026-06-24T07:20:32.875162+00:00"}}}}}}}},"400":{"description":"Bad Request"}}}},"/payment/session/{sessionId}":{"delete":{"summary":"Delete Payment Session","tags":[],"operationId":"delete_payment_session","description":"Deletes an existing payment session. Once deleted, the hosted payment URL stops working and payment credentials can no longer be retrieved for the session.","parameters":[{"in":"path","name":"sessionId","schema":{"type":"string"},"required":true,"description":"The sessionId returned by Create Payment Session"},{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Payment session deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"integer"},"message":{"type":"string"}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","code":200,"message":"Payment session deleted successfully"}}}}}},"400":{"description":"Bad Request"},"404":{"description":"Payment session not found"}}}},"/payment/session/credentials":{"post":{"summary":"Get Payment Credentials","tags":[],"operationId":"get_payment_credentials","description":"Retrieves the payment credentials for a payment session the customer has already authorized through the hosted payment flow. Optionally pass the merchant URL to get credentials for a specific merchant.","parameters":[{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId"],"properties":{"sessionId":{"type":"string","description":"The sessionId returned by Create Payment Session"},"merchantUrl":{"type":"string","description":"Optional. Website URL of the merchant the credentials will be used on"}}},"examples":{"Example":{"summary":"Example","value":{"sessionId":"01a1d3ad-e7d9-7981-8a1e-c0a1b9ec65c1","merchantUrl":"https://saltiebeauty.com"}},"SessionOnly":{"summary":"Without merchantUrl","value":{"sessionId":"01a1d3ad-e7d9-7981-8a1e-c0a1b9ec65c1"}}}}}},"responses":{"200":{"description":"Payment credentials retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"type":{"type":"string","description":"Credential type (e.g. \"card\")"},"info":{"type":"object","properties":{"cardNumber":{"type":"string","description":"Card number"},"cvv":{"type":"string","description":"Card verification value"},"expiryMonth":{"type":"string","description":"Two-digit expiry month"},"expiryYear":{"type":"string","description":"Four-digit expiry year"}}}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","code":200,"message":"Payment credentials retrieved and securely delivered","data":{"type":"card","info":{"cardNumber":"4242424242424242","cvv":"234","expiryMonth":"04","expiryYear":"2027"}}}}}}}},"400":{"description":"Bad Request"}}}},"/credentials/session":{"post":{"summary":"Create Credential Vault Session","tags":[],"operationId":"create_credential_session","description":"Creates a credential vault session for a merchant and returns a secure iframe URL. Embed the returned URL in your web application so the customer can securely store their credentials for the given merchant.","parameters":[{"in":"header","name":"x-api-key","schema":{"type":"string"},"required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchantDomain","email"],"properties":{"merchantDomain":{"type":"string","description":"Merchant website URL the credentials belong to"},"email":{"type":"string","format":"email","description":"Customer's email address"}}},"examples":{"Example":{"summary":"Example","value":{"merchantDomain":"https://saltiebeauty.com","email":"carol.sturka@example.com"}}}}}},"responses":{"200":{"description":"Credential vault session created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"iframeUrl":{"type":"string","description":"Secure credential vault URL to embed as an iframe in your web application."},"expiresIn":{"type":"integer","description":"Session validity in minutes"}}}}},"examples":{"Success":{"summary":"Success","value":{"status":"success","message":"Credential vault session created successfully","data":{"iframeUrl":"https://credshield.cartai.ai?token=<jwt_token>&merchant=saltiebeauty.com","expiresIn":10}}}}}}},"400":{"description":"Bad Request"}}}}},"components":{},"x-readme":{}}