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

# Get order by partner reference

> Returns YOUR order, addressed by the reference you submitted at creation. Key-scoped: an unknown or foreign reference answers the identical 404 `order_not_found`. Live view with frozen prices: `status`, quantities and `cod_total` are current; each item's `price` and the `shipping_fee` stay the creation-time figures. Details: https://mart.ps/api/docs#orders.



## OpenAPI

````yaml /openapi.json get /api/v1/orders/{partner_reference}
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/orders/{partner_reference}:
    get:
      tags:
        - Orders
      summary: Get order by partner reference
      description: >-
        Returns YOUR order, addressed by the reference you submitted at
        creation. Key-scoped: an unknown or foreign reference answers the
        identical 404 `order_not_found`. Live view with frozen prices: `status`,
        quantities and `cod_total` are current; each item's `price` and the
        `shipping_fee` stay the creation-time figures. Details:
        https://mart.ps/api/docs#orders.
      operationId: getOrderByPartnerReference
      parameters:
        - name: partner_reference
          in: path
          required: true
          description: >-
            The reference you submitted to POST /api/v1/orders, exactly as you
            sent it (references are stored byte-for-byte). Letters, digits, dot,
            underscore, hyphen; max 64 characters.
          schema:
            type: string
            pattern: ^[A-Za-z0-9._-]{1,64}$
            maxLength: 64
            example: '100245'
      responses:
        '200':
          description: 'The partner''s order: live status and quantities, frozen prices.'
          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:
                          order:
                            $ref: '#/components/schemas/PartnerOrder'
              example:
                status: success
                status_code: 200
                message: OK
                data:
                  order:
                    partner_reference: '100245'
                    status:
                      id: 5
                      name: تم التوصيل
                    payment_type: cod
                    created_at: '2026-08-01T10:15:00+00:00'
                    updated_at: '2026-08-03T09:40:12+03:00'
                    cod_total: 240
                    shipping_fee: 35
                    free_shipping: true
                    products:
                      - product_id: 9597
                        combination_id: 41206
                        quantity: 2
                        price: 120
                        line_total: 240
                    shipping_address:
                      customer_name: محمد علي
                      phone: '0599123456'
                      extra_phone: null
                      state_id: 386
                      state_name: الخليل
                      address: شارع الإرسال، عمارة 12
                      notes: null
                    cancellation: null
                meta: null
                error: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/OrderNotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
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
    PartnerOrder:
      type: object
      description: >-
        The order-read shape: live status/quantities/totals with creation-frozen
        prices, fee and delivery address. Every key is always present
        (structural stability). Mart's internal order id and the settlement
        reward block are deliberately absent — the creation response remains the
        settlement record. The `money` block is the live view of what the order
        earns.
      required:
        - partner_reference
        - status
        - payment_type
        - created_at
        - updated_at
        - order_total
        - cod_total
        - shipping_fee
        - free_shipping
        - payment_reference
        - products
        - shipping_address
        - cancellation
        - money
      properties:
        partner_reference:
          type: string
          example: '100245'
        status:
          type: object
          description: >-
            The latest customer-visible order state — the same status the
            customer sees on the storefront, in the order's language. `id` is an
            opaque status identifier (NOT Mart's order id); `name` is display
            text.
          required:
            - id
            - name
          properties:
            id:
              type: integer
              example: 5
            name:
              type: string
              example: تم التوصيل
        payment_type:
          type: string
          enum:
            - cod
            - card
          description: >-
            Frozen at creation. Present on EVERY read — orders created before
            the field existed read back as `cod` (which is what they were).
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          description: Last modification of the order (status changes, BO edits).
        order_total:
          type: number
          format: double
          description: >-
            The live order total (products plus any delivery fee the customer
            carries) — the payment-neutral figure; for card orders, the amount
            that was charged.
        cod_total:
          type: number
          format: double
          description: >-
            What the courier collects: the live order total for cod, 0.00 for
            card.
        shipping_fee:
          type: number
          format: double
          description: The delivery fee frozen at creation.
        free_shipping:
          type: boolean
          description: Current value — BO edits can change it.
        payment_reference:
          type: string
          nullable: true
          description: >-
            The gateway (Lahza) transaction reference charged for a card order;
            null for cod.
        products:
          type: array
          items:
            type: object
            required:
              - product_id
              - combination_id
              - quantity
              - price
              - line_total
            properties:
              product_id:
                type: integer
                description: >-
                  Stable product identifier used in catalog synchronization and
                  order creation.
              combination_id:
                type: integer
                nullable: true
                description: Null for simple products.
              quantity:
                type: integer
                description: >-
                  Current effective quantity: ordered minus refunded/returned,
                  floored at 0.
              price:
                type: number
                format: double
                description: >-
                  Your selling price per unit, frozen at creation — never the
                  current catalog price.
              line_total:
                type: number
                format: double
                description: price × quantity.
        shipping_address:
          type: object
          description: >-
            The delivery snapshot stored at creation — not the customer's
            current profile address. `state_name` is resolved from `state_id`
            for display.
          required:
            - customer_name
            - phone
            - extra_phone
            - state_id
            - state_name
            - address
            - notes
          properties:
            customer_name:
              type: string
            phone:
              type: string
            extra_phone:
              type: string
              nullable: true
            state_id:
              type: integer
            state_name:
              type: string
            address:
              type: string
            notes:
              type: string
              nullable: true
        cancellation:
          $ref: '#/components/schemas/OrderCancellation'
        money:
          type: object
          required:
            - gross
            - shipping_deduction
            - net
            - earning_state
            - available_at
          description: >-
            What this order earns your account and when it can be counted.
            `gross`, `shipping_deduction` and `net` are the order's current
            settlement figures (`net` = `gross` - `shipping_deduction`), kept in
            step with Mart's staff edits. `available` means this order's money
            has matured, not that it can be withdrawn: a debt on the account can
            offset it. When `earning_state` is `reversed` every figure is
            `0.00`. In the creation response (201 and every replay) this block
            is a record of what was created, so it is always `pending` with a
            null `available_at`; read the order for the live state.
          properties:
            gross:
              type: number
              format: double
              description: The order's gross product reward.
            shipping_deduction:
              type: number
              format: double
              description: >-
                The delivery fee taken out of it; 0.00 unless free_shipping is
                true.
            net:
              type: number
              format: double
              description: gross - shipping_deduction. What this order earns your account.
            earning_state:
              type: string
              enum:
                - pending
                - held
                - available
                - reversed
              description: >-
                `pending`: not earned yet, or not known. `held`: earned, inside
                its hold. `available`: this order's money matured. `reversed`:
                the order was cancelled or returned and earns nothing.
            available_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                When the held money matures; null unless the order is `held` or
                `available` and has a maturity date.
    OrderCancellation:
      type: object
      nullable: true
      description: >-
        Present on every order read, `null` unless the order was cancelled
        **through this API**. A back-office cancellation leaves it null: the
        order's `status` still shows it cancelled, but this block records only
        what you did.
      required:
        - requested_via_api
        - reason
        - cancelled_at
      properties:
        requested_via_api:
          type: boolean
          description: Always `true` when this block is present.
          example: true
        reason:
          type: string
          nullable: true
          description: The reason you supplied, or null if you sent none.
          example: Customer requested cancellation
        cancelled_at:
          type: string
          format: date-time
          description: When the order reached the cancelled state, ISO 8601 with offset.
          example: '2026-08-04T08:15:00+00:00'
    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'
    Forbidden:
      description: >-
        The key does not have the scope this endpoint needs
        (`insufficient_scope`, `details.required_scope` names it; checked before
        the group and the rate limit, so it uses no quota), or the key customer
        is missing/inactive (`api_customer_not_configured`) or outside the
        allowed groups (`customer_group_not_allowed`). Group membership is
        re-checked on every request; access resumes when the customer rejoins an
        allowed group.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    OrderNotFound:
      description: >-
        No order with that `partner_reference` on YOUR account
        (`order_not_found`). Deliberately identical whether the reference never
        existed or belongs to another partner — the response never reveals other
        accounts' references.
      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'
    UnprocessableEntity:
      description: >-
        Invalid parameter value (`invalid_parameter`); `error.details` names the
        parameter.
      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'
  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.