Issue a Refund

You can refund full paid orders back to the buyer's payment method. Creating a refund starts with a refund request. Once the refund is requested, you can add refundLines for the actual amounts to refund.

Refunds must go back onto the original method of payment and currency used by the buyer. When you're ready to issue the refund, you can approve it and start the refund payment process.

When refunding specific order lines or seller orders, you can choose to charge the refund to the seller or the marketplace operator. The chargedTo field determines who is responsible for covering the refund cost. If set to chargedTo: SELLER, the refund will be deducted from the seller's next payout. This option is not available for refunds scoped to the entire marketplace order.

Permission Requirements

You must be a marketplace operator with the MANAGE_REFUNDS permission to create and process refunds.

Refund lifecycle

Refunds go through a state-driven lifecycle comprised of the following states:

Status	Description
REQUESTED	Initial state where the refund process starts.
CANCELED	The refund is cancelled and no more actions will be taken.
DECLINED	The refund request is declined. No further actions will be taken.
APPROVED	The refund is approved and prepared for the payment stage.
PROCESSING	The payment process starts. For native gateways like Stripe, this status is automatic after approval.
FAILED	The payment failed. With native gateways, this status is automatic if a payment error occurs.
PAID	The refund is successful. With native gateways, this status is automatic upon successful payment.
LOCKED	For refunds with chargedTo: SELLER, the refund reaches this state when the associated seller payout is locked.
SETTLED	Final state of a successful refund. Refunds with chargedTo: MARKETPLACE reach this state once the refund is successfully paid. Refunds with chargedTo: SELLER reach this state once the payout with the refund charge has been successfully processed.

---

Step 1: Initiate the refund

Use the refundCreate mutation to start the refund process. The refund will be created in the REQUESTED state.

1

Create the refund

The refundCreate mutation accepts the following input:

Field	Description
order	The id of the marketplace order (nauticalOrder) you wish to refund.
name	Name for the refund.
descriptionHtml	(Optional) Use to capture a reason for the refund or a general description.

For additional input fields, see the RefundCreateInput API reference.

Request

mutation {
  refundCreate(
    input: { 
      order: "TmF1dGljYWxPcmRlcjo0OTA=", 
      name: "RefundOrder#490", 
      description: "Wrong size purchased" 
    }
  ) {
    refund {
      id
      name
      status
    }
    refundErrors {
      message
      field
      code
    }
  }
}

Show more ↓

After adding a refund, you can update or delete it using refundUpdate and refundsDelete mutations.

---

Step 2: Add refund lines

After creating the refund, you can add refundLines. A refund line is a segment of the total refund. There are three types of refund lines you can use:

• Order line refund lines
• Seller order refund lines
• Marketplace order refund lines

You can add multiple refund lines. However, mixing different refund methods is not allowed. For example, you cannot refund a percentage of the order and later refund a specific order line.

After adding refundLines, you can update or delete them if needed using the refundLinesUpdate and refundLinesDelete mutations.

Order line refunds

Order line refunds can be used to refund specific items within the order or to refund shipping fees.

1

(Optional)Query seller order lines

2

Add order line refund line

To add an order line refund line, use the refundLinesAdd mutation with the following fields set appropriately:

Field	Description
refundScope	The id of the seller order line (nauticalOrder.subOrder.line.id).
chargedTo	Set to MARKETPLACE if the marketplace operator will cover the refund cost, or set to SELLER to deduct the refund from the seller's next payout.
lineType	Set to ENTIRE_SCOPE. This will automatically calculate the appropriate amount to refund for the order line, inclusive of any applicable taxes.
quantity	Set to the quantity of the order line to refund.

Request

mutation {
  refundLinesAdd(
    refundId: "UmVmdW5kOjE2"
    lineItems: {
      chargedTo: SELLER
      refundScope: "T3JkZXJMaW5lOjIwOA=="
      lineType: ENTIRE_SCOPE
      quantity: 1
    }
  ) {
    refund {
      lines(first: 5) {
        edges {
          node {
            id
            chargedTo
            refundScope {
              __typename
            }
            lineType
            lineScope
            total {
              net {
                baseAmount
              }
              tax {
                baseAmount
              }
              gross {
                baseAmount
              }
            }
          }
        }
      }
    }
    refundErrors {
      message
      field
      code
    }
  }
}

Show more ↓

3

Add shipping refund line

Shipping is a separate line item in each seller order that can be included in the refund if desired.

To add a shipping line refund line, use the refundLinesAdd mutation with the following fields set appropriately:

