Return delivery charges

In this guide we’ll go through 2 scenarios that will detail how to pass back return delivery charges to the customer.

6 minute read

What you’ll learn

In this guide you’ll learn:

2 scenarios where return shipment charges can be passed back to the customer
The Operator and Seller APIs calls that can be used to drive those scenarios

Scenario 1

Return charges with postage charges in original sale

Use Case

The customer makes a sale for $10 (incl. tax) plus postage of $2 (incl. tax).
The commission on goods is 20%.
The customer refunds the items and is charged $3 for return shipment.
The net sale is $0.
The net payout to the seller is $3.
The net commission earned is $0.

	Customer	Seller	Operator
Sale	10	8	2
Postage	2	2	0
Customer Paid (A)	12	10	2

Sale refund	-10	-8	-2
Postage refund	-2	-2	0
Return charge	3	3	0
Net refund (B)	-9	-7	-2

Net payouts (A+B)	3	3	0

Steps

1. Operator creates an order

You can get the variantId and cost.amount used on the following orderCreate example using the advertsWhere query or something similar.

orderCreate

mutation CreateOrderAU($input: OrderCreateMutationInput!) {
 orderCreate(input: $input) {
  status
  errors {
   field
   messages
  }
  order {
   id
   invoices {
    edges {
     node {
      id
      legacyId
      lineItems {
       id
       quantity
      }
     }
    }
   }
  }
 }
}

Variables

{
  "input": {
    "order": {
      "firstName": "Jane",
      "surname": "Doe",
      "phone": "0405123456",
      "billingFirstName": "John",
      "billingSurname": "Doe",
      "emailAddress": "john@email.com",
      "billingEmailAddress": "john@email.com",
      "address": {
        "address": "1 Bourke Street",
        "city": "London",
        "country": {
          "code": "UK"
        },
        "postcode": "3000",
        "state": {
          "name": "London"
        }
      }
    },
    "lineItems": [
      {
        "variantId": "VmFyaWFudC04MzA=",
        "quantity": 1,
        "cost": {
          "amount": 1000
        },
        "postage": {
          "amount": 200
        },
        "metadata": {
          "key": "shipping_method",
          "value": "Standard"
        }
      }
    ]
  }
}

2. Seller creates a shipment

This step assumes that the Seller has obtained an invoice and associated line items using something like the invoices query.

You can get a list of the shipment carrier Ids used in the shipmentCreate example below, by using the shipmentCarriers query.

shipmentCreate

mutation CreateShipment($input: ShipmentCreateMutationInput!) {
 shipmentCreate(input: $input) {
  status
  errors {
   field
   messages
  }
  shipment {
   id
  }
 }
}

Variables

{
  "input": {
    "invoiceId": "SW52b2ljZS0zNTE1Nw==",
    "postageCarrierId": "U2hpcG1lbnRDYXJyaWVyLTIz",
    "dispatchedAt": "2024-09-30",
    "trackingNumber": "123",
    "shippedItems": [
      {
        "quantity": 1,
        "lineItemId": "TGluZUl0ZW0tMzY1NDg="
      }
    ],
    "note": null
  }
}

3. Operator creates a refund request

refundRequestCreate

mutation RefundRequestCreate($input: RefundRequestCreateMutationInput!) {
 refundRequestCreate(input: $input) {
  refundRequest {
   id
   status
  }
  errors {
   field
   messages
  }
 }
}

Variables

{
  "input": {
    "invoiceId": "SW52b2ljZS0zNTE1NQ==",
    "lineItems": [
      {
        "lineItemId": "TGluZUl0ZW0tMzY1NDY=",
        "reason": "Buyer changed their mind",
        "quantity": 1,
        "status": "PENDING_APPROVAL"
      },
      {
        "custom": "Postage refund",
        "amountPerItemCents": 200,
        "quantity": 1,
        "status": "PENDING_APPROVAL"
      },
      {
        "custom": "Return postage charge",
        "amountPerItemCents": -300,
        "quantity": 1,
        "status": "PENDING_APPROVAL"
      }
    ],
    "notes": [
      {
        "note": "Change of mind within T&Cs"
      }
    ]
  }
}

4. Seller accepts the refund and creates a return shipment

refundRequestLineItemAccept

mutation RefundRequestLineItemAccept(
 $input: RefundRequestLineItemAcceptMutationInput!
) {
 refundRequestLineItemAccept(input: $input) {
  refundRequestLineItem {
   status
  }
  errors {
   field
   messages
  }
 }
}

Variables

