> ## Documentation Index > Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit savings order > Create a top up or withdrawal order for a user's savings plan. ## OpenAPI ````yaml POST /savings/orders openapi: 3.0.3 info: title: Wealthyhood Savings Orders API version: 1.0.0 description: > Savings-specific trading endpoints for Wealthyhood portfolios. All requests use machine-to-machine (M2M) authentication. Each request requires: - A bearer access token (M2M token with required scopes) - An `x-user-id` header to specify which user's data to access servers: - url: https://{host} variables: host: default: api.wealthyhood.com description: Wealthyhood API host name. security: - bearerAuth: [] tags: - name: Savings Orders description: Submit top ups or withdrawals against a user's savings plan. paths: /savings/orders: post: tags: - Savings Orders summary: Submit a savings order description: > Submit a top up (buy) or withdrawal (sell) savings order. The request only requires the savings side, currency, and amount. The underlying savings instrument is implied by the selected currency. parameters: - $ref: '#/components/parameters/XUserId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSavingsOrderRequest' examples: topUp: summary: Savings top up request value: side: Buy currency: EUR amount: 250 withdrawal: summary: Savings withdrawal request value: side: Sell currency: EUR amount: 150 responses: '200': description: Savings order accepted for processing content: application/json: schema: $ref: '#/components/schemas/SavingsOrder' example: id: 7501d8537fb3fc001234abcd displayId: ORD-ABC123 side: Buy status: Pending currency: EUR amount: 250 settledAt: '2024-07-12T00:00:00.000Z' createdAt: '2024-07-11T10:00:00Z' updatedAt: '2024-07-11T10:00:00Z' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' components: parameters: XUserId: name: x-user-id in: header required: true description: >- User identifier for the M2M client to specify which user's data to access. schema: type: string pattern: ^[a-f0-9]{24}$ schemas: CreateSavingsOrderRequest: type: object required: - side - currency - amount properties: side: type: string description: Savings order direction. enum: - Buy - Sell currency: type: string description: ISO 4217 currency that identifies the savings product. enum: - GBP - EUR - USD amount: type: number format: double description: Monetary amount to invest or withdraw. minimum: 0.01 SavingsOrder: type: object required: - id - side - status - isin - consideration properties: id: type: string description: Savings order identifier. displayId: type: string description: User-friendly display identifier for the order (e.g. ORD-ABC123). side: type: string enum: - Buy - Sell description: >- Direction of the savings order (`Buy` for top up, `Sell` for withdrawal). status: type: string enum: - Pending - Matched - Rejected - Settled - Cancelled description: Current order status. isin: type: string description: ISIN of the savings product. quantity: type: number format: double description: Order quantity (optional). consideration: type: object required: - currency - amount description: Savings order consideration with currency and amount. properties: currency: type: string description: ISO 4217 currency code example: EUR enum: - GBP - EUR - USD amount: type: number format: double description: Monetary amount in major units example: 250 minimum: 0 settledAt: type: string format: date-time nullable: true description: ISO datetime when the savings order is expected to settle. fees: type: object nullable: true description: Fee breakdown for the savings order (optional). properties: realtimeExecution: type: object properties: currency: type: string enum: - GBP - EUR - USD amount: type: number format: double createdAt: type: string format: date-time description: Timestamp when the order was created (optional). filledAt: type: string format: date-time nullable: true description: ISO datetime when order was matched unitPrice: type: object description: Price per unit in major units (e.g. 1.00 for €1.00). properties: currency: type: string enum: - GBP - EUR - USD amount: type: number format: double fxRate: type: object nullable: true description: >- Exchange rate used for currency conversion (optional, present for foreign currency orders). properties: rate: type: number format: double description: Exchange rate value currency: type: string description: ISO 4217 currency code enum: - GBP - EUR - USD isCancellable: type: boolean description: Whether the order can be cancelled by the user. ApiErrorResponse: type: object properties: status: type: integer error: type: object properties: message: type: string description: type: string nullable: true responseId: type: string format: uuid responses: BadRequestError: description: Validation failure or business rule violation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: 400 error: message: Amount must be greater than zero description: Operation failed responseId: 7c91c5fe-d5a8-4b82-8e3f-5af2e30e43c2 UnauthorizedError: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: 401 error: message: User not found responseId: 145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a ForbiddenError: description: >- Authenticated user cannot act on the requested portfolio or lacks scopes. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: 403 error: message: Portfolio does not belong to user responseId: 5e467f79-c62c-4d83-9810-7a0f8529fd76 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Auth0-issued access token that includes the scopes listed for the endpoint. ````