> ## 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)).

# Save your payout method

> Saves how your money is paid. For a bank transfer send `iban` and `account_holder_name`, and optionally `national_id`; `method` may be left out, as before cash existed. For cash at Mart's office send `"method": "cash"`, the collector's full name as `account_holder_name` and optionally their ID number as `national_id`; no IBAN. Cash is offered only where Mart allows it for your account (`403` `cash_not_allowed`): save it once before your first cash withdrawal, naming who collects (yourself, or someone with their ID number). A bank transfer is offered only where Mart allows it for your account: elsewhere an IBAN is refused with `422` `bank_transfer_not_allowed` and nothing is saved. Switching between bank and cash is refused while a withdrawal is open (`409` `payout_method_change_blocked`: cancel it first). A request without `method` on a cash account switches it back to bank, so it needs an IBAN. Leaving `national_id` out keeps the one already saved; sending `null` or an empty string clears it. **A switch between bank and cash never carries the ID number over:** leaving `national_id` out on a switch clears it, so send it whenever the collector (or, back to bank, the account holder) has one. The IBAN may be typed with spaces or in lower case: it is stored without them, in upper case. Its check digits, its length for the country and its country are checked: only the countries Mart has enabled for your account are accepted. **Saving or changing the IBAN locks withdrawals for a number of hours set for your account** (`withdrawals_locked_until`); a change never shortens a lock that is still running. A switch between bank and cash, and for cash a change of the collector's name or ID number, locks the same way. For a bank transfer, changing only the name or the national ID does not lock. Saving what is already saved changes nothing and starts no lock. Every change is recorded with who made it. `403` `withdrawals_disabled` when withdrawals are not enabled for your account. `422` `invalid_payout_method` when `method` is neither `bank` nor `cash`. `422` `bank_transfer_not_allowed` for a bank transfer where it is not offered, before the IBAN is checked. `422` `invalid_iban` says why in `error.details.reason` (`format`, `country_not_allowed`, `length`, `checksum`, `bban`) with `country` and `expected_length` where they apply; no error ever repeats what you sent. A paused account can save. When the ledger cannot be read the answer is `503` `ledger_unavailable`, and nothing is saved. Full behaviour: https://mart.ps/api/docs#money/payout-method-save.



## OpenAPI

````yaml /openapi.json put /api/v1/payout-method
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/payout-method:
    put:
      tags:
        - Money
      summary: Save your payout method
      description: >-
        Saves how your money is paid. For a bank transfer send `iban` and
        `account_holder_name`, and optionally `national_id`; `method` may be
        left out, as before cash existed. For cash at Mart's office send
        `"method": "cash"`, the collector's full name as `account_holder_name`
        and optionally their ID number as `national_id`; no IBAN. Cash is
        offered only where Mart allows it for your account (`403`
        `cash_not_allowed`): save it once before your first cash withdrawal,
        naming who collects (yourself, or someone with their ID number). A bank
        transfer is offered only where Mart allows it for your account:
        elsewhere an IBAN is refused with `422` `bank_transfer_not_allowed` and
        nothing is saved. Switching between bank and cash is refused while a
        withdrawal is open (`409` `payout_method_change_blocked`: cancel it
        first). A request without `method` on a cash account switches it back to
        bank, so it needs an IBAN. Leaving `national_id` out keeps the one
        already saved; sending `null` or an empty string clears it. **A switch
        between bank and cash never carries the ID number over:** leaving
        `national_id` out on a switch clears it, so send it whenever the
        collector (or, back to bank, the account holder) has one. The IBAN may
        be typed with spaces or in lower case: it is stored without them, in
        upper case. Its check digits, its length for the country and its country
        are checked: only the countries Mart has enabled for your account are
        accepted. **Saving or changing the IBAN locks withdrawals for a number
        of hours set for your account** (`withdrawals_locked_until`); a change
        never shortens a lock that is still running. A switch between bank and
        cash, and for cash a change of the collector's name or ID number, locks
        the same way. For a bank transfer, changing only the name or the
        national ID does not lock. Saving what is already saved changes nothing
        and starts no lock. Every change is recorded with who made it. `403`
        `withdrawals_disabled` when withdrawals are not enabled for your
        account. `422` `invalid_payout_method` when `method` is neither `bank`
        nor `cash`. `422` `bank_transfer_not_allowed` for a bank transfer where
        it is not offered, before the IBAN is checked. `422` `invalid_iban` says
        why in `error.details.reason` (`format`, `country_not_allowed`,
        `length`, `checksum`, `bban`) with `country` and `expected_length` where
        they apply; no error ever repeats what you sent. A paused account can
        save. When the ledger cannot be read the answer is `503`
        `ledger_unavailable`, and nothing is saved. Full behaviour:
        https://mart.ps/api/docs#money/payout-method-save.
      operationId: putPayoutMethod
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutMethodRequest'
            example:
              iban: PS92 PALS 0000 0000 0400 1234 5670 2
              account_holder_name: Al Noor Shop
              national_id: '123456789'
      responses:
        '200':
          description: >-
            Saved. The same object `GET` returns. Also `200` when nothing
            changed.
          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:
                          payout_method:
                            $ref: '#/components/schemas/PayoutMethod'
              example:
                status: success
                status_code: 200
                message: OK
                data:
                  payout_method:
                    status: locked
                    iban: PS92PALS000000000400123456702
                    iban_country: PS
                    account_holder_name: Al Noor Shop
                    national_id: null
                    updated_at: '2026-11-06T09:30:00+00:00'
                    withdrawals_locked_until: '2026-11-08T09:30:00+00:00'
                    method: bank
                    pickup_instructions: null
                meta: null
                error: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WithdrawalsDisabled'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          $ref: '#/components/responses/PayoutMethodChangeBlocked'
        '422':
          $ref: '#/components/responses/PayoutMethodInvalid'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/LedgerUnavailable'
