--- updatedAt: 2026-05-26T22:53:01.000Z agentTools: projectIndex: https://developer.vinoshipper.com/llms.txt --- # Purchase an Order with a Stripe Card Terminal Process payment through the Vinoshipper using stripe terminal you have paired to your account. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Vinoshipper API Docs", "version": "3.0", "x-logo": { "url": "/static/img/brand/vinoshipper-logo.svg" } }, "servers": [ { "url": "https://vinoshipper.com" } ], "tags": [ { "name": "Order", "description": "Post-purchase order operations" }, { "name": "Order", "description": "Pre-purchase order operations" } ], "paths": { "/api/v3/p/orders/{orderNumber}/terminal": { "post": { "tags": [ "Order" ], "summary": "Purchase an Order with a Stripe Card Terminal", "description": "Process payment through the Vinoshipper using stripe terminal you have paired to your account.", "operationId": "purchaseWithTerminal", "parameters": [ { "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeTerminalIdentifier" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Request has failed validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed", "content": {} }, "403": { "description": "Insufficient permission", "content": {} }, "404": { "description": "Not Found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BasicAuth": [] } ] } } }, "components": { "schemas": { "Error": { "required": [ "code", "description" ], "type": "object", "properties": { "description": { "type": "string" }, "code": { "type": "string" }, "field": { "type": "string" }, "shortDescription": { "type": "string" } } }, "ErrorDetails": { "required": [ "status", "type" ], "type": "object", "properties": { "status": { "type": "integer", "format": "int32" }, "type": { "type": "string", "enum": [ "VALIDATION", "COMPLIANCE", "PAYMENT_FAILURE", "SERVER_ERROR", "ACCESS_DENIED", "CONFLICT" ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "ErrorResponse": { "required": [ "error" ], "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetails" } } }, "AccessPoint": { "required": [ "businessName", "city", "country", "lat", "lng", "locationId", "postalCode", "stateCode", "street1" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "locationId": { "type": "string", "description": "UPS Location ID" }, "lat": { "type": "number", "readOnly": true }, "lng": { "type": "number", "readOnly": true }, "imageUrl": { "type": "string", "description": "A full URL to an image associated with the Access Point", "nullable": true, "readOnly": true }, "hours": { "type": "string", "description": "Text describing open hours", "nullable": true, "readOnly": true }, "note": { "type": "string", "description": "Optional note from access point", "nullable": true, "readOnly": true }, "businessName": { "type": "string", "readOnly": true }, "street1": { "type": "string", "readOnly": true }, "street2": { "type": "string", "nullable": true, "readOnly": true }, "city": { "type": "string", "readOnly": true }, "postalCode": { "type": "string", "readOnly": true }, "stateCode": { "type": "string", "readOnly": true }, "country": { "type": "string", "description": "Two letter country code", "readOnly": true }, "phoneNumber": { "type": "string", "nullable": true, "readOnly": true } }, "description": "UPS access point", "nullable": true }, "Address": { "required": [ "city", "country", "fullName", "poBox", "postalCode", "stateCode", "street1", "suspectedPOBox", "verifiedNotPOBox" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "nullable": true, "readOnly": true }, "salutation": { "type": "string", "description": "Formal greeting or title of the customer" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "businessName": { "type": "string", "nullable": true }, "fullName": { "type": "string", "description": "Use firstName and lastName instead.", "nullable": true, "deprecated": true }, "street1": { "type": "string" }, "street2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "postalCode": { "type": "string", "description": "ZIP Code" }, "stateCode": { "type": "string" }, "country": { "type": "string", "description": "Two letter country code", "default": "US" }, "phoneNumber": { "type": "string", "description": "Use phone instead.", "nullable": true, "deprecated": true }, "phone": { "$ref": "#/components/schemas/InternationalPhoneNumber" }, "accessPoint": { "$ref": "#/components/schemas/AccessPoint" }, "description": { "type": "string", "description": "A description for the address, e.g. Home, Work", "nullable": true }, "suspectedPOBox": { "type": "boolean", "description": "True if the address is suspected of being a PO Box", "readOnly": true }, "poBox": { "type": "boolean", "description": "True if this address is confirmed as a PO Box", "readOnly": true }, "verifiedNotPOBox": { "type": "boolean", "description": "True if someone has confirmed this address is not a PO Box. Club processing skips its PO Box check for such an address even when the text still reads like one.", "readOnly": true }, "linkedAddress": { "$ref": "#/components/schemas/LinkedAddress" } }, "description": "The address of the location where the sale is made", "nullable": true }, "InternationalPhoneNumber": { "type": "object", "properties": { "number": { "type": "string" }, "country": { "type": "integer", "format": "int32" }, "extension": { "type": "string" } }, "nullable": true }, "LinkedAddress": { "required": [ "city", "country", "fullName", "postalCode", "stateCode", "street1" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "nullable": true, "readOnly": true }, "salutation": { "type": "string", "description": "Formal greeting or title of the customer" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "businessName": { "type": "string", "nullable": true }, "fullName": { "type": "string", "description": "Use firstName and lastName instead.", "nullable": true, "deprecated": true }, "street1": { "type": "string" }, "street2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "postalCode": { "type": "string", "description": "ZIP Code" }, "stateCode": { "type": "string" }, "country": { "type": "string", "description": "Two letter country code", "default": "US" }, "phoneNumber": { "type": "string", "description": "Use phone instead.", "nullable": true, "deprecated": true }, "phone": { "$ref": "#/components/schemas/InternationalPhoneNumber" }, "description": { "type": "string", "description": "A description for the address, e.g. Home, Work", "nullable": true }, "accessPoint": { "$ref": "#/components/schemas/AccessPoint" } } }, "OrderInvoiceView": { "required": [ "paid" ], "type": "object", "properties": { "terms": { "type": "string", "description": "Payment terms code (DUE_ON_RECEIPT, NET_15, NET_30)" }, "termsLabel": { "type": "string", "description": "Human-readable payment terms label" }, "dueDate": { "type": "string", "description": "Payment due date, null for DUE_ON_RECEIPT or no terms", "format": "date" }, "paidAt": { "type": "string", "description": "When the invoice was marked as paid, null if unpaid", "format": "date" }, "paid": { "type": "boolean", "description": "Whether the invoice has been paid" }, "paymentMethod": { "type": "string", "description": "How the invoice was paid (SalePaymentMethod enum name, e.g. CHECK), null until marked paid" }, "paymentMethodDisplayName": { "type": "string", "description": "Display label for paymentMethod (e.g. Check)" } }, "description": "Invoice details for a wholesale order", "nullable": true }, "SpecialInstructions": { "type": "object", "properties": { "producerNote": { "maxLength": 1024, "type": "string", "description": "A note for the producer's internal use, not displayed to customers.", "nullable": true }, "giftNote": { "type": "string", "description": "A customer provided gift note, appears on receipt and packing slip.", "nullable": true }, "shipDate": { "pattern": "YYYY-MM-dd", "type": "string", "description": "The date the shipment should be held until.", "format": "date", "nullable": true } } }, "AgeVerificationDetail": { "required": [ "verified" ], "type": "object", "properties": { "verified": { "type": "boolean" }, "idScanUrl": { "type": "string" } } }, "BoxDimensions": { "required": [ "depthInches", "heightInches", "widthInches" ], "type": "object", "properties": { "widthInches": { "type": "number", "description": "The box width in inches" }, "heightInches": { "type": "number", "description": "The box height in inches" }, "depthInches": { "type": "number", "description": "The box depth in inches" } } }, "BoxWeight": { "required": [ "lbs" ], "type": "object", "properties": { "lbs": { "type": "number", "description": "The box weight in pounds" } } }, "CustomerAddress": { "required": [ "city", "postalCode", "stateCode", "street1" ], "type": "object", "properties": { "street1": { "type": "string" }, "street2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "stateCode": { "type": "string" } } }, "CustomerOrderNotificationPreferences": { "type": "object", "properties": { "failedDeliveryEnabled": { "type": "boolean", "description": "Controls failed delivery attempt notifications (UPS delivery failures). Includes first, second, and final delivery failure notifications.\nUse true to always send these emails or false to never send them. Null/omitted fields follow the global disableCustomerNotifications setting.\nNote: Updates replace ALL notification preferences - omitted fields are removed. You must include all preferences you want to keep." }, "accessPointEnabled": { "type": "boolean", "description": "Controls UPS Access Point (AP) delivery notifications. Includes arrived at AP, unable to deliver to AP, and AP pickup required notifications.\nUse true to always send these emails or false to never send them. Null/omitted fields follow the global disableCustomerNotifications setting.\nNote: Updates replace ALL notification preferences - omitted fields are removed. You must include all preferences you want to keep." } }, "description": "Granular email notification preferences that override the global disableCustomerNotifications setting. Allows independent control of specific notification types." }, "DateOfBirth": { "required": [ "day", "month", "year" ], "type": "object", "properties": { "day": { "type": "integer", "format": "int32" }, "month": { "type": "integer", "format": "int32" }, "year": { "type": "integer", "format": "int32" } } }, "ExtraFeeDetail": { "required": [ "amount", "label" ], "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "number" }, "description": { "type": "string" } }, "description": "Extra fee details that add up to the extra fee total. " }, "IdAndName": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" } }, "description": "The store associated with the order" }, "MultiPack": { "required": [ "discount", "price", "productId", "quantity", "sku", "upc" ], "type": "object", "properties": { "productId": { "type": "integer", "format": "int32" }, "productName": { "type": "string" }, "sku": { "type": "string" }, "upc": { "type": "string" }, "productTaxonomy": { "$ref": "#/components/schemas/ProductTaxonomyView" }, "quantity": { "type": "integer", "format": "int32" }, "price": { "type": "number" }, "discount": { "type": "number" } } }, "Order": { "required": [ "ageVerification", "customer", "extraFee", "extraFeesAdjusted", "extraFeesTotal", "guestCheckout", "isCompliant", "orderNumber", "orderStatus", "packaging", "platformCharges", "productDiscount", "shipping", "shippingDiscount", "specialInstructions", "status", "taxes", "taxesAdjusted", "taxesTotal", "tipAmount", "total", "vsOrderNumber" ], "type": "object", "properties": { "orderNumber": { "type": "string", "description": "The external order number. For API orders this is your externally supplied number; otherwise it is Vinoshipper's order number." }, "vsOrderNumber": { "type": "string", "description": "Vinoshipper's internal order number. Changes when the order is modified (e.g. 12345A)." }, "cartType": { "type": "string" }, "sourceUrl": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCESS", "AGE_VERIFICATION_FAILED", "AGE_VERIFICATION_LOCKED", "DELETED", "PROBLEM", "PAYMENT_AUTHORIZED", "PAYMENT_CAPTURE_FAILED", "PENDING_PAYMENT" ] }, "orderStatus": { "type": "string", "enum": [ "OPEN", "LABELS_GENERATED", "SENT_TO_FULFILLMENT", "SHIPPED", "RETURNED", "DELIVERED", "PICKED_UP", "CANCELLED", "UNPAID", "PROBLEM", "NEW_MEMBER" ] }, "customer": { "$ref": "#/components/schemas/OrderCustomer" }, "guestCheckout": { "type": "boolean", "description": "True when the order was placed through guest checkout for an anonymous buyer rather than a customer" }, "shipToAddress": { "$ref": "#/components/schemas/Address" }, "productDiscount": { "type": "number" }, "shippingDiscount": { "type": "number" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" } }, "packs": { "type": "array", "items": { "$ref": "#/components/schemas/MultiPack" } }, "shipping": { "$ref": "#/components/schemas/ShippingDetail" }, "packaging": { "type": "number", "description": "Packaging fee charged to customer" }, "extraFee": { "type": "number", "description": "Use extraFeesTotal instead.", "deprecated": true }, "extraFeeDetails": { "type": "array", "description": "Use extraFees instead", "deprecated": true, "items": { "$ref": "#/components/schemas/ExtraFeeDetail" } }, "extraFees": { "type": "array", "description": "Extra fee details that add up to the extra fee total. ", "items": { "$ref": "#/components/schemas/ExtraFeeDetail" } }, "extraFeesTotal": { "type": "number", "description": "Extra fees total" }, "extraFeesAdjusted": { "type": "number", "description": "Difference between the other fees collected from customer and the Vinoshipper calculated other fees amount owed" }, "taxesTotal": { "type": "number", "description": "Total of taxes on value of products and shipping" }, "taxesAdjusted": { "type": "number", "description": "Difference between the taxes collected from customer and the Vinoshipper calculated tax amount owed" }, "taxes": { "$ref": "#/components/schemas/TaxDetails" }, "tipAmount": { "type": "number", "description": "Total tip amount" }, "total": { "type": "number" }, "specialInstructions": { "$ref": "#/components/schemas/SpecialInstructions" }, "holds": { "type": "array", "description": "The order's active holds: reasons it should not ship yet. Empty when it has none.", "items": { "$ref": "#/components/schemas/OrderHoldView" } }, "isCompliant": { "type": "boolean" }, "purchasedAt": { "type": "string", "format": "date-time" }, "canceledAt": { "type": "string", "format": "date-time" }, "shippedAt": { "type": "string", "description": "\n For carrier orders this is the time Vinoshipper received a scan notification from the\n carrier. For pickup and local delivery orders it is the time the order was marked picked\n up or delivered. If that date is later edited within the same calendar month, this is\n updated to match deliveredAt. Edits into a different calendar month leave this value\n unchanged.\n ", "format": "date-time" }, "deliveredAt": { "type": "string", "description": "\n For carrier shipments this is the time we received notification from the carrier that the\n order was successfully delivered. For other order types it is the pickup or delivery date,\n which the producer can edit after the fact.\n ", "format": "date-time" }, "metaFields": { "type": "object", "additionalProperties": { "type": "string" } }, "orderProblems": { "type": "array", "items": { "$ref": "#/components/schemas/Problem" } }, "ageVerification": { "$ref": "#/components/schemas/AgeVerificationDetail" }, "platformCharges": { "$ref": "#/components/schemas/PlatformCharges" }, "cancelReason": { "type": "string" }, "fulfillmentAccount": { "type": "string", "description": "The fulfillment account or route name to use when the producer allows multiple external fulfillment options. Most producers will not use this field." }, "store": { "$ref": "#/components/schemas/IdAndName" }, "customerNotificationPreferences": { "$ref": "#/components/schemas/CustomerOrderNotificationPreferences" }, "invoice": { "$ref": "#/components/schemas/OrderInvoiceView" }, "purchaseOrder": { "type": "string", "description": "The wholesale purchase order" }, "paymentMethod": { "type": "string", "description": "How the order was paid. Empty until a wholesale invoice is marked as paid; otherwise auto-derived from the payment processor." }, "paymentMethodDisplayName": { "type": "string", "description": "Display label for paymentMethod" }, "saleLocation": { "$ref": "#/components/schemas/ProducerLocationView" } } }, "OrderCustomer": { "required": [ "fullName", "wholesale" ], "type": "object", "properties": { "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "address": { "$ref": "#/components/schemas/CustomerAddress" }, "dateOfBirth": { "$ref": "#/components/schemas/DateOfBirth" }, "wholesale": { "type": "boolean", "readOnly": true }, "wholesaleType": { "type": "string", "readOnly": true, "enum": [ "DISTRIBUTOR", "RETAILER", "RESTAURANT", "OTHER" ] }, "company": { "type": "string" }, "id": { "type": "integer", "format": "int32" }, "fullName": { "type": "string" }, "customerSince": { "type": "string", "format": "date" } } }, "OrderHoldActorView": { "required": [ "role" ], "type": "object", "properties": { "role": { "type": "string", "description": "The kind of user who placed a hold", "enum": [ "PRODUCER", "ADMIN", "BUYER", "SHIPPER", "SYSTEM" ] }, "userId": { "type": "integer", "description": "Vinoshipper user id of the person who placed the hold. Null for automatic holds and guest buyers.", "format": "int32", "nullable": true } }, "description": "Who placed a hold", "nullable": true }, "OrderHoldView": { "required": [ "blocksExport", "type" ], "type": "object", "properties": { "type": { "type": "string", "description": "A kind of hold. An order has at most one hold of each type. More types will be added: a client should accept a value it doesn't know.", "enum": [ "HOLD_UNTIL" ] }, "expiresOn": { "type": "string", "description": "The hold lifts at the start of this date in the producer's timezone. Null for a hold that stays until it is removed.", "format": "date", "nullable": true }, "blocksExport": { "type": "boolean", "description": "Whether the hold keeps the order from being sent to a fulfillment center" }, "placedBy": { "$ref": "#/components/schemas/OrderHoldActorView" }, "placedAt": { "type": "string", "description": "When the hold was placed. Null for holds placed before this was recorded.", "format": "date-time", "nullable": true }, "note": { "type": "string", "description": "Note from the producer or admin who placed the hold", "nullable": true } }, "description": "A reason the order should not ship yet" }, "OrderLine": { "required": [ "alcoholPercentage", "category", "discount", "price", "productId", "quantity", "sku", "taxes", "upc" ], "type": "object", "properties": { "productId": { "type": "integer", "format": "int32" }, "productName": { "type": "string" }, "productVintage": { "type": "string" }, "sku": { "type": "string" }, "upc": { "type": "string" }, "category": { "type": "string" }, "productTaxonomy": { "$ref": "#/components/schemas/ProductTaxonomyView" }, "quantity": { "type": "integer", "format": "int32" }, "price": { "type": "number" }, "discount": { "type": "number" }, "alcoholPercentage": { "type": "number" }, "packProductId": { "type": "integer", "format": "int32" }, "taxes": { "$ref": "#/components/schemas/Taxes" }, "cogs": { "type": "number", "description": "Cost of goods sold per unit, snapshotted at order time with fallback to historical average", "nullable": true }, "grossCogs": { "type": "number", "description": "Gross COGS (cogs × quantity)", "nullable": true } } }, "Package": { "required": [ "box" ], "type": "object", "properties": { "carrier": { "type": "string", "description": "The carrier that was actually used to ship the package or null if unknown", "enum": [ "UPS", "FEDEX", "GLS", "SELF" ] }, "trackingNumber": { "type": "string" }, "box": { "$ref": "#/components/schemas/ShipmentBox" } } }, "PlatformCharges": { "required": [ "amountDue", "creditCardFee", "fundsReceived", "pickPackFee", "shipping", "stateFees", "taxExcise", "taxSales", "vinoshipperFee" ], "type": "object", "properties": { "fundsReceived": { "type": "number" }, "creditCardFee": { "type": "number" }, "pickPackFee": { "type": "number" }, "vinoshipperFee": { "type": "number" }, "shipping": { "type": "number" }, "taxSales": { "type": "number" }, "taxExcise": { "type": "number" }, "stateFees": { "type": "number" }, "amountDue": { "type": "number" } } }, "Problem": { "required": [ "code", "description", "resolvableByShippingClass", "type" ], "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "resolvableByShippingClass": { "type": "boolean", "description": "True if another shipping class, such as local delivery, would clear this problem. It still blocks the order until that choice is made." } } }, "ProducerLocationView": { "required": [ "address", "name" ], "type": "object", "properties": { "name": { "type": "string" }, "address": { "$ref": "#/components/schemas/Address" } }, "description": "The location where the sale was made", "nullable": true }, "ProductTaxonomyView": { "required": [ "displayName", "externalId", "id", "sortOrder" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "externalId": { "type": "string" }, "displayName": { "type": "string" }, "sortOrder": { "type": "integer", "format": "int32" } } }, "ShipmentBox": { "required": [ "containsAlcohol", "weight" ], "type": "object", "properties": { "weight": { "$ref": "#/components/schemas/BoxWeight" }, "dimensions": { "$ref": "#/components/schemas/BoxDimensions" }, "containsAlcohol": { "type": "boolean" } } }, "Shipper": { "required": [ "id", "isFulfillmentCenter", "name" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "isFulfillmentCenter": { "type": "boolean", "description": "If true, the shipper is a fulfillment center and you cannot use the schedule shipment api to create shipping labels." } } }, "ShippingDetail": { "required": [ "carrier", "price", "rateCode", "shipper" ], "type": "object", "properties": { "carrier": { "type": "string", "enum": [ "UPS", "FEDEX", "GLS", "SELF" ] }, "rateCode": { "type": "string" }, "price": { "type": "number" }, "shipper": { "$ref": "#/components/schemas/Shipper" }, "rateDescription": { "type": "string" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } }, "taxes": { "$ref": "#/components/schemas/Taxes" } } }, "TaxDetails": { "required": [ "cityTaxRate", "cityTaxes", "countyTaxRate", "countyTaxes", "customStateTaxes", "otherTaxRate", "otherTaxes", "stateTaxRate", "stateTaxes" ], "type": "object", "properties": { "county": { "type": "string" }, "countyTaxRate": { "type": "number" }, "countyReportingCode": { "type": "string" }, "countyTaxes": { "type": "number" }, "city": { "type": "string" }, "cityTaxRate": { "type": "number" }, "cityReportingCode": { "type": "string" }, "cityTaxes": { "type": "number" }, "state": { "type": "string" }, "stateTaxRate": { "type": "number" }, "stateTaxes": { "type": "number" }, "otherTaxRate": { "type": "number" }, "otherTaxes": { "type": "number" }, "customStateTaxes": { "type": "number" } }, "description": "The summary of taxes charged" }, "Taxes": { "required": [ "taxRate", "taxableValue", "taxes" ], "type": "object", "properties": { "taxRate": { "type": "number" }, "taxableValue": { "type": "number" }, "taxes": { "type": "number" } } }, "StripeTerminalIdentifier": { "type": "object", "properties": { "vsTerminalId": { "type": "integer", "description": "Vinoshipper's internal id for the terminal", "format": "int32" }, "stripeTerminalId": { "type": "string", "description": "Stripe's id for the terminal" }, "serialNumber": { "type": "string", "description": "The serial number (S/N) on the back of the terminal" } } } }, "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic" } } } } ```