Integration Reference

BACK API Integration

One reference for the full round trip: push your orders into Back, receive webhook events as returns are processed, and confirm refunds once you settle them. Three touchpoints, one shared data model.

Import orders · you → Back Webhooks · Back → you Refund confirm · you → Back application/json

01Overview

Integrating with Back has three touchpoints, and they form a loop around a single order.

1 · You send orders to Back. The Import Orders API is the starting point — you push your order and product data so Back knows what exists and can later match a return to the right item.

2 · Back sends events to you. When a customer starts a return, Back grades it, runs your rules, and creates the return shipment — pushing a webhook event to your endpoint at each step. Every event reuses one payload shape, so you write one handler and branch on the event name.

3 · You confirm refunds to Back. When a refund is due, Back initiates it and you settle it on your store, then confirm back so Back can close the loop.

All three speak JSON. Outbound calls (import, refund confirm) go to https://live.api.back.tech; inbound webhooks arrive at the endpoint you register on the Back portal.

02Integration flow

From onboarding to a live round trip.

1 · Import your orders
you → Back
Send order and product data to POST /api/order/add (up to 500 orders per request). This seeds Back with everything a return might reference. See Import orders.
2 · Build a webhook endpoint
your side
Expose a public HTTPS URL that accepts POST with a JSON body. It just needs to read the body, return 2xx quickly, and process asynchronously.
3 · Secure it with a bearer token (optional)
optional
If you want to verify calls came from Back, configure a token and Back sends it as Authorization: Bearer <token>. Leave it blank to skip auth. See Authentication.
4 · Register the webhook on the Back portal
Back portal
Add your URL (and optional token), then select which of the fifteen events should fire to it.
5 · Receive events & confirm refunds
Back → you → Back
Back pushes a payload whenever a selected event occurs. For refunds you settle on your store, then call back to confirm — see Refund handling.

03Order lifecycle

Events fire in roughly this order. Each stage is where a part of the payload first becomes available.

order.createdorder exists in Back
order.return.createdcustomer starts return
order.return.gradedgrade object appears
order.return.rule.completerule, refund, charges appear
shipping.createdshipping object appears
shipping.label.createdlabel & QR appear
order.refund.initiatedyou settle & confirm

Not every order takes the happy path — grading can be skipped (grade.skiped), and shipping or labels can fail (shipping.failed, shipping.label.failed).

04Import orders

The starting point for any integration. Send Back your order and product data so a return can later be matched to the right item.

POSThttps://live.api.back.tech/api/order/add
Content-Type: application/json

[ { /* order */ }, { /* order */ } ]   // array, up to 500 orders

The body is an array of orders (max 500 per request). Each order carries the products purchased, the customer's address and contact, and order metadata such as payment mode and costs — the inputs Back's rule engine works from. Fields not documented here are generated server-side.

Always returns HTTP 200 — read the bodySuccess or failure is in the response body, not the status code. On full success, failed is null (or empty) and message states how many were imported. On partial or complete failure, failed is an array of items, each with a reason and the order that failed. A malformed payload that fails validation returns 400.
ConventionsDates use YYYY-MM-DD in requests (responses may use ISO 8601 date-time).  order_id, team_name and client_name are the reference names shared by the Back team during onboarding — send them exactly as given.  Each field below is tagged required or optional — send every required field for the order to process correctly.

Request body