{
  "input": {
    "refundRequestLineItemId": "UmVmdW5kUmVxdWVzdExpbmVJdGVtLTc5MA==",
    "notes": [
      {
        "note": "This item does not need to be returned."
      }
    ]
  }
}

returnShipmentCreate

mutation createReturnShipment($input: ReturnShipmentCreateMutationInput!) {
 returnShipmentCreate(input: $input) {
  shipment {
   id
   carrier {
    name
    trackingUrl
   }
   attachments {
    url
    alt
   }
  }
  errors {
   field
   messages
  }
 }
}

Variables

{
  "input": {
    "refundRequestId": "UmVmdW5kUmVxdWVzdC01Mjc=",
    "carrierId": "U2hpcG1lbnRDYXJyaWVyLTcw",
    "trackingNumber": "ABC-1234",
    "shippedItems": [
      {
        "lineItemId": "UmVmdW5kUmVxdWVzdExpbmVJdGVtLTc1Ng==",
        "quantity": 1
      }
    ],
    "attachments": [
      {
        "filename": "packing_slip.jpg",
        "dataBase64": "<BASE 64 STRING HERE>"
      }
    ]
  }
}

5. Seller accepts the items as returned

refundRequestLineItemReturn

mutation RefundRequestLineItemReturn(
 $input: RefundRequestLineItemReturnMutationInput!
) {
 refundRequestLineItemReturn(input: $input) {
  refundRequestLineItem {
   status
  }
  errors {
   field
   messages
  }
 }
}

Variables

{
  "input": {
    "refundRequestLineItemId": "UmVmdW5kUmVxdWVzdExpbmVJdGVtLTc5MA==",
    "notes": [
      {
        "note": "This item does not need to be returned."
      }
    ]
  }
}

6. Operator approves the refund

refundRequstLineItemApprove

mutation RefundRequestApprove($input: RefundRequestApproveInput!) {
 refundRequestApprove(input: $input) {
  refundRequest {
   id
   status
  }
  errors {
   field
   messages
  }
 }
}

Variables

{
  "input": {
    "refundRequestId": "UmVmdW5kUmVxdWVzdC0xNTc5"
  }
}

7. Operator pays out the seller based on remittance advice

Webhook Payload

{
  "data": {
    "node": {
      "attachments": [],
      "createdAt": "2024-09-28T00:23:48+01:00",
      "id": "UmVtaXR0YW5jZUFkdmljZS03Njc=",
      "legacyId": 767,
      "totalCents": 200,
      "commissionAmountTotalCents": 0,
      "seller": {
        "id": "U2VsbGVyLTE=",
        "businessName": "Sample Business"
      },
      "remittances": [
        {
          "id": "UmVtaXR0YW5jZS0yNTky",
          "createdAt": "2024-09-27T23:16:40+01:00",
          "invoice": {
            "id": "SW52b2ljZS0zNTE1MQ==",
            "legacyId": 35151,
            "commissionInvoiceId": "#35151-G",
            "order": {
              "id": "T3JkZXItMjkyNDc=",
              "externalIds": []
            },
            "totalCents": 1200,
            "commissionAmountCents": 200,
            "lineItems": [
              {
                "id": "TGluZUl0ZW0tMzY1NDI=",
                "commissionAmountCents": 200,
                "commissionAmountTaxCents": 33,
                "commissionRate": "20.0",
                "commissionTaxRate": 0.2,
                "totalCents": 1000,
                "discountCents": 0,
                "taxTotalCents": 167,
                "taxRate": 0.2,
                "subtotalCents": 1000,
                "quantity": 1,
                "metadata": [
                  {
                    "key": "shipping_method",
                    "value": "Standard"
                  }
                ]
              }
            ],
            "createdAt": "2024-09-27T23:02:30+01:00"
          },
          "invoiceAmendment": null
        },
        {
          "id": "UmVtaXR0YW5jZS0yNTkz",
          "createdAt": "2024-09-27T23:55:44+01:00",
          "invoice": null,
          "invoiceAmendment": {
            "id": "SW52b2ljZUFtZW5kbWVudC03MDY=",
            "creditNoteId": "CN-35151-1",
            "commissionCreditNoteId": "CN-35151-G-1",
            "invoice": {
              "id": "SW52b2ljZS0zNTE1MQ==",
              "commissionInvoiceId": "#35151-G"
            },
            "order": {
              "id": "T3JkZXItMjkyNDc=",
              "externalIds": []
            },
            "lineItems": [
              {
                "lineItem": {
                  "id": "TGluZUl0ZW0tMzY1NDI=",
                  "commissionAmountCents": 200,
                  "commissionAmountTaxCents": 33,
                  "commissionRate": "20.0",
                  "commissionTaxRate": 0.2,
                  "totalCents": 1000,
                  "discountCents": 0,
                  "taxTotalCents": 167,
                  "taxRate": 0.2,
                  "subtotalCents": 1000,
                  "quantity": 1,
                  "metadata": [
                    {
                      "key": "shipping_method",
                      "value": "Standard"
                    }
                  ]
                },
                "id": "SW52b2ljZUFtZW5kbWVudExpbmVJdGVtLTExOTA=",
                "amountCents": -1000,
                "taxRate": 0.2,
                "quantity": 1,
                "taxCents": -167,
                "totalCents": -1000,
                "commissionAmountCents": -200,
                "commissionTaxCents": -33
              },
              {
                "lineItem": null,
                "id": "SW52b2ljZUFtZW5kbWVudExpbmVJdGVtLTExOTE=",
                "amountCents": -200,
                "taxRate": null,
                "quantity": 1,
                "taxCents": -33,
                "totalCents": -200,
                "commissionAmountCents": 0,
                "commissionTaxCents": 0
              },
              {
                "lineItem": null,
                "id": "SW52b2ljZUFtZW5kbWVudExpbmVJdGVtLTExOTI=",
                "amountCents": 300,
                "taxRate": null,
                "quantity": 1,
                "taxCents": 50,
                "totalCents": 300,
                "commissionAmountCents": 0,
                "commissionTaxCents": 0
              }
            ],
            "totalCents": -900,
            "commissionAmountTotalCents": -200
          }
        }
      ]
    }
  }
}

