> ## Documentation Index > Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt > Use this file to discover all available pages before exploring further. # List Trades > List Trades ## OpenAPI ````yaml openapi/v1-en.yaml GET /api/v1/trades openapi: 3.0.3 info: title: Subotiz API description: Subotiz OpenAPI version: 1.0.0 servers: - url: https://{api}.subotiz.com variables: api: default: api security: - sec0: [] tags: - name: Subscription description: Subscription - name: Price description: Price - name: Trade description: Trade - name: Payment description: Payment - name: Checkout Session description: Checkout Session - name: Customer description: Customer - name: Customer Portal description: Customer Portal paths: /api/v1/trades: get: tags: - Trade summary: List Trades description: List Trades operationId: v1-trade-list-trade parameters: - name: trade_ids in: query description: Trade ID array, filter trades whose IDs belong to this array schema: type: array items: type: string - name: status in: query description: |- Payment status: - requires_payment_method: Initial state - processing: Payment processing - succeeded: Payment successful schema: type: string - name: starting_after in: query description: >- Cursor for pagination. `starting_after` is the object ID that defines your position in the list. For example, if you want to get the next page, you can use the last object's ID as the parameter value after getting the object list for the first time. Cannot be used together with `ending_before` schema: type: string - name: ending_before in: query description: >- Cursor for pagination. `ending_before` is the object ID that defines your position in the list. For example, if you want to get the previous page, you can use the first object's ID as the parameter value after getting the object list for the first time. Cannot be used together with `starting_after` schema: type: string - name: limit in: query description: >- Pagination parameter, number of items per page, default: 10, interface defaults to sorting by creation time in descending order. Limit: [1, 100] schema: type: integer format: int32 - name: order_ids in: query description: Third-party order numbers schema: type: array items: type: string - name: created_at.gt in: query description: >- Minimum value to filter by (exclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z') schema: type: string - name: created_at.gte in: query description: >- Minimum value to filter by (inclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z') schema: type: string - name: created_at.lt in: query description: >- Maximum value to filter by (exclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z') schema: type: string - name: created_at.lte in: query description: >- Maximum value to filter by (inclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z') schema: type: string - name: customer_id in: query description: Only return Trade for the customer that this customer ID specifies. schema: type: string - $ref: '#/components/parameters/HeaderRequestID' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListTradesResponse' '400': description: ending_before and starting_after cannot be set at the same time content: application/json: schema: $ref: '#/components/schemas/BaseResponse' example: code: invalid_request_error message: >- ending_before and starting_after cannot be set at the same time. components: parameters: HeaderRequestID: name: Request-Id in: header description: The unique identifier of the request required: true schema: type: string default: 008e3967-a1b5-48bb-be14-d5bff5092e61 schemas: ListTradesResponse: type: object properties: code: type: string description: error code message: type: string description: error message data: $ref: '#/components/schemas/ListTradesResponse_Data' description: Query trade response by order_id BaseResponse: type: object properties: code: type: string description: error code message: type: string description: error message ListTradesResponse_Data: type: object properties: has_more: type: boolean description: Whether there is more data list: type: array items: $ref: '#/components/schemas/Trade' description: Trade list description: Query trade response by order_id Trade: type: object properties: trade_id: type: string description: Trade ID access_no: type: string description: Third-party access number merchant_id: type: string description: Merchant ID amount: type: string description: Payment amount, truncated to two decimal places currency: type: string description: Currency customer_id: type: string description: Platform customer ID callback_url: type: string description: Webhook notification callback URL metadata: type: object additionalProperties: type: string description: >- A set of key-value pairs that can be attached to an object, allowing you to store additional information in a structured format. last_payment_error: allOf: - $ref: '#/components/schemas/LastPaymentError' description: >- Last payment error information, if this field has a value, it indicates payment failure. next_action: allOf: - $ref: '#/components/schemas/NextAction' description: Next action order_id: type: string description: Third-party order number last_trans_id: type: string description: Order transaction ID paid_at: type: string description: Payment success time payment_mode: type: string description: >- Payment business mode: - subscription: Initial subscription payment, requires collecting customer payment information, pass `payment_method_data` field, returns `payment_token` for subsequent subscription renewals upon successful payment - recurring_payment: Subscription renewal payment, requires passing `payment_token` to complete payment, no need to collect user payment information payment_token: type: string description: >- Payment token returned for subscription payment, used for subsequent subscription renewals payment_method: type: string description: Payment method payment_channel: type: string description: Payment channel return_url: type: string description: >- Redirect page after payment channel accepts successfully in scenarios like 3DS redirect payment trade_status: type: string description: >- Payment status: - requires_payment_method: Initial order status. The customer has not completed payment (may not have initiated it or is still in process), or a subscription renewal charge has been initiated but the result is not yet available. - payment_failed: The provider declined the payment request due to reasons such as insufficient funds, failed card verification, or risk control restrictions. The customer can try again. - processing: The payment has been submitted by the customer and is being processed by the provider. The result is pending — possibly under risk review, bank processing, or delayed settlement. - succeeded: The payment has been confirmed successfully by the provider, and the funds have been credited. - closed: The trade order is closed when its status is no longer expected to change positively, such as after a subscription renewal fails (after multiple retries) or when no payment result is returned for over 7 days. txn_time: type: string description: Trade initiation time, time when client initiates the interface created_at: type: string description: Creation time refund_status: type: string description: >- Refund status: - no_refund: No refund - partially_refunded: A partial refund has been successfully issued, and the refunded amount is less than the total trade order value. - refunded: The full amount of the trade order has been successfully refunded. total_refunded_amount: type: string description: Refund amount, truncated to two decimal places session_id: type: string description: Session id session_url: type: string description: Session url refer_info: allOf: - $ref: '#/components/schemas/ReferInfo' description: Source information of the customer order_type: type: string description: >- Order types generated under different purchase or billing scenarios: - onetime_payment: The trade order is created for a one-time payment request. - subscription: The trade order is created for initiating a subscription payment request. - recurring_payment: The trade order is created by the Subotiz subscription renewal service. - token_payment: The trade order is created when the merchant charges a customer using an existing subscription contract token. line_items: type: array items: $ref: '#/components/schemas/LineItem' description: The line items purchased by the customer discounts: allOf: - $ref: '#/components/schemas/Discounts' description: >- Discounts applied to the trade, including all discount information for this trade closed_at: type: string description: Trade closed at closed_reason: type: string description: |- The reason for the order being closed - timeout: Payment timed out - renewal_failed: Subscription renewal failed (including retries) first_source_channel: type: string description: The source where this checkout session was initially created. last_source_channel: type: string description: The source where this checkout session was last accessed. billing_address: allOf: - $ref: '#/components/schemas/BillingAddress' description: The customer's billing address tax_amount: type: string description: Tax amount payment_info: allOf: - $ref: '#/components/schemas/PaymentInfo' description: Payment information description: Trade LastPaymentError: type: object properties: code: type: string description: System returned transaction return code message: type: string description: System returned transaction return description NextAction: type: object properties: type: type: string description: |- Type of next action required by client: - redirect: Redirect redirect: allOf: - $ref: '#/components/schemas/NextActionRedirect' description: Redirect information client: allOf: - $ref: '#/components/schemas/NextActionClient' description: Client operation information description: NextAction ReferInfo: type: object properties: country_code: type: string description: The country code of the client (ISO 2 format) ip: type: string description: The customer's IP address device: type: string description: |- The type of the customer's equipment - pc: Refers to the types of personal computer devices including desktops and laptops. - mobile: Refers to portable device types that have wireless connection capabilities and include smart phones and tablets. user_agent: type: string description: The customer's user agent description: ReferInfo LineItem: type: object properties: id: type: string title: type: string price: type: string price_id: type: string quantity: type: string sku: type: string vendor: type: string cycle_unit: type: string Discounts: type: object properties: current_period: type: array items: $ref: '#/components/schemas/CurrentPeriodDiscount' description: The current period's discount details description: Trade order discount information BillingAddress: type: object properties: first_name: type: string last_name: type: string email: type: string phone: type: string country_code: type: string country: type: string province_code: type: string province: type: string area: type: string city: type: string address: type: string address1: type: string zip: type: string company: type: string phone_area_code: type: string PaymentInfo: type: object properties: verification: allOf: - $ref: '#/components/schemas/Verification' description: >- Card payment security verification result (CVC / AVS / 3DS); null for non-card payments or on failure authcode: type: string description: >- Issuing bank authorization code; present for card payments, empty for non-card payments network_transaction_id: type: string description: >- Network transaction ID (card scheme side transaction identifier); present for card payments, empty for non-card payments description: >- PaymentInfo - Payment details, passed through to the merchant on the order side NextActionRedirect: type: object properties: url: type: string description: Redirect URL NextActionClient: type: object properties: confirm_url: type: string description: Confirm payment URL apple_pay_session: type: string description: ApplePay session data for creation CurrentPeriodDiscount: type: object properties: discount_id: type: string description: The unique identifier for the discount discount_amount: type: string description: The amount discounted discount_code: type: string description: The discount code used description: Details for a discount applied in the current period Verification: type: object properties: cvc_check: type: string description: 'CVC check result: pass / fail / unchecked / unavailable' avs: allOf: - $ref: '#/components/schemas/Avs' description: Address verification results; null when not triggered three_d_secure: allOf: - $ref: '#/components/schemas/ThreeDSecure' description: 3DS verification results; null when 3DS not performed description: Verification - Card payment verification results Avs: type: object properties: line1_check: type: string description: 'Address line check: pass / fail / unchecked / unavailable' postal_code_check: type: string description: 'Postal code check: pass / fail / unchecked / unavailable' description: Avs - Address verification results ThreeDSecure: type: object properties: authentication_flow: type: string description: 'Authentication flow: frictionless / challenge' result: type: string description: >- Result: authenticated / attempt_acknowledged / not_supported / failed / exempted / processing_error result_reason: type: string description: Failure or downgrade reason, empty when successful version: type: string description: 3DS protocol version, e.g. 2.2.0 eci: type: string description: ECI indicator; empty when not returned description: ThreeDSecure - 3DS verification details securitySchemes: sec0: type: http description: >- Bearer API Key authentication. Format: Authorization: Bearer {your_api_key} scheme: bearer ````