SWAP Webhooks (latest version) (Returns V2)

Webhooks are a way for applications to communicate automatically with each other. When an event occurs in Swap (for example, a return is processed), a webhook sends real-time data to another system via an HTTP callback. This process is automated, so no manual action is needed to update information across systems.

Webhooks are especially useful for keeping your app synchronised with returns information or triggering additional actions after certain events take place.

This article is for users of Returns V2. For the Returns V1 version, click here.

Events

Swap webhooks are available for the following events:

Return created – triggered when a new return is created in the portal.
Return processed – triggered when the RMA is finalised and processed in your dashboard.

Versions

There are two versions of webhook payloads:

Version 1 – the original schema (still supported).
Version 2 – the new schema, which adds fields such as RMA number, shipping address, and support for split shipments. This is the latest and recommended version

Security

All webhook requests include a JWT for authentication, signed with your secret key.

Version 2 webhooks also include an HMAC signature for additional verification.

You can use either method to confirm that the request came from Swap.

How to Configure a Webhook

Go to the Integrations screen in your dashboard.
Click on New webhook.
Fill out the required fields (all required unless stated otherwise):
- Webhook Name – Give your webhook an identifying name.
- Description – Add a description for your convenience (for example: the objective of the webhook).
- URL – The endpoint where the webhook should send data.
- Event – Choose the event that will trigger the webhook.
After creating the first webhook, you will be shown a secret key to enable authentication. Copy it and store it securely. It cannot be revealed again.
To revoke or regenerate the key, contact our support team.

Request construction

Swap sends a POST request to your configured webhook URL whenever the event occurs.

Headers:

Content-Type: application/json

Body:

{ "jwt": "{signed_jwt}", "payload": { "return": { ... }, "version": "v2" } }

Payload fields

General Fields