Scenario 2

Return charges with no postage charges in original sale

Use Case

The customer makes a sale for $10 (incl. tax).
The commission on goods is 20%.
The customer refunds the items and is charged $3 for return shipment.
The net sale is $0.
The net payout to the seller is $3.
The net commission earned is $0.

	Customer	Seller	Operator
Sale	10	8	2
Postage	0	0	0
Customer Paid (A)	10	8	2

Sale refund	-10	-8	-2
Postage refund	0	0	0
Return charge	3	3	0
Net refund (B)	-7	-5	-2

Net payouts (A+B)	3	3	0

Steps

The steps are identical to Scenario 1 except for:

Step 1: There is no postage applied in orderCreate
Step 3: The refundRequestCreate step does not include the refund on postage

The examples specific for this scenario are shown below:

1. Operator creates an order

orderCreate

mutation CreateOrderAU($input: OrderCreateMutationInput!) {
 orderCreate(input: $input) {
  status
  errors {
   field
   messages
  }
  order {
   id
   invoices {
    edges {
     node {
      id
      legacyId
      lineItems {
       id
       quantity
      }
     }
    }
   }
  }
 }
}

Variables

{
  "input": {
    "order": {
      "firstName": "Jane",
      "surname": "Doe",
      "phone": "0405123456",
      "billingFirstName": "John",
      "billingSurname": "Doe",
      "emailAddress": "john@email.com",
      "billingEmailAddress": "john@email.com",
      "address": {
        "address": "1 Bourke Street",
        "city": "London",
        "country": {
          "code": "UK"
        },
        "postcode": "3000",
        "state": {
          "name": "London"
        }
      }
    },
    "lineItems": [
      {
        "variantId": "VmFyaWFudC04MzA=",
        "quantity": 1,
        "cost": {
          "amount": 1000
        },
        "metadata": {
          "key": "shipping_method",
          "value": "Standard"
        }
      }
    ]
  }
}

3. Operator creates a refund request

refundRequestCreate

mutation RefundRequestCreate($input: RefundRequestCreateMutationInput!) {
 refundRequestCreate(input: $input) {
  refundRequest {
   id
   status
  }
  errors {
   field
   messages
  }
 }
}

variables

{
  "input": {
    "invoiceId": "SW52b2ljZS0zNTE1NQ==",
    "lineItems": [
      {
        "lineItemId": "TGluZUl0ZW0tMzY1NDY=",
        "reason": "Buyer changed their mind",
        "quantity": 1,
        "status": "PENDING_APPROVAL"
      },
      {
        "custom": "Return postage charge",
        "amountPerItemCents": -300,
        "quantity": 1,
        "status": "PENDING_APPROVAL"
      }
    ],
    "notes": [
      {
        "note": "Change of mind within T&Cs"
      }
    ]
  }
}