{"openapi":"3.1.0","info":{"title":"Voqado agent storefront","version":"1.0.0","description":"A print storefront built for shopping assistants. Start with GET /api/agents/catalog?summary=1, then ?product=<slug> for one product. Find a product, quote it exactly, and hand the owner a pay link. The owner reviews and pays in the cart. Artwork can be sent after payment. Bank details for checks are added by the owner in a secure step from the cart, never through an agent. Do not send bank details to an agent or to this API.","contact":{"email":"print@voqado.co","url":"https://www.voqado.co/agents"}},"externalDocs":{"url":"https://www.voqado.co/agents/docs"},"servers":[{"url":"https://www.voqado.co"}],"paths":{"/api/agents/catalog":{"get":{"operationId":"getCatalog","summary":"Every orderable product with options, quantities and starting price.","description":"Call ?summary=1 first: every product slug, its options, default options, quantities and starting price in a small response. Then call ?product=<slug> for one product with every option set and its quantities. The full catalog without a filter is several hundred KB.","parameters":[{"name":"product","in":"query","schema":{"type":"string"},"description":"One product slug."},{"name":"category","in":"query","schema":{"type":"string"},"description":"One category slug."},{"name":"summary","in":"query","schema":{"type":"string","enum":["1"]},"description":"Leave out the per option quantity ladders. Use this for the first call."}],"responses":{"200":{"description":"The catalog.","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer"},"currency":{"const":"usd"},"products":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"categoryName":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"values":{"type":"array","items":{"type":"string"}}}}},"defaultOptions":{"type":"object","additionalProperties":{"type":"string"}},"quantities":{"type":"array","items":{"type":"integer"}},"quantityLadders":{"type":"array","items":{"type":"object","properties":{"options":{"type":"object","additionalProperties":{"type":"string"}},"quantities":{"type":"array","items":{"type":"integer"}}}}},"startingPrice":{"type":["object","null"],"properties":{"amountCents":{"type":"integer"},"quantity":{"type":"integer"},"label":{"type":"string"}}}}}}}}}}},"404":{"description":"No orderable product with that slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/quote":{"post":{"operationId":"quote","summary":"Exact prices, shipping and problems for up to 30 lines. Writes nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"const":"usd"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLine"}},"subtotalCents":{"type":"integer"},"promo":{"type":["object","null"],"properties":{"code":{"type":"string"},"status":{"type":"string","enum":["applied","refused","checked-at-payment"]},"discountCents":{"type":"integer"},"message":{"type":"string"}}},"itemsCents":{"type":"integer"},"shipping":{"$ref":"#/components/schemas/Shipping"},"totalBeforeTaxCents":{"type":"integer"},"orderable":{"type":"boolean"},"suggestions":{"type":"array","maxItems":2,"items":{"$ref":"#/components/schemas/Suggestion"}},"notes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Invalid body, or a refused bank field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body over 64 KB or more than 30 lines.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type is not application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 30 requests a minute per address.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents/order":{"post":{"operationId":"createPayLink","summary":"A signed pay link for the owner. Charges nothing and stores nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"A pay link, valid for 7 days.","content":{"application/json":{"schema":{"type":"object","required":["payUrl","expiresAt","lines","subtotalCents"],"properties":{"payUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLine"}},"subtotalCents":{"type":"integer"},"subtotal":{"type":"string"},"promo":{"type":["object","null"],"properties":{"code":{"type":"string"},"status":{"type":"string","enum":["applied","refused","checked-at-payment"]},"discountCents":{"type":"integer"},"message":{"type":"string"}}},"shipping":{"$ref":"#/components/schemas/Shipping"},"totalBeforeTaxCents":{"type":"integer"},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/Suggestion"}},"notes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Invalid body, or a refused bank field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"At least one line cannot be ordered as asked.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"status":{"type":"integer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLine"}}}}}}},"413":{"description":"Body over 64 KB or more than 30 lines.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type is not application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited: 10 requests a minute per address.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Pay links are switched off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Line":{"type":"object","required":["product","quantity"],"additionalProperties":false,"properties":{"product":{"type":"string","description":"Product slug from the catalog.","examples":["standard-business-cards"]},"quantity":{"type":"integer","minimum":1,"description":"One of the quantities listed for the chosen options."},"options":{"type":"object","additionalProperties":{"type":"string"},"description":"Option key to value, from the catalog. Required options left out take the default configuration."},"customization":{"type":"object","additionalProperties":{"type":"string"},"description":"Garments and bags: \"sizes\" such as \"M 6, L 4\" and \"colors\". Never bank details."}}},"Request":{"type":"object","required":["lines"],"additionalProperties":false,"properties":{"lines":{"type":"array","minItems":1,"maxItems":30,"items":{"$ref":"#/components/schemas/Line"}},"promoCode":{"type":"string","maxLength":24}}},"QuoteLine":{"type":"object","properties":{"index":{"type":"integer"},"product":{"type":"string"},"name":{"type":["string","null"]},"url":{"type":["string","null"]},"quantity":{"type":"integer"},"options":{"type":"object","additionalProperties":{"type":"string"}},"priceCents":{"type":["integer","null"]},"price":{"type":["string","null"]},"status":{"type":"string","enum":["ready","owner-step","problem"]},"problem":{"type":["string","null"]},"ownerSteps":{"type":"array","items":{"type":"string"}},"nextQuantity":{"type":["object","null"],"properties":{"quantity":{"type":"integer"},"priceCents":{"type":"integer"},"price":{"type":"string"},"savingPercentPerUnit":{"type":"integer"}}},"allowedQuantities":{"type":"array","items":{"type":"integer"},"description":"Present on a line refused for its quantity: the quantities sold with its options."}}},"Shipping":{"type":"object","properties":{"method":{"const":"Standard"},"cents":{"type":"integer"},"freeShippingThresholdCents":{"type":"integer"},"freeShippingGapCents":{"type":"integer"}}},"Suggestion":{"type":"object","properties":{"product":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"reason":{"type":"string"},"startingPrice":{"type":["string","null"]}}},"Error":{"type":"object","required":["error","status"],"properties":{"error":{"type":"string"},"status":{"type":"integer"}}}}}}