[ ] orders
array · max 500root
Array of order objects. Each order holds the products purchased; when a customer starts a return, Back looks up this list to find the product and trigger the returns flow.
order_id
stringrequired
Reference name shared by Back at onboarding. e.g. "USP001"
unique_code
stringrequired
Postcode of the delivery address, with all spaces removed. e.g. "UB83BY"
team_name
stringrequired
Reference name shared by Back at onboarding. e.g. "vip-store"
client_name
stringrequired
Reference name shared by Back at onboarding. e.g. "us-polo"
address
objectrequired
Where the order was shipped — the retailer's customer address.
line_1
stringrequired
line_2
stringoptional
Unit / building. Empty accepted.
state
stringoptional
Empty accepted.
city
stringrequired
postal_code
stringrequired
country_alpha2
stringrequired
ISO 3166-1 alpha-2, e.g. GB.
contact
objectrequired
Primary contact for the order.
company_name
stringrequired
Company for the order. If you don't have one, repeat the customer's first / last name.
first_name
stringrequired
last_name
stringoptional
Empty accepted.
contact_phone
stringrequired
E.164 or local format.
contact_email
string · emailrequired
order_date
stringrequired
Datetime the order was created (e.g. JS Date.toString()).
total_order_value
stringoptional
Total exactly as received from the source — kept as a string. e.g. "201"
platform_name
stringoptional
Marketplace / platform label, e.g. Amazon. Empty accepted.
first_order_date
string · dateoptional
The customer's first purchase, YYYY-MM-DD. Empty / null accepted.
customer_score
stringoptional
Customer segment, used to apply different rules per segment. Use one of: FRAUD, POOR, FAIR, GOOD, VERY GOOD, EXCELLENT, VIP.
lifetime_value
numberoptional
Customer's overall spend — also used for segmentation.
payment
objectrequired
Payment and promo info.
currency
stringrequired
ISO 4217, e.g. GBP.
discount_code_type
stringoptional
e.g. FLAT, PERCENT.
free_delivery
booleanoptional
order_value_for_free_delivery
numberoptional
payment_mode
stringoptional
e.g. VOUCHER.
other_payment_mode
stringoptional
Specify when payment_mode is OTHER.
products
object[]required
Line items in the order — send each line exactly as it appears in the order, with its real quantity. Back splits multi-quantity lines into individual units internally.
team_name
stringrequired
As shared at onboarding.
name
stringrequired
Product title.
actual_price
numberrequired
Final per-unit price the customer paid. Used to compute profit and other rule-engine inputs.
category_name
stringrequired
Product category label.
product_id
stringrequired
Your identifier for the product.
variant_id
stringrequired
Your identifier for the specific variant (size / colour / style) of this product.
description
stringrequired
Product description.
brand
stringoptional
rrp
numberrequired
Recommended retail price (per unit).
cogs
numberoptional
Cost of goods sold — input for product-level rules.
vat
numberoptional
duty
numberoptional
discount_code
stringoptionalnullable
discount_value
numberoptional
Discount applied to the product. Back computes the GBP-normalised value internally.
sku
stringoptional
sku_color
stringrequired
sku_size
stringrequired
sku_value
numberoptional
quantity
numberoptional
Send the real quantity from the order (may be more than 1). Back splits it into individual units internally. Defaults to 1.
priority
enumoptional
high | normal. Default normal.
return_allowed
booleanoptional
Default true. Send false for items that may not be returned.
return_by_date
string · daterequired
YYYY-MM-DD. After this date the customer can't return the product.
purchased_date
string · dateoptional
YYYY-MM-DD. Empty / null accepted.
delivery_date
string · daterequired
YYYY-MM-DD.
delivery_status
stringrequired
Current delivery status. If the item is delivered / ready to return, send "delivered". Cannot be null.
images
string[] · urioptional
product_meta
stringoptional
JSON-encoded string of extra attributes — useful for spotting patterns (e.g. a problematic manufacturer).
returnType
stringoptional
Return mode allowed for this item, e.g. RETURN, EXCHANGE.
shipping_details
objectrequired
Per-item shipping specifics — Back uses these to create the return shipment.
origin_country_alpha2
stringrequired
The customer's country (ISO alpha-2).
declared_currency
stringrequired
declared_customs_value
stringrequired
hs_code
stringrequired
Harmonised System tariff code, used to create the shipment.
contains_battery_pi966
booleanrequired
Lithium battery, PI 966.
contains_battery_pi967
booleanrequired
Lithium battery, PI 967.
contains_liquids
booleanrequired
actual_weight
numberoptional
In kg.
dimensions
objectoptional
Packed size of the product, in cm.
length
numberoptional
In cm. Defaults to 1.
width
numberoptional
In cm. Defaults to 1.
height
numberoptional
In cm. Defaults to 1.
insurance
objectoptionalnullable
Optional shipment insurance. When is_insured is true, insured_amount and insured_currency become required.
is_insured
booleanoptional
Defaults to false.
insured_amount
numberconditional
Required when is_insured is true; otherwise optional (defaults to 0).
insured_currency
stringconditional
Required when is_insured is true; otherwise optional (defaults to GBP).
variants
objectoptional
Only relevant if you offer exchange as a return mode — these are the exchange options shown to the customer. Set per product since options differ by item.
size[]
object[]optional
Available size options, e.g. { "value": "STD", "label": "Standard" }.
value
stringoptional
label
stringoptional
color[]
object[]optional
Available colour options, e.g. { "value": "BLK", "label": "Black" }.
value
stringoptional
label
stringoptional

