Skip to content

SellerPayoutBatch ​

Type: schema

Description ​

A settlement batch that groups a seller's payout-eligible invoices into a single transfer.

TypeScript Definition ​

typescript
SellerPayoutBatch: {{
            /** @description Human-readable batch reference, e.g. `PB-TNSFR9Q0HA7J`. */
            batch_number?: string;
            /** @description Total credits applied to the batch from its `adjustments`, as a decimal string. */
            credit_adjustments?: string;
            /** @description Total debits applied to the batch from its `adjustments`, as a decimal string. */
            debit_adjustments?: string;
            /** @description Payout batch ULID. */
            id?: string;
            /** @description Snapshot of the seller's payout config at batch creation. When `true`, shipping charges are part of the payable amount. */
            include_shipping_in_payout?: boolean;
            /** @description Snapshot of the seller's payout config at batch creation. When `true`, tax collected on the invoices is part of the payable amount. */
            include_tax_in_payout?: boolean;
            /**
             * @description `system` for scheduled batch runs, `admin` for manually created batches.
             * @enum {string}
             */
            initiated_by?: "system" | "admin";
            /** @description The admin user who created the batch. `null` when `initiated_by` is `system`. */
            initiated_by_user_id?: string | null;
            /** @description Number of payout invoices settled by this batch. */
            invoice_count?: number;
            /** @description Marketplace context for this payout batch. Returned as `null` when not applicable. */
            marketplace_detail?: {
                /**
                 * @description Marketplace ULID.
                 * @example 01KVZ1TK3V1ZB8TK2V3E3G64FS
                 */
                id?: string;
                /** @example internal */
                marketplace_type?: components["schemas"]["MarketplaceType"];
                /** @example Davai Marketplace */
                name?: string;
                /** @example davai-marketplace */
                slug?: string;
                /** @example f7ul64jr3n */
                store_id?: string;
            } | null;
            /** @description Slug of the payment provider that transferred the batch, for example `juspay` or `icici-cib`. `null` until the batch is transferred, and for batches settled manually. */
            payment_gateway?: string | null;
            /** @description Reference number issued by the bank or gateway for the transfer, such as the NEFT UTR. `null` until the batch is transferred. */
            payment_gateway_reference_no?: string | null;
            /** @description Instrument used for the transfer, one of `CC`, `DC`, `NEFT`, `RTGS`, `IMPS`, `UPI`, or `WALLET`. `null` until the batch is transferred. */
            payment_method?: string | null;
            /** @description How the batch was paid to the seller, either `bank-transfer` or `payment-gateway`. `null` until the batch is transferred. */
            payment_mode?: string | null;
            /**
             * @description Snapshot of the store `payout` configuration at batch creation. `auto` batches are settled through a connected provider; `manual` batches are paid outside the platform and recorded with the manual-payment endpoint.
             * @enum {string}
             */
            payment_option?: "auto" | "manual";
            /** @description Transfers made to the seller against this batch, as `SellerPayoutBatchPayment` objects. Covers both provider transfers and payments recorded through the manual-payment endpoint. Empty until a transfer is attempted; each entry carries its own `payment_status`, so a retried batch lists one entry per attempt. */
            payments?: components["schemas"]["SellerPayoutBatchPayment"][];
            /**
             * Format: date-time
             * @description End of the invoice eligibility window covered by this batch.
             */
            period_end?: string;
            /**
             * Format: date-time
             * @description Start of the invoice eligibility window covered by this batch.
             */
            period_start?: string;
            remarks?: string | null;
            /**
             * Format: date-time
             * @description When the batch is scheduled to be transferred to the seller.
             */
            scheduled_at?: string;
            seller_id?: string;
            seller_name?: $Read<string>;
            /**
             * @description Batch lifecycle state. A batch is `scheduled` (`created` when an admin created it), `processing` while its transfer is under way, and `completed` once the seller is paid; `payment_failed` when its transfer still fails after its retries, `on_hold` while it is held, and `cancelled` when it is cancelled or broken up.
             * @enum {string}
             */
            status?: "created" | "scheduled" | "processing" | "completed" | "cancelled" | "on_hold" | "payment_failed";
            /** @description Net amount payable to the seller: `total_invoice_amount` - `total_charges` + `credit_adjustments` - `debit_adjustments`. Decimal string. */
            to_be_paid?: string;
            /** @description Sum of marketplace charges deducted across all invoices in the batch, as a decimal string. */
            total_charges?: string;
            /** @description Sum of the batched invoice amounts, before charges and adjustments, as a decimal string. */
            total_invoice_amount?: string;
            /** @description Sum of `loyalty_point_redeemed` across invoices in the batch, as a decimal string. */
            total_loyalty_point_redeemed?: string;
        };
        /**
         * SellerPayoutBatchPayment
         * @description Transfer recorded on a `SellerPayoutBatch`. Mirrors `OrderPayment`, with payout settlement field types.
         */
}

Component References ​

ReferenceResolves To
components["schemas"]["MarketplaceType"]MarketplaceType
components["schemas"]["SellerPayoutBatchPayment"]SellerPayoutBatchPayment

OpenAPI Schema ​