components:
  schemas:
    PayoutMethodRequest:
      type: object
      required:
        - account_holder_name
      properties:
        method:
          type: string
          enum:
            - bank
            - cash
          description: >-
            Optional. `bank` (the default when left out) or `cash`. `cash` is
            accepted only when Mart offers it to your account (`403`
            `cash_not_allowed`), and `bank` only when Mart offers a bank
            transfer to your account (`422` `bank_transfer_not_allowed`). You
            cannot switch between the two while a withdrawal is open (`409`
            `payout_method_change_blocked`).
          example: bank
        iban:
          type: string
          description: >-
            Required for a bank transfer, ignored for cash. Spaces and case are
            ignored. Up to 34 characters once cleaned.
          example: PS92PALS000000000400123456702
        account_holder_name:
          type: string
          description: >-
            2 to 70 characters, letters first. Names in any script, including
            Arabic. For cash, the full name of the person who will collect the
            money, as on their ID card.
          example: Al Noor Shop
        national_id:
          type: string
          nullable: true
          description: >-
            Optional. 5 to 32 letters, digits or hyphens. Arabic digits are
            accepted and stored as 0 to 9. Omitted keeps the saved one, except
            on a switch between bank and cash, which clears it; `null` or an
            empty string clears it. For cash, the collector's ID number: send it
            on the switch.
          example: '123456789'
    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
    PayoutMethod:
      type: object
      required:
        - status
        - iban
        - iban_country
        - account_holder_name
        - national_id
        - updated_at
        - withdrawals_locked_until
        - method
        - pickup_instructions
      properties:
        status:
          type: string
          enum:
            - not_set
            - active
            - locked
          description: >-
            `not_set`: nothing saved yet. `active`: saved, withdrawals not
            locked by it. `locked`: withdrawals are locked until
            `withdrawals_locked_until`.
          example: locked
        iban:
          type: string
          nullable: true
          description: >-
            The whole IBAN, upper case, without spaces. `null` when not set, and
            when you are paid in cash. Kept, and shown, while a bank transfer is
            not offered to your account, but not paid to.
          example: PS92PALS000000000400123456702
        iban_country:
          type: string
          nullable: true
          description: The IBAN's two-letter country. `null` for cash.
          example: PS
        account_holder_name:
          type: string
          nullable: true
          example: Al Noor Shop
          description: >-
            The account holder. For cash, the full name of the person who
            collects the money at the office.
        national_id:
          type: string
          nullable: true
          description: >-
            The national ID you saved, or `null`. For cash, the collector's ID
            number, checked against their ID card at the office.
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: The last change to the payout method.
          example: '2026-11-06T09:30:00+00:00'
        withdrawals_locked_until:
          type: string
          format: date-time
          nullable: true
          description: Set only while `status` is `locked`.
          example: '2026-11-08T09:30:00+00:00'
        method:
          type: string
          nullable: true
          enum:
            - bank
            - cash
            - null
          description: >-
            How you are paid: `bank` (a transfer to `iban`) or `cash` (collected
            at Mart's office). `null` when not set.
          example: bank
        pickup_instructions:
          type: string
          nullable: true
          description: >-
            For cash: where and when to collect (Mart's office address and
            hours), as Mart wrote it. `null` for a bank transfer, and when Mart
            has none published right now.
          example: null
    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.
  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
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: >-
        The request body is missing, is not valid JSON, or is not a JSON object
        (`bad_request`).
    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'
    PayoutMethodChangeBlocked:
      description: >-
        The payout method cannot switch between bank and cash while a withdrawal
        is open (`payout_method_change_blocked`), so that every request is paid
        the way it was made. Cancel the open request, or wait until it is paid
        or rejected. Nothing was saved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    PayoutMethodInvalid:
      description: >-
        The method (`invalid_payout_method`: `bank` or `cash`), the IBAN
        (`invalid_iban`), the account holder name
        (`invalid_account_holder_name`) or the national ID
        (`invalid_national_id`) is not valid, or a bank transfer is not offered
        to your account (`bank_transfer_not_allowed`: nothing was saved).
        `error.details` says why and never repeats what you sent: for the IBAN
        `reason`, `country` and `expected_length` where they apply.
      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'
    LedgerUnavailable:
      description: >-
        The balance and ledger cannot be answered right now
        (`ledger_unavailable`). It is never answered with zeros or an empty
        list: retry later. There is no `Retry-After`.
      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.