Example request

POST /api/order/add · request body
[
  {
    "order_id": "USP001",
    "unique_code": "UB83BY",
    "total_order_value": "201",
    "team_name": "vip-store",
    "client_name": "us-polo",
    "order_date": "Mon Sep 10 2025 13:28:06 GMT+0100",
    "platform_name": "Amazon",
    "customer_score": "GOOD",
    "lifetime_value": 100,
    "first_order_date": "2025-08-05",
    "address": {
      "line_1": "56 Example Street",
      "line_2": " ",
      "state": "England",
      "city": "London",
      "postal_code": "E1 6JJ",
      "country_alpha2": "GB"
    },
    "contact": {
      "company_name": "Example Retail Ltd",
      "first_name": "Alex",
      "last_name": "Johnson",
      "contact_phone": "+442079460000",
      "contact_email": "alex.johnson@example.com"
    },
    "payment": {
      "currency": "GBP",
      "discount_code_type": "FLAT",
      "free_delivery": false,
      "order_value_for_free_delivery": 5,
      "payment_mode": "VOUCHER"
    },
    "products": [
      {
        "team_name": "vip-store",
        "name": "USB-C Fast Charger 25W",
        "actual_price": 10,
        "category_name": "Clothes, Shoes & Accessories",
        "product_id": "REG52",
        "variant_id": "REG52-BLK-STD",
        "description": "USB-C fast charger, 25W",
        "brand": "Nike",
        "rrp": 15,
        "cogs": 5,
        "quantity": 1,
        "priority": "high",
        "return_allowed": true,
        "return_by_date": "2025-08-31",
        "purchased_date": "2025-08-10",
        "delivery_date": "2025-08-12",
        "delivery_status": "delivered",
        "images": [ "https://cdn.example.com/products/charger-front.jpg" ],
        "sku": "usb-c-fast-charger-25w",
        "sku_color": "Black",
        "sku_size": "STD",
        "vat": 1,
        "duty": 1,
        "shipping_details": {
          "origin_country_alpha2": "GB",
          "actual_weight": 0.1,
          "declared_currency": "GBP",
          "declared_customs_value": "10",
          "hs_code": "85044095",
          "contains_battery_pi966": false,
          "contains_battery_pi967": false,
          "contains_liquids": false,
          "dimensions": { "length": 5, "width": 1, "height": 1 },
          "insurance": { "is_insured": false, "insured_amount": 0, "insured_currency": "GBP" }
        },
        "variants": {
          "size": [ { "value": "STD", "label": "Standard" } ],
          "color": [ { "value": "BLK", "label": "Black" } ]
        },
        "returnType": "RETURN"
      }
    ]
  }
]

Responses

HTTP 200 is always returned (except for a malformed payload, which returns 400). Inspect the envelope to determine the real outcome.