json
{
  "title": "SellerPayoutBatch",
  "description": "A settlement batch that groups a seller's payout-eligible invoices into a single transfer.",
  "type": "object",
  "properties": {
    "batch_number": {
      "description": "Human-readable batch reference, e.g. `PB-TNSFR9Q0HA7J`.",
      "type": "string"
    },
    "credit_adjustments": {
      "description": "Total credits applied to the batch from its `adjustments`, as a decimal string.",
      "type": "string"
    },
    "debit_adjustments": {
      "description": "Total debits applied to the batch from its `adjustments`, as a decimal string.",
      "type": "string"
    },
    "id": {
      "description": "Payout batch ULID.",
      "type": "string"
    },
    "include_shipping_in_payout": {
      "description": "Snapshot of the seller's payout config at batch creation. When `true`, shipping charges are part of the payable amount.",
      "type": "boolean"
    },
    "include_tax_in_payout": {
      "description": "Snapshot of the seller's payout config at batch creation. When `true`, tax collected on the invoices is part of the payable amount.",
      "type": "boolean"
    },
    "initiated_by": {
      "description": "`system` for scheduled batch runs, `admin` for manually created batches.",
      "type": "string",
      "enum": [
        "system",
        "admin"
      ]
    },
    "initiated_by_user_id": {
      "description": "The admin user who created the batch. `null` when `initiated_by` is `system`.",
      "type": [
        "string",
        "null"
      ]
    },
    "invoice_count": {
      "description": "Number of payout invoices settled by this batch.",
      "type": "integer"
    },
    "marketplace_detail": {
      "description": "Marketplace context for this payout batch. Returned as `null` when not applicable.",
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "id": {
          "description": "Marketplace ULID.",
          "type": "string",
          "example": "01KVZ1TK3V1ZB8TK2V3E3G64FS"
        },
        "marketplace_type": {
          "example": "internal",
          "$ref": "#/components/schemas/MarketplaceType"
        },
        "name": {
          "type": "string",
          "example": "Davai Marketplace"
        },
        "slug": {
          "type": "string",
          "example": "davai-marketplace"
        },
        "store_id": {
          "type": "string",
          "example": "f7ul64jr3n"
        }
      }
    },
    "payment_gateway": {
      "description": "Slug of the payment provider that transferred the batch, for example `juspay` or `icici-cib`. `null` until the batch is transferred, and for batches settled manually.",
      "type": [
        "string",
        "null"
      ]
    },
    "payment_gateway_reference_no": {
      "description": "Reference number issued by the bank or gateway for the transfer, such as the NEFT UTR. `null` until the batch is transferred.",
      "type": [
        "string",
        "null"
      ]
    },
    "payment_method": {
      "description": "Instrument used for the transfer, one of `CC`, `DC`, `NEFT`, `RTGS`, `IMPS`, `UPI`, or `WALLET`. `null` until the batch is transferred.",
      "type": [
        "string",
        "null"
      ]
    },
    "payment_mode": {
      "description": "How the batch was paid to the seller, either `bank-transfer` or `payment-gateway`. `null` until the batch is transferred.",
      "type": [
        "string",
        "null"
      ]
    },
    "payment_option": {
      "description": "Snapshot of the store `payout` configuration at batch creation. `auto` batches are settled through a connected provider; `manual` batches are paid outside the platform and recorded with the manual-payment endpoint.",
      "type": "string",
      "enum": [
        "auto",
        "manual"
      ]
    },
    "payments": {
      "description": "Transfers made to the seller against this batch, as `SellerPayoutBatchPayment` objects. Covers both provider transfers and payments recorded through the manual-payment endpoint. Empty until a transfer is attempted; each entry carries its own `payment_status`, so a retried batch lists one entry per attempt.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SellerPayoutBatchPayment"
      }
    },
    "period_end": {
      "description": "End of the invoice eligibility window covered by this batch.",
      "type": "string",
      "format": "date-time"
    },
    "period_start": {
      "description": "Start of the invoice eligibility window covered by this batch.",
      "type": "string",
      "format": "date-time"
    },
    "remarks": {
      "type": [
        "string",
        "null"
      ]
    },
    "scheduled_at": {
      "description": "When the batch is scheduled to be transferred to the seller.",
      "type": "string",
      "format": "date-time"
    },
    "seller_id": {
      "type": "string"
    },
    "seller_name": {
      "type": "string",
      "readOnly": true
    },
    "status": {
      "description": "Batch lifecycle state. A batch is `scheduled` (`created` when an admin created it), `processing` while its transfer is under way, and `completed` once the seller is paid; `payment_failed` when its transfer still fails after its retries, `on_hold` while it is held, and `cancelled` when it is cancelled or broken up.",
      "type": "string",
      "enum": [
        "created",
        "scheduled",
        "processing",
        "completed",
        "cancelled",
        "on_hold",
        "payment_failed"
      ]
    },
    "to_be_paid": {
      "description": "Net amount payable to the seller: `total_invoice_amount` - `total_charges` + `credit_adjustments` - `debit_adjustments`. Decimal string.",
      "type": "string"
    },
    "total_charges": {
      "description": "Sum of marketplace charges deducted across all invoices in the batch, as a decimal string.",
      "type": "string"
    },
    "total_invoice_amount": {
      "description": "Sum of the batched invoice amounts, before charges and adjustments, as a decimal string.",
      "type": "string"
    },
    "total_loyalty_point_redeemed": {
      "description": "Sum of `loyalty_point_redeemed` across invoices in the batch, as a decimal string.",
      "type": "string"
    }
  },
  "x-tags": [
    "Payouts"
  ]
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: