Thanks for being patient while we implement your feedback to improve the developer experience.

Capture order payment

POST /orders/{order_id}/payment_actions/capture

Request

Capture the payment for an order. When there are no payment method validation issues, the capture process is successful, the payment_status updates to capture pending, and the payment request is scheduled. The payment request itself occurs asynchronously. Requires at least one of the following scopes:

  • store_v2_orders
  • store_v2_transactions

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Response

Resource Created.

Body

object | application/json

    example

    {}

    Void

    POST /orders/{order_id}/payment_actions/void

    Request

    Void the payment for an order. When there are no payment method validation issues, the void process is successful, the payment_status updates to void pending, and the void payment request is scheduled. The payment request itself occurs asynchronously.

    Requires at least one of the following scopes:

    • store_v2_orders
    • store_v2_transactions

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Content-Type in header with default of application/json - string - required

      The MIME type of the request body.

    Response

    Resource Created.

    Body

    object | application/json

      example

      {}

      Create a Refund Quote

      POST /orders/{order_id}/payment_actions/refund_quotes

      Request

      Calculate the tax amount, total refund amount and get available payment options for an order refund by providing items and costs or quantities to refund.

      Requires at least one of the following scopes:

      • store_v2_orders
      • store_v2_transactions

      Note: Order refunds are processed consecutively. Processing synchronous refunds on an order are not yet supported.

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Content-Type in header with default of application/json - string - required

        The MIME type of the request body.

      Body

      object | application/json

      Request body for refund quotes.

      • items        array[]
        required

      example

      {
  "items": [
    {
      "item_type": "SHIPPING",
      "item_id": 1,
      "amount": 1.99,
      "quantity": 3,
      "reason": "Customer requested refund"
    }
  ]
}

      Response

      Body

      object | application/json

      • data        object

      • meta        object

        Response metadata.

      example

      {
  "data": {
    "order_id": 0,
    "total_refund_amount": 1.99,
    "total_refund_tax_amount": 1.95,
    "rounding": 0,
    "adjustment": -10.2,
    "tax_inclusive": true,
    "refund_methods": [
      [
        {
          "provider_id": "checkout_paypalexpress",
          "provider_description": "Paypal Express",
          "amount": 9.99,
          "offline": true,
          "offline_provider": true,
          "offline_reason": "Multiple online refunds are not available."
        }
      ]
    ]
  },
  "meta": {}
}

      Create a Refund

      POST /orders/{order_id}/payment_actions/refunds

      Request

      Creates a refund. When there are no payment method validation issues, the refund process is successful and the refund payment request is scheduled. The payment request itself occurs asynchronously.

      Requires at least one of the following scopes:

      • store_v2_orders
      • store_v2_transactions

      Note: Order refunds are processed consecutively. Processing synchronous refunds on an order are not yet supported.

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Content-Type in header with default of application/json - string - required

        The MIME type of the request body.

      Body

      object | application/json

      Request body for refund requests.

      • items        array[]
        required

      • payments        array[object]
        required

      • merchant_calculated_override        object

        Merchant explicitly provided override based on their own calculation.

        This override gives merchants the flexibility to

        • bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund
        • use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System)

        Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated.

      example

      {
  "items": [
    {
      "item_type": "SHIPPING",
      "item_id": 1,
      "amount": 1.99,
      "quantity": 3,
      "reason": "Customer requested refund"
    }
  ],
  "payments": [
    {
      "provider_id": "checkout_paypalexpress",
      "amount": 9.99,
      "offline": true
    }
  ],
  "merchant_calculated_override": {
    "total_amount": 1.99,
    "total_tax": 0
  }
}

      Response

      Body

      object | application/json

      • data        object

      • meta        object

        Response metadata.

      example

      {
  "data": {
    "order_id": 0,
    "reason": "string",
    "total_amount": 1.99,
    "total_tax": 0,
    "uses_merchant_override_values": true,
    "items": [
      {
        "item_type": "PRODUCT",
        "item_id": 0,
        "reason": "string",
        "quantity": 0,
        "requested_amount": 1.99
      }
    ],
    "payments": [
      {
        "provider_id": "storecredit",
        "amount": 1.99,
        "offline": true,
        "is_declined": true,
        "declined_message": "string"
      }
    ]
  },
  "meta": {}
}

      Get Refunds for Order

      GET /orders/{order_id}/payment_actions/refunds

      Request

      Returns a list of refunds ordered by refund ID in ascending order for the given order.

      Requires at least one of the following scopes:

      • store_v2_transactions_read_only
      • store_v2_transactions
      • store_v2_orders_read_only
      • store_v2_orders

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Accept in header with default of application/json - string - required

        The MIME type of the response body.

      • order_id in path - integer - required

        The ID of the Order to which the transactions belong.

      example

      curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/[order_id]/payment_actions/refunds' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

      Response

      Body

      object | application/json

      Response payload for Refund resource.

      • data        array[object]

        Collection of Refunds

      • meta        object

        Response metadata.

      example

      {
  "data": [
    {
      "order_id": 0,
      "reason": "string",
      "total_amount": 1.99,
      "total_tax": 0,
      "uses_merchant_override_values": true,
      "items": [
        {
          "item_type": "PRODUCT",
          "item_id": 0,
          "reason": "string",
          "quantity": 0,
          "requested_amount": 1.99
        }
      ],
      "payments": [
        {
          "provider_id": "storecredit",
          "amount": 1.99,
          "offline": true,
          "is_declined": true,
          "declined_message": "string"
        }
      ]
    }
  ],
  "meta": {}
}

      Get a Refund

      GET /orders/payment_actions/refunds/{refund_id}

      Request

      Returns a refund by refund ID.

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Accept in header with default of application/json - string - required

        The MIME type of the response body.

      • refund_id in path - integer - required

        Refund ID.

      example

      curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/orders/payment_actions/refunds/[refund_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

      Response

      Body

      object | application/json

      • data        object

      • meta        object

        Response metadata.

      Example

      {
  "data": {
    "id": 12,
    "order_id": 180,
    "user_id": 0,
    "created": "2022-06-16T16:44:15+00:00",
    "reason": "",
    "total_amount": 50,
    "total_tax": 5,
    "uses_merchant_override_values": false,
    "payments": [
      {
        "id": 13,
        "provider_id": "storecredit",
        "amount": 50,
        "offline": true,
        "is_declined": false,
        "declined_message": ""
      }
    ],
    "items": [
      {
        "item_type": "PRODUCT",
        "item_id": 87,
        "quantity": 1,
        "requested_amount": null,
        "reason": "Wrong item sent."
      }
    ]
  },
  "meta": {}
}

      Create Refund Quotes - BATCH

      POST /stores/{store_hash}/v3/orders/payment_actions/refund_quotes

      Request

      Calculate the tax amount, total refund amount and get available payment options for an order refund by providing items and costs or quantities to refund.

      This endpoint will accept a batch of one or more.

      Requires at least one of the following scopes:

      • store_v2_orders
      • store_v2_transactions

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • store_hash in path - string - required
      • Accept in header with default of application/json - string - required

        The MIME type of the response body.

      Body

      array | application/json

      Request body for batch refund quotes.

      • items        array[]

      example

      {
  "items": [
    {
      "item_type": "SHIPPING",
      "item_id": 1,
      "amount": 1.99,
      "quantity": 3,
      "reason": "Customer requested refund"
    }
  ]
}

      Response

      Body

      object | application/json

      • data        array[object]

      • errors        array[object]

      • meta        object

      example

      {
  "data": [
    {
      "order_id": 0,
      "total_refund_amount": 1.99,
      "total_refund_tax_amount": 1.95,
      "rounding": 0,
      "adjustment": -10.2,
      "tax_inclusive": true,
      "refund_methods": [
        [
          {
            "provider_id": "checkout_paypalexpress",
            "provider_description": "Paypal Express",
            "amount": 9.99,
            "offline": true,
            "offline_provider": true,
            "offline_reason": "Multiple online refunds are not available."
          }
        ]
      ]
    }
  ],
  "errors": [
    {
      "order_id": 0,
      "status": 422,
      "error": "string"
    }
  ],
  "meta": {
    "meta": {
      "total": 36,
      "count": 36,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "previous": "string",
        "current": "?page=1&limit=50",
        "next": "string"
      }
    }
  }
}

      Get All Refunds

      GET /stores/{store_hash}/v3/orders/payment_actions/refunds

      Request

      Returns a list of refunds ordered by refund ID in ascending order.

      Requires at least one of the following scopes:

      • store_v2_transactions_read_only
      • store_v2_transactions
      • store_v2_orders_read_only
      • store_v2_orders

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string - required
      • order_id:in in query - array

        Filter by order_id. Accepts multiple as comma-separated values.

      • id:in in query - array

        Filter by refund id. Accepts multiple as comma-separated values.

      • created:min in query - string

        Filter results so they are later than or equal to provided date.

        Must be in url-encoded RFC 3339 format. e.g. 2020-01-15T01:02:34-01:00 is RFC 3339 format. Url-encoded this will be 2020-01-15T01%3A02%3A34%2B01%3A00

      • created:max in query - string

        Filter results so they are earlier than or equal to provided date.

        Must be in url-encoded RFC 3339 format. e.g. 2020-01-15T01:02:34-01:00 is RFC 3339 format. Url-encoded this will be 2020-01-15T01%3A02%3A34%2B01%3A00

      • page in query - integer

        Specifies the page number in a limited (paginated) list of items.

      • limit in query - integer

        Controls the number of items per page in a limited (paginated) list of items.

      example

      curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/stores/[store_hash]/v3/orders/payment_actions/refunds' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

      Response

      Body

      object | application/json

      Response payload for Refund resource.

      • data        array[object]

        Collection of Refunds

      • meta        object

        Response metadata.

      example

      {
  "data": [
    {
      "order_id": 0,
      "reason": "string",
      "total_amount": 1.99,
      "total_tax": 0,
      "uses_merchant_override_values": true,
      "items": [
        {
          "item_type": "PRODUCT",
          "item_id": 0,
          "reason": "string",
          "quantity": 0,
          "requested_amount": 1.99
        }
      ],
      "payments": [
        {
          "provider_id": "storecredit",
          "amount": 1.99,
          "offline": true,
          "is_declined": true,
          "declined_message": "string"
        }
      ]
    }
  ],
  "meta": {}
}