200 · import result
object
success
boolean
Operation was accepted — not a per-item success flag.
data.data
string
Status string, e.g. "success".
data.value.message
string
Human-readable summary, e.g. how many orders were queued.
data.value.failed
object[]null on success
null when everything imported. Otherwise an array of failures, each with a reason (e.g. "Team or Client not found!!"), the echoed order that failed, and a server-generated batchUid.
error
string
Empty on success or handled failures.
200 · success (all items accepted)
{
  "success": true,
  "data": {
    "data": "success",
    "value": {
      "message": "1 Orders imported. Order are in queue. you'll receive the update through webhook.",
      "failed": null
    }
  },
  "error": ""
}
200 · accepted but items failed validation / lookup
{
  "success": true,
  "data": {
    "data": "success",
    "value": {
      "message": "0 Orders imported. Order are in queue. you'll receive the update through webhook.",
      "failed": [
        {
          "reason": "Team or Client not found!!",
          "order": { /* the echoed order that failed */ },
          "batchUid": "2880e8d2-163d-41c7-aebd-372baaca403b"
        }
      ]
    }
  },
  "error": ""
}
StatusMeaning
200Request processed. Check data.value.failed for per-item outcomes.
400Invalid payload — failed schema (Joi) validation. Fix the body and resend.

05Authentication optional

Webhooks are calls from Back to you. Bearer auth on them is optional — add it only if you want to verify the caller is Back.

When registering the webhook you may supply a secret token. If you do, Back attaches it to every delivery in the standard Authorization header; verify it before trusting the body and return 401 if it's missing or wrong. Leave the token blank and Back sends no Authorization header, so your endpoint should accept the call as-is. (Access for your outbound calls — Import Orders and Refund confirm — is provisioned by the Back team at onboarding.)

POSThttps://your-app.example.com/webhooks/back
// Authorization is sent only if you configured a token.
// The signature headers are sent whenever a token is configured.
Authorization: Bearer <YOUR_WEBHOOK_TOKEN>
X-8ack-Timestamp: <unix-ms>
X-8ack-Signature: sha256=<hex-hmac>
Content-Type: application/json

{ /* event payload — see Webhook payload */ }
If you do use a tokenValidate it with a constant-time comparison and treat it like any other secret — store it in your environment and rotate it from the portal if it leaks.

Signature verification. Whenever a token is configured, Back also HMAC-signs every delivery so you can verify integrity and freshness. Compute HMAC-SHA256 over the string {X-8ack-Timestamp}.{raw request body} using your webhook token as the secret, hex-encode it, and compare it (constant-time) with the value of X-8ack-Signature after its sha256= prefix. Reject the request if it doesn't match, or if X-8ack-Timestamp is outside your allowed clock skew (replay protection).

Delivery & retriesUse a public endpoint reachable from Back — HTTPS is strongly recommended (though not strictly enforced). Delivery is at-least-once: if your endpoint is slow, unreachable, or returns a non-2xx status, Back retries with exponential backoff (up to 5 attempts). The same event can therefore arrive more than once — make your handler idempotent and dedupe on the payload id. Return 2xx quickly and do heavy work asynchronously.

06Events

The event name arrives alongside the payload. Branch your handler on it.