Field	Description
return_id	Unique identifier for the return in Swap
rma_number	RMA number assigned to the return
order_name	Display name of the order (e.g. #1001)
original_order_name	Original order name from the commerce platform
order_id	Unique ID of the order (Shopify GID or equivalent)
date_created	Timestamp when the return was created
date_updated	Timestamp when the return was last updated
submitted_at	Timestamp when the customer submitted the return
type_string	Human-readable return type (e.g. “Refund, Exchange”)
type	Array of return types (Refund, Shop Now Credit, Shop Later Credit, Exchange, Additional Payment)
delivery_status	Delivery status of the return shipment (delivered, in-transit, pre-transit, etc.)
return_status	Current status of the RMA (created, processed, closed, needs-review, etc.)
total	Total return value
total_additional_payment	Any additional payment collected for the return
total_refund_value_customer_currency	Refund value in the customer’s currency
total_tax	Total refunded tax amount
total_shipping	Total refunded shipping amount
total_exchange	Total value of exchange items
gift_card_credit	Amount issued as gift card credit
customer_currency	ISO currency code used for the customer (e.g. USD, EUR)
customer_name	Customer’s full name
customer_email	Customer’s email address
customer_phone	Customer’s phone number (if available)
customer_tags	Tags applied to the customer (e.g. vip, returning)
customer_national_id	Customer’s national ID (if provided)
store_id	Unique identifier for the store in Swap
store_name	Name of the store

Address Fields

Field	Description
billing_address	Customer’s billing address (name, address1, address2, city, state_province_code, country_code, zipCode)
shipping_address	Customer’s shipping address (same structure as billing)

Product fields (products array)

Field	Description
product_id	Unique identifier for the product in Swap
shopify_product_id	Shopify product GID
shopify_variant_id	Shopify variant GID
order_number	Order number the item belongs to
original_order_name	Original order name
date	Timestamp of when the product was added to the return
product_name	Product title
variant_name	Variant name (e.g. “Large / Blue”)
full_sku_description	Full SKU description (product + variant)
sku	SKU of the product
barcode	Barcode of the product
main_reason_id	Identifier for the main return reason
main_reason_text	Human-readable main reason text
sub_reason_id	Identifier for the sub-reason
sub_reason_text	Human-readable sub-reason text
comments	Free-text comments left by the customer
item_count	Quantity returned
cost	Value of the item(s)
return_type	Return type for the item (Refund, Exchange, etc.)
currency	ISO currency code
collection	Collections/tags applied to the product
product_alt_type	Alternative product type
recycle_material	Recyclable material info (if provided)
grams	Product weight in grams
intake_reason	Reason for intake (internal)
tags	Tags applied to the product

Exchange product fields (exchange_products array)

Field	Description
sku	SKU of the exchange product
product_name	Product title
shopify_product_id	Shopify product GID
shopify_variant_id	Shopify variant GID
quantity	Quantity being exchanged
price	Price of the exchange product
taxes	Tax applied to the product
discount	Discount applied to the product
grams	Product weight in grams
variant_name	Variant name
full_sku_description	Full SKU description (product + variant)

Processing details

Field	Description
processed_by	Information about the user who processed the return (userId, firstName, lastName)
quality_control_status	QC outcome (passed, failed, etc.)
delivered_date	Date the return was delivered back

Shipping details

Field	Description
tracking_number	Tracking number for the return shipment
shipping_carrier	Carrier name (e.g. FedEx Ground)
shipping_label_url	Link to the return shipping label
shipping_tracking_url	Link to the carrier’s tracking page
is_international	Boolean indicating if the shipment is international
shipping_cost	Cost of the return shipment

Return shipments (return_shipments array)

Field	Description
shipment_id	Unique identifier for the shipment
location_id	Location ID (Shopify GID)
destination_location_id	Destination location (if split shipment)
display_name_returns_portal	Display name shown in returns portal
carrier_id	Carrier identifier
postage_fee	Postage fee for this shipment
label_type	Type of label (label, QR, own)
shipping_service	Name of the shipping service
display_name	Display name of the carrier
using_split_shipment	Boolean indicating if split shipment was used
label_provider_type	Label provider type (e.g. EASY_POST)
tracking_number	Tracking number for this shipment
tracking_url	Tracking link for this shipment
package	Package details (weight and dimensions)
items	Array of product objects (same structure as products)

Notes and links

Field	Description
return_notes	Array of notes, each with message, state, type, created_at, created_by
portal_quick_link	Customer-facing link to the return in the portal

Example payload

{
  "jwt": "xxx.yyy.zzz",
  "payload": {
    "return": {
      "return_id": "RET-2024-001",
      "rma_number": "RMA-2024-001",
      "order_name": "#1001",
      "original_order_name": "#1001",
      "order_id": "gid://shopify/Order/1234567890",
      "date_created": "2024-01-15T10:30:00Z",
      "date_updated": "2024-01-16T15:45:00Z",
      "submitted_at": "2024-01-15T12:00:00Z",
      "type": [
        "Refund",
        "Exchange"
      ],
      "delivery_status": "delivered",
      "return_status": "completed",
      "total": 29.99,
      "store_id": "store_123abc",
      "store_name": "Fashion Store",
      "customer_name": "John Doe",
      "customer_email": "[email protected]",
      "customer_phone": "+1234567890",
      "customer_tags": "vip, returning",
      "billing_address": {},
      "shipping_address": {},
      "products": [],
      "exchange_products": [],
      "processed_by": {
        "userId": "agent-123",
        "firstName": "John",
        "lastName": "Smith"
      },
      "quality_control_status": "passed",
      "tracking_number": "1Z999AA1234567890",
      "shipping_carrier": "FedEx Ground",
      "shipping_label_url": "https://example.com/label.pdf",
      "shipping_tracking_url": "https://fedex.com/...",
      "is_international": false,
      "shipping_cost": 12.99,
      "return_shipments": [
        {
          "shipment_id": "SHIP-001",
          "carrier_id": "fedex_ground",
          "postage_fee": 12.99,
          "tracking_number": "1Z999AA1234567890",
          "tracking_url": "https://fedex.com/...",
          "package": {
            "weight": 500,
            "dimensions": {
              "length": 20,
              "width": 15,
              "height": 10,
              "unit": "inches"
            }
          },
          "items": []
        }
      ],
      "portal_quick_link": "https://returns.example.com/store-slug?o=#1001",
      "return_notes": [
        {
          "message": "Return processed successfully",
          "state": "returns",
          "type": "note",
          "created_at": "2024-01-16T15:45:00Z",
          "created_by": "John Smith"
        }
      ]
    },
    "version": "v2"
  }
}