{"openapi":"3.0.0","info":{"title":"Order.co API - Bearer Token Auth","version":"2","description":"External API for querying spend history and shipment data on Order.co, authenticated via API Token (Bearer).\n\nThis API uses scoped Bearer Token authentication. Tokens are issued per organization and carry specific scopes that control access to individual endpoints. The organization is resolved automatically from the token — no Organization-Id header is required.\n\nFor the legacy Application Key / Secret Key authentication, see the Order.co API - Legacy Auth documentation.\n","contact":{"email":"tech@order.co"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"}},"servers":[{"url":"https://app.order.co/api/"}],"tags":[{"name":"Locations","description":"Create and update locations for an organization."},{"name":"Savings","description":"Retrieve AI-generated savings recommendations for an organization."},{"name":"Shipments","description":"Retrieve active shipment and tracking information for an organization."},{"name":"Spend History","description":"Retrieve historical spending data for an organization."}],"paths":{"/locations":{"post":{"tags":["Locations"],"summary":"Create a new location for the organization.","operationId":"createLocation","description":"Creates a new location under the organization resolved from the bearer token.\n\n**Required scope:** `locations:write`\n\nNote: `deactivated_at` is not an accepted field on this endpoint. If included in the request body it is silently ignored — locations are always created active.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","description":"Bearer token for authentication. Must be in the format: `Bearer ord_<48 hex characters>`. The token determines which organization the request is scoped to and which permissions are available.\n","required":true,"schema":{"type":"string","example":"Bearer ord_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationCreateRequest"},"example":{"location":{"value":"Building 5","description":"Warehouse","address_attributes":{"line_1":"159 5th Ave","line_2":"Floor 700","city":"New York","state":"NY","zipcode":"10010","country":"US","attn_to":"Tom","name":"Order.co","nickname":"HQ","phone_number":"5164912895","delivery_instructions":"Leave at front desk"}}}}}},"responses":{"201":{"description":"Location created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"400":{"description":"The request body failed validation (e.g., a required address field was blank).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationValidationError"},"example":{"errors":["Address line 1 can't be blank"]}}}},"401":{"description":"Authentication failed — missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Token is valid but lacks the required scope (locations:write).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientScopeError"},"example":{"error":"Insufficient scope. Required: locations:write"}}}},"404":{"description":"Organization not found for the provided token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Organization not found or unauthorized"}}}}}}}}},"/locations/{id}":{"put":{"tags":["Locations"],"summary":"Update an existing location.","operationId":"updateLocation","description":"Updates an existing location within the organization resolved from the bearer token. Only the fields provided in the request body are updated.\n\n**Required scope:** `locations:write`\n\nNote: `deactivated_at` is not an accepted field on this endpoint. If included in the request body it is silently ignored.\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","description":"Bearer token for authentication. Must be in the format: `Bearer ord_<48 hex characters>`. The token determines which organization the request is scoped to and which permissions are available.\n","required":true,"schema":{"type":"string","example":"Bearer ord_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"}},{"name":"id","in":"path","description":"The internal ID of the location in Order.co.","required":true,"schema":{"type":"integer","example":42}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationUpdateRequest"},"example":{"location":{"value":"Building 5 (Updated)","description":"Warehouse - East Wing","address_attributes":{"line_1":"159 5th Ave","line_2":"Floor 701","city":"New York","state":"NY","zipcode":"10010","country":"US","attn_to":"Tom","name":"Order.co","nickname":"HQ East","phone_number":"5164912895","delivery_instructions":"Leave at loading dock"}}}}}},"responses":{"200":{"description":"Location updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Location"}}}},"400":{"description":"The update was rejected — either the request body failed validation, or the location is deactivated (deactivated locations cannot be updated; the update is rejected outright, not partially applied).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationValidationError"},"examples":{"validation_error":{"summary":"Request body failed validation","value":{"errors":["Address line 1 can't be blank"]}},"deactivated_location":{"summary":"Location is deactivated","value":{"errors":["Location is deactivated"]}}}}}},"401":{"description":"Authentication failed — missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Token is valid but lacks the required scope (locations:write).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientScopeError"},"example":{"error":"Insufficient scope. Required: locations:write"}}}},"404":{"description":"Not found — either the organization could not be resolved from the token (auth layer), or no location with the given `id` exists within that organization (business-logic lookup; also returned if the `id` belongs to a different organization). Note the differing body shape between the two causes: the organization case uses a singular `error` string, the location case uses a plural `errors` array.\n","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},{"$ref":"#/components/schemas/LocationValidationError"}]},"examples":{"organization_not_found":{"summary":"Organization not found for the provided token","value":{"error":"Organization not found or unauthorized"}},"location_not_found":{"summary":"No location with this id in the resolved organization","value":{"errors":["Location not found"]}}}}}}}}},"/savings/recommendations":{"get":{"tags":["Savings"],"summary":"Retrieve savings recommendations for an organization.","operationId":"getSavingsRecommendations","description":"Returns AI-generated product swap recommendations that could reduce spending for the authenticated organization. Each recommendation identifies a currently purchased product and a lower-cost alternative from another vendor, along with estimated savings.\n\nResults are ordered by rank (highest potential savings first) and support pagination.\n\n**Required scope:** `savings:read`\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","description":"Bearer token for authentication. Must be in the format: `Bearer ord_<48 hex characters>`. The token determines which organization the request is scoped to and which permissions are available.\n","required":true,"schema":{"type":"string","example":"Bearer ord_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"}},{"name":"page","in":"query","description":"Page number to return. Default is 1.\n","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"default":1,"example":1}},{"name":"per_page","in":"query","description":"Number of records to return per page. Default is 5. Maximum is 25.\n","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":25,"default":5,"example":5}}],"responses":{"200":{"description":"Savings recommendations with pagination.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavingsRecommendation"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"data":[{"id":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","original_product":{"organizations_product_id":12345,"name":"Brawny Tall Kitchen Bags 13gal","vendor_id":101,"vendor_name":"Staples","unit_price":{"amount":"14.99","currency":"USD"},"order_count_90d":8,"quantity_90d":40,"charged_subtotal_90d":{"amount":"599.60","currency":"USD"}},"recommended_product":{"product_id":67890,"name":"Brawny Tall Kitchen Bags 13gal","vendor_id":202,"vendor_name":"HD Supply","unit_price":{"amount":"11.49","currency":"USD"}},"savings":{"per_unit":{"amount":"3.50","currency":"USD"},"percentage":"23.3","potential_90d":{"amount":"140.00","currency":"USD"}},"recommendation_reason":"cross_vendor_same_product","rank":1,"purchase_stats_window_days":90,"computed_at":"2026-05-12T08:00:00Z"},{"id":"a4f7b23c91de5f0812abc3456789def0123456789abcdef0123456789abcdef01","original_product":{"organizations_product_id":23456,"name":"Copy Paper 8.5x11 Case","vendor_id":303,"vendor_name":"Amazon Business","unit_price":{"amount":"42.99","currency":"USD"},"order_count_90d":12,"quantity_90d":24,"charged_subtotal_90d":{"amount":"1031.76","currency":"USD"}},"recommended_product":{"product_id":78901,"name":"Copy Paper 8.5x11 Case","vendor_id":404,"vendor_name":"Staples","unit_price":{"amount":"34.99","currency":"USD"}},"savings":{"per_unit":{"amount":"8.00","currency":"USD"},"percentage":"18.6","potential_90d":{"amount":"192.00","currency":"USD"}},"recommendation_reason":"cross_vendor_same_product","rank":2,"purchase_stats_window_days":90,"computed_at":"2026-05-12T08:00:00Z"}],"pagination":{"current_page":1,"per_page":5,"total_count":2}}}}},"401":{"description":"Authentication failed — missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Token is valid but lacks the required scope (savings:read).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientScopeError"}}}},"404":{"description":"Organization not found for the provided token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Organization not found or unauthorized"}}}}}},"500":{"description":"Internal server error (e.g., data warehouse unavailable).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Unable to fetch savings recommendations"}}}}}}}}},"/shipments/active":{"get":{"tags":["Shipments"],"summary":"Retrieve active shipments for an organization.","operationId":"getActiveShipments","description":"Retrieves shipment and tracking data for the authenticated organization. Results are scoped to the user identified by the `X-User-Email` header and support optional filtering by tracking category and pagination.\n\n**Required scope:** `shipments:read`\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","description":"Bearer token for authentication. Must be in the format: `Bearer ord_<48 hex characters>`. The token determines which organization the request is scoped to and which permissions are available.\n","required":true,"schema":{"type":"string","example":"Bearer ord_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"}},{"name":"X-User-Email","in":"header","description":"Email address of the user within the organization to scope results to. Must match an existing user in the organization associated with the Bearer token.\n","required":true,"schema":{"type":"string","format":"email","example":"jane.doe@example.com"}},{"name":"tracking_category","in":"query","description":"Filter shipments by tracking category. When omitted, all active shipments are returned regardless of category. `coming_soon` covers shipments that are in transit or out for delivery. `needs_attention` covers failed deliveries and items available for pickup. `other` covers info received, delayed, and unknown statuses.\n","required":false,"schema":{"type":"string","enum":["coming_soon","delivered","needs_attention","other"],"example":"coming_soon"}},{"name":"page","in":"query","description":"Page number to return. Default is 1.\n","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"default":1,"example":1}},{"name":"per_page","in":"query","description":"Number of records to return per page. Default is 25. Maximum is 100.\n","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":100,"default":25,"example":25}}],"responses":{"200":{"description":"Active shipment data with pagination and request metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ActiveShipmentItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"type":"object","properties":{"tracking_category":{"type":"string","nullable":true,"description":"The tracking category filter applied to the request, if any.","example":"coming_soon"}}}}},"example":{"data":[{"ai_shipment_summary":"Your package is on its way and expected to arrive by Friday.","courier_name":"UPS","delivered_at":null,"estimated_delivery_date":{"start":"2025-10-04T00:00:00Z","end":"2025-10-06T00:00:00Z"},"location":"New York Office","status":"in_transit","tracking_category":"coming_soon","tracking_number":"1Z999AA10123456784","tracking_url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","updated_at":"2025-10-03T14:22:00Z","vendor_name":"Office Supplies Inc","order":{"number":"67890","purchase_order_number":"PO-2025-001"},"products":[{"name":"White Grocery Bags","quantity":10}]}],"pagination":{"current_page":1,"per_page":25},"meta":{"tracking_category":"coming_soon"}}}}},"400":{"description":"Bad request — the `X-User-Email` header is missing or does not match any user in the organization associated with the Bearer token.\n"},"401":{"description":"Authentication failed — missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Token is valid but lacks the required scope (shipments:read).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientScopeError"}}}},"404":{"description":"Organization not found for the provided token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Organization not found or unauthorized"}}}}}}}}},"/spend_history":{"get":{"tags":["Spend History"],"summary":"Retrieve spend history for an organization.","operationId":"getSpendHistory","description":"Retrieves historical spending data for the authenticated organization with optional date filtering and pagination support.\n\n**Required scope:** `spend_history:read`\n","security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","description":"Bearer token for authentication. Must be in the format: `Bearer ord_<48 hex characters>`. The token determines which organization the request is scoped to and which permissions are available.\n","required":true,"schema":{"type":"string","example":"Bearer ord_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6"}},{"name":"start_date","in":"query","description":"Filter spend history records from this date (inclusive). Format: YYYY-MM-DD.\n","required":false,"schema":{"type":"string","format":"date","example":"2025-09-01"}},{"name":"end_date","in":"query","description":"Filter spend history records up to this date (inclusive). Format: YYYY-MM-DD.\n","required":false,"schema":{"type":"string","format":"date","example":"2025-09-23"}},{"name":"per_page","in":"query","description":"Number of records to return per page. Default is 1000.\n","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"maximum":10000,"default":1000,"example":100}},{"name":"page","in":"query","description":"Page number to return. Default is 1.\n","required":false,"schema":{"type":"integer","format":"int32","minimum":1,"default":1,"example":1}}],"responses":{"200":{"description":"Spend history data with pagination.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SpendHistoryItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"example":{"data":[{"id":12345,"organization_id":52032,"order_id":67890,"order_vendor_id":54321,"product_id":98765,"product_name":"White Grocery Bags","item_description":"White Grocery Bags - 100 count","quantity":10.0,"unit_price":2500,"total_price":25000,"currency":"USD","vendor_id":11111,"vendor_name":"Office Supplies Inc","completed_at":"2024-01-15T14:30:00Z","created_at":"2024-01-10T09:15:00Z","location_id":22222,"location_name":"Main Office","cost_center_id":33333,"cost_center_name":"Operations","user_id":44444,"user_name":"John Doe","accounting_codes":[{"id":55555,"value":"OFFICE-SUPPLIES","description":"Office Supplies Account"}],"status":"completed","fulfillment_type":"standard"}],"pagination":{"current_page":1,"per_page":1000}}}}},"401":{"description":"Authentication failed — missing, invalid, or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"403":{"description":"Token is valid but lacks the required scope (spend_history:read).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientScopeError"}}}},"404":{"description":"Organization not found for the provided token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Organization not found or unauthorized"}}}}}},"500":{"description":"Internal server error (e.g., data warehouse unavailable).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Database connection failed"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API Token issued by Order.co. Tokens use the prefix `ord_` followed by 48 hex characters (52 characters total). Each token is scoped to a specific organization and carries permission scopes that control which endpoints it can access.\n\nExample: `ord_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6`\n\nInclude in requests as: `Authorization: Bearer ord_...`\n"}},"schemas":{"ActiveShipmentItem":{"type":"object","properties":{"ai_shipment_summary":{"type":"string","nullable":true,"description":"AI-generated summary of the shipment status.","example":"Your package is on its way and expected to arrive by Friday."},"courier_name":{"type":"string","nullable":true,"description":"Name of the courier handling the shipment.","example":"UPS"},"delivered_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO 8601 timestamp of when the shipment was delivered. Null if not yet delivered.","example":"2025-10-06T10:30:00Z"},"estimated_delivery_date":{"type":"object","description":"Estimated delivery window for the shipment.","properties":{"start":{"type":"string","format":"date-time","nullable":true,"description":"Start of the estimated delivery window (ISO 8601).","example":"2025-10-04T00:00:00Z"},"end":{"type":"string","format":"date-time","nullable":true,"description":"End of the estimated delivery window (ISO 8601).","example":"2025-10-06T00:00:00Z"}}},"location":{"type":"string","nullable":true,"description":"Name of the delivery location associated with the order.","example":"New York Office"},"status":{"type":"string","description":"Normalized shipment status.","example":"in_transit"},"tracking_category":{"type":"string","nullable":true,"description":"High-level tracking category derived from the shipment status.","example":"coming_soon"},"tracking_number":{"type":"string","description":"The carrier tracking number.","example":"1Z999AA10123456784"},"tracking_url":{"type":"string","nullable":true,"description":"URL to the carrier's tracking page for this shipment.","example":"https://www.ups.com/track?tracknum=1Z999AA10123456784"},"updated_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the last update to this tracking record.","example":"2025-10-03T14:22:00Z"},"vendor_name":{"type":"string","nullable":true,"description":"Name of the vendor who fulfilled the order.","example":"Office Supplies Inc"},"order":{"type":"object","description":"Order information associated with this shipment.","properties":{"number":{"type":"string","description":"Internal order ID.","example":"67890"},"purchase_order_number":{"type":"string","nullable":true,"description":"External purchase order number, if set.","example":"PO-2025-001"}}},"products":{"type":"array","description":"Products included in this shipment.","items":{"type":"object","properties":{"name":{"type":"string","description":"Product name (uses custom name if set, otherwise catalog name).","example":"White Grocery Bags"},"quantity":{"type":"number","description":"Quantity of this product in the shipment.","example":10}}}}}},"SpendHistoryItem":{"type":"object","properties":{"id":{"type":"integer","description":"Line item ID.","example":12345},"organization_id":{"type":"integer","description":"Organization ID.","example":52032},"order_id":{"type":"integer","description":"Order ID.","example":67890},"order_vendor_id":{"type":"integer","description":"Order vendor ID.","example":54321},"product_id":{"type":"integer","description":"Product ID.","example":98765},"product_name":{"type":"string","description":"Product name.","example":"White Grocery Bags"},"item_description":{"type":"string","description":"Line item description.","example":"White Grocery Bags - 100 count"},"quantity":{"type":"number","description":"Quantity ordered.","example":10.0},"unit_price":{"type":"number","description":"Unit price in cents.","example":2500},"total_price":{"type":"number","description":"Total price in cents.","example":25000},"currency":{"type":"string","description":"ISO 4217 currency code.","example":"USD"},"vendor_id":{"type":"integer","description":"Vendor ID.","example":11111},"vendor_name":{"type":"string","description":"Vendor name.","example":"Office Supplies Inc"},"completed_at":{"type":"string","format":"date-time","description":"When the transaction was completed.","example":"2024-01-15T14:30:00Z"},"created_at":{"type":"string","format":"date-time","description":"When the line item was created.","example":"2024-01-10T09:15:00Z"},"location_id":{"type":"integer","description":"Location ID.","example":22222},"location_name":{"type":"string","description":"Location name.","example":"Main Office"},"cost_center_id":{"type":"integer","description":"Cost center ID.","example":33333},"cost_center_name":{"type":"string","description":"Cost center name.","example":"Operations"},"user_id":{"type":"integer","description":"User ID who placed the order.","example":44444},"user_name":{"type":"string","description":"User name.","example":"John Doe"},"accounting_codes":{"type":"array","items":{"$ref":"#/components/schemas/AccountingCode"}},"status":{"type":"string","description":"Line item status.","example":"completed"},"fulfillment_type":{"type":"string","description":"Fulfillment type.","example":"standard"}}},"AccountingCode":{"type":"object","properties":{"id":{"type":"integer","description":"Accounting code ID.","example":55555},"value":{"type":"string","description":"Accounting code value.","example":"OFFICE-SUPPLIES"},"description":{"type":"string","description":"Accounting code description.","example":"Office Supplies Account"}}},"SavingsRecommendation":{"type":"object","properties":{"id":{"type":"string","description":"Deterministic identifier derived from the organization, product, and candidate product. Stable across requests for the same recommendation.\n","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"original_product":{"type":"object","description":"The product the organization currently purchases.","properties":{"organizations_product_id":{"type":"integer","description":"Organization-specific product ID.","example":12345},"name":{"type":"string","description":"Display name of the product.","example":"Brawny Tall Kitchen Bags 13gal"},"vendor_id":{"type":"integer","description":"Current vendor ID.","example":101},"vendor_name":{"type":"string","description":"Current vendor name.","example":"Staples"},"unit_price":{"$ref":"#/components/schemas/Money"},"order_count_90d":{"type":"integer","description":"Number of orders for this product in the last 90 days.","example":8},"quantity_90d":{"type":"integer","description":"Total quantity ordered in the last 90 days.","example":40},"charged_subtotal_90d":{"$ref":"#/components/schemas/Money"}}},"recommended_product":{"type":"object","description":"The lower-cost alternative product being recommended.","properties":{"product_id":{"type":"integer","description":"Candidate product ID.","example":67890},"name":{"type":"string","description":"Display name of the recommended product.","example":"Brawny Tall Kitchen Bags 13gal"},"vendor_id":{"type":"integer","description":"Recommended vendor ID.","example":202},"vendor_name":{"type":"string","description":"Recommended vendor name.","example":"HD Supply"},"unit_price":{"$ref":"#/components/schemas/Money"}}},"savings":{"type":"object","description":"Estimated savings if the organization switches to the recommended product.","properties":{"per_unit":{"$ref":"#/components/schemas/Money"},"percentage":{"type":"string","description":"Estimated savings as a percentage of the original unit price.","example":"23.3"},"potential_90d":{"$ref":"#/components/schemas/Money"}}},"recommendation_reason":{"type":"string","description":"Why this recommendation was generated.","example":"cross_vendor_same_product"},"rank":{"type":"integer","description":"Rank within the organization, ordered by potential savings (1 = highest savings).\n","example":1},"purchase_stats_window_days":{"type":"integer","description":"Number of days of purchase history used to compute the recommendation.","example":90},"computed_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when this recommendation was computed.","example":"2026-05-12T08:00:00Z"}}},"Money":{"type":"object","description":"A monetary amount with currency.","properties":{"amount":{"type":"string","description":"Decimal amount as a string to preserve precision.","example":"14.99"},"currency":{"type":"string","description":"ISO 4217 currency code.","example":"USD"}}},"Pagination":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page number.","example":1},"per_page":{"type":"integer","description":"Number of items per page.","example":1000},"total_count":{"type":"integer","description":"Total number of records across all pages. Present on endpoints that support it (e.g., savings recommendations).\n","example":42}}},"AuthenticationError":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized"}}},"InsufficientScopeError":{"type":"object","properties":{"error":{"type":"string","example":"Insufficient scope. Required: spend_history:read"}}},"LocationCreateRequest":{"type":"object","required":["location"],"properties":{"location":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"Location name.","example":"Building 5"},"description":{"type":"string","description":"Human-readable description of the location.","example":"Warehouse"},"address_attributes":{"$ref":"#/components/schemas/LocationAddressAttributes"}}}}},"LocationUpdateRequest":{"type":"object","required":["location"],"description":"All fields are optional — only the fields provided are updated, existing values are left unchanged.\n","properties":{"location":{"type":"object","properties":{"value":{"type":"string","description":"Location name.","example":"Building 5 (Updated)"},"description":{"type":"string","description":"Human-readable description of the location.","example":"Warehouse - East Wing"},"address_attributes":{"$ref":"#/components/schemas/LocationAddressAttributes"}}}}},"LocationAddressAttributes":{"type":"object","description":"Physical address details for the location.","properties":{"line_1":{"type":"string","description":"Street address line 1.","example":"159 5th Ave"},"line_2":{"type":"string","description":"Street address line 2 (suite, floor, etc.).","example":"Floor 700"},"city":{"type":"string","example":"New York"},"state":{"type":"string","description":"State or province code.","example":"NY"},"zipcode":{"type":"string","example":"10010"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","example":"US"},"attn_to":{"type":"string","description":"Attention to (recipient name).","example":"Tom"},"name":{"type":"string","description":"Address label or name.","example":"Order.co"},"nickname":{"type":"string","description":"Short, friendly label for the address (optional).","example":"HQ"},"phone_number":{"type":"string","example":"5164912895"},"delivery_instructions":{"type":"string","description":"Special instructions for deliveries.","example":"Leave at front desk"}}},"Location":{"type":"object","description":"Sanitized location payload. Never includes internal-only IDs (organization_id, address_id), timestamps, or deactivated_at/deleted_at.\n","properties":{"id":{"type":"integer","description":"Internal location ID in Order.co.","example":42},"value":{"type":"string","description":"Location name.","example":"Building 5"},"description":{"type":"string","example":"Warehouse"},"address":{"$ref":"#/components/schemas/Address"}}},"Address":{"type":"object","description":"Physical address associated with the location.","properties":{"line_1":{"type":"string","example":"159 5th Ave"},"line_2":{"type":"string","example":"Floor 700"},"city":{"type":"string","example":"New York"},"state":{"type":"string","example":"NY"},"zipcode":{"type":"string","example":"10010"},"country":{"type":"string","example":"US"},"attn_to":{"type":"string","example":"Tom"},"name":{"type":"string","example":"Order.co"},"nickname":{"type":"string","nullable":true,"example":"HQ"},"phone_number":{"type":"string","example":"5164912895"},"delivery_instructions":{"type":"string","example":"Leave at front desk"}}},"LocationValidationError":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"string"},"example":["Address line 1 can't be blank"]}}}}}}