order.created
An order has been imported into Back from your sales channel.The starting point — the order now exists in our system and can receive a return.
order.return.created
Your customer has started a return for a product in an order.Fires the moment the return request is submitted. Grade, rule, refund and shipping data are not present yet.
grade.skiped
Grading was skipped for this return, but processing still moves on to the rule engine.No AI grade is attached. Use this to handle returns that bypass inspection.
order.return.graded
The returned product has been inspected and graded.The grade object (label, system grade, confidence) is now populated.
order.return.rule.complete
Your automation rules have finished running for this return.After this, refund, charges and deductionCharges become available.
order.return.ai.action.complete
The AI-driven rule actions for this return have been applied.Fires after the grading rule engine runs its AI actions — following order.return.rule.complete.
order.return.offer.accept
Your customer accepted a keep-it / discount offer instead of returning the product.The item stays with the customer — no return shipment is created for it. Fires when the offer is accepted via the offer-action step.
order.return.offer.reject
Your customer declined the offer and is proceeding with the return.The return continues as normal — return shipping is initiated once every offer in the request has been decided.
order.refund.initiated
Back has determined a refund is due and initiated it.The money or credit moves on your side. Process it on your store, then confirm back to us via the Refund Confirmation API.
shipping.created
A return shipment has been created with the carrier.The shipping_details object (carrier, shipping id, tracking codes) becomes available.
shipping.failed
Creating the return shipment failed.Inspect the error, then retry or handle the shipment manually.
shipping.label.created
The shipping label was generated for an already-created shipment.Label URL and QR code become available inside shipping_details.
shipping.label.failed
Label generation failed for an otherwise-created shipment.The shipment exists but has no printable label yet.
shipping.status.updated
The carrier reported a new tracking status for the return shipment.Read the latest state from shipping_details.shippingStatus (e.g. in transit, out for delivery, delivered). This can fire several times as the shipment progresses.
shipping.cancelled
The return shipment was cancelled at the carrier.The shipment is no longer active; shipping_details.shippingStatus reflects the cancellation.

07Conditional objects

One payload shape is reused for every event, so several objects are absent or null until the matching step has run. Always null-check before reading them.

ObjectAvailable fromUntil then
aiRuleDataRule engine completes (order.return.rule.complete)Absent — no rule has run yet
returnDetails.gradeProduct is graded (order.return.graded)Absent — and never appears if grading was skipped (grade.skiped)
returnDetails.refundRules completeAbsent
returnDetails.chargesRules completeAbsent
returnDetails.deductionChargesRules complete. If the deduction rule is based on shipping, it is only populated once shipping is created.Absent / zeroed
shipping_detailsShipping is created (shipping.created)null
shipping_details · label URLsLabel is created (shipping.label.created) — label_url, label_path, qr_code_url, tracking_numbernull even though the shipping object exists
Write defensivelyTreat any object in the table as optional on every event. Reading returnDetails.grade.label before the return is graded will throw — guard with a presence check first.

08Webhook payload

The full envelope, sanitized. Identifiable and client-specific values are shown as {{PLACEHOLDERS}}. Expand any object to see its fields.