Field	Description
refundScope	The id of the seller order (nauticalOrder.subOrder.id).
chargedTo	Set to MARKETPLACE if the marketplace operator will cover the refund cost, or set to SELLER to deduct the refund from the seller's next payout.
lineType	Set to SHIPPING.
amount	Enter the dollar amount to refund for the shipping cost. Enter the cost of shipping, before tax. Any applicable taxes will be calculated and added automatically.

Request

mutation {
  refundLinesAdd(
    refundId: "UmVmdW5kOjE2"
    lineItems: {
      chargedTo: SELLER
      refundScope: "T3JkZXI6MTQx"
      amount: 15
      lineType: SHIPPING
      quantity: 1
    }
  ) {
    refund {
      lines(first: 5) {
        edges {
          node {
            id
            chargedTo
            refundScope {
              __typename
            }
            lineType
            lineScope
            total {
              net {
                baseAmount
              }
              tax {
                baseAmount
              }
              gross {
                baseAmount
              }
            }
          }
        }
      }
    }
    refundErrors {
      message
      field
      code
    }
  }
}

Show more ↓

Seller order refunds

To add a refund line specific to a seller order, set the refundScope field to the id of the seller order (order). Seller order refunds can be based on a fixed amount or a percentage of the order.

Percentage based

1

(Optional)Query seller orders

2

Add percentage-based seller order refund line

To add a percentage-based seller order refund line, use the refundLinesAdd mutation with the following fields set appropriately:

Field	Description
refundScope	The id of the seller order (order).
chargedTo	Set to MARKETPLACE if the marketplace operator will cover the refund cost, or set to SELLER to deduct the refund from the seller's next payout.
lineType	Set to PERCENTAGE.
percentage	Set to the percentage to refund. The percentage will be calculated against the product and shipping subtotals. If taxes are separate from base prices, they'll be automatically calculated and added to this amount.

Request

mutation {
  refundLinesAdd(
    refundId: "UmVmdW5kOjE1"
    lineItems: {
      chargedTo: SELLER
      refundScope: "T3JkZXI6Njkz"
      lineType: PERCENTAGE
      percentage: 20
      quantity: 1
    }
  ) {
    refund {
      lines(first: 5) {
        edges {
          node {
            id
            chargedTo
            refundScope {
              __typename
            }
            lineType
            lineScope
            total {
              net {
                amount
              }
              tax {
                amount
              }
              gross {
                amount
              }
            }
          }
        }
      }
    }
    refundErrors {
      message
      field
      code
    }
  }
}

Show more ↓

Fixed amount

1

(Optional)Query seller orders

2

Add fixed amount seller order refund line

To add a fixed-rate seller order refund line, use the refundLinesAdd mutation with the following fields set appropriately:

Field	Description
refundScope	The id of the seller order (order).
chargedTo	Set to MARKETPLACE if the marketplace operator will cover the refund cost, or set to SELLER to deduct the refund from the seller's next payout.
lineType	Set to FIXED_AMOUNT.
percentage	Set to the exact dollar amount to refund. Taxes are not added to manual fixed-rate refunds. You must handle the tax remittance separately, if applicable, in your tax tool such as Avalara.

Request

mutation {
  refundLinesAdd(
    refundId: "UmVmdW5kOjE0"
    lineItems: {
      chargedTo: SELLER
      refundScope: "T3JkZXI6Njc3"
      lineType: FIXED_AMOUNT
      amount: 20
      quantity: 1
    }
  ) {
    refund {
      lines(first: 5) {
        edges {
          node {
            id
            chargedTo
            refundScope {
              __typename
            }
            lineType
            lineScope
            total {
              net {
                amount
              }
              tax {
                amount
              }
              gross {
                amount
              }
            }
          }
        }
      }
    }
    refundErrors {
      message
      field
      code
    }
  }
}

Show more ↓

Marketplace order refunds

When the refund spans across multiple seller orders, you can scope a refundLine to the entire marketplace order by setting the nauticalOrder.id as the refundScope.

Marketplace order refunds can be based on a fixed amount or a percentage of the nauticalOrder.

Percentage based

1

(Optional)Query the marketplace order

2

Add percentage-based marketplace order refund line

To add a percentage-based marketplace order refund line, use the refundLinesAdd mutation with the following fields set appropriately:

Field	Description
refundScope	The id of the marketplace order (nauticalOrder).
chargedTo	Must be set to MARKETPLACE for marketplace order scopes.
lineType	Set to PERCENTAGE.
percentage	Set to the percentage to refund. The percentage will be calculated against the product and shipping subtotals. If taxes are separate from base prices, they'll be automatically calculated and added to this amount.

Request

