Return label API for ecommerce reverse logistics
Generate return label and return instruction PDFs from ecommerce or support data with label-sized pages, barcodes, and template reprints.
/api/v1/pdf/render Render return label PDFs or return instruction sheets from RMA, customer, item, destination, and barcode data so a returns portal can provide a deterministic document to the customer.
When to use this API
- Your system already created the RMA and return authorization.
- A carrier or returns system has already supplied the label payload or tracking data.
- You need a PDF label or instruction sheet that can be downloaded, emailed, or reprinted.
- You want the same return label layout reused through Template Render.
What it does not replace
- You need gPdf to approve the return, buy postage, or create a carrier shipment.
- You need direct carrier API orchestration.
- You need printer command output such as ZPL.
Which endpoint to call
/api/v1/pdf/render
JSON Render is the default path for this workflow.
/api/v1/template-render
Use this when the workflow needs the related API path, template contract, or capabilities lookup.
Minimal request
POST /api/v1/pdf/render - return label with RMA barcode.
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 5,
"y": 8,
"content": "RETURN TO",
"style": { "font_size": 9, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 5,
"y": 18,
"content": "Acme Returns\n500 Dock Door 4\nColumbus OH 43215",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "RMA-2026-77881",
"x": 5,
"y": 70,
"width": 88,
"height": 20,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
What gPdf handles
- PDF rendering for label-sized return labels and instruction pages.
- Barcode, text, address, RMA, and service blocks.
- Template binding for approved return label or instruction layouts.
- Deterministic output for customer re-downloads and support reprints.
What your system owns
- Return eligibility, RMA state, carrier account, postage, tracking number, and customer messaging.
- Correct barcode payloads, destination address, item references, and return window rules.
- Email delivery, portal download, and support audit trail.
Production checklist
- Validate the return payload with the carrier or returns provider before rendering.
- Print and scan labels on the same stock customers or stores will use.
- Include an X-Request-Id and store the RMA-to-PDF trace in your support logs.
- Make repeated downloads idempotent from the customer's perspective.
- Separate label rendering from refund approval logic.
Claim boundaries
- gPdf renders return label PDFs; it does not authorize returns or buy postage.
- Carrier acceptance and barcode payload correctness remain yours.
- The public API returns PDF, not ZPL or direct printer commands.
Reverse logistics needs clear ownership
Return labels combine customer experience and carrier rules. gPdf owns PDF rendering. Your return system owns eligibility, RMA state, tracking, carrier payloads, and customer communication.
Keep that boundary visible in the integration. Generate the return decision first, then render the document from the finalized data.
FAQ
- Does gPdf create the return shipment?
- No. Your carrier or returns platform creates the shipment and payload. gPdf renders that data into a PDF.
- Can return labels be generated from templates?
- Yes. Use Template Render once the return label or instruction layout is approved.
- Can the PDF include return instructions?
- Yes. The same render request can create a label page, an instruction page, or both depending on your layout.
- Does gPdf replace carrier certification?
- No. Carrier acceptance, scanner tests, and payload rules remain your responsibility.