event
string
The event name (see Events). Branch your handler on it.
id
string
Unique id for this delivery. Delivery is at-least-once, so the same event may arrive more than once — dedupe on id.
created_at
string
ISO 8601 timestamp of when this delivery was generated.
orderDetails
objectroot
The data wrapper — all order, product, return and shipping data lives inside it, alongside the top-level event, id and created_at.
address
object
Customer's delivery address for the original order.
line_1
string
Street line 1. {{ADDRESS_LINE_1}}
line_2
string
Street line 2 / unit. {{ADDRESS_LINE_2}}
city
string
state
string
postal_code
string
country_alpha2
string
ISO 3166-1 alpha-2 country code, e.g. GB.
location
object
GeoJSON point for the address.
type
string
Always Point.
coordinates
number[]
[longitude, latitude].
contact
object
Customer contact. Phone and email are base64-encoded in transit — decode on your side.
company_name
string
{{COMPANY_NAME}}
contact_name
string
{{CUSTOMER_NAME}}
first_name
string
{{CUSTOMER_FIRST_NAME}}
last_name
string
{{CUSTOMER_LAST_NAME}}
contact_phone
string · base64
{{CUSTOMER_PHONE_B64}} — base64 of the phone number.
contact_email
string · base64
{{CUSTOMER_EMAIL_B64}} — base64 of the email.
payment
object
Order-level payment summary.
currency
string
ISO 4217 code, e.g. GBP.
discount_code_type
string
FLAT or percentage-based.
free_delivery
boolean
order_value_for_free_delivery
number
Threshold above which delivery is free.
payment_mode
string
e.g. VOUCHER, CARD.
other_payment_mode
string
total_order_value
string
In the order currency.
total_order_value_gbp
string
Normalised to GBP.
order_id
stringkey
Order identifier. {{ORDER_ID}}
client_name
string
{{CLIENT_NAME}}
team_name
string
{{TEAM_NAME}}
first_order_date
string · ISO date
order_date
string · date
payment_orderIds
array
platform_name
string
Source sales channel, e.g. meesho.
unique_code
string
productDetails
object
The product the return concerns. Repeats address, location, contact and payment (with product-level price fields), plus the fields below.
payment
object
Product-level pricing. Each amount also has a _gbp twin.
rrp / rrp_gbp
number
Recommended retail price.
actual_price / actual_price_gbp
number
Price paid. Drives rule conditions like product.payment.actual_price_gbp.
cogs / cogs_gbp
number
Cost of goods sold.
discount_code
string
discount_value / discount_value_gbp
number
shipping_details
object
Physical attributes used to ship the return.
dimensions
object
length, width, height in cm.
insurance
object
is_insured, insured_amount, insured_currency.
actual_weight
number
In kg.
origin_country_alpha2
string
declared_currency / declared_customs_value
string
hs_code
string
Harmonised System customs code.
contains_battery_pi966 / pi967
boolean
contains_liquids
boolean
variants
object
color and size arrays.
aiRuleData
objectconditional
The rule and grading-flow configuration that was matched. Absent until the rule engine completes. See the dedicated breakdown under returnDetails.aiRuleData.
product_id
stringkey
{{PRODUCT_ID}}
original_product_id
string
The product id as originally imported, before any internal remapping.
variant_id
string
Identifier for the specific variant of this line item, composed from order / product / SKU attributes.
client_id
string
{{CLIENT_ID}}
brand
string
{{BRAND}}
name
string
Product display name.
sku / sku_color / sku_size / sku_value
string · number
category
object
category_name.
quantity
number
quantity_index
number
Position of this unit within the ordered quantity — each unit is sent as its own product object (see Import orders).
images
string[]
Product image URLs. Client-scoped paths shown as {{ASSET_PATH}}.
priority
string
high / medium / low.
delivery_status / delivery_date
string
purchased_date / order_date
string
return_allowed
boolean
return_by_date
string · ISO date
Return window cutoff.
description / product_meta
string
product_meta is a JSON-encoded string of extra attributes.
duty / vat
number
returnDetails
object
Everything about the return itself — request, images, grading outcome, disposition, refund and charges. Also echoes the order/product keys (order_id, team_name, client_name, product_id, original_product_id, priority).
return_req_id
stringkey
Unique id for the return request.
product_name
string
skip_type
string
e.g. REQUIRED — controls whether steps can be skipped.
return_images
object[]
Customer-uploaded images. Each has caption, instruction, file_path, mime_type, plus a background-removed copy (bgremove_path, bgremove_provider). Paths shown as {{ASSET_PATH}}.
tags
array
Return reasons, e.g. ["Too small"].
user_comment
string
returnType
string
e.g. RETURN, EXCHANGE.
cashbackType
string
e.g. REFUND.
retake_photos / payment_required
boolean
grade_status
string
e.g. COMPLETED.
weighted_confidence
number
Overall confidence of the grading outcome (0–1).
graded_at / graded_by
string · object
graded_by.user_alias identifies the grader (e.g. an AI grader).
grade
objectconditional
Present only after order.return.graded. Absent when grading is skipped.
id
string
Identifier of the grade record.
label
string
Grade letter, e.g. C.
grade_code
string
system_level_grade
string
Human label, e.g. Poor.
priority
number
executive_comment
string
action
object
What to do with the returned item — and where and how it ships.
status
string
e.g. ACCEPT.
action
string
e.g. SEND_TO_WAREHOUSE, SEND_TO_PARTNER.
location
object
Destination address (may include country), contact (phone/email encrypted), location_title, location_type (e.g. WAREHOUSE, CHARITY). Identity values shown as {{WAREHOUSE_*}}.
partner
object
partnerName and partnerId of the disposition partner (e.g. a charity). Set when the action routes to a partner.
shipping_carrier
object
Carrier selected to move the return — carrier_id, carrier_name, carrier, auth_company, shippingCarrier.
pickup_options
object
shippingClass_id, pickup_type (e.g. PICKUP), pickup_collection_date_enabled.
aiRuleData
objectconditional
Present only after the rule engine completes (order.return.rule.complete). Describes the matched rule and the grading flow it triggered.
rule.ruleTitle / rule.priority
string · number
rule.rules[]
object[]
The conditions that matched — each has a component (with mappingKey like product.payment.actual_price_gbp), an expression (GT, LT, EQ…) and a value.
rule.actions[]
object[]
Resulting actions, e.g. GRADING_FLOW → AI_FLOW.
rule.payload[]
object[]
Evaluated results of each condition.
action
string
Selected flow, e.g. AI_FLOW.
gradeRules.rules[]
object[]
The grade matrix (A–E). Each entry maps a grade_label / grade_code to score ranges for AI_DETECTION, AI_OCR_VALUE, AI_COMPARISON and STAIN_CONFIDENCE (fromto).
gradeRules.fallback
object
Grade applied if nothing matches.
refund
objectconditional
Present only after rules complete. This is where the refund_type you act on lives — see Refund handling.
refund_type
enumact on this
CASH or STORE_CREDIT — tells you how to settle with your customer.
refund_amount / currency
number · string
refund_method
stringnullable
refund_refrence
stringnullable
Your reference once you settle — you send this back in the confirmation call. (Field name is spelled refrence.)
status
string
e.g. PENDINGAPPROVED.
accepted / approved_by
boolean · string
charges
objectconditional
Present only after rules complete. Fees levied on the return.
chargeBack / chargeBackGbp
object
value, priceType (FLAT), priceOf (e.g. shippingCost).
dispositionRate / dispositionRateGbp
number
shippingCost / shippingCostFinal (+Gbp)
number
deductionCharges
objectconditional
Created once rules complete. If the deduction rule is based on shipping, it is only populated after shipping.created.
deduction / deductionGbp
number
priceType / currency
string
actual_price_gbp / refundValue
number
Net amount after deductions.
return_status
object
return_state (e.g. SHIPPING_SUCCESS), orderStatus, orderStatusColor.
dispositionData
object
Resale/feedback data — feedback and feedbacks[].
browser_data
object
Device/session metadata captured at return. ip{{CUSTOMER_IP}}, fingerprint{{DEVICE_FINGERPRINT}}; plus browser, platform, screen, timezone, etc.
vision_id
string
Reference to the vision/inspection record.
return_image_history / screenshot
array
collection_date
string · ISO datenullable
Scheduled pickup / collection date-time for the return shipment. Set once collection is arranged.
offering
object
action and offer — any incentive presented in place of a refund (action: "NA" when none).
payment_orderId
stringnullable
shipping_details
objectconditional
null until shipping.created. Label and QR fields inside stay null until shipping.label.created.
label
object
Carrier label result.
labelData.label_url
stringnull → label.created
labelData.tracking_number
stringnullable
labelData.tracking_page_url
stringnullable
isInitiated / isSuccess
boolean
labelError
stringnullable
Populated on shipping.label.failed.
label_path
objectnull → label.created
mime_type, file_path, url of the printable label PDF.
qr_code_path / qr_code_url
object · string
Drop-off QR code image.
shipping_id
stringkey
isShippingCreated / isLabelCreated
boolean
shippingCreatedDateTime / labelCreatedDateTime / deliveredDateTime
stringnullable
shippingCarrier / shippingCarrierDetails
string
e.g. DPD.
shippingPartner
string
shippingCost / currency / shippingStatus
string
shippingStatus e.g. created.
tracking_codes
string[]
Carrier tracking number(s). tracking_codes_ngrams is a search-index helper you can ignore.
primary / status / payment_required
boolean
contractId / policyNumber / dropoffLocation / status_note
stringnullable

