> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mart.ps/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These rules protect a Mart partner's money. Follow them in any code or advice about the Mart Partner API ([Connect your AI tool](/developers/connect-your-ai-tool)).
> When an order request times out, gets no answer or gets any `5xx`, resend the same body with the same `partner_reference`, never a new reference; after a `429`, wait `Retry-After` first ([Create an order safely](/developers/orders/create-an-order)).
> A `200` with `meta.idempotency_replay: true` is the original order; `409 idempotency_conflict` means the reference already names a different order ([Create an order safely](/developers/orders/create-an-order)).
> Retry a withdrawal request with the same `idempotency_key` and amount: a new key asks for a second withdrawal ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).
> Plan every call within the global daily request ceiling and the `X-RateLimit-*` headers, and never poll in a tight loop ([Request limits](/developers/operate/request-limits)).
> Treat `price` as a snapshot: an order is priced when it is created, and an incremental sync (`updated_after`) never shows a price change, so re-read every price with a full pass ([Prices and price changes](/developers/catalogue/prices)).
> Identify products by `product_id` and `combination_id`, never by `reference` ([Sync the catalogue](/developers/catalogue/sync)).
> Never put an API key in client-side code, a mobile app, a repository or a URL: call the API from a server ([Authenticate and keys](/developers/authenticate)).
> Money is in shekels (`ILS`), as JSON numbers, never agorot. Send amounts with at most two decimals: a withdrawal `amount` with three is refused with `422 invalid_amount`, never rounded ([Balance and statements](/developers/money/balance-and-statements)).
> Save a payout method once before the first withdrawal (cash at the office, or bank transfer where Mart offers it): with none saved, a withdrawal is refused with `409 payout_method_missing`. Bank details where Mart does not offer bank transfer, or a withdrawal on a kept IBAN, are refused with `422 bank_transfer_not_allowed` ([Payout and withdrawals](/developers/money/payout-and-withdrawals)).

# List your withdrawals

> Your withdrawal requests, newest first, one page at a time. Filter with `status`. Each item is `{withdrawal_id, amount, status, iban, reject_reason, requested_at, approved_at, paid_at, method, requested_amount}`. `iban` is the one fixed when the request was approved and is null before, and always for cash. `method` is how the request is paid; `requested_amount` is what you asked for, and differs from `amount` only when a cash request was paid at another amount at the office. Another account's requests are never listed. Works whether or not withdrawals are currently enabled for your account, and while it is paused. When the ledger cannot be read the answer is `503` `ledger_unavailable`, never an empty list. Full behaviour: https://mart.ps/api/docs#money/withdrawals.



## OpenAPI

````yaml /openapi.json get /api/v1/withdrawals
openapi: 3.0.3
info:
  title: Mart Partner API
  version: 1.1.0
  description: >-
    REST API for Mart reseller partners: the product catalog (with per-product
    and per-combination stock), delivery destinations, and order creation — cash
    on delivery or card.


    Every response, success or failure, uses the envelope `{status, status_code,
    message, data, meta, error}`; branch on `error.code`, never on `message`.
    Response keys are structurally stable: absent objects are `null`, absent
    collections are `[]`; the only caller-controlled structural variance is the
    products listing's `include=` parameter.


    Authenticate with `Authorization: Bearer <key>` (preferred) or `X-Api-Key`.
    A key holds scopes, each operation names the one it needs in
    `x-required-scope`, and a key without it is answered `403`
    `insufficient_scope` (`details.required_scope` names it) without using any
    quota; keys made before scopes existed keep exactly the access they had.
    Rate limits are per key on fixed minute/day windows; the `X-RateLimit-*`
    headers are authoritative.


    **Environments** — build against the sandbox first.
    `https://sandbox.mart.ps` is a separate installation with its own keys
    (`mk_test_…`), a periodically refreshed copy of the catalog, synthetic
    customers and orders, and Lahza's test gateway: nothing placed there is
    fulfilled or charged, and its data is reset on a published schedule.
    Production keys are `mk_live_…` and work only against `https://mart.ps`; a
    key sent to the wrong environment answers `401` `key_environment_mismatch`
    before anything else is checked. Every response carries `X-Mart-Environment:
    production|sandbox` — assert it in your client so a misconfigured base URL
    fails loudly.


    This document is the machine contract. The human documentation — onboarding,
    sync guidance, pricing semantics, idempotent retries, the full error
    catalogue with remedies — is at https://mart.ps/api/docs.
