Returns Extension

br.dev.bcp.shopping.returns extends order and declares return policy in the business profile.

Overview

This extension covers Brazilian distance-commerce returns in two parts:

• Policy in the discovery profile: withdrawal period and request channel, so the consumer can see return rights before checkout completion.
• Return record on the order: BCP already models post-sale changes as order adjustments[]; this extension adds return reason, legal deadlines, and reverse logistics fields.

The seven-day withdrawal period starts at confirmed delivery, represented by the existing delivered fulfillment event.

Discovery

{
  "capabilities": {
    "br.dev.bcp.shopping.returns": [
      {
        "version": "2026-07-14",
        "extends": "br.dev.bcp.shopping.order",
        "spec": "https://bcp.dev.br/2026-07-14/specification/returns",
        "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/returns.json",
        "config": {
          "withdrawal_period_days": 7,
          "request_channel": "https://loja.example.com.br/devolucoes"
        }
      }
    ]
  }
}

Schema Composition

• order.adjustments[] entries are extended for return-specific data.
• Policy config is defined by schemas/shopping/types/returns_config.json.
• Schema: schemas/shopping/returns.json.

Fields

Policy config

Field	Type	Required	Description
withdrawal_period_days	integer	No	Withdrawal period in calendar days, minimum 7, counted from confirmed delivery.
request_channel	string	No	Channel used to request returns; should include the purchase channel.

Return adjustment fields

Field	Type	Required	Description
reason	open string	No	Suggested values: withdrawal, defect, wrong_product.
acknowledged_at	date-time	No	When the seller acknowledged the request.
reverse_shipping_code	string	No	Reverse shipping/posting code.
carrier	string	No	Carrier handling the reverse flow.
deadline	date-time	No	Deadline for the consumer to ship the product back.

Normative Rules

1. The withdrawal right MUST be disclosed before completion; policy config is the protocol source for that disclosure.
2. BCP transactions are distance-commerce transactions; withdrawal rules apply to all transactions unless a future extension scopes otherwise.
3. The seller MUST acknowledge return requests within the legally required period applicable to the transaction.
4. Withdrawal refunds MUST be integral, including paid freight, represented by negative return adjustments and totals.

Example

Order response excerpt:

{
  "id": "ord_789",
  "fulfillment": {
    "events": [
      {
        "id": "ev_9",
        "type": "delivered",
        "occurred_at": "2026-07-01T16:20:00-03:00",
        "line_items": [{ "id": "li_1", "quantity": 1 }]
      }
    ]
  },
  "adjustments": [
    {
      "id": "adj_1",
      "type": "return",
      "status": "pending",
      "occurred_at": "2026-07-03T10:00:00-03:00",
      "reason": "withdrawal",
      "acknowledged_at": "2026-07-04T09:00:00-03:00",
      "reverse_shipping_code": "BR123456789XX",
      "carrier": "Correios",
      "deadline": "2026-07-13T23:59:59-03:00",
      "line_items": [{ "id": "li_1", "quantity": -1 }]
    }
  ]
}