Example payload

A trimmed, sanitized envelope. The grade matrix and repeated objects are abbreviated; expand the schema above for the full field list.

order.return.rule.complete · request body
{
  "orderDetails": {
    "order_id": "{{ORDER_ID}}",
    "client_name": "{{CLIENT_NAME}}",
    "team_name": "{{TEAM_NAME}}",
    "platform_name": "meesho",
    "contact": {
      "contact_name": "{{CUSTOMER_NAME}}",
      "contact_phone": "{{CUSTOMER_PHONE_B64}}",   // base64
      "contact_email": "{{CUSTOMER_EMAIL_B64}}"    // base64
    },
    "payment": { "currency": "GBP", "total_order_value_gbp": "187.00" },
    "productDetails": {
      "product_id": "{{PRODUCT_ID}}",
      "name": "Sample product",
      "sku": "SAMPLE-SKU", "sku_color": "Black", "sku_size": "XL",
      "payment": { "actual_price_gbp": 187, "cogs_gbp": 130.9 },
      "images": [ "{{ASSET_PATH}}/1.webp" ]
    },
    "returnDetails": {
      "return_req_id": "YNUZBD3NC5",
      "returnType": "RETURN",
      "tags": [ [ "Too small" ] ],
      "grade_status": "COMPLETED",
      "grade": { "label": "C", "system_level_grade": "Poor", "grade_code": "CC" },   // after order.return.graded
      "refund": {
        "refund_type": "CASH",            // CASH | STORE_CREDIT — act on this
        "refund_amount": 187,
        "currency": "GBP",
        "status": "PENDING",
        "refund_refrence": null
      },
      "deductionCharges": { "deductionGbp": 0, "refundValue": 187 },
      "action": {
        "status": "ACCEPT",
        "action": "SEND_TO_PARTNER",
        "partner": { "partnerName": "Charity Partner", "partnerId": "partner_123" },
        "pickup_options": { "pickup_type": "PICKUP" }
      },
      "collection_date": "2026-07-27T04:21:00.000Z"
    },
    "shipping_details": {                          // null until shipping.created
      "shipping_id": "MV163509342",
      "shippingCarrier": "DPD",
      "shippingStatus": "created",
      "tracking_codes": [ "5420740800" ],
      "label_path": null                          // url appears after shipping.label.created
    }
  }
}