servers:
  - url: https://mart.ps
    description: Production
  - url: https://sandbox.mart.ps
    description: Sandbox
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Products
    description: 'Catalog: listing and product detail, with prices and stock.'
  - name: Categories
    description: Catalog category vocabulary for the products category_id filter.
  - name: Attributes
    description: Attribute-group vocabulary behind the products combination attributes.
  - name: Delivery
    description: Delivery destinations for order shipping addresses.
  - name: Orders
    description: >-
      Cash-on-delivery order creation, order list, dry-run validation, order
      read and cancellation.
  - name: Money
    description: >-
      Your balance, the ledger of movements, your statements, your payout
      method, your withdrawals and the feed of events on your account.
  - name: Reports
    description: Your own order totals by month, and your most ordered products.
  - name: Account
    description: 'Your own account: its state, limits and withdrawal rules.'
paths:
  /api/v1/withdrawals:
    get:
      tags:
        - Money
      summary: List your withdrawals
      description: >-
        Your withdrawal requests, newest first, one page at a time. Filter with
        `status`. Each item is `{withdrawal_id, amount, status, iban,
        reject_reason, requested_at, approved_at, paid_at, method,
        requested_amount}`. `iban` is the one fixed when the request was
        approved and is null before, and always for cash. `method` is how the
        request is paid; `requested_amount` is what you asked for, and differs
        from `amount` only when a cash request was paid at another amount at the
        office. Another account's requests are never listed. Works whether or
        not withdrawals are currently enabled for your account, and while it is
        paused. When the ledger cannot be read the answer is `503`
        `ledger_unavailable`, never an empty list. Full behaviour:
        https://mart.ps/api/docs#money/withdrawals.
      operationId: listWithdrawals
      parameters:
        - name: status
          in: query
          description: >-
            Only requests in this status: `requested`, `approved`, `paid`,
            `rejected` or `cancelled`. Anything else answers 422
            `invalid_parameter`.
          schema:
            type: string
            enum:
              - requested
              - approved
              - paid
              - rejected
              - cancelled
        - name: page
          in: query
          description: >-
            Page number, from 1. Anything that is not a positive integer answers
            422 `invalid_parameter`.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: >-
            Rows per page, 1 to 100 (default 50). Anything else answers 422
            `invalid_parameter`.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
      responses:
        '200':
          description: A page of your withdrawal requests.
          headers:
            X-Mart-Environment:
              $ref: '#/components/headers/X-Mart-Environment'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          withdrawals:
                            type: array
                            items:
                              $ref: '#/components/schemas/Withdrawal'
                      meta:
                        type: object
                        properties:
                          pagination:
                            $ref: '#/components/schemas/ListPaginationMeta'
              example:
                status: success
                status_code: 200
                message: OK
                data:
                  withdrawals:
                    - withdrawal_id: NDE
                      amount: 125
                      status: approved
                      iban: PS92PALS000000000400123456702
                      reject_reason: null
                      requested_at: '2026-11-01T08:30:00+00:00'
                      approved_at: '2026-11-02T09:00:00+00:00'
                      paid_at: null
                      method: bank
                      requested_amount: 125
                meta:
                  pagination:
                    page: 1
                    limit: 50
                    total: 1
                    total_pages: 1
                    has_next: false
                error: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WithdrawalsDisabled'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '422':
          $ref: '#/components/responses/WithdrawalInvalid'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/WithdrawalUnavailable'