mutation {
  refundLinesAdd(
    refundId: "UmVmdW5kOjE1"
    lineItems: {
      chargedTo: MARKETPLACE
      refundScope: "TmF1dGljYWxPcmRlcjo0OTk="
      lineType: PERCENTAGE
      percentage: 15
      quantity: 1
    }
  ) {
    refund {
      lines(first: 5) {
        edges {
          node {
            id
            chargedTo
            refundScope {
              __typename
            }
            lineType
            lineScope
            total {
              net {
                amount 
              }
              tax {
                amount
              }
              gross {
                amount
              }
            }
          }
        }
      }
    }
    refundErrors {
      message
      field
      code
    }
  }
}

Show more ↓

Fixed amount

1

(Optional)Query the marketplace order

2

Add fixed amount marketplace order refund line

To add a fixed-rate marketplace order refund line, use the refundLinesAdd mutation with the following fields set appropriately:

Field	Description
refundScope	The id of the marketplace order (nauticalOrder).
chargedTo	Must be set to MARKETPLACE for marketplace order scopes.
lineType	Set to FIXED_AMOUNT.
amount	Set to the dollar amount to refund. Taxes are not added to manual fixed-rate refunds. You must handle the tax remittance separately, if applicable, in your tax tool such as Avalara.

Request

mutation {
  refundLinesAdd(
    refundId: "UmVmdW5kOjE0"
    lineItems: {
      chargedTo: MARKETPLACE
      refundScope: "TmF1dGljYWxPcmRlcjo0OTA="
      lineType: FIXED_AMOUNT
      amount: 20
      quantity: 1
    }
  ) {
    refund {
      lines(first: 5) {
        edges {
          node {
            id
            chargedTo
            refundScope {
              __typename
            }
            lineType
            lineScope
            total {
              net {
                amount
              }
              tax {
                amount
              }
              gross {
                amount
              }
            }
          }
        }
      }
    }
    refundErrors {
      message
      field
      code
    }
  }
}

Show more ↓

---

Step 3: Approve or decline the refund

After setting up the refund and adding the necessary refundLines, it's time to finalize the refund. At this stage, you can either approve or decline the refund.

Use the refundsChangeStatus mutation to move the refund to either APPROVED or DECLINED.

Approve a refund

mutation {
  refundsChangeStatus(ids: "UmVmdW5kOjEx", status: APPROVED) {
    refundErrors {
      message
      code
      field
    }
  }
}

Decline a refund

mutation {
  refundsChangeStatus(ids: "UmVmdW5kOjEx", status: DECLINED) {
    refundErrors {
      message
      code
      field
    }
  }
}

---

Step 4: Issue refund payments

After a refund gets approved, it's automatically sent back to the buyer's payment method with native credit card gateways like Stripe or Braintree. If you're using a different gateway, you'll need to manually create a payment and update the refund status.

Automatic payments

Refunds are sent to the original payment method. If you're using an integrated gateway like Stripe, the refund is automatically issued upon approval.

The refund status updates to PAID after the payment goes through.

1

Check refund payment status

To check refund payment details and statuses, use the refund query:

Request

{
  refund(id: "UmVmdW5kOjE1") {
    status
    payments(first: 5) {
      totalCount
      edges {
        node {
          id
          paymentType
          refundMethod {
            __typename
            ... on Transaction {
              id
              token
              amount{
                amount
                currency
              }
              kind
              isSuccess
              error
              payment {
                gateway
                chargeStatus
                total{
                  currency
                  amount
                }
              }
            }
          }
        }
      }
    }
  }
}

Show more ↓

Manually issue payment

For payment gateways like nautical.payments.wire, you must manually progress the refund to the paid state.

1

Update the refund to the processing state

Move the refund to the PROCESSING state with the refundsChangeStatus mutation:

Request

mutation {
  refundsChangeStatus(ids: "UmVmdW5kOjEx", status: PROCESSING) {
    refundErrors {
      message
      code
      field
    }
  }
}

2

Query checkout lines

Query the nauticalOrder to retrieve the payment id:

Request

{
  nauticalOrder(id: "TmF1dGljYWxPcmRlcjo0OTg=") {
    payments {
      id
      gateway
    }
    totalRefunded {
      amount
    }
  }
}

3

Create refund payment

Use the payment id to create payments against the refund through the refundPaymentsAdd mutation:

Request

mutation {
  refundPaymentsAdd(
    payments: { id: "UGF5bWVudDo4NTY=", amount: 50.00 }
    refund: "UmVmdW5kOjEz"
  ) {
    refundErrors {
      message
      field
    }
  }
}

4

Update the refund status

Mark the refund as PAID using the refundsChangeStatus mutation:

Request

mutation {
  refundsChangeStatus(ids: "UmVmdW5kOjEz", status: PAID) {
    refundErrors {
      message
      code
      field
    }
  }
}