09Refund handling

Back decides a refund is due and fires order.refund.initiated. The actual settlement happens on your store — then you tell us it's done.

Read returnDetails.refund.refund_type to know how to settle:

refund_typeWhat you do
CASHRefund money back to the customer's original payment method, for the amount in refund.refund_amount / currency.
STORE_CREDITIssue store credit / a voucher to the customer for the same amount instead of returning cash.
Sequence1. Receive order.refund.initiated.   2. Settle the refund on your store (cash or store credit).   3. Confirm back to Back with the call below, passing your settlement reference. We then mark the refund APPROVED.

10Confirm a refund

After you've settled, call this endpoint so Back can close the refund. This is the one call that goes from you to Back.

POSThttps://live.api.back.tech/api/dashboard/webhook/refund
curl --request POST \
  --url https://live.api.back.tech/api/dashboard/webhook/refund \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "{{ORDER_ID}}",
    "product_id": "{{PRODUCT_ID}}",
    "refund": {
      "refund_type": "CASH",
      "status": "APPROVED",
      "refund_refrence": "{{YOUR_REFERENCE}}"
    }
  }'
FieldNotes
order_idThe order from the webhook payload.
product_idThe product the refund applies to.
refund.refund_typeCASH or STORE_CREDIT — the type you actually settled.
refund.statusSet to APPROVED once the refund has been completed on your side.
refund.refrenceYour settlement reference, returned to Back for reconciliation. Note the field is spelled refund_refrence.
Use the exact field nameThe reference field is refund_refrence (one "e" missing). Send it verbatim or the confirmation won't bind.

BACK API Integration — order import, webhook handling, and refund confirmation. Sample data is sanitized; every identifiable and client-specific value is a placeholder.

v1.6.1 · Updated 2026-07-28