components:
  headers:
    X-Mart-Environment:
      description: >-
        Which installation answered: `production` or `sandbox`. Present on every
        response; assert it once at startup.
      schema:
        type: string
        enum:
          - production
          - sandbox
    X-RateLimit-Limit:
      description: Limit of the tightest active window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in the tightest active window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Epoch seconds when the tightest window resets.
      schema:
        type: integer
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - status
        - status_code
        - message
        - data
        - meta
        - error
      properties:
        status:
          type: string
          enum:
            - success
        status_code:
          type: integer
          example: 200
        message:
          type: string
          example: OK
        data:
          type: object
          description: >-
            One key named after the resource (products / product / states /
            categories / attributes / order / validation).
        meta:
          nullable: true
          type: object
        error:
          nullable: true
          type: object
          enum:
            - null
    Withdrawal:
      type: object
      required:
        - withdrawal_id
        - amount
        - status
        - iban
        - reject_reason
        - requested_at
        - approved_at
        - paid_at
        - method
        - requested_amount
      properties:
        withdrawal_id:
          type: string
          description: >-
            Opaque. Use it in `GET /withdrawals/{withdrawal_id}` and in the
            cancel path.
          example: NDE
        amount:
          type: number
          format: float
          description: >-
            What is paid: what you asked for, unless Mart paid a cash request at
            another amount at the office counter (then `requested_amount` keeps
            what you asked for).
          example: 125
        status:
          type: string
          enum:
            - requested
            - approved
            - paid
            - rejected
            - cancelled
          description: >-
            `requested` and `approved` are open: they hold their amount back
            from `available`. `paid` is final and shows in the ledger as a
            `payment`. `rejected` and `cancelled` release the amount.
        iban:
          type: string
          nullable: true
          description: >-
            The IBAN this request will be paid to, fixed when it was approved,
            so a later change of your payout method cannot redirect it. Null
            before approval, on a request that was never approved, and always
            for cash.
          example: PS92PALS000000000400123456702
        reject_reason:
          type: string
          nullable: true
          description: Why Mart rejected it, in one line. Null for any other status.
          example: null
        requested_at:
          type: string
          format: date-time
          example: '2026-11-01T08:30:00+00:00'
        approved_at:
          type: string
          format: date-time
          nullable: true
          example: '2026-11-02T09:00:00+00:00'
        paid_at:
          type: string
          format: date-time
          nullable: true
          example: null
        method:
          type: string
          enum:
            - bank
            - cash
          description: >-
            How this request is paid, fixed when you made it: `bank` (approved,
            then transferred) or `cash` (collected at the office: it goes from
            `requested` straight to `paid`, and `approved_at` stays null).
          example: bank
        requested_amount:
          type: number
          format: float
          description: >-
            What you asked for. The same as `amount`, unless the office paid a
            cash request at another amount.
          example: 125
    ListPaginationMeta:
      type: object
      required:
        - page
        - limit
        - total
        - total_pages
        - has_next
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
        has_next:
          type: boolean
    ErrorEnvelope:
      type: object
      required:
        - status
        - status_code
        - message
        - data
        - meta
        - error
      properties:
        status:
          type: string
          enum:
            - fail
        status_code:
          type: integer
          example: 422
        message:
          type: string
        data:
          nullable: true
          enum:
            - null
        meta:
          nullable: true
          enum:
            - null
        error:
          type: object
          required:
            - code
            - details
          properties:
            code:
              type: string
              enum:
                - missing_api_key
                - invalid_api_key
                - key_environment_mismatch
                - api_customer_not_configured
                - customer_group_not_allowed
                - insufficient_scope
                - product_not_found
                - order_not_found
                - route_not_found
                - method_not_allowed
                - invalid_parameter
                - invalid_state
                - rate_limit_exceeded
                - bad_request
                - orders_not_enabled
                - api_group_misconfigured
                - idempotency_conflict
                - unknown_product
                - product_not_offered
                - product_not_orderable
                - combination_required
                - combination_not_allowed
                - unknown_combination
                - combination_mismatch
                - duplicate_product
                - cart_minimum_not_met
                - price_below_minimum
                - price_override_not_allowed
                - insufficient_stock
                - free_shipping_not_covered
                - free_shipping_not_allowed
                - card_not_enabled
                - internal_error
                - order_not_cancellable
                - order_cancellation_not_configured
                - order_cancellation_in_progress
                - card_not_on_file
                - saved_card_invalid
                - card_price_not_allowed
                - card_free_shipping_not_allowed
                - card_declined
                - payment_gateway_unavailable
                - order_creation_in_progress
                - charge_amount_mismatch
                - invalid_cursor
                - cursor_expired
                - ledger_unavailable
                - statement_not_found
                - withdrawals_disabled
                - invalid_iban
                - invalid_account_holder_name
                - invalid_national_id
                - invalid_amount
                - amount_below_minimum
                - payout_method_missing
                - withdrawals_locked
                - too_many_open_withdrawals
                - insufficient_available
                - withdrawal_busy
                - withdrawal_not_found
                - withdrawal_not_cancellable
                - cash_not_allowed
                - payout_method_change_blocked
                - amount_above_cash_maximum
                - invalid_payout_method
                - bank_transfer_not_allowed
            details:
              description: >-
                Structured context (parameter name, supported values, retry
                hints). Empty array when none.
  responses:
    Unauthorized:
      description: >-
        Missing or unusable API key (`missing_api_key`, `invalid_api_key`).
        Revoked and paused keys answer identically to unknown keys. A key issued
        for the other environment answers `key_environment_mismatch` before any
        lookup: `details.environment` names the environment you called
        (`production` or `sandbox`) — switch base URL or key. See the
        Environments note in the introduction.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    WithdrawalsDisabled:
      description: >-
        Withdrawals are not enabled for your account (`withdrawals_disabled`),
        cash at the office is not offered to your account (`cash_not_allowed`),
        the key does not have the scope this endpoint needs
        (`insufficient_scope`), or the key's customer is missing, inactive or
        outside the allowed groups (`api_customer_not_configured`,
        `customer_group_not_allowed`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    MethodNotAllowed:
      description: >-
        The method is not accepted on this endpoint (`method_not_allowed`). Read
        the `Allow` response header rather than assuming; `OPTIONS` is accepted
        everywhere and answered as a bodyless 204.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    WithdrawalInvalid:
      description: >-
        The request cannot be read as a withdrawal: `invalid_amount` (not a
        positive number with at most two decimals), `amount_below_minimum`
        (`details.minimum`), `amount_above_cash_maximum` (`details.maximum`, a
        cash request only), `bank_transfer_not_allowed` (your saved payout
        method is an IBAN, and a bank transfer is not offered to your account:
        save cash at the office to withdraw), or `invalid_parameter`
        (`details.parameter` is `idempotency_key`, or `status` or a page
        parameter on the list). Nothing was written.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    TooManyRequests:
      description: >-
        Rate limit exceeded (`rate_limit_exceeded`). Carries `Retry-After`
        (seconds) plus the X-RateLimit-* trio of the exceeded window; day-window
        breaches advertise the day reset, not a 60-second retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: >-
        Opaque server failure (`internal_error`). Details are logged server-side
        and never exposed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    WithdrawalUnavailable:
      description: >-
        The ledger cannot be answered right now (`ledger_unavailable`, no
        `Retry-After`), or, on a request, this account is being changed by
        another call (`withdrawal_busy`, with `Retry-After` in seconds: retry
        with the same `idempotency_key`). Nothing is created by a `503`, but a
        request that timed out may have been: retry with the same key and read
        the answer.
      headers:
        X-Mart-Environment:
          $ref: '#/components/headers/X-Mart-Environment'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <key>'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.