> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tabby.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get dispute by id
> Returns detailed information about dispute.
## OpenAPI
````yaml get /api/v1/disputes/{disputeId}
openapi: 3.1.0
info:
title: Tabby API Reference
version: 1.0.0
x-logo:
url: assets/tabby-new.png
altText: tabby Logo
description: |
Tabby Documentation: **[docs.tabby.ai](https://docs.tabby.ai/)**
servers:
- url: https://api.tabby.ai/
description: Production (UAE, Kuwait)
- url: https://api.tabby.sa/
description: Production (KSA)
security: []
tags:
- name: Checkout
description: >-
Checkout is a whole process of customer data collection and payment
authorization.
- name: Payments
description: >-
The core of tabby is a payments flow enabling you to handle payments at
your webstore.
- name: Webhooks
description: Manage webhook endpoints.
- name: Disputes
description: >-
The Disputes API is designed to simplify the process of handling disputes
and help merchants resolve issues with customer orders more efficiently.
Merchants can use this API to retrieve a list of disputes, view details
about a specific dispute, and approve or challenge a bunch of disputes. It
mirrors the functionality available in Tabby Merchant Dashboard and
operates exclusively with live payments using live credentials. A secret
key is required for using the Disputes API.
paths:
/api/v1/disputes/{disputeId}:
get:
tags:
- Disputes
summary: Get dispute by id
description: Returns detailed information about dispute.
operationId: getDispute
parameters:
- $ref: '#/components/parameters/disputeIdParam'
responses:
'200':
$ref: '#/components/responses/Dispute'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError_Disputes'
'500':
$ref: '#/components/responses/UnexpectedError'
security:
- bearerAuth:
- secret_key
components:
parameters:
disputeIdParam:
in: path
name: dispute_id
required: true
schema:
type: string
format: uuid
example: dispute id, uuid format
description: ID of the dispute.
responses:
Dispute:
description: Success. Returns dispute info.
content:
application/json:
schema:
type: object
properties:
dispute:
$ref: '#/components/schemas/Dispute'
required:
- dispute
BadRequestError_bad_request:
description: >-
One of the required fields is missing or request is not formatted
correctly.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_400_bad_request'
AuthenticationError_invalid_secret_key:
description: The request cannot be authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_401_invalid_secret_key'
NotFoundError_Disputes:
description: You are using an incorrect ID.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_404_dispute_not_found'
UnexpectedError:
description: Something bad happened. We're notified.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_500'
schemas:
Dispute:
type: object
properties:
id:
$ref: '#/components/schemas/DisputeID'
attachments:
$ref: '#/components/schemas/DisputeAttachments'
payment_id:
$ref: '#/components/schemas/PaymentID'
description: ID of the payment.
amount:
type: string
example: '100.00'
description: Total disputed amount.
currency:
$ref: '#/components/schemas/Currency'
description: >-
The currency of the dispute. It's always equal to the currency of
the payment.
created_at:
$ref: '#/components/schemas/DisputeCreatedAt'
expired_at:
$ref: '#/components/schemas/DisputeExpiredAt'
status:
$ref: '#/components/schemas/DisputeStatus'
reason:
$ref: '#/components/schemas/DisputeReason'
days_left:
$ref: '#/components/schemas/DisputeDaysLeft'
history:
type: array
items:
$ref: '#/components/schemas/DisputeHistoryItem'
items:
type: array
items:
$ref: '#/components/schemas/DisputeOrderItem'
order_number:
type: string
example: '#1234'
description: Merchant-assigned order number.
comment:
$ref: '#/components/schemas/DisputeComment'
required:
- id
- attachments
- payment_id
- amount
- currency
- created_at
- expired_at
- status
- reason
- days_left
- history
- items
- order_number
- comment
Error_400_bad_request:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: bad_data
error:
type: string
example: bad_request
Error_401_invalid_secret_key:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: not_authorized
error:
type: string
example: invalid secret key
Error_404_dispute_not_found:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: not_found
error:
type: string
example: dispute not found
Error_500:
type: string
example: Internal Server error
DisputeID:
type: string
format: uuid
example: dispute id, uuid format
readOnly: true
description: ID of the dispute.
DisputeAttachments:
type: array
nullable: true
items:
type: string
example: attachment_1
readOnly: true
description: Array of links to images which were uploaded by customer.
PaymentID:
type: string
format: uuid
example: payment id, uuid format
readOnly: true
description: >-
Unique identifier for the payment (UUID), assigned by Tabby. Save it on
your side!
Currency:
type: string
enum:
- AED
- SAR
- KWD
example: AED
description: >
ISO 4217 currency code for the payment amount. Currently there are 3
possible currency options - depending on the country where the store is
located:
- `AED` - United Arab Emirates Dirham
- `SAR` - Saudi Riyal
- `KWD` - Kuwaiti Dinar
DisputeCreatedAt:
type: string
readOnly: true
example: '2018-10-17T00:00:00.000Z'
description: >-
Date and time the Dispute was created, in UTC, and displayed in ISO 8601
datetime format.
DisputeExpiredAt:
type: string
readOnly: true
example: '2018-10-17T00:00:00.000Z'
description: >-
Date and time of the expiration of the Dispute, in UTC, and displayed in
ISO 8601 datetime format.
DisputeStatus:
type: string
readOnly: true
enum:
- new
- declined
- cancelled
- refunded
- in_progress
- evidence_merchant
- evidence_customer
example: new
description: |
The current status of the dispute:
- `new` - dispute pending merchant approval for refund or initiate a challenge
- `declined` - dispute was declined by Tabby support
- `cancelled` - dispute was canceled by customer
- `refunded` - dispute was approved or the order was refunded via Payments API
- `in_progress` - merchant challenged dispute and need a response from Tabby support
- `evidence_merchant` - waiting for evidence from the merchant
- `evidence_customer` - waiting for evidence from the customer
DisputeReason:
type: string
readOnly: true
enum:
- unreceived_refund
- identity_theft
- product_issue
- not_delivered
example: unreceived_refund
description: >
Cause of the dispute was created (selected by customer). There are only
four reasons:
- `unreceived_refund` - a refund not received
- `identity_theft` - I did not place this order (also known as identity theft)
- `product_issue` - there was a problem with the product
- `not_delivered` - the order was not delivered
DisputeDaysLeft:
type: integer
format: uint16
description: How many days left before dispute will be automatically approved.
DisputeHistoryItem:
type: object
properties:
attachments:
type: array
items:
type: string
example: attachment_1
description: >-
Array of links to images which were uploaded by customer or
merchant.
created_at:
type: string
example: '2018-10-17T00:00:00.000Z'
description: >-
Date and time of creation of dispute history items, in UTC, and
displayed in ISO 8601 datetime format.
created_by:
type: string
example: email address of the source
description: >
Indicates the entity responsible for the creation of the record. It
can take one of the following values:
- If `source` is set to `customer`, this field will contain the email address of the customer;
- If `source` is set to `merchant` and the action was performed through the merchant-dashboard, then field will contain the email address of the dashboard user;
- If `source` is set to `merchant` and the action was performed through the Disputes API, this field will contain the constant value 'Disputes API';
- If `source` is set to `tabby-support`, this field will be empty.
content:
type: string
example: customer comment
description: >
Contains additional information or comments related to the performed
action. It can take one of the following values:
- If `source` is set to `customer`, this field will contain the customer's comment.
- If `source` is set to `merchant`, this field will contain the reason for the challenge.
- If `source` is set to `tabby-support`, this field will be empty.
source:
type: string
enum:
- customer
- merchant
- tabby-support
example: merchant
description: >
This field specifies author that led to the creation of the record.
It can take one of the following values:
- `customer`: Indicates that the action was initiated by a customer;
- `merchant`: Indicates that the action was initiated by a merchant;
- `tabby-support`: Indicates that the action was initiated by Tabby support.
event_type:
type: string
enum:
- dispute_created
- dispute_approved
- dispute_declined
- dispute_canceled
- dispute_in_arbitration
- dispute_amount_changed
- dispute_comment_added
- evidence_merchant
- evidence_customer
- evidence_merchant_provided
- evidence_customer_provided
- merchant_14d_unresponsive
- customer_14d_unresponsive
example: dispute_created
description: |
The event type of the dispute history item:
- `dispute_created` - the customer raised a dispute;
- `dispute_approved` - disputed was approved and amount was refunded to customer;
- `dispute_declined` - dispute was declined by Tabby support;
- `dispute_canceled` - dispute was canceled by customer;
- `dispute_in_arbitration` - merchant challenged dispute (e.g incorrect amount);
- `dispute_amount_changed` - disputed amount was changed;
- `dispute_comment_added` - merchant added comment to the dispute;
- `evidence_merchant` - agent requested evidence from the merchant;
- `evidence_customer` - agent requested evidence from the customer;
- `evidence_merchant_provided` - merchant provided evidence;
- `evidence_customer_provided` - customer provided evidence;
- `merchant_14d_unresponsive` - merchant did not respond within 14 days;
- `customer_14d_unresponsive` - customer did not respond within 14 days.
note:
type: string
example: additional comments
description: >-
Contains additional message provided by merchant while perform
action.
required:
- attachments
- created_at
- created_by
- content
- source
- event_type
DisputeOrderItem:
type: object
properties:
reference_id:
type: string
example: payment id
description: Reference id from payment.
title:
type: string
example: Order item title
description: Order item title.
unit_price:
type: string
example: '100.00'
description: Order item unit price.
required:
- reference_id
- title
- unit_price
DisputeComment:
type: string
example: additional comments
description: The customer additional comments on the causes of the dispute.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
Bearer authentication header of the form `Bearer `, where
`` is your `